AyuCLouD-Services返回首页

Transmission 自动添加种子:watch 目录、Docker 与失败排查

更新于 2026-11-14 · ayu-ssr.buzz

简答: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 daemonsettings.json 或启动参数watch-dir 指向的目录watch-dir-enabled 与 start-added-torrents必须确认 daemon 实际读取的配置目录
NASdaemon 配置或 NAS 应用的配置界面NAS 内部真实路径由 daemon 配置决定宿主机显示路径与 daemon 看到的路径可能不同
Docker容器配置与挂载规则容器内的 watch 路径由容器内 Transmission 配置决定宿主机路径必须映射到相同的容器内路径,且用户权限匹配
磁力链接图形界面、transmission-remote 或 RPC磁力链接文本由添加参数决定不能把普通文本磁力链接当作 .torrent 文件放入 watch 目录

Windows、macOS 和 Linux 桌面端怎么开启自动添加

第一步,创建一个专用文件夹,例如 watch,不要直接使用下载目录。这样可以把“待导入的种子文件”和“已下载内容”分开,排查时也更容易。

  1. Windows:打开 Transmission 的设置或偏好设置,查找 watch directory、watch folder 或监视目录相关选项,选择刚创建的文件夹,并启用监视功能。若界面没有显示相同的中文名称,以当前客户端设置页为准。
  2. macOS:在 Transmission 设置中查找监视目录选项,选择一个当前用户有读取权限的文件夹。若放入文件后没有反应,先退出并重新打开客户端,再测试一个新复制进去的 .torrent 文件。
  3. 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 配置文件说明

  1. 先停止 daemon,避免运行中的进程把内存中的旧配置重新写回文件。
  2. 备份当前的 settings.json。
  3. 确认或修改以下字段,路径替换为你的实际目录:

"watch-dir": "/srv/transmission/watch"

"watch-dir-enabled": true

"start-added-torrents": true

"trash-original-torrent-files": false

  1. 确认监视目录已创建,并让运行 daemon 的用户拥有读取权限。
  2. 启动 daemon 后,把测试用的 .torrent 文件复制到监视目录。
  3. 在 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,而不是宿主机路径。

  1. 在宿主机创建三个用途分开的目录:配置目录、下载目录、watch 目录。
  2. 将宿主机 watch 目录挂载到容器内的固定路径,例如 /watch。
  3. 将 Transmission 的 watch-dir 设置为容器内路径,并开启 watch-dir-enabled。
  4. 确认容器内运行用户能读取 watch 目录,也能写入配置目录和下载目录。
  5. 进入容器检查文件是否真的可见,再复制测试种子:

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 的添加任务功能。

相关阅读

参考资料

  1. Transmission 配置字段说明
  2. Transmission 配置文件说明
  3. Transmission daemon 命令行选项
  4. Transmission RPC 添加任务规范
  5. transmission-remote 参数说明