Docker 开源工具

Transmission Docker 容器化部署指南

Transmission 是由LinuxServer.io团队提供的容器化应用，基于Transmission BitTorrent客户端构建。Transmission设计理念为简单易用且功能强大，具备BitTorrent客户端所需的核心特性：加密传输、Web管理界面、节点交换、磁力链接支持、DHT网络、µTP协议、UPnP与NAT-PMP端口转发、WebSeed支持、监控目录、Tracker编辑、全局及每种子速度限制等。

概述

Transmission 是由 LinuxServer.io 团队提供的容器化应用，基于 Transmission BitTorrent 客户端构建。Transmission 设计理念为简单易用且功能强大，具备 BitTorrent 客户端所需的核心特性：加密传输、Web 管理界面、节点交换、磁力链接支持、DHT 网络、µTP 协议、UPnP 与 NAT-PMP 端口转发、WebSeed 支持、监控目录、Tracker 编辑、全局及每种子速度限制等。

LinuxServer.io 提供的 Transmission 容器具有以下特点：

  • 定期且及时的应用更新
  • 简单的用户权限映射（PGID/PUID）
  • 基于 s6 overlay 的自定义基础镜像
  • 每周基础操作系统更新，通过跨生态系统的通用层减少空间占用、downtime 和带宽消耗
  • 定期安全更新

本文档将详细介绍如何通过 Docker 容器化方式部署 Transmission，包括环境准备、镜像拉取、容器配置、功能测试及生产环境优化建议。

环境准备

Docker 环境安装

部署 Transmission 容器前，需先确保服务器已安装 Docker 环境。推荐使用以下一键安装脚本快速部署 Docker 及相关组件：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

脚本将自动完成 Docker Engine、Docker Compose 等组件的安装与配置，并启动 Docker 服务。安装完成后，可通过 docker --version 命令验证安装是否成功。

镜像准备

拉取 Transmission 镜像

使用以下命令通过轩辕镜像加速地址拉取最新版本的 TRANSMISSION 镜像：

docker pull xxx.xuanyuan.run/linuxserver/transmission:latest

如需指定其他版本，可访问 Transmission 镜像标签列表 查看所有可用标签，并将命令中的 latest 替换为目标标签。

容器部署

基础部署命令

使用以下 docker run 命令部署 Transmission 容器，包含必要的端口映射、数据卷挂载和环境变量配置：

docker run -d \
  --name=transmission \
  -p 9091:9091 \
  -p 51413:51413 \
  -p 51413:51413/udp \
  -v /opt/transmission/config:/config \
  -v /opt/transmission/downloads:/downloads \
  -v /opt/transmission/watch:/watch \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -e USER=admin \
  -e PASS=your_secure_password \
  --restart unless-stopped \
  xxx.xuanyuan.run/linuxserver/transmission:latest

参数说明

参数说明
-d后台运行容器
--name=transmission指定容器名称为 transmission
-p 9091:9091映射 Web 管理界面端口
-p 51413:51413映射 BT 下载 TCP 端口
-p 51413:51413/udp映射 BT 下载 UDP 端口
-v /opt/transmission/config:/config挂载配置文件目录，持久化配置数据
-v /opt/transmission/downloads:/downloads挂载下载文件目录
-v /opt/transmission/watch:/watch挂载监控目录，自动加载新增的 torrent 文件
-e PUID=1000指定运行用户 ID（可通过 id your_username 命令获取）
-e PGID=1000指定运行用户组 ID（可通过 id your_username 命令获取）
-e TZ=Asia/Shanghai指定时区（如 Asia/Shanghai、Etc/UTC 等）
-e USER=adminWeb 界面登录用户名（可选，不设置则无需认证）
-e PASS=your_secure_passwordWeb 界面登录密码（可选，与 USER 同时设置生效）
--restart unless-stopped容器退出时自动重启（除非手动停止）

可选配置参数

根据实际需求，可添加以下可选环境变量：

