Transmission 4.1.4 Docker Compose 部署指南

目标：在装有 Docker 的服务器上以 Docker Compose 部署 Transmission 4.1.4 下载服务，覆盖镜像选型、三目录数据持久化、启动验证、RPC 认证开启与日常运维命令。已在 Ubuntu 24.04 LTS（x86_64）+ Docker 29.9.2 + Docker Compose v5.6.1 环境实测通过（2026-11-01），部署形态为 transmission-daemon + 内置 Web UI + transmission-remote 命令行管理。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• Docker：29.9.2（docker --version）
• Docker Compose：v5.6.1（docker compose version）
• 软件版本：Transmission 4.1.4（当前最新稳定版，2026-11-01 核对 GitHub Releases）
• 容器镜像：linuxserver/transmission（Linuxserver.io 构建版本 4.1.4-r0-ls367，构建日期 2026-10-30）
• 服务器 IP：192.168.146.128（示例环境实际地址，下同）
• 端口规划：宿主机 8142 → 服务 Web/RPC 端口 9091；宿主机 51413（TCP+UDP）→ peer 传入连接端口 51413
• 数据目录：/opt/transmission/（compose 文件与数据目录同置，下分 config / downloads / watch 三个子目录）

二、镜像选型说明

Transmission 官方发行物是源码与各平台桌面客户端，未发布官方容器镜像，服务器容器化部署通常选用社区维护的构建。本文采用 Linuxserver.io（LSIO）团队维护的 linuxserver/transmission 镜像，理由如下：

1. 更新跟随上游：本文实测镜像内部版本 4.1.4-r0-ls367（构建日期 2026-10-30），与 Transmission 官方最新稳定版 4.1.4（2026-10-24 发布）同步；
2. 环境变量标准化：PUID/PGID/TZ 三件套解决容器内进程与宿主机目录的属主与时区一致性问题；
3. 目录约定清晰：/config（配置与状态）、/downloads（下载与做种数据）、/watch（种子监视目录）三个挂载点覆盖全部持久化需求；
4. 内置全套命令行工具：transmission-daemon、transmission-remote、transmission-create、transmission-show、transmission-edit 五件套齐备。

⚠️ 网络说明：2026-11-01 实测本网络环境直接从 Docker Hub（docker.io）拉取该镜像速度极慢、长时间无进度。已改用国内中转源 docker.m.daocloud.io，实测可正常拉取（回显见部署步骤）。若服务器网络不受限，可将镜像地址写回 lscr.io/linuxserver/transmission:latest 或 linuxserver/transmission:latest 原样使用。

💡 技术拓展：BT 客户端的容器镜像除 LSIO 构建外，常见还有官方源码自建镜像、Hotio 构建与各 NAS 系统应用市场套件。选型时关注三点：内部版本跟随上游的速度、是否暴露标准化 PUID/PGID/TZ 环境变量、是否内置全套 CLI 工具。本文实测采用 LSIO 构建，三者均满足且社区文档最全。

三、前置条件

1. 服务器已安装 Docker 与 Docker Compose 插件；
2. 端口 8142、51413（TCP 与 UDP）未被占用且防火墙放行（51413 UDP 是 DHT/STUN 类流量必需，TCP 是 peer 连接必需，两者都要放行）；
3. 服务器可访问容器镜像仓库（拉取镜像）。

验证 Docker 环境：

docker --version
docker compose version

实测回显：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

四、部署步骤

4.1 创建目录结构

mkdir -p /opt/transmission/{config,downloads,watch} && cd /opt/transmission

三个目录的职责分工：

• config/：daemon 的配置与运行状态（settings.json、resume 断点文件、种子元数据缓存、统计文件等），必须持久化；
• downloads/：下载完成与做种数据（内含 complete / incomplete 子目录，由 daemon 自动创建）；
• watch/：监视目录，把 .torrent 文件放进这里会被自动添加为下载任务（daemon 处理后改名为 .torrent.added）。

4.2 编写 docker-compose.yml

在 /opt/transmission/ 下创建 docker-compose.yml：

name: transmission-4.1.4-stack
services:
  transmission:
    image: docker.m.daocloud.io/linuxserver/transmission:latest
    container_name: transmission-4.1.4-app
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - /opt/transmission/config:/config
      - /opt/transmission/downloads:/downloads
      - /opt/transmission/watch:/watch
    ports:
      - "8142:9091"
      - "51413:51413"
      - "51413:51413/udp"
    restart: unless-stopped

配置项说明：

• name：Compose 项目名，固定为 transmission-4.1.4-stack，避免与服务器上其他 Compose 项目互相干扰；
• image：LSIO 构建的 Transmission 镜像，经国内中转源 docker.m.daocloud.io 拉取（网络受限环境的实测可用渠道，见第二章 ⚠️ 说明）；
• PUID=1000/PGID=1000：容器内 transmission-daemon 以宿主机 UID/GID 1000 的身份读写挂载目录，避免下载文件属主错乱；用 id 命令查询实际用户后按需修改；
• TZ=Asia/Shanghai：容器内时区，影响日志与 Web 界面时间显示；
• volumes 三个挂载：配置、数据、监视目录与宿主机一一对应，重建服务不丢数据；
• ports 三个映射：8142 是 Web 界面与 RPC 端口（内部 9091）；51413 同时映射 TCP 与 UDP，是 BT peer 传入连接端口，缺 UDP 会影响 DHT 发现；
• restart: unless-stopped：宿主机重启或进程崩溃后自动拉起（手工停止的不自动重启）。

