Transmission RPC 是什么?作用、端口、URL 与配置方法
简答:Transmission RPC 是用于远程读取状态、添加或暂停任务、修改会话设置的控制接口。它通常通过 HTTP POST 发送 JSON 请求,当前官方文档给出的默认地址是 http://host:9091/transmission/rpc;9091 是管理端口,不能与 BT 对等连接使用的 peer port 混为一谈。先确认 Transmission 正在运行,再用最小请求验证 RPC 地址、认证和会话标识。
定义:Transmission RPC(Remote Procedure Call,远程过程调用)是 Transmission 客户端或 daemon 对外提供的远程管理接口,不是 BT 下载协议本身。
先看结论:RPC、Web UI 与 peer port 怎么区分
如果你只是想远程打开 Transmission、添加任务或查看下载状态,关注的是 RPC 管理接口;如果你想让 Transmission 与其他 BT 客户端建立对等连接,关注的是 peer port。两者用途、验证方法和防火墙规则都不同。
| 对象 | 作用 | 常见地址或端口 | 验证方式 | 出问题时先回退什么 |
|---|---|---|---|---|
| RPC | 读取会话信息、添加、暂停、继续、删除或修改任务 | http://主机:9091/transmission/rpc,端口和路径可改 | 发送 HTTP POST JSON 请求 | 先改回本机访问或原来的端口、路径 |
| Web UI | 浏览器图形界面,底层通常通过 RPC 与 Transmission 会话交互 | 通常与 RPC 服务使用同一管理入口 | 浏览器访问对应管理地址 | 关闭反向代理或直接测试 daemon 地址 |
| transmission-daemon | 无桌面界面运行 Transmission 的后台进程 | RPC 服务和 BT 网络服务分别监听 | 查看进程、日志和 RPC 响应 | 停止 daemon 后恢复备份配置 |
| peer port | 与其他 BT 对等节点通信 | 官方配置文档列出的默认值为 51413 | 检查监听、防火墙、NAT 和节点连接 | 恢复原 peer port,不要拿它替代 RPC 端口 |
Transmission 官方无界面使用文档明确把 daemon 接收远程命令的接口称为 RPC,并将 TCP 9091 与 BT 的 TCP/UDP 端口分开说明。配置文档则分别列出 rpc_port 和 peer_port。可查看 官方 Headless Usage 文档 与 官方配置文件文档。
Transmission RPC 能做什么?
RPC 可以把图形界面中的许多操作变成程序请求。官方 RPC 规范列出的能力包括读取会话信息、查看全局统计、查询任务进度、添加和移除任务、启动、停止、校验以及关闭 daemon 等。
- 读取状态:查询 Transmission 版本、RPC 版本、速度限制、下载目录和任务状态。
- 管理任务:添加 torrent 或磁力任务,启动、暂停、继续、校验和删除任务。
- 批量自动化:让 RSS 工具、脚本或第三方客户端通过 RPC 调用 Transmission。
- 集中管理:把运行在 NAS、服务器或其他主机上的 Transmission 与本机界面分离。
因此,“RPC 能连接但下载没速度”并不矛盾:这说明管理请求可能已经成功,但 peer port、tracker、DHT、任务资源或网络路径仍需单独判断。RPC 只负责控制和查询,不会自动替代 BT 对等连接。
当前官方 RPC 规范说明,Transmission 4.1.0 开始支持 JSON-RPC 2.0,并将 RPC 字符串转换为 snake_case;旧协议和旧字段在 Transmission 4 中仍被支持但已标记为弃用。具体发行版、镜像或旧版本的兼容性仍应以实际返回的 RPC 版本和对应文档为准,不能仅凭配置字段名称判断。
最小验证:用 curl 判断 RPC 是否能连接
下面的例子只查询会话版本,不会添加、暂停或删除任务。将 127.0.0.1:9091 换成 Transmission 所在主机的管理地址;如果 Transmission 在容器中,先确认宿主机端口映射与容器内部监听端口的关系。
- 确认 Transmission daemon 或桌面客户端正在运行。
- 先发送一次请求,保存响应头:
curl -i -u '用户名:密码' -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","params":{"fields":["version"]},"method":"session_get","id":1}' http://127.0.0.1:9091/transmission/rpc - 如果返回
409,从响应头复制X-Transmission-Session-Id,再把它加入请求头并重试。 - 如果返回 JSON 且包含
result,说明 HTTP 路径和 RPC 请求已到达服务端;若结果中没有预期字段,再核对版本和请求格式。
官方规范说明,RPC 使用 HTTP POST 传输 JSON;默认 URL 是 http://host:9091/transmission/rpc,但端口和路径可以修改。多数 RPC 服务还要求 X-Transmission-Session-Id,首次请求或会话标识失效时会返回 409,并在响应头中给出新的标识。详见 官方 RPC specification。
重试格式可以写成:curl -i -u '用户名:密码' -H 'Content-Type: application/json' -H 'X-Transmission-Session-Id: 从409响应头复制的值' -d '{"jsonrpc":"2.0","params":{"fields":["version"]},"method":"session_get","id":1}' http://127.0.0.1:9091/transmission/rpc。不要把真实密码直接写入会被其他用户读取的脚本、历史记录或公开日志。
常见 RPC 配置字段:先按版本和发行方式核对
配置字段不能脱离版本、GUI/daemon、操作系统和打包方式直接套用。当前官方配置文件文档给出了 snake_case 形式,但同一文档也说明 Transmission 4.1.0 开始处于格式迁移阶段,旧 kebab-case 格式仍可能出现。修改前应停止客户端或 daemon、备份配置文件,修改后再启动并观察日志。
| 字段 | 作用 | 核验重点 |
|---|---|---|
rpc_enabled | 是否启用 RPC | daemon 与桌面客户端的默认状态可能不同,以实际配置和日志为准 |
rpc_bind_address | RPC 监听地址 | 本机访问、局域网访问和容器映射需要不同的网络前提 |
rpc_port | RPC 管理端口 | 官方当前配置文档列出的默认值为 9091,但发行版可能修改 |
rpc_url | RPC 路径前缀 | 官方文档列出的默认路径前缀为 /transmission/,完整请求路径通常包含 rpc |
rpc_authentication_required | 是否要求 HTTP Basic 认证 | 开启后需同时确认用户名、密码和客户端是否发送认证头 |
rpc_username、rpc_password | RPC 登录凭据 | 密码可能在启动后被重新保存为加盐形式,不要覆盖正在运行的配置 |
rpc_whitelist | 允许访问 RPC 的 IP 范围 | 这是 IP 访问控制,不等于域名 Host 校验 |
rpc_host_whitelist | 允许出现在 HTTP Host 头中的域名 | 域名访问失败时检查 Host 校验;IP 地址与 localhost 有特殊处理 |
官方配置文档还提醒,编辑配置文件前应关闭客户端,否则运行中的程序可能把旧设置重新写回去。daemon 可通过发送 SIGHUP 重新加载设置,但是否适用于你的发行版和服务管理方式,应先查看日志并保留备份。需要回退时,停止服务、恢复备份文件,再启动并验证原地址。
Docker、NAS 与反向代理:先分清三层地址
容器场景最容易把“容器内部地址”“宿主机映射端口”和“浏览器访问地址”混为一谈。排查时按下面顺序确认:
- 服务层:Transmission 在容器内是否启用了 RPC,监听地址和端口是什么。
- 映射层:宿主机是否把管理端口映射到容器 RPC 端口;映射后的宿主机端口不一定仍是 9091。
- 路径层:反向代理是否保留了
/transmission/rpc路径,是否正确转发 POST、认证头和X-Transmission-Session-Id。
如果直接访问宿主机地址可以返回 409 或 JSON,而经过域名访问出现 404,优先检查反向代理路径重写;如果出现 Host 校验相关错误,检查 rpc_host_whitelist 与实际域名;如果局域网内能访问、远程访问失败,则再检查防火墙、路由器和访问边界。不要在没有认证、访问控制或加密保护的情况下直接把 RPC 管理端口暴露到公网。
SSH 隧道也只能把本地端口转发到 SSH 登录主机能访问的目标。如果 Transmission 与 SSH 服务不在同一台主机,命令中的远端 127.0.0.1 指向的是 SSH 登录主机,而不是你的电脑;这时必须改用登录主机可达的目标地址,或通过跳板机、ProxyJump 等方式明确转发链路。
RPC 连接失败怎么判断:按现象分流
| 现象 | 可能范围 | 先做什么 | 停止条件与回退 |
|---|---|---|---|
| 连接超时或拒绝 | 服务未运行、端口错误、监听地址或防火墙不匹配 | 在 Transmission 所在主机本机测试,再检查监听端口和容器映射 | 不要继续改配置;恢复原端口并重启服务 |
| 401 | 认证已启用但用户名或密码不匹配 | 确认客户端是否发送 Basic 认证,重新输入凭据 | 不要反复尝试真实密码;确认无锁定或暴力保护影响 |
| 403 | IP 白名单或 Host 白名单拒绝访问 | 检查访问来源 IP、域名和两个 whitelist 字段 | 优先从本机或局域网安全入口验证,不要直接关闭全部限制 |
| 404 | RPC 路径或反向代理重写错误 | 核对完整路径是否包含 /rpc,再绕过代理测试 | 恢复原代理路径和备份配置 |
| 409 | 缺少或过期的会话标识 | 读取响应头中的 X-Transmission-Session-Id 并重发原请求 | 不要把 409 当作端口关闭 |
| RPC 成功但下载无速度 | 任务资源、tracker、DHT、peer port 或网络路径问题 | 查看任务状态、节点数量、tracker 状态和 peer port 监听 | 不要为了“提速”直接修改 MTU、关闭安全软件或反复换配置 |
判断成功时,不要只看 HTTP 状态码。官方规范说明,RPC 服务通常即使请求失败也返回 HTTP 200,真正结果要结合 JSON 的 result 或 error 字段判断;409 则是会话标识流程中的特殊情况。
安全设置:RPC 管理端口不要与下载端口混用
RPC 可以执行添加、暂停、删除任务等管理操作,因此应把它当作管理面而不是普通网页端口处理。较稳妥的顺序是:
- 优先只监听本机或可信局域网地址。
- 开启认证,并使用独立且不重复的强密码。
- 使用 IP 白名单和 Host 白名单限制来源。
- 跨网络访问时,优先使用 VPN、SSH 隧道或带 HTTPS 的反向代理。
- 先从本机执行最小
session_get请求,再逐层增加局域网、容器和代理链路。
官方 RPC 规范说明,认证采用 HTTP Basic Authentication;同时提供 DNS rebinding protection 相关的 Host 校验说明。配置文档则列出 rpc_authentication_required、rpc_whitelist、rpc_host_whitelist 等字段。安全设置改动后,应使用允许的入口验证一次,再从不允许的入口确认确实被拒绝。
如果你只想解决“远程控制 Transmission”,无需先调整 DNS、MTU 或 peer port。先完成 RPC 地址、路径、认证和会话标识验证;只有当 RPC 已经正常、任务仍无节点或连接质量异常时,才进入 BT 网络层排查。
相关阅读与下一步
如果你还不确定应该从哪里开始,可以先看 Transmission 远程访问怎么设置,了解本机、局域网和远程访问的差别;需要浏览器操作时,查看 Transmission Web UI 怎么设置;如果问题发生在容器或 NAS,再看 Transmission Docker 容器化部署完整指南。
推荐:如果你的 Transmission RPC 已能连接,但跨网络访问仍有延迟、丢包或办公连接不稳定,可先按访问链路逐段复现,再了解边界云加速官网提供的网络连接诊断与线路服务。
常见问题
Transmission RPC 是不是一种下载协议?
不是。RPC 是远程管理接口,用于读取状态、添加或控制任务;真正的 BT 对等连接仍由 Transmission 的网络功能和 peer port 等配置负责。
Transmission RPC 默认端口是不是 9091?
当前官方配置文档把 rpc_port 的默认值列为 9091,RPC 规范给出的默认完整地址是 http://host:9091/transmission/rpc。但端口和路径可以被发行版、容器映射或管理员修改,实际使用前应查看配置和监听日志。
为什么第一次请求 Transmission RPC 返回 409?
多数 RPC 服务要求 X-Transmission-Session-Id。第一次请求或会话标识过期时,服务端会返回 409,并在响应头给出新的标识;客户端读取该值后重发原请求即可。
RPC 能连接,但 Transmission 下载速度仍然是 0,说明什么?
这通常只能说明管理接口可用,不能证明任务已经找到可用节点。应继续检查任务元数据、tracker、DHT、peer 数量、peer port 监听、NAT 和网络路径。
rpc_url 应该填写什么?
当前官方配置文档将 rpc_url 列为路径前缀,默认值为 /transmission/;RPC 规范给出的完整接口路径是 /transmission/rpc。不同客户端可能要求填写完整 URL、路径前缀或单独端口,必须按客户端字段说明核对。
可以直接把 9091 暴露到公网吗?
不建议直接暴露。RPC 具备任务管理权限,应至少配置认证和访问控制;跨网络访问优先使用 VPN、SSH 隧道或 HTTPS 反向代理,并先用本机最小请求验证。