-e WHITELIST=192.168.1.0/24,10.0.0.0/8 \  # IP 白名单，限制仅允许指定 IP 段访问 Web 界面
-e HOST_WHITELIST=example.com,*.domain.com \  # 主机白名单，限制仅允许指定域名访问 Web 界面
-e PEERPORT=51413 \  # 指定 BT 监听端口（需与端口映射保持一致）-e TRANSMISSION_WEB_HOME=/path/to/custom/ui \  # 指定自定义 Web 界面路径
--read-only=true \  # 以只读文件系统运行容器（需额外挂载临时目录）--user=1000:1000 \  # 以非 root 用户运行容器

功能测试

容器部署完成后，建议进行以下测试以验证功能正常：

1. 容器状态检查

检查容器是否正常运行：

docker ps | grep transmission

若状态显示为Up，表示容器启动成功。

2. Web 界面访问测试

通过浏览器访问 Transmission Web 管理界面：

http:// 服务器 IP:9091

若设置了用户名和密码，会提示输入凭据。登录成功后可看到 Transmission 的管理界面，包括当前下载任务、种子列表、设置等功能。

3. 日志查看

查看容器运行日志，确认无错误信息：

docker logs -f transmission

正常启动日志应包含类似以下内容：

[2024-05-20 10:00:00.000] Transmission 4.0.5 (bb6b5a062e) started (session.c:768)
[2024-05-20 10:00:00.000] RPC Server Adding address to whitelist: 127.0.0.1 (rpc-server.c:957)
[2024-05-20 10:00:00.000] RPC Server Serving RPC and Web requests on 0.0.0.0:9091/transmission/ (rpc-server.c:1323)
[2024-05-20 10:00:00.000] DHT Initializing DHT (tr-dht.c:272)
[2024-05-20 10:00:00.000] Using settings from "/config/settings.json" (settings.c:826)

4. 下载功能测试

在 Web 界面中添加一个测试 torrent 文件或磁力链接，检查是否能正常开始下载，下载完成后文件是否保存到 /downloads 目录。

生产环境建议

为确保 TRANSMISSION 在生产环境中稳定、安全运行，建议采取以下措施：

1. 数据持久化优化

  • 确保 /config、/downloads 和/watch目录挂载到主机持久化存储，避免容器删除后数据丢失
  • 对于大规模部署，考虑使用 NFS 或分布式存储作为下载目录，提高存储扩展性

2. 安全加固

  • 务必设置强密码（USER和 PASS 参数），避免未授权访问
  • 使用 WHITELIST 或HOST_WHITELIST限制仅允许信任的 IP/ 域名访问 Web 界面
  • 配置防火墙，仅开放必要端口（9091、51413），并限制端口访问来源
  • 定期更新镜像（docker pull xxx.xuanyuan.run/linuxserver/transmission:latest）以获取安全补丁
  • 避免使用默认 BT 端口（51413），可自定义端口减少被封锁风险

3. 资源限制

根据服务器配置和下载需求，为容器设置资源限制：

--memory=4g \  # 限制最大使用内存为 4GB
--memory-swap=4g \  # 限制内存 + 交换分区总使用量为 4GB
--cpus=2 \  # 限制 CPU 使用核心数为 2 核
--device-read-bps /dev/sda:100mb \  # 限制磁盘读取速度为 100MB/s
--device-write-bps /dev/sda:100mb \  # 限制磁盘写入速度为 100MB/s

4. 监控与日志

  • 使用 docker logs -f transmission 实时监控容器运行状态
  • 配置日志轮转，避免日志文件过大：docker run ... --log-opt max-size=10m --log-opt max-file=3 ...
  • 集成第三方监控工具（如 Prometheus + Grafana），通过 Transmission 的 RPC 接口收集下载速度、种子数量等指标

5. 自动更新

结合 Docker 镜像更新工具（如 Diun）实现镜像更新通知：

# docker-compose.yml 示例
version: "3"
services:
  diun:
    image: crazymax/diun:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./diun:/data
    environment:
      - DIUN_WATCH_WORKERS=20
      - DIUN_WATCH_SCHEDULE=0 */6 * * *
      - DIUN_PROVIDERS_DOCKER=true
      - DIUN_NOTIF_MAIL_HOST=smtp.example.com
      - DIUN_NOTIF_MAIL_PORT=587
      - DIUN_NOTIF_MAIL_USER=user@example.com
      - DIUN_NOTIF_MAIL_PASS=password
      - DIUN_NOTIF_MAIL_FROM=diun@example.com
      - DIUN_NOTIF_MAIL_TO=admin@example.com
    restart: unless-stopped

