AyuCLouD-Services返回首页

Transmission RPC 是什么?作用、端口、URL 与配置方法

更新于 2026-11-03 · ayu-ssr.buzz

简答: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。两者用途、验证方法和防火墙规则都不同。

Transmission 相关组件与端口对照
对象作用常见地址或端口验证方式出问题时先回退什么
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 在容器中,先确认宿主机端口映射与容器内部监听端口的关系。

  1. 确认 Transmission daemon 或桌面客户端正在运行。
  2. 先发送一次请求,保存响应头: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
  3. 如果返回 409,从响应头复制 X-Transmission-Session-Id,再把它加入请求头并重试。
  4. 如果返回 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是否启用 RPCdaemon 与桌面客户端的默认状态可能不同,以实际配置和日志为准
rpc_bind_addressRPC 监听地址本机访问、局域网访问和容器映射需要不同的网络前提
rpc_portRPC 管理端口官方当前配置文档列出的默认值为 9091,但发行版可能修改
rpc_urlRPC 路径前缀官方文档列出的默认路径前缀为 /transmission/,完整请求路径通常包含 rpc
rpc_authentication_required是否要求 HTTP Basic 认证开启后需同时确认用户名、密码和客户端是否发送认证头
rpc_username、rpc_passwordRPC 登录凭据密码可能在启动后被重新保存为加盐形式,不要覆盖正在运行的配置
rpc_whitelist允许访问 RPC 的 IP 范围这是 IP 访问控制,不等于域名 Host 校验
rpc_host_whitelist允许出现在 HTTP Host 头中的域名域名访问失败时检查 Host 校验;IP 地址与 localhost 有特殊处理

官方配置文档还提醒,编辑配置文件前应关闭客户端,否则运行中的程序可能把旧设置重新写回去。daemon 可通过发送 SIGHUP 重新加载设置,但是否适用于你的发行版和服务管理方式,应先查看日志并保留备份。需要回退时,停止服务、恢复备份文件,再启动并验证原地址。

Docker、NAS 与反向代理:先分清三层地址

容器场景最容易把“容器内部地址”“宿主机映射端口”和“浏览器访问地址”混为一谈。排查时按下面顺序确认:

  1. 服务层:Transmission 在容器内是否启用了 RPC,监听地址和端口是什么。
  2. 映射层:宿主机是否把管理端口映射到容器 RPC 端口;映射后的宿主机端口不一定仍是 9091。
  3. 路径层:反向代理是否保留了 /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 连接失败怎么判断:按现象分流

RPC 常见现象、判断与低风险回退
现象可能范围先做什么停止条件与回退
连接超时或拒绝服务未运行、端口错误、监听地址或防火墙不匹配在 Transmission 所在主机本机测试,再检查监听端口和容器映射不要继续改配置;恢复原端口并重启服务
401认证已启用但用户名或密码不匹配确认客户端是否发送 Basic 认证,重新输入凭据不要反复尝试真实密码;确认无锁定或暴力保护影响
403IP 白名单或 Host 白名单拒绝访问检查访问来源 IP、域名和两个 whitelist 字段优先从本机或局域网安全入口验证,不要直接关闭全部限制
404RPC 路径或反向代理重写错误核对完整路径是否包含 /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 可以执行添加、暂停、删除任务等管理操作,因此应把它当作管理面而不是普通网页端口处理。较稳妥的顺序是:

  1. 优先只监听本机或可信局域网地址。
  2. 开启认证,并使用独立且不重复的强密码。
  3. 使用 IP 白名单和 Host 白名单限制来源。
  4. 跨网络访问时,优先使用 VPN、SSH 隧道或带 HTTPS 的反向代理。
  5. 先从本机执行最小 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 反向代理,并先用本机最小请求验证。

相关阅读

参考资料

  1. Transmission 官方 RPC specification
  2. Transmission 官方 Headless Usage 文档
  3. Transmission 官方配置文件编辑文档