4.3 拉取镜像并启动

cd /opt/transmission
docker compose pull
docker compose up -d

实测回显（首次部署时 pull 有逐层下载进度，此处为镜像已在本机缓存时的快速回显）：

 Image docker.m.daocloud.io/linuxserver/transmission:latest Pulling
 Image docker.m.daocloud.io/linuxserver/transmission:latest Pulled

 Container transmission-4.1.4-app Creating
 Container transmission-4.1.4-app Created
 Container transmission-4.1.4-app Starting
 Container transmission-4.1.4-app Started

4.4 查看启动日志确认版本

docker compose logs transmission | head -30

实测回显（节选首尾）：

[migrations] started
[migrations] no migrations found
───────────────────────────────────────
      ██╗     ███████╗██╗ ██████╗
      ██║     ███████╗██║██╔═══██╗
      ██║     ███████╗██║██║   ██║
      ██║     ╚════██║██║██║   ██║
      ███████╗███████║██║╚██████╔╝
      ╚══════╝╚══════╝╚═╝ ╚═════╝
   Brought to you by linuxserver.io
───────────────────────────────────────
GID/UID
───────────────────────────────────────
User UID:    1000
User GID:    1000
───────────────────────────────────────
Linuxserver.io version: 4.1.4-r0-ls367
Build-date: 2026-10-30T01:38:25+00:00
───────────────────────────────────────

日志确认三件事：PUID/PGID 生效值（1000/1000）、镜像内部版本（4.1.4-r0-ls367）、无报错行。

4.5 验证服务可用

确认服务进程状态与端口监听：

docker compose ps

实测回显：

NAME                     STATUS                  PORTS
transmission-4.1.4-app   Up 5 seconds            0.0.0.0:51413->51413/tcp, 0.0.0.0:51413->51413/udp, [::]:51413->51413/tcp, [::]:51413->51413/udp, 0.0.0.0:8142->9091/tcp, [::]:8142:9091/tcp

验证 Web 界面（HTTP 301 是 daemon 把 /transmission/ 重定向到 /transmission/web/，属正常行为）：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8142/transmission/
curl -s http://localhost:8142/transmission/web/ | head -3

实测回显：

301

<!doctype html>
<html lang="en" xml:lang="en">
  <head>

浏览器访问 http://192.168.146.128:8142/transmission/web/ 即可打开 Transmission Web 界面。默认 RPC 未启用认证（局域网环境可直接使用），生产或公网环境请按 4.6 节开启认证后再对外。

4.6 开启 RPC 认证（建议步骤）

默认配置无认证，任何能连到 8142 端口的主机都可以操作下载任务。开启用户名密码认证的步骤（示例账号 admin / q1w2e3r4）：

1. 先停止服务（daemon 运行中修改 settings.json 会被其内存配置覆盖，这是 Transmission 的管理特性，详见本专栏配置篇）：

docker compose down

2. 编辑 /opt/transmission/config/settings.json 中三个 RPC 键：

"rpc-authentication-required": true,
"rpc-username": "admin",
"rpc-password": "q1w2e3r4",

3. 重新启动并验证：

docker compose up -d

