Transmission 4.1.4 配置参数详解

目标：逐项讲清 Transmission 4.1.4 守护进程配置文件 settings.json 的全部参数：默认值、含义、运行时修改方式与生效机制，并给出两档生产配置模板。已在 Ubuntu 24.04 LTS（x86_64）+ Transmission 4.1.4（守护进程形态，RPC 端口 9091）环境实测通过（2026-11-01），文中所有参数默认值取自 4.1.4 首次启动生成的原始配置文件。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• 软件版本：Transmission 4.1.4（transmission-remote --version 实测：transmission-remote 4.1.4 (a6d907d9ea)）
• 运行形态：transmission-daemon 守护进程 + 内置 Web UI + transmission-remote 命令行管理
• 配置文件：/etc/transmission-daemon/settings.json（apt 方式安装的默认路径；其余形态按实际 --config-dir 对应的 settings.json 理解，键完全一致）
• RPC 服务：127.0.0.1:9091（rpc-url 为 /transmission/）
• 参数清单来源：4.1.4 首次启动自动生成的 settings.json 原文（90 个键，全文见第四章总览）

二、前置条件

1. 已安装并启动 transmission-daemon（安装方式不限：发行版软件源、二进制或服务器编排形态均可，参数键一致）；
2. 命令行可用 transmission-remote 连接 RPC（transmission-remote 127.0.0.1:9091 -si 有输出）；
3. 对配置文件所在目录有读写权限。

验证连接：

transmission-remote 127.0.0.1:9091 -si

实测回显（节选）：

VERSION
  Daemon version: 4.1.4 (a6d907d9ea)
  RPC version: 19
  RPC minimum version: 14

CONFIG
  Configuration directory: /etc/transmission-daemon
  Download directory: /opt/downloads/complete
  Listen port: 51413

💡 说明：RPC version 19 是 4.x 的 RPC 协议版本，-si 输出的 CONFIG/LIMITS/MISC 三段与 settings.json 的参数一一对应，是核对配置是否生效的最快途径。

三、参数查看与修改方式

settings.json 的修改有两条路径，各有适用场景，核心结论先记住：daemon 运行中手改配置文件无效且随时可能被覆盖，离线改文件必须等进程完全停止后再动笔。

3.1 查看当前生效配置

两种方式互补：

# 方式一：读配置文件（看声明值）
grep -E '"(speed-limit-down|rpc-port)"' /etc/transmission-daemon/settings.json

实测回显：

    "speed-limit-down": 888,
    "rpc-port": 9091,

# 方式二：问 daemon（看运行时生效值）
transmission-remote 127.0.0.1:9091 -si

实测回显（节选 LIMITS 段）：

LIMITS
  Peer limit: 200
  Upload speed limit: Unlimited (Disabled limit: 200 kB/s; Disabled turtle limit: 50 kB/s)
  Download speed limit: 777 kB/s (Enabled limit: 777 kB/s; Disabled turtle limit: 50 kB/s)

两者不一致时（上例：文件里 888、daemon 内存里 777）以 -si 为准——那是正在生效的值。

3.2 运行时修改（推荐：transmission-remote）

RPC 路径改的是 daemon 内存配置，立即生效，且 daemon 会在进程退出时把内存值写回 settings.json 持久化。以限速为例：

transmission-remote 127.0.0.1:9091 -d 500 -u 200
transmission-remote 127.0.0.1:9091 -si | sed -n '/LIMITS/,/MISC/p'

实测回显：

127.0.0.1:9091/transmission/rpc/ returned a successful response
LIMITS
  Peer limit: 200
  Default seed ratio limit: Unlimited
  Default idle seeding time limit: Unlimited
  Upload speed limit: 200 kB/s (Enabled limit: 200 kB/s; Disabled turtle limit: 50 kB/s)
  Download speed limit: 500 kB/s (Enabled limit: 500 kB/s; Disabled turtle limit: 50 kB/s)

-d/-u 在设值的同时自动启用限速开关；-D/-U 解除限制。各类参数对应的 transmission-remote 选项在第五章各分类节给出。

3.3 离线修改（改文件）的正确顺序与覆盖实测

systemd 形态的标准流程：

systemctl stop transmission-daemon
# 确认进程完全退出后再编辑
systemctl is-active transmission-daemon

实测回显：

inactive

vi /etc/transmission-daemon/settings.json
systemctl start transmission-daemon

为什么必须等进程停止？以下是实测的覆盖过程（4.1.4 环境实录，2026-11-01）：

1. daemon 运行中，RPC 先设了限速 777 kB/s（内存值 777，此时文件里还是旧值 500）；
2. 手工把文件里的 speed-limit-down 改成 999——观察 60 秒，文件保持 999，说明 daemon 平时并不主动把内存值刷盘；
3. 执行停止命令后 3 秒内又手工把文件改成 888，然后启动 daemon；
4. 启动后 -si 查询：Download speed limit: 777 kB/s——daemon 在退出过程中把内存值 777 写盘，覆盖了停止时立即手改的 888。

结论：从发出停止命令到 daemon 完成收尾写盘有数秒窗口，窗口内手改的值会被吞掉。正确姿势是 systemctl stop 后用 systemctl is-active（或 pgrep transmission-daemon）确认 inactive/无进程，再编辑文件。

3.4 rpc-password 的明文自动哈希机制

settings.json 里的 rpc-password 支持写明文，daemon 启动读到明文后会立即替换为 { 开头的哈希串并写回文件。实测：写入明文 q1w2e3r4，启动后文件中变为：

    "rpc-password": "{4fde9ad6cfb831f7d2c895d96e44f831ae61f5b5SBBExugQ",

认证仍按原明文密码工作。该机制意味着：改密码只需停进程把哈希串改成新明文即可；而运行中的文件里看到哈希串并不代表密码泄露（哈希不可逆推）。

四、参数总览

以下为 4.1.4 首次启动生成的 settings.json 全部 90 个键与首装默认值（原文照录）。按语义分组解读见第五章；表中「含义」为简要说明。

💡 说明：首装默认值中目录类键（download-dir 等）随安装形态而异——apt 包默认 /var/lib/transmission-daemon/ 系列路径，其余形态为各自 --config-dir 约定路径；其余键值全平台一致。表中默认值取自 4.1.4 实际生成文件（目录键按 apt 形态填写）。

五、核心参数分类详解

5.1 RPC 服务组（rpc-*）

RPC 组控制 daemon 的管理面——Web 界面、transmission-remote、第三方 App 都走这条路，安全配置的重中之重。

运行时对应命令（实测）：

transmission-remote 127.0.0.1:9091 -n admin:q1w2e3r4 -l        # 带认证访问
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9091/transmission/rpc

认证开启前后的回显对比（实测）：

401        # 认证开启后，无凭据访问
200        # 带 -n admin:q1w2e3r4 或 Basic Auth 凭据

5.2 下载目录组（download-dir / incomplete-dir / watch-dir）

watch 目录实测行为：把 demo.torrent 放入监视目录后，daemon 自动添加任务并把它改名为 demo.torrent.added：

$ ls /var/lib/transmission-daemon/watch/
demo.torrent.added

.added 后缀即「已处理」标记，避免重复导入；.torrent.added 文件可安全清理。

5.3 速度限制组（speed-limit-* / alt-speed-*）

双档限速是 Transmission 的特色：普通档 + 「乌龟」档，乌龟档可按时段自动切换（如白天全速、夜间限速保带宽）。

运行时对应命令（实测回显见 3.2）：-d <kB/s>/-u <kB/s> 设普通档并启用、-D/-U 解除；-asd/-asu 设乌龟档速率、-as/-AS 切换乌龟档开关。

-si 会话信息里的限速显示格式（实测）：

  Upload speed limit: 200 kB/s (Enabled limit: 200 kB/s; Disabled turtle limit: 50 kB/s)
  Download speed limit: 500 kB/s (Enabled limit: 500 kB/s; Disabled turtle limit: 50 kB/s)

括号内分别是：普通档当前值（Enabled/Disabled 表示开关状态）与乌龟档配置值。

5.4 队列组（-queue- / queue-stalled-*）

队列的价值：几十个任务同时活跃会互相争抢带宽与磁盘 IO，排队机制让活跃任务跑满带宽。-l 列表中状态为 Stopped 的排队任务在活跃任务完成后自动接续。

5.5 peer 与连接组（peer-* / reqq / port-forwarding）

5.6 协议特性组（dht / pex / lpd / encryption / utp / tcp / sequential）

运行时对应命令：-o/-O 切 DHT、-x/-X 切 PEX、-y/-Y 切 LPD、-er/-ep/-et 切三档加密。

💡 技术拓展：DHT/PEX/LPD 三者都是「无 tracker 找节点」的发现机制——DHT 走分布式哈希表（大公网）、PEX 走已连接 peer 交换（滚雪球）、LPD 走局域网广播（同网段）。私有种子（private flag）会禁用全部三者，防止内部分发物外泄节点；公共种子保持默认（DHT/PEX 开）可获得最好的节点覆盖。

5.7 做种策略组（ratio-* / idle-seeding-* / seed-queue）

运行时对应命令：-gsr <ratio> 全局分享率、-sr <ratio> 单任务分享率、-SR 不限；-gisl <分钟>/-isl <分钟> 空闲做种上限、-ISL 不限。挂机做种保分享率场景常用 -gsr 2.0（下到 2.0 停）。

5.8 黑名单组（blocklist-*）

黑名单是 IP 级过滤（屏蔽恶意节点/反 P2P 组织地址段），常用公开列表如 level1。运行时更新命令：

transmission-remote 127.0.0.1:9091 --blocklist-update

默认占位 URL 的实测报错（未替换地址时）：

Error: Couldn't fetch blocklist: Not Found (404)

把 blocklist-url 改成真实黑名单列表地址（如 iblocklist 的 level1 列表下载地址）后更新成功，文件落配置目录的 blocklists/ 子目录。

5.9 脚本钩子组（script-torrent-*）

三个生命周期钩子，配绝对路径脚本路径与独立开关：

脚本以 daemon 运行身份执行，注意脚本内路径权限。配合 watch 目录可搭「丢种子进目录 → 自动下载 → 完成后自动处理」的无人值守流水线。

5.10 杂项（cache / message-level / umask / pidfile 等）

六、生产配置模板

6.1 低资源 NAS 挂机档（1-2 核 / 1GB 内存 / 机械硬盘）

适用：家庭 NAS 无人值守下载 + 适度做种，控制内存与磁盘 IO 占用。

"cache-size-mb": 4,
"download-queue-enabled": true,
"download-queue-size": 3,
"peer-limit-global": 100,
"peer-limit-per-torrent": 30,
"upload-slots-per-torrent": 8,
"speed-limit-down-enabled": false,
"speed-limit-up-enabled": true,
"speed-limit-up": 5120,
"alt-speed-enabled": false,
"ratio-limit": 2.0,
"ratio-limit-enabled": true,
"dht-enabled": true,
"pex-enabled": true,
"encryption": 1,
"message-level": 2,
"preallocation": 1

要点：上传限速 5MB/s 保家庭带宽可用、分享率 2.0 自动停种防硬盘写爆、连接数与上传槽收敛降内存、preallocation 快速模式减少机械盘寻道。

6.2 高带宽 seedbox 档（4 核+ / 4GB 内存+ / SSD）

适用：VPS/独服做种保分享率，最大化吞吐。

"cache-size-mb": 32,
"download-queue-enabled": true,
"download-queue-size": 10,
"peer-limit-global": 500,
"peer-limit-per-torrent": 80,
"upload-slots-per-torrent": 20,
"speed-limit-down-enabled": false,
"speed-limit-up-enabled": false,
"ratio-limit": 5.0,
"ratio-limit-enabled": true,
"rpc-authentication-required": true,
"rpc-whitelist-enabled": true,
"rpc-whitelist": "127.0.0.1,192.168.1.0/24",
"anti-brute-force-enabled": true,
"anti-brute-force-threshold": 10,
"blocklist-enabled": true,
"utp-enabled": false,
"encryption": 1,
"preallocation": 2

要点：不限速跑满带宽、大缓存+多连接吃满 SSD、公网暴露必须认证+白名单+防爆破三件套、blocklist 屏蔽恶意节点、preallocation 完整预分配防碎片。

七、常见问题

Q1：改了 settings.json 重启后值又变回去了？

进程退出时会把内存配置写盘，覆盖了停止窗口内手改的值（完整实测过程见 3.3）。改文件必须等 systemctl is-active 显示 inactive 后再动笔；或改用 transmission-remote 运行时调参。

Q2：rpc-password 明文写进去重启后变乱码了？

自动哈希机制（见 3.4），{ 开头串是哈希不是损坏，登录仍用原明文。

Q3：-si 显示的限速和文件里不一致？

以 -si（内存生效值）为准。文件值可能是 RPC 修改后尚未退出写盘的旧值。

Q4：watch 目录放了种子没反应？

确认 watch-dir-enabled=true 且路径正确；检查文件确实以 .torrent 结尾；inotify 在某些网络文件系统（NFS/CIFS）上失效，设 watch-dir-force-generic=true 改轮询。已处理的种子会改名为 .torrent.added，别把它误当失败。

Q5：限速单位是什么？

kB/s（千字节每秒），1 MB/s = 1024 kB/s。带宽按 bit 计的运营商标称值需先除 8（如 100Mbps 带宽 ≈ 12800 kB/s）。

Q6：umask 改了不生效？

umask 只影响新写入文件；存量文件用 chown/chmod 修正，且注意 daemon 的运行用户身份才是属主决定因素（软件源安装为 transmission 用户，其余形态见部署篇对应章节）。

八、参考链接

• 《Transmission 4.1.4 介绍与选型指南》：定位与同类客户端选型对比
• 《Transmission 4.1.4 Docker Compose 部署指南》：容器形态部署与三目录挂载
• 《Transmission 4.1.4 常用 CLI 命令与工具详解》：transmission-remote 全参数与种子工具实测
• 官方配置文档：https://github.com/transmission/transmission/blob/main/docs/Configuration-Files.md
• GitHub 仓库：https://github.com/transmission/transmission