故障排查

1. 容器无法启动

  • 检查日志 ：使用docker logs transmission 查看错误信息，常见问题包括：
    • 权限问题：/config或 /downloads 目录权限不足，需确保主机目录所有者 ID 与 PUID 一致
    • 端口冲突：端口已被其他服务占用，使用 netstat -tulpn | grep 端口号 检查冲突进程
    • 配置文件损坏：删除 /config/settings.json 后重启容器，自动生成默认配置
  • 检查 Docker 状态：确保 Docker 服务正常运行：systemctl status docker

2. Web 界面无法访问

  • 检查端口映射 ：确认容器端口已正确映射到主机：docker port transmission 预期输出：9091/tcp -> 0.0.0.0:9091 51413/tcp -> 0.0.0.0:51413 51413/udp -> 0.0.0.0:51413
  • 检查防火墙规则：确保服务器防火墙允许端口访问：# 对于 ufw 防火墙 ufw allow 9091/tcp ufw allow 51413/tcp ufw allow 51413/udp # 对于 firewalld 防火墙 firewall-cmd --add-port=9091/tcp --permanent firewall-cmd --add-port=51413/tcp --permanent firewall-cmd --add-port=51413/udp --permanent firewall-cmd --reload
  • 检查白名单设置 ：若配置了WHITELIST 或HOST_WHITELIST，确认访问 IP/ 域名在白名单范围内

3. 下载速度慢或无法连接 peers

  • 检查端口转发：确认路由器已正确配置端口转发（UPnP/NAT-PMP），将 BT 端口（51413）转发到服务器 IP
  • 检查 tracker 状态：在 Web 界面 ” 种子 ”->”Tracker” 中查看 Tracker 连接状态，若显示 ” 无法连接 ” 可能是 Tracker 服务器故障或网络限制
  • 检查 DHT 网络 ：确保 DHT 功能已启用（默认启用），可在settings.json 中确认："dht-enabled": true, "utp-enabled": true
  • 检查防火墙策略：确保服务器出站连接不受限制，BT 下载需要连接多个外部节点

4. 容器以非 root 用户运行时权限问题

  • 确保主机挂载目录所有者 ID 与容器 PUID/PGID 一致：chown -R 1000:1000 /opt/transmission/config chown -R 1000:1000 /opt/transmission/downloads chown -R 1000:1000 /opt/transmission/watch
  • 使用 --user=1000:1000 参数时，确保该用户有足够权限访问挂载目录

参考资源

总结

本文详细介绍了 Transmission 的 Docker 容器化部署方案，包括环境准备、镜像拉取、容器配置、功能测试、生产环境优化及故障排查等内容。通过容器化部署，可快速搭建 Transmission BT 客户端，同时保证部署一致性、环境隔离性和运维便捷性。

关键要点：

  • 使用轩辕提供的一键脚本快速安装 Docker 环境，简化部署流程
  • 通过轩辕镜像加速地址拉取 Transmission 镜像，提高下载速度
  • 容器部署时需注意端口映射、数据卷挂载和用户权限配置，确保功能正常
  • 生产环境中应重视安全加固（如设置密码、IP 白名单）、资源限制和数据持久化
  • 故障排查以日志分析为核心，重点关注端口冲突、权限问题和网络连接

后续建议：

  • 深入学习 Transmission 高级特性，如自定义 Web 界面、自动更新 blockList、速度限制策略等
  • 根据实际业务需求调整容器资源配置，平衡下载性能与服务器负载
  • 探索 Transmission 的 RPC 接口，实现自动化任务管理（如通过脚本添加下载任务、监控下载进度）
  • 考虑使用 Docker Compose 或 Kubernetes 进行编排，简化多容器管理和扩展
  • 定期关注Transmission 镜像标签列表，及时更新镜像以获取新功能和安全修复
© 2022 - 2026 轩源的网络日志
使用 Hugo 构建
主题 Stack，作者 Jimmy