AyuCLouD-Services返回首页

Transmission Docker 容器化部署完整指南

更新于 2026-10-23 · ayu-ssr.buzz

简答：Transmission Docker 部署的核心是三件事：把 /config、/downloads、/watch 持久化，把 9091 Web 端口与 BT 端口正确映射，并让 PUID、PGID 对应宿主机目录权限。先复制本文的 Compose 示例，替换路径和用户组 ID，再用日志、Web 页面和端口测试完成验收。本站不是 Transmission 官方网站，也不提供或认定其下载入口；本文仅整理可核验的容器部署方法。

定义：Transmission Docker 容器化部署，是把 Transmission 运行在 Docker 容器中，并通过 Compose 管理配置、下载目录、监听端口和容器生命周期。

先做这一步：创建目录并确认权限

建议先在宿主机规划三个目录：config保存 Transmission 配置，downloads保存下载文件，watch用于自动加载种子文件。LinuxServer 镜像文档将容器内的这三个路径分别用于配置、下载和 watch 目录，并通过 PUID、PGID映射宿主机用户权限。参考：LinuxServer Transmission 镜像说明。

sudo mkdir -p /srv/transmission/{config,downloads,watch}

id youruser
# 记录输出中的 uid 和 gid，例如 uid=1000、gid=1000

sudo chown -R 1000:1000 /srv/transmission

上面的 1000:1000只是示例，必须替换为实际运行用户的 UID 和 GID。若容器能打开 Web 页面但无法创建下载文件，优先检查这里，而不是先修改端口。

完整 compose.yaml 示例

在工作目录创建 compose.yaml。下面示例使用 LinuxServer 发布的 Transmission 镜像；其文档列出 x86-64 与 arm64 支持，并提供 9091、51413 TCP 和 51413 UDP 的基础映射示例。部署前请根据你的平台和目录替换变量。

services:
  transmission:
    image: lscr.io/linuxserver/transmission:latest
    container_name: transmission
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - USER=change-me
      - PASS=change-me
      - PEERPORT=51413
      # - WHITELIST=192.168.*.*
      # - HOST_WHITELIST=transmission.example.com
    volumes:
      - /srv/transmission/config:/config
      - /srv/transmission/downloads:/downloads
      - /srv/transmission/watch:/watch
    ports:
      - "9091:9091"
      - "51413:51413"
      - "51413:51413/udp"
    restart: unless-stopped

必须替换：PUID、PGID、TZ、三个宿主机目录、Web 用户名和密码。PEERPORT要与 Docker 映射的 BT 端口保持一致；如果你把宿主机端口改成其他数值，建议容器内外也保持同一个端口，减少排查变量。LinuxServer 的镜像页面明确说明，PEERPORT应与 Docker 配置中的映射端口一致。

关于 latest：示例为了易懂使用 latest。生产环境可先在测试目录验证，再改用已经验证过的版本标签；更新前备份 /srv/transmission/config。本文不替你指定一个未核实的固定版本号。

启动、登录与首次验收

  1. 进入 compose.yaml所在目录，执行 docker compose config，先检查 YAML 和变量格式。
  2. 执行 docker compose pull拉取镜像，再执行 docker compose up -d启动容器。
  3. 执行 docker compose ps确认容器处于运行状态，执行 docker compose logs --tail=100 transmission查看启动日志。
  4. 在同一局域网浏览器访问 http://服务器IP:9091/。Transmission 官方文档将 9091列为默认远程控制端口；容器部署时仍以实际映射为准，参考：Transmission Web Interface 文档。
  5. 登录后添加一个合法且你有权下载的任务，确认任务能进入队列，并检查文件是否出现在宿主机的 /srv/transmission/downloads目录。

如果页面能打开但下载目录没有文件，先看日志，再检查宿主机目录的所有者和权限。Docker Compose 的卷挂载用于保存容器外的持久化数据，参考：Docker Compose volumes 文档。

端口、网络模式与路由器转发怎么选

场景推荐方式需要注意
仅在局域网使用 Web 管理bridge 网络加 9091端口映射只允许局域网访问，Web 密码不要留空
需要外部节点主动连接映射 51413 TCP 和 UDP宿主机防火墙、路由器转发和 PEERPORT 必须一致
NAS 图形化管理 Docker使用 Compose 项目或等效配置确认 NAS 的路径映射和用户组 ID
多个 Transmission 实例为每个实例分配不同 Web、TCP、UDP 端口每个实例使用独立 config 目录
不熟悉 Docker 网络先不要使用 host 模式bridge 加明确端口映射更容易核对

Transmission 官方端口转发文档说明，BT 通信会涉及 TCP 和 UDP，路由器转发到宿主机只是其中一环；宿主机防火墙也需要允许对应端口。端口开放并不等于 Web 管理端口应该暴露到公网，9091应优先限制在局域网，或放在带 HTTPS 和身份认证的反向代理之后。参考：Transmission Port Forwarding Guide。

公网访问与 RPC 安全边界