启动后 daemon 首次读到明文密码会自动将其替换为哈希串（{ 开头的长字符串），这是正常现象，认证仍按原明文密码工作。验证认证已生效——不带凭据应被 401 拒绝、带凭据正常：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8142/transmission/web/
curl -s -o /dev/null -w '%{http_code}\n' -u admin:q1w2e3r4 http://localhost:8142/transmission/web/

实测回显：

401
200

此后浏览器访问 Web 界面会弹出认证框，命令行工具用 -n admin:q1w2e3r4 携带凭据（详见本专栏 CLI 命令篇）。

五、数据持久化说明

部署形态把全部状态落在宿主机 /opt/transmission/ 下，重建服务不丢失任何数据。验证方式：down 后重新 up，任务列表与配置应原样恢复。

docker compose down && docker compose up -d

实测回显（重建后配置与任务均保留，下载目录中文件原样存在）：

 Container transmission-4.1.4-app Removing
 Container transmission-4.1.4-app Removed
 Network transmission-4.1.4-stack_default Removing
 Network transmission-4.1.4-stack_default Removed
 Container transmission-4.1.4-app Creating
 Container transmission-4.1.4-app Created
 Container transmission-4.1.4-app Starting
 Container transmission-4.1.4-app Started

ls /opt/transmission/config/ /opt/transmission/downloads/

实测回显（daemon 首次启动后自动生成的状态文件，节选）：

/opt/transmission/config/:
bandwidth-groups.json  blocklists  dht.dat  lock  queue.json  resume  settings.json  stats.json  torrents

/opt/transmission/downloads/:
complete

各文件职责：

六、环境变量表

LSIO 构建的全部配置落在挂载的 settings.json 中，镜像不再提供 TRANSMISSION_* 形式的配置环境变量（旧版镜像曾有，现已弃用），调参统一走配置文件或 RPC。

七、配置参数说明与配置文件挂载

容器的全部行为配置集中在 /opt/transmission/config/settings.json（挂载自宿主机 /opt/transmission/config/settings.json），首次启动时由镜像以默认值生成。关键键与容器形态的对应关系：

完整的全参数逐项解释、修改生效机制（daemon 运行中会覆盖手改的配置文件）与生产配置模板，见本专栏 《Transmission 4.1.4 配置参数详解》。

八、等价 docker run

与上述 docker-compose.yml 等价的单命令形态（临时验证用，长期运行建议仍用 Compose 管理数据目录与项目名）：

docker run -d \
  --name transmission-4.1.4-app \
  -p 8142:9091 \
  -p 51413:51413 \
  -p 51413:51413/udp \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -v /opt/transmission/config:/config \
  -v /opt/transmission/downloads:/downloads \
  -v /opt/transmission/watch:/watch \
  --restart unless-stopped \
  docker.m.daocloud.io/linuxserver/transmission:latest

与 compose 版的差异：缺少项目名隔离（compose 的 name: 让 down 操作精确作用于本项目），网络挂在默认 bridge 而非独立网络；参数含义与 compose 版一一对应。

九、常用运维命令

# 查看服务状态与端口映射
docker compose ps

# 查看实时日志（排障第一入口）
docker compose logs -f transmission

# 重启服务（配置改动后生效的标准姿势之一）
docker compose restart transmission

# 停止并移除服务（数据目录保留）
docker compose down

# 升级镜像：拉取新版后重建
docker compose pull && docker compose up -d

升级实测（拉取新版镜像并滚动重建，数据与配置因挂载而保留）：

cd /opt/transmission
docker compose pull
docker compose up -d

实测回显：

 Image docker.m.daocloud.io/linuxserver/transmission:latest Pulling
 Image docker.m.daocloud.io/linuxserver/transmission:latest Pulled
 Container transmission-4.1.4-app Running

💡 说明：latest 标签滚动更新，升级前建议备份 /opt/transmission/config/ 目录；升级后用 docker compose logs transmission | grep version 核对新版本号。

十、常见问题

Q1：镜像拉取极慢或超时怎么办？

Docker Hub 直连慢是 2026-11-01 实测遇到的实际情况。解法是换国内中转源：把 compose 里镜像地址写成 docker.m.daocloud.io/linuxserver/transmission:latest（本文采用的形态）。也可给 Docker 守护进程配置 HTTP 代理后使用原始镜像地址。

Q2：下载的文件属主是别的用户，或容器内写入报权限错误？

容器内进程按 PUID/PGID 身份写文件。执行 id（或 id <目标用户>）确认宿主机用户的 UID/GID，把 compose 里 PUID/PGID 改成对应值后 docker compose up -d 重建。已错乱的历史文件用 chown -R 1000:1000 /opt/transmission/downloads 修正。

Q3：Web 界面打不开（连接被拒）？

依次排查：docker compose ps 确认容器 Up；curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8142/transmission/ 在服务器本机验证（正常 301）；本机通而远程不通则是防火墙/安全组未放行 8142。

Q4：Web 界面提示 401 或反复要求登录？

4.6 节开启了 RPC 认证，登录用 settings.json 里 rpc-username 与设置时的明文密码。settings.json 中的 rpc-password 是哈希串，属正常现象；忘记密码时停服务、把 rpc-password 改回明文新密码、rpc-username 保留，重启后 daemon 会重新哈希。

Q5：改了 settings.json 不生效，或改完被改回去？

daemon 运行中会以内存配置覆盖 settings.json（含退出过程）。标准流程：docker compose down → 确认容器已退出 → 编辑配置文件 → docker compose up -d。运行中的临时调参改用 RPC 工具（transmission-remote），见本专栏 CLI 命令篇。

Q6：端口测试显示 Port is open: No？

Web 界面或 RPC 的端口连通性测试依赖外部测试源主动回连 51413 端口。服务器在内网/NAT 后且未做端口映射时该测试必然失败，属环境限制而非服务故障；确认 compose 已同时映射 51413 的 TCP 与 UDP、防火墙已放行即可。

十一、参考链接

• 《Transmission 4.1.4 介绍与选型指南》：版本现状与同类客户端选型对比
• 《Transmission 4.1.4 配置参数详解》：settings.json 全参数与生效机制
• 《Transmission 4.1.4 常用 CLI 命令与工具详解》：transmission-remote 等五件套命令实测
• LSIO 镜像说明：https://hub.docker.com/r/linuxserver/transmission
• Transmission 官方站点：https://transmissionbt.com/
• GitHub 仓库：https://github.com/transmission/transmission