Transmission Docker 安装手册

Transmission 是一款轻量、跨平台的 BitTorrent 客户端，自带 Web UI，资源占用低，适合跑在 NAS / 服务器 / 软路由上做 7×24 下载。 本手册基于官方 lscr.io/linuxserver/transmission 镜像（LinuxServer.io 维护，支持 x86/ARM64），覆盖：Docker 部署、权限配置、Web UI 访问、路径映射、用户安全、区块加密、反代 HTTPS、备份迁移、排错，以及 Transmission vs qBittorrent 选型。

---

目录

• 一、核心概念
• 二、架构与组件
• 三、环境准备
• 四、Docker 部署
  • 4.1 目录规划
  • 4.2 docker-compose.yml（推荐）
  • 4.3 docker run 方式
  • 4.4 启动与验证
• 五、Web UI 访问与配置
  • 5.1 登录认证
  • 5.2 关键设置
  • 5.3 中文界面
• 六、路径与权限（重点）
  • 6.1 卷映射说明
  • 6.2 PUID / PGID
  • 6.3 权限排错
• 七、用户与安全管理
  • 7.1 RPC 认证
  • 7.2 白名单
  • 7.3 区块加密（防运营商检测）
• 八、HTTPS 反代（NPM / Nginx）
• 九、进阶用法
  • 9.1 自定义设置文件
  • 9.2 脚本钩子（完成/种子停止）
  • 9.3 限速与调度
• 十、备份与迁移
• 十一、更新升级
• 十二、常见问题排查
• 附 A：完整 docker-compose.yml
• 附 B：Transmission vs qBittorrent

---

一、核心概念

概念	说明
Transmission	守护进程 transmission-daemon + Web UI + CLI 客户端的统称
transmission-daemon	后台服务，常驻运行，管理所有种子任务
Web UI	默认端口 9091，浏览器即可管理（官方原生 + 第三方主题）
RPC	Web UI / 远程客户端与 daemon 通信的接口，认证即保护此接口
Watchdir	监视目录，放入 .torrent 文件自动添加任务
Blocklist	黑名单（常用于屏蔽 BT 监控/爬取客户端），官方支持自动更新
Encryption	协议加密，防运营商 DPI 识别 BT 流量

💡 Transmission 设计哲学：一个 daemon + 多个前端。Docker 容器内跑 daemon，你在任意设备的浏览器/App 里连同一个 Web UI 即可。

---

二、架构与组件

浏览器 / App
    │  HTTP(S) :9091
    ▼
┌─────────────────────────────┐
│  Nginx Proxy Manager (可选)  │  ← 终结 TLS、鉴权、域名访问
└────────────┬────────────────┘
             │  HTTP :9091
             ▼
┌─────────────────────────────┐
│  transmission 容器           │
│  ┌───────────────────────┐  │
│  │ transmission-daemon   │  │  ← 下载引擎
│  │  + Web UI (:9091)     │  │
│  └───────────────────────┘  │
│  /config  /downloads        │  ← 卷映射
└────────────┬────────────────┘
             │
             ▼
        宿主机磁盘（完成目录、做种目录）

端口说明：

• 9091/tcp：Web UI / RPC（必映射）
• 51413/tcp + 51413/udp：BitTorrent 数据传输（建议映射，否则仅靠 DHT 速度慢）

---

三、环境准备

• Docker 20.10+ / Docker Compose v2+
• Linux 主机（Ubuntu/Debian/NAS 均可），或 macOS/Windows（WSL2）
• 目录规划（见 4.1）
• 确认 UID/GID（用于权限对齐，见 6.2）

# 查看当前用户的 uid/gid
id $USER
# 输出示例：uid=1000(myuser) gid=1000(myuser)

---

四、Docker 部署

4.1 目录规划

推荐结构（下载目录与配置分离，便于备份与权限管理）：

/srv/transmission/          # 或 /opt/transmission/
├── config/                 # 配置、session、blocklist、resume 数据
├── downloads/              # 下载完成目录（可读写权限宽松）
│   ├── complete/           # 完成
│   ├── incomplete/         # 未完成（可选，配合 settings.json）
│   └── watch/              # 监视目录（放入 .torrent 自动添加）
└── docker-compose.yml

创建目录并设置权限（关键，见第六章）：

sudo mkdir -p /srv/transmission/{config,downloads/complete,downloads/incomplete,downloads/watch}
sudo chown -R 1000:1000 /srv/transmission
sudo chmod -R 755 /srv/transmission

4.2 docker-compose.yml（推荐）

version: "3.8"

services:
  transmission:
    image: linuxserver/transmission:4.1.3
    container_name: transmission
    restart: unless-stopped
    environment:
      - PUID=1000                  # ← 改成你的 uid
      - PGID=1000                  # ← 改成你的 gid
      - TZ=Asia/Shanghai
      # Web UI / RPC 认证（强烈建议设置）
      - TRANSMISSION_WEB_HOME=/transmission-web/   # 可选：第三方 UI 主题
      # 以下为初始化默认值；改密码/白名单推荐改 settings.json（见 5.2/7.x）
    ports:
      - "9091:9091"                # Web UI / RPC
      - "51413:51413"              # TCP 数据传输
      - "51413:51413/udp"          # UDP 数据传输
    volumes:
      - ./config:/config           # 配置与状态
      - ./downloads:/downloads    # 下载目录
    # 可选：加入已有网络，配合 NPM 反代
    # networks:
    #   - proxy

# networks:
#   proxy:
#     external: true

⚠️ LinuxServer 镜像通过 PUID/PGID 以普通用户运行（区别于前面 NPM 的 root 问题），权限对齐是关键。

4.3 docker run 方式

docker run -d \
  --name transmission \
  --restart unless-stopped \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -p 9091:9091 \
  -p 51413:51413 \
  -p 51413:51413/udp \
  -v /srv/transmission/config:/config \
  -v /srv/transmission/downloads:/downloads \
  lscr.io/linuxserver/transmission:latest

4.4 启动与验证

cd /srv/transmission
docker compose up -d
docker compose logs -f transmission

健康检查：

# 1. 容器状态
docker ps | grep transmission

# 2. 端口监听
ss -tlnp | grep 9091

# 3. Web UI 响应
curl -I http://127.0.0.1:9091
# 应返回 HTTP/1.1 401 Unauthorized（有认证=正常）或 200 + 登录页

# 4. RPC 接口测试（需认证）
curl -u 'transmission:your_password' \
  http://127.0.0.1:9091/transmission/rpc

浏览器打开 http://服务器IP:9091 → 出现登录框即成功。

---

五、Web UI 访问与配置

5.1 登录认证

Transmission 的 Web UI 使用 RPC 认证：

• 默认用户名：transmission
• 默认密码：transmission（旧版为空）
• 首次登录后务必改密码（见 5.2 或 7.1）

💡 LinuxServer 镜像首次启动时若未设 TRANSMISSION_RPC_* 环境变量，会自动生成随机密码并写入日志：

docker compose logs transmission | grep -i password

5.2 关键设置

登录后点左下角**「设置」（齿轮图标）**，重点配置：

下载（Downloading）

项	建议
下载目录	/downloads/complete
未完成目录	/downloads/incomplete（勾选「保持未完成文件」）
种子文件位置	/downloads/watch（勾选「自动添加」）

隐私（Privacy）

项	建议
加密	必选（Require encrypted / 强制加密，防运营商 DPI）
PEX / DHT / LPD	保持开启（增强可连接性）

对等（Peers）

项	建议
全局最大连接数	200~500
每种子最大连接	50~100
阻塞列表	启用 + 填入 URL（见 7.3）

速度（Speed）

• 按你的带宽设置上限，或开启「按时限速」避开高峰

远程访问（Remote）

• 见第七章：认证、白名单

5.3 中文界面

Transmission 官方 Web UI 无内置中文（类似 NPM 的情况），方案：

1. 浏览器翻译：Chrome/Edge 右键 → 翻译成中文（最快）
2. 第三方主题（推荐）：transmission-web-control 中文增强 UI

   environment:
     - TRANSMISSION_WEB_HOME=/transmission-web/   # 挂载到 /config/transmission-web
   volumes:
     - ./transmission-web:/config/transmission-web   # 放入第三方 UI 静态文件
   

   或使用集成了中文 UI 的镜像（社区维护）。

---

六、路径与权限（重点）

这是 Transmission Docker 部署最容易踩坑的部分，务必理解。

6.1 卷映射说明

容器内路径	宿主机路径	说明
/config	./config	settings.json、session、blocklist、resume
/downloads	./downloads	下载根目录（完成/未完成/watch）

LinuxServer 镜像内 daemon 运行用户为 PUID:PGID（默认 1000:1000），它必须对 /config 和 /downloads 有读写权。

6.2 PUID / PGID

让容器内用户对齐宿主机文件属主，避免权限错乱：

# 宿主机查看目标 uid/gid（推荐用专门账号，如 media）
id media
# uid=1001(media) gid=1001(media)

# 则 compose 中：
environment:
  - PUID=1001
  - PGID=1001

注意：若下载目录被其他容器（如 Sonarr/Radarr/Jellyfin）共享，需保证所有容器用同一 PUID:PGID，否则互相无法读写。

6.3 权限排错

症状：日志报 Permission denied / 种子状态卡「找不到文件」/ 无法写入。

诊断：

# 容器内测试写盘
docker compose exec transmission sh -c 'touch /downloads/test && echo OK && rm /downloads/test'
docker compose exec transmission sh -c 'touch /config/test && echo OK && rm /config/test'

修复：

# 1. 宿主机修正归属（PUID:PGID 对应的值）
sudo chown -R 1000:1000 /srv/transmission
sudo chmod -R 755 /srv/transmission/downloads
sudo chmod -R 700 /srv/transmission/config   # 配置含认证信息，收紧

# 2. 若使用 ACL（如共享给 media 组）
sudo setfacl -R -m g:media:rwX /srv/transmission/downloads

# 3. 重启
docker compose restart transmission

⚠️ 不要把 /downloads 挂到 SMB/NFS 等远程文件系统且不配好权限，否则容器内写入会失败。本地 ext4/xfs 最稳。

---

七、用户与安全管理

7.1 RPC 认证

强烈建议不要无密码暴露 9091 端口。改密码两种方式：

方式 A：环境变量（首次启动生效）

environment:
  - TRANSMISSION_RPC_USERNAME=myuser
  - TRANSMISSION_RPC_PASSWORD=MySecurePass!
  - TRANSMISSION_RPC_AUTHENTICATION_REQUIRED=true
  - TRANSMISSION_RPC_HOST_WHITELIST=127.0.0.1,192.168.9.*

方式 B：直接编辑 settings.json（推荐，灵活）

# 先停容器再改，避免运行时被覆盖
docker compose stop transmission
nano /srv/transmission/config/settings.json

关键字段：

{
  "rpc-authentication-required": true,
  "rpc-username": "myuser",
  "rpc-password": "{a69f734b06e...}",      // 明文密码会被自动哈希
  "rpc-host-whitelist": "127.0.0.1,192.168.9.*",
  "rpc-whitelist-enabled": true,
  "rpc-port": 9091,
  "rpc-bind-address": "0.0.0.0"
}

改完启动：docker compose start transmission。

7.2 白名单

• rpc-whitelist：限制可访问 RPC 的 IP（如 127.0.0.1,192.168.9.*）
• 若经 NPM 反代，需把反代 IP 加入白名单，或设 rpc-whitelist-enabled: false（此时依赖反代鉴权保护）

7.3 区块加密（防运营商检测）

Encryption（协议加密） —— 在 Web UI「隐私」设置：

• Encryption mode = Require encrypted（强制，拒绝未加密连接）

Blocklist（IP 黑名单） —— 屏蔽 BT 监控客户端：

• Web UI 勾选「启用阻塞列表」，填入 URL：
  • https://github.com/Naunter/BT-Blacklist/raw/main/blocklist.txt
  • 或 https://api.fightbattles.online/blocklist（社区维护）
• 支持自动更新，设置更新周期即可。

📌 配合 VPN / WireGuard 使用可进一步规避运营商限速，属进阶方案。

---

八、HTTPS 反代（NPM / Nginx）

结合你前面搭建的 Nginx Proxy Manager，把 transmission.example.com 代理到 :9091，统一 HTTPS + 鉴权。

NPM 配置（Proxy Host）：

• Domain：transmission.example.com
• Scheme：http
• Forward Host：192.168.9.99（宿主机 IP，因 Transmission 用 host/bridge 网络）
• Forward Port：9091
• SSL：Request Cert → Force SSL
• Advanced（自定义 Nginx，支持 WebSocket + RPC）：

  location / {
      proxy_pass http://192.168.9.99:9091;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      # RPC 长轮询
      proxy_read_timeout 300;
      proxy_send_timeout 300;
  }
  

直接 Nginx 配置示例：

server {
    listen 443 ssl http2;
    server_name transmission.example.com;
    ssl_certificate     /path/fullchain.pem;
    ssl_certificate_key /path/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:9091;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 300;
    }
}

💡 Transmission RPC 用长轮询 + 普通 HTTP，反代无需特殊 WebSocket 配置；若用第三方 UI 有实时通知则按上补 Upgrade 头。

---

九、进阶用法

9.1 自定义设置文件

/config/settings.json 是核心配置，修改前务必停容器：

常用字段速查：

{
  "download-dir": "/downloads/complete",
  "incomplete-dir": "/downloads/incomplete",
  "incomplete-dir-enabled": true,
  "watch-dir": "/downloads/watch",
  "watch-dir-enabled": true,
  "cache-size-mb": 64,
  "encryption": 2,                  // 0=允许 1=优先 2=强制
  "blocklist-enabled": true,
  "blocklist-url": "https://.../blocklist.txt",
  "speed-limit-up": 100,            // KB/s
  "speed-limit-down": 5000,
  "alt-speed-enabled": true,         // 按时限速
  "seedRatioLimit": 2.0,
  "seedRatioLimited": true
}

9.2 脚本钩子（完成 / 种子停止）

Transmission 支持 脚本触发（种子下载完成 / 做种停止时执行），适合自动化整理：

在 settings.json 中配置：

{
  "script-torrent-done-enabled": true,
  "script-torrent-done-filename": "/config/scripts/on-complete.sh",
  "script-torrent-stopped-enabled": true,
  "script-torrent-stopped-filename": "/config/scripts/on-stopped.sh"
}

示例 on-complete.sh（自动移动到分类目录）：

#!/bin/sh
# TRANSMISSION 会注入环境变量：TR_TORRENT_NAME, TR_TORRENT_DIR 等
echo "[$(date)] Done: $TR_TORRENT_NAME" >> /config/scripts/done.log
# 例如：mv "$TR_TORRENT_DIR/$TR_TORRENT_NAME" /downloads/complete/movies/

挂载脚本目录并赋予执行权限：

volumes:
  - ./scripts:/config/scripts

chmod +x /srv/transmission/scripts/*.sh

9.3 限速与调度

Web UI「速度」→「按时限速」：

• 设置时段（如 08:00–23:00 低速，夜间全速）
• 配合 alt-speed-down/up 两套速率

也可通过 transmission-remote CLI 动态调整（做进 cron）：

transmission-remote http://127.0.0.1:9091 --auth myuser:mypass \
  --alt-speed

---

十、备份与迁移

需备份的核心数据：

• /config/settings.json —— 全部配置
• /config/resume/ + /config/torrents/ —— 种子状态、做种进度（迁移后无缝续种的关键）
• /config/blocklists/ —— 黑名单
• /downloads/ —— 已下载文件（体积大，可按需）

备份脚本（cron 每日）：

#!/bin/bash
DEST=/srv/backups/transmission-$(date +%F)
mkdir -p $DEST
docker compose -f /srv/transmission/docker-compose.yml stop transmission
cp -a /srv/transmission/config $DEST/
# 下载文件可选增量备份
# rsync -a /srv/transmission/downloads $DEST/
docker compose -f /srv/transmission/docker-compose.yml start transmission

迁移到新机：

1. 新机跑起同样的 compose（PUID:PGID 一致）
2. 停容器 → 拷贝 config/ 覆盖 → 启动
3. Transmission 会自动校验已有文件并继续做种，无需重新下载

---

十一、更新升级

cd /srv/transmission
docker compose pull          # 拉最新镜像
docker compose up -d         # 重建容器
docker compose logs -f       # 观察启动

注意事项：

• LinuxServer 镜像自动处理权限（PUID/PGID），升级一般不会丢配置
• 大版本升级前备份 config/
• 固定版本可用 tag（如 :4.0.6）而非 latest 便于回滚

---

十二、常见问题排查

问题	原因 / 解决
页面打不开 :9091	容器未启动 / 端口冲突；docker ps + ss -tlnp | grep 9091
401 Unauthorized 但忘记密码	编辑 settings.json 删 rpc-password 字段并重启，恢复默认
种子无速度 / 连不上 peers	51413 端口未映射；docker ps 检查；或运营商封锁，启加密 + VPN
下载报 Permission denied	权限问题，见第六章；chown -R PUID:PGID
种子状态「找不到文件」	/downloads 映射不一致或路径被改；核对 settings.json 路径
迁移后全部重新下载	未备份 resume/ + torrents/；按第十章操作可续种
CPU/IO 高	cache-size-mb 调小 / 限速并发连接数
反代后登录失败	RPC 白名单未含反代 IP；设 rpc-whitelist-enabled: false 或加 IP
Blocklist 不更新	URL 失效 / 容器内无外网；手动下载测试 curl
日志狂刷错误	docker compose logs --tail=100 定位；多半是权限或配置 JSON 语法

日志位置：

# 容器日志
docker compose logs -f transmission

# daemon 日志（若启用）
tail -f /srv/transmission/config/transmission-daemon.log

---

附 A：完整 docker-compose.yml

可直接复制使用（先改 PUID/PGID 与密码）：

version: "3.8"

services:
  transmission:
    image: lscr.io/linuxserver/transmission:latest
    container_name: transmission
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - TRANSMISSION_RPC_USERNAME=myuser
      - TRANSMISSION_RPC_PASSWORD=MySecurePass!
      - TRANSMISSION_RPC_AUTHENTICATION_REQUIRED=true
      - TRANSMISSION_WEB_HOME=/transmission-web/
    ports:
      - "9091:9091"
      - "51413:51413"
      - "51413:51413/udp"
    volumes:
      - ./config:/config
      - ./downloads:/downloads
      - ./scripts:/config/scripts
    # networks:
    #   - proxy

# networks:
#   proxy:
#     external: true

---

附 B：Transmission vs qBittorrent

对比项	Transmission	qBittorrent
资源占用	⭐ 极低（C 编写）	低-中（C++/Qt）
Web UI	简洁、原生、移动端友好	功能全、可分类/标签/搜索
中文 UI	❌ 需第三方 / 浏览器翻译	✅ 官方内置中文
搜索插件	❌	✅ 内置搜索（需安装 python 插件）
分类/标签	基础	强大
限速/调度	支持	支持更细
脚本钩子	✅	✅
区块加密	✅	✅
第三方主题	✅ transmission-web-control	有限
Docker 镜像	LinuxServer（成熟）	LinuxServer（成熟）
适合	轻量、NAS、7×24、低配设备、追求稳定	功能全面、分类管理、中文偏好

结论：

• 要轻量稳定、低配 NAS / 软路由 → Transmission ✅
• 要中文 + 搜索 + 分类 + 标签 → qBittorrent
• 两者可共存（不同端口），按需选用

---

参考资源

• 官方：https://transmissionbt.com/
• GitHub：https://github.com/transmission/transmission
• LinuxServer 镜像：https://docs.linuxserver.io/images/docker-transmission/
• Docker Hub：https://hub.docker.com/r/linuxserver/transmission
• 第三方 Web UI（中文）：https://github.com/ronggang/transmission-web-control

---

更新于 2026-09-13 · 适用 Transmission 4.x / LinuxServer 镜像 latest