不要直接把 9091映射到公网后就认为部署完成。Transmission 的 RPC 接口支持用户名密码认证、IP 白名单和主机名白名单；官方 RPC 文档还说明，RPC 请求存在 Host 校验和 CSRF 会话标识机制。参考：Transmission RPC 规范。

  • Web 管理只给局域网访问时，可在防火墙限制来源网段。
  • 确需远程管理时，使用 HTTPS 反向代理，并设置强密码。
  • 使用 WHITELIST限制允许访问 RPC 的 IP，使用 HOST_WHITELIST限制允许使用的域名；具体写法以镜像页面和生成的配置文件为准。
  • 不要把密码直接提交到公开代码仓库；Compose 文件权限应限制为管理用户可读。
  • 如果出现 421 或 Host 未被允许，检查访问地址是否与主机名白名单一致，而不是反复重启容器。

常见问题：按现象排查

现象优先检查处理方法
9091打不开容器状态、端口映射、防火墙执行 docker compose ps和 ss -lntp | grep 9091，确认访问的是宿主机 IP
页面能开但无法下载目录权限和挂载路径检查 docker inspect transmission，再核对 chown后的 UID/GID
RPC 返回 421Host 白名单使用允许的 IP 或域名，或按当前配置修正 HOST_WHITELIST
端口测试关闭PEERPORT、宿主机防火墙、路由器确认 TCP/UDP 都映射，路由器转发到正确的宿主机，且端口号一致
重建后设置丢失/config是否持久化确认宿主机 config 目录没有写错，重建前先备份该目录

Transmission 官方 RPC 规范提供了端口测试接口，可返回端口是否可从外部访问；但“端口开放”只说明可达性，不能直接代表下载速度或所有节点连接正常。排查时应把 Web 可达、文件可写和 BT 端口可达分开验证。

更新、备份与回滚

LinuxServer 的更新流程是先拉取新镜像，再重新创建容器；只要 /config正确挂载，配置可以在容器重建后保留。参考：LinuxServer Transmission 更新说明。

  1. 先暂停或记录正在运行的任务，备份 /srv/transmission/config。
  2. 执行 docker compose pull transmission。
  3. 执行 docker compose up -d transmission重建并启动。
  4. 查看 docker compose logs --tail=100 transmission，再登录 Web 页面确认任务列表和下载目录。
  5. 如果新镜像出现异常，停止容器并恢复经过备份的 config，再改回已验证的镜像标签进行回滚。

不要在 Transmission 正在运行时直接编辑 settings.json，否则运行中的进程可能覆盖修改。需要改配置时，先停止容器，备份文件，修改后再启动，并以当前镜像文档为准。

本文的最短验收清单

  • 目录：/config、/downloads、/watch均映射到宿主机。
  • 权限：PUID、PGID与宿主机目录所有者匹配。
  • Web：能访问 http://服务器IP:9091/并完成登录。
  • 文件：测试任务产生的文件确实落在宿主机下载目录。
  • 端口：PEERPORT与 TCP/UDP 映射一致，必要时再配置路由器和防火墙。
  • 安全：9091不直接暴露公网，远程访问使用访问控制和 HTTPS。
  • 维护：升级前备份 config，升级后检查日志、任务和文件。

接下来可以继续排查什么

如果容器已经正常运行，但下载任务仍然无速度、端口关闭或跨网络访问异常，可继续查看本站的Transmission Docker 网络排查指南，再根据具体设备选择对应的Transmission 安装配置与连接排查步骤。

常见问题

Transmission Docker 为什么能打开 Web 页面，却不能下载到宿主机？

最常见原因是下载目录权限或挂载路径不正确。先执行 docker inspect transmission 检查 /downloads 的实际绑定路径，再用宿主机目录的 UID、GID修正 chown，并查看容器日志中的 permission denied。

Transmission Docker 一定要使用 host 网络吗？

不一定。局域网使用通常可以采用 bridge 网络并明确映射 9091、51413 TCP 和 UDP；只有在明确理解端口和服务发现差异时再考虑 host 模式。本文示例优先使用更容易核对的 bridge 方式。

PEERPORT 和 Docker 端口映射为什么要一致？

镜像文档明确要求 PEERPORT 与 Docker 配置中的映射端口保持一致。若 Transmission 内部监听一个端口、宿主机映射另一个端口，路由器转发和端口测试就容易指向错误位置。

容器重建后 Transmission 的任务和设置会消失吗？

如果 /config 没有持久化映射，或者映射到了错误目录，就可能看起来像设置丢失。正确挂载宿主机 config 目录，并在升级前备份它，通常可以保留配置和任务状态。

Transmission Docker 的 9091端口可以直接开放到公网吗？

不建议直接暴露。9091是 Web/RPC 管理入口，应优先限制局域网访问；确需远程管理时，使用 HTTPS 反向代理、强密码、IP或主机名白名单，并根据当前配置排查 RPC 的 Host 校验。

相关阅读

参考资料

  1. LinuxServer Transmission Docker 镜像与 Compose 参数
  2. Transmission RPC 规范与端口测试说明
  3. Transmission Web Interface 官方文档
  4. Transmission 官方端口转发指南
  5. Docker Compose volumes 官方文档
  6. hub.docker.com