Transmission 自动添加种子:watch 目录、Docker 与失败排查
简答:Transmission 自动添加种子主要依靠 watch 目录:开启监视目录后,把 .torrent 文件复制进去,Transmission 会尝试加载。磁力链接不能直接当作 .torrent 文件放入该目录,应通过图形界面、transmission-remote 或 RPC 添加。
定义:Transmission 的 watch directory 是一个由客户端或 daemon 监视的文件夹,用于自动发现并加载其中的新 .torrent 文件。
先用这张表确认入口、目录和限制
如果你只想让 Transmission 自动加载种子文件,先确认下面四项:监视功能已开启、文件确实是 .torrent、Transmission 运行账户能读取该目录、下载目录对运行账户可写。Transmission 的配置字段包括 watch-dir、watch-dir-enabled、start-added-torrents 和 trash-original-torrent-files;具体配置名称可参考其配置文件说明。Transmission 配置字段说明
| 使用场景 | 设置入口或字段 | 输入内容 | 自动开始 | 限制与核对点 |
|---|---|---|---|---|
| Windows 桌面端 | 设置或偏好设置中的 watch directory 相关选项 | 宿主机上的监视文件夹 | 由 start-added-torrents 或界面选项决定 | 具体菜单名称随客户端界面变化,需核对当前设置页 |
| macOS 桌面端 | 设置或偏好设置中的监视目录选项 | 可被当前用户读取的文件夹 | 需核对当前选项 | 文件系统权限、目录事件和客户端运行状态都可能影响识别 |
| Linux daemon | settings.json 或启动参数 | watch-dir 指向的目录 | watch-dir-enabled 与 start-added-torrents | 必须确认 daemon 实际读取的配置目录 |
| NAS | daemon 配置或 NAS 应用的配置界面 | NAS 内部真实路径 | 由 daemon 配置决定 | 宿主机显示路径与 daemon 看到的路径可能不同 |
| Docker | 容器配置与挂载规则 | 容器内的 watch 路径 | 由容器内 Transmission 配置决定 | 宿主机路径必须映射到相同的容器内路径,且用户权限匹配 |
| 磁力链接 | 图形界面、transmission-remote 或 RPC | 磁力链接文本 | 由添加参数决定 | 不能把普通文本磁力链接当作 .torrent 文件放入 watch 目录 |
Windows、macOS 和 Linux 桌面端怎么开启自动添加
第一步,创建一个专用文件夹,例如 watch,不要直接使用下载目录。这样可以把“待导入的种子文件”和“已下载内容”分开,排查时也更容易。
- Windows:打开 Transmission 的设置或偏好设置,查找 watch directory、watch folder 或监视目录相关选项,选择刚创建的文件夹,并启用监视功能。若界面没有显示相同的中文名称,以当前客户端设置页为准。
- macOS:在 Transmission 设置中查找监视目录选项,选择一个当前用户有读取权限的文件夹。若放入文件后没有反应,先退出并重新打开客户端,再测试一个新复制进去的
.torrent文件。 - Linux 图形界面:GTK 或 Qt 客户端同样需要设置 watch directory 和启用开关。项目文档说明,启用监视目录后,daemon、GTK 和 Qt 客户端可以监视新加入的
.torrent文件。Transmission watch directory 配置说明
第二步,把一个完整的 .torrent 文件复制到监视目录,而不是把下载页面、快捷方式或磁力链接文本文件复制进去。第三步,观察 Transmission 的任务列表:任务出现,说明自动添加成功;任务出现但暂停,说明还需要检查自动开始设置;任务完全不出现,则优先检查目录、扩展名、权限和客户端是否仍在运行。
Linux transmission-daemon:用 settings.json 配置
daemon 场景最容易遇到的问题是“编辑了一个 settings.json,但实际运行的服务读取的是另一个配置目录”。Transmission 的配置文件说明列出了不同客户端和 daemon 的配置位置,并指出 settings.json 保存客户端设置。Transmission 配置文件说明
- 先停止 daemon,避免运行中的进程把内存中的旧配置重新写回文件。
- 备份当前的
settings.json。 - 确认或修改以下字段,路径替换为你的实际目录:
"watch-dir": "/srv/transmission/watch"
"watch-dir-enabled": true
"start-added-torrents": true
"trash-original-torrent-files": false
- 确认监视目录已创建,并让运行 daemon 的用户拥有读取权限。
- 启动 daemon 后,把测试用的
.torrent文件复制到监视目录。 - 在 Web UI 或命令行中确认任务是否出现、是否开始下载、保存位置是否正确。
transmission-daemon --dump-settings 可用于查看 daemon 支持的配置选项;如果服务由 systemd 管理,还应查看服务单元的启动参数,确认是否通过 --config-dir 指向了其他目录。daemon 的命令行选项包含 watch directory、配置目录和 RPC 端口等参数。Transmission daemon 命令行选项
不要只根据默认路径猜测配置文件位置。服务账户、用户账户和容器账户可能分别使用不同的配置目录;实际路径应以启动参数、服务文件和运行账户为准。
Docker 和 NAS:先核对宿主机路径、容器路径与权限
Docker 中自动添加失败,常见原因不是 Transmission 没有 watch 功能,而是“宿主机看到的目录”和“容器内 Transmission 读取的目录”不是同一个路径。假设宿主机目录为 /srv/transmission/watch,容器内路径为 /watch,那么 Transmission 的 watch-dir 必须写成容器内的 /watch,而不是宿主机路径。
- 在宿主机创建三个用途分开的目录:配置目录、下载目录、watch 目录。
- 将宿主机 watch 目录挂载到容器内的固定路径,例如
/watch。 - 将 Transmission 的
watch-dir设置为容器内路径,并开启watch-dir-enabled。 - 确认容器内运行用户能读取 watch 目录,也能写入配置目录和下载目录。
- 进入容器检查文件是否真的可见,再复制测试种子:
docker exec -it transmission sh
ls -la /watch
如果宿主机目录里有文件,但容器内的 /watch 为空,问题在挂载关系;如果文件可见但任务不出现,继续检查扩展名、配置字段和日志;如果任务出现但下载失败,检查下载目录的写入权限。NAS 应用也遵循相同原则:以 Transmission 进程实际看到的路径和用户权限为准,不要只看 NAS 文件管理器中的路径。
磁力链接不能直接放进 watch 目录,替代方法是什么
watch directory 主要监视新加入的 .torrent 文件,因此普通磁力链接文本不能直接通过“放入 watch 文件夹”的方式导入。Transmission 的 RPC 规范把磁力链接作为 torrent_add 的添加参数处理,同时也支持通过文件名或 URL 添加种子文件。Transmission RPC 添加任务规范
桌面端可以直接使用“打开链接”或添加任务入口;服务器环境可以使用 transmission-remote:
transmission-remote http://127.0.0.1:9091/transmission/ --add "magnet:?xt=..."
实际 RPC 地址、认证信息和端口应以你的部署设置为准。transmission-remote 支持通过 --add 添加种子文件或 URL,也支持用 --download-dir 指定下载目录。transmission-remote 参数说明
如果你想保留“投递文件自动处理”的工作流,可以先用其他受信任工具把磁力链接解析为合法的 .torrent 文件,再把生成的文件放入 watch 目录;不要把包含磁力链接的纯文本文件直接改名为 .torrent,那仍然不是有效的种子文件。
自动添加不生效:按这个顺序排查
| 现象 | 优先检查 | 处理方法 |
|---|---|---|
| 文件放入后完全没有任务 | watch 开关、目录路径、扩展名 | 确认 watch-dir-enabled 为启用状态,复制完整的 .torrent 文件,并核对客户端实际读取的目录 |
| 任务出现但没有自动下载 | 自动开始选项 | 检查 start-added-torrents 或添加任务时是否默认暂停 |
| 任务出现但下载目录报错 | 下载目录权限和路径 | 让运行 Transmission 的用户拥有写入权限,并确认容器内路径存在 |
| Docker 宿主机有文件,容器内没有 | volume 挂载 | 检查宿主机路径、容器路径和挂载模式是否一致 |
| 重启后配置失效 | 配置文件被覆盖或编辑错文件 | 停服务后修改,检查 --config-dir、服务单元和持久化挂载 |
| macOS 运行中不识别新文件 | 客户端状态、目录权限和版本行为 | 先重启客户端,用新文件测试;当前具体版本表现需核实,不要只凭单一案例判断 |
| 原始种子文件消失 | trash-original-torrent-files | 需要保留原文件时将该选项关闭;需要自动清理时,先确认任务已成功添加 |
最后做一次闭环验证:新建测试目录,放入一个可用的 .torrent 文件,确认任务出现在列表中,再确认是否自动开始、下载目录是否正确、原始文件是否按预期保留或删除。不要一开始就用大量种子测试,否则很难判断是路径问题、权限问题还是重复任务问题。
不要把 RPC 管理端口和 BT peer 端口混为一谈
Transmission 的 RPC 端口用于 Web UI、远程客户端或 transmission-remote 管理 daemon;BT peer 端口用于与其他节点建立连接,两者用途不同。daemon 的命令行选项分别列出了 RPC 端口和 peer port。Transmission daemon 参数列表
如果只是配置 watch 目录,不需要把 RPC 管理端口直接暴露到公网。更稳妥的做法是限制监听地址、使用认证、通过局域网或受控的反向代理访问,并在路由器和防火墙中只开放必要端口。端口转发、连接速度和下载速度不是 watch 目录自动添加功能本身的验证指标;先确认任务能否被加载,再单独排查网络连接、peer 端口和做种状态。
常见问题
Transmission 自动添加种子需要什么格式?
watch 目录主要用于自动加载有效的 .torrent 文件。磁力链接、网页快捷方式和普通文本文件不能直接当作种子文件处理。
为什么种子文件放进 watch 文件夹后没有反应?
按顺序检查监视开关、实际目录、文件扩展名、Transmission 是否运行、运行账户是否有读取权限,以及 daemon 是否读取了另一份配置文件。
Transmission 自动添加后能否自动开始下载?
可以通过 start-added-torrents 或添加任务时的启动选项控制,但不同客户端界面名称可能不同。任务出现但暂停时,优先检查这一项。
Docker 里 watch 目录应该填写宿主机路径还是容器路径?
应填写 Transmission 在容器内看到的路径。例如宿主机目录映射到容器的 /watch,watch-dir 就应指向 /watch。
自动添加后原始 torrent 文件为什么不见了?
检查 trash-original-torrent-files。该选项用于控制添加完成后是否删除监视目录中的原始种子文件,需要保留时应关闭并重新验证。
磁力链接可以放进 watch 目录自动添加吗?
普通磁力链接不能直接通过 watch 目录导入。请使用图形界面、transmission-remote 或 RPC 的添加任务功能。
相关阅读
- Transmission 自动启动设置
- Transmission Docker 目录与权限配置
- Transmission 下载目录权限排查
- Transmission 磁力链接无法下载排查
- Transmission Web UI 与远程访问