Decypharr 是一款面向 Debrid 与 Usenet 的开源媒体网关（Media Gateway），能让 Sonarr、Radarr 等 *Arr 应用直接流式播放云端媒体，无需本地下载占满硬盘。本教程将带你用 Docker 在 10 分钟内完成 Decypharr 部署，并通过首次运行向导（Setup Wizard）六步完成全部核心配置。

一、Decypharr 是什么？为什么值得部署

一句话理解：没有 Decypharr，Sonarr 找到种子后要靠 qBittorrent 把文件完整下到硬盘；有了 Decypharr，请求会转发给你的 Debrid 服务商（如 Real Debrid），媒体直接在云端就绪，再由 Decypharr 挂载成本地文件系统供媒体服务器播放。

它的核心能力包括：

• 🎬免本地下载：文件从 Debrid / Usenet 直连流式传输，省空间
• 🔁原生兼容 Arr：模拟 qBittorrent 与 Sabnzbd API，Sonarr / Radarr 即插即用
• 🌐多服务商：支持 Real Debrid、All Debrid、Debrid Link、Torbox、Premiumize
• 📡Usenet 直连：通过 NNTP 直接流式读取，无需额外下载客户端
• 🗄️灵活挂载：DFS 自定义文件系统、Rclone、WebDAV、NFS / SMB 共享

部署完成后，你会看到这样的主界面——下载队列、进度与协议状态一目了然：

二、部署前的 3 项快速准备

在开始之前，请确认以下条件（约 1 分钟）：

💡 端口规划：Web UI 默认使用8282；若后续启用 NFS / SMB 共享，还分别需要20490与1445端口（详见 安装文档）。

三、Docker Compose 一键部署 Decypharr

1. 创建 docker-compose.yml

在你喜欢的位置（例如~/decypharr）创建docker-compose.yml：

services: decypharr: image: cy01/blackhole:latest container_name: decypharr ports: - "8282:8282" # 可选：NFSv4 共享（在设置中开启 NFS 后生效） # - "2049:20490/tcp" # 可选：SMB 共享（Windows 客户端需占用宿主机 445 端口） # - "445:1445/tcp" volumes: - /mnt/:/mnt:rshared - ./configs/:/app # config.json 必须位于该目录 restart: unless-stopped devices: - /dev/fuse:/dev/fuse:rwm cap_add: - SYS_ADMIN security_opt: - apparmor:unconfined

几个关键配置的含义：

• ./configs/:/app：配置目录，首次运行向导完成后所有设置都保存在这里
• /dev/fuse+SYS_ADMIN+apparmor:unconfined：DFS 文件系统挂载所需的 FUSE 权限；如果你确定只用 API / WebDAV 而不用本地挂载，可考虑精简
• 若不使用本地挂载，/mnt/:/mnt:rshared一行也可以注释掉

镜像构建细节可参考 Dockerfile，其中还内置了 healthcheck 与 rclone 依赖。

2. 启动并验证

docker compose up -d

等待约 10 秒后打开浏览器访问：

http://localhost:8282

如果看到Setup Wizard（设置向导）页面，说明部署成功 ✅（也可以先执行docker compose logs -f确认服务正常启动）。

四、首次运行向导：6 步完成核心配置

Decypharr 首次启动会自动进入向导，顶部进度条共 6 步：Authentication → Debrid Account → Usenet Provider → Download Folder → Mount System → Overview。每步都可按需跳过，但至少配置一个 Debrid 或 Usenet 服务商才能完成。

步骤 1：创建管理员账号（可选）

• 填写Username与Password，用于保护 Web 界面
• 也可以点击Skip Authentication跳过（仅限内网环境，不推荐）
• 完成后系统会自动生成 API Token并展示一次，请及时保存

步骤 2：连接 Debrid 服务商

1. 在Debrid Provider下拉框选择你的服务商（Real Debrid、All Debrid、Debrid Link、Torbox、Premiumize）
2. 粘贴从服务商后台复制的API Key
3. 点击Next；没有 Debrid 可先点Skip Debrid

🔑 提示：API Key 一般都在服务商官网的 Personal API / Settings 页面，格式为一长串字母数字组合。

步骤 3：配置 Usenet 服务商（可选）

如果你使用 Usenet（NZB），填写 NNTP 连接信息：

只玩 Debrid 的用户直接Skip Usenet即可。

步骤 4：指定下载文件夹

填写Download Folder Path（如data/downloads），用于存放需要落盘的内容。默认值通常可以直接使用。

步骤 5：选择挂载方式

挂载类型决定了媒体文件如何"出现"在你的系统里：

• Mount Path：文件出现的位置，例如/mnt/remote
• Cache Directory：本地缓存目录，例如/mnt/cache

💡 注意：选择 DFS / Rclone 时，请确保你的docker-compose.yml已包含 FUSE 相关配置（第三步已默认带上）。

步骤 6：确认并完成（Overview）

核对各步设置后点击Complete Setup，向导会跳转到主仪表盘，并仅展示一次你的 API Token——这是后续接入 Sonarr / Radarr 的关键凭据，务必复制保存。

五、部署完成后的下一步

恭喜！Decypharr 已在运行。接下来可以：

1. 接入 Sonarr / Radarr：在 Arr 的Settings → Download Clients中新增qBittorrent客户端（用于 Debrid 种子，Host 填 Decypharr 地址、端口 8282）；若配置了 Usenet，则新增Sabnzbd客户端。完整参数见 连接 Sonarr 与 Radarr 指南
2. 开启共享服务：在Settings中启用 NFS / SMB / WebDAV，让 Plex、Jellyfin 或 NAS 直接访问媒体库
3. 细调配置：所有设置都保存在config.json，大部分可在 Web 界面修改，完整字段说明见 配置参考

六、常见问题快速解答

Q1：打开 8282 端口没反应？先用docker compose ps确认容器运行中，再docker compose logs查看报错；若在远程服务器上，检查防火墙是否放行 8282 端口。

Q2：向导提示"至少配置一个 Debrid 或 Usenet 服务商"？Debrid 与 Usenet 是 Decypharr 的两大内容来源，二选一必填。没有服务商账号时，可先跳过全部配置项之后在Settings中补填。

Q3：挂载目录是空的或挂载失败？检查 Docker 是否具备 FUSE 权限（/dev/fuse、SYS_ADMIN），并确认宿主机/mnt目录存在且权限正确。

Q4：忘记保存 API Token？编辑配置目录中的auth.json查看或重置 Token（见 配置参考 - 认证部分）。

到这里，你的 Decypharr 媒体网关已经完全可用。更多进阶玩法——虚拟文件夹、队列自动清理、修复 Worker（Repair）等，可继续在 官方文档 中探索。祝观影愉快！🍿