Transmission Web UI 怎么设置?跨平台开启、访问与排障指南
简答:Transmission Web UI 是内置的远程管理界面,最短流程是:开启 Remote/RPC、设置认证、确认 9091 管理端口,再用“设备 IP:端口”访问。桌面版通常从偏好设置开启,Linux 服务和 Docker 则需要检查 settings.json、端口映射、目录权限与防火墙。若页面能打开但任务不连接,还要单独检查 peer port,而不是只看 9091。
定义:Transmission Web UI 是 Transmission 内置的浏览器管理界面,用于远程添加、暂停、删除任务和查看下载状态,不等同于 BitTorrent 对等连接端口。
先看最快设置方法:按部署方式选择
如果你已经安装好 Transmission,先不要修改大量高级参数。按照下面的最短流程操作:开启远程访问,启用用户名和密码,确认管理端口,使用正确的访问路径,最后添加一个合法的种子文件或磁力链接验证。
| 使用方式 | 开启入口 | 常见访问地址 | 首先检查什么 |
|---|---|---|---|
| Windows Qt | Edit → Preferences → Remote | http://127.0.0.1:9091/ 或 http://电脑IP:9091/ | Allow remote access、认证和 IP 限制 |
| Linux 图形界面 | Edit → Preferences → Remote | http://电脑IP:9091/ | 服务是否监听 9091 |
| macOS | Transmission → Settings → Remote | http://电脑IP:9091/ | Remote 页面和本机防火墙 |
| Linux daemon | 修改 JSON 配置或使用命令行 | http://服务器IP:9091/transmission/ | rpc-enabled、认证、白名单 |
| Docker/NAS | Compose 环境变量与容器配置 | http://宿主机IP:9091/transmission/ | 9091 映射、卷目录权限、容器日志 |
官方文档说明,Transmission 各种形态都内置 Web Interface;默认远程控制端口是 9091,本机访问可以使用 127.0.0.1:9091。部分 daemon 或容器环境会使用默认 RPC 路径 /transmission/,因此出现空白页或 404 时,应同时尝试带路径和不带路径的地址,而不是直接判断服务不可用。Transmission Web Interface 官方文档 github.com
Windows、Linux 和 macOS 如何开启 Web UI
桌面端的设置思路基本一致,但菜单名称和入口位置不同。官方文档给出的通用流程是进入 Remote 页面,勾选允许远程访问;如果需要保护管理界面,再启用认证并填写用户名、密码;如果只允许局域网或指定设备访问,则配置 IP 限制。
- Windows:打开 Transmission Qt,进入
Edit → Preferences → Remote,勾选允许远程访问;需要登录时启用认证并设置用户名、密码。 - Linux 图形界面:打开 Transmission,进入
Edit → Preferences,再打开Remote页面完成同样设置。 - macOS:从系统菜单栏进入
Transmission → Settings → Remote,检查远程访问和认证选项。 - 保存后测试:在运行 Transmission 的机器上先访问
http://127.0.0.1:9091/;本机可访问后,再用同一局域网内另一台设备访问http://设备局域网IP:9091/。
如果本机能打开、其他设备打不开,优先检查操作系统防火墙、设备是否处于同一局域网,以及 Remote 页面是否启用了“仅允许指定 IP”。官方配置中,RPC 白名单默认用于限制可访问地址;放宽限制前应先确认访问范围。官方跨平台开启步骤 官方配置文件说明 github.com
Linux daemon 与 settings.json 怎么设置
Linux daemon 适合服务器、NAS 或无桌面的设备。配置文件通常使用 JSON 格式,但配置文件位置会因安装方式、发行版和容器镜像不同而变化,不能只凭一个固定路径判断。修改前先停止 Transmission 或对应服务,并备份配置;官方文档明确提醒,客户端仍在运行时修改可能被旧设置覆盖。
- 停止 Transmission daemon 或容器,确认进程已经退出。
- 备份当前配置文件,例如复制为
settings.json.bak。 - 检查并按实际需求设置
rpc-enabled、rpc-port、rpc-url、rpc-authentication-required、rpc-username和rpc-whitelist。 - 确认下载目录和未完成目录存在,并且运行 Transmission 的用户具有读写权限。
- 启动服务后再访问 Web UI;如果服务支持重新加载,也可以按官方方式发送
SIGHUP,但初次排障更建议完整停止、备份、启动。
官方配置说明中,rpc-port 默认值为 9091,rpc-url 默认值为 /transmission/;peer-port 默认值为 51413,它是对等连接端口,不是浏览器管理端口。自 Transmission 4.1.0 起,配置字符串逐步转向 snake_case,新旧字段格式可能因版本和保存格式不同而变化,因此不要把旧版字段名直接覆盖到新配置中。Transmission 配置文件官方说明 github.com
一个用于核对字段含义的最小示例是:
{"rpc_enabled": true, "rpc_port": 9091, "rpc_authentication_required": true, "peer_port": 51413}
示例只用于理解字段,不建议在未确认版本、配置格式和安全边界前直接覆盖整个文件。
Docker 或 NAS 上设置 Transmission Web UI
Docker 环境最容易出现“容器在运行,但浏览器打不开”或“Web UI 能打开,任务却没有连接”的情况,原因通常是管理端口、对等端口、目录映射和权限分别配置,不能只看容器是否启动。
以常见的 LinuxServer Transmission 镜像文档为例,Web UI 使用容器端口 9091,BT 对等连接通常映射 TCP 和 UDP 的 51413;配置目录挂载到 /config,下载目录可挂载到 /downloads,自动监控目录可挂载到 /watch。镜像还提供 USER、PASS、WHITELIST、HOST_WHITELIST 和 PEERPORT 等参数。具体镜像的变量名不能与其他镜像混用。LinuxServer Transmission 容器文档 github.com
- 先规划宿主机目录,例如配置目录、已完成下载目录、未完成下载目录和 watch 目录。
- 在 Compose 中映射
9091:9091;如果需要改善对等连接,再分别映射 peer port 的 TCP 和 UDP。 - 设置容器用户的 UID/GID,并确保宿主机目录属于该用户或用户组,否则可能出现下载目录不可写。
- 首次启动后访问
http://宿主机IP:9091/transmission/;若页面返回 404,再检查容器日志、实际 RPC 路径和 Web UI 文件。 - 在 Web UI 中添加任务,选择容器内部可见的路径,例如
/downloads,不要直接填写宿主机路径。
Docker 中最常见的路径错误是把宿主机目录写进 Web UI。宿主机的 /data/downloads 只有在映射为容器内的 /downloads 后,Transmission 才能使用 /downloads 这个容器路径。若页面能打开但添加任务后报目录不存在或权限错误,应先检查卷映射和容器内目录,而不是修改 DNS 或 MTU。
9091 与 51413 的区别:页面能开不代表任务能连接
| 项目 | 用途 | 典型字段或端口 | 异常表现 |
|---|---|---|---|
| Web UI/RPC | 浏览器管理 Transmission | rpc-port,默认 9091 | 拒绝连接、401、403、404、页面空白 |
| Peer port | 与其他对等节点建立 BitTorrent 连接 | peer-port,默认 51413 | 页面可登录,但任务长期无连接或速度异常 |
| 下载目录 | 保存完整和未完成文件 | download-dir、incomplete-dir | 任务添加失败、目录不存在、权限错误 |
| RPC 路径 | Web UI 请求的 URL 路径 | /transmission/ | 根地址 404,但带路径可用 |
官方配置将 RPC 和 peer port 作为不同选项处理:RPC 端口负责控制接口,peer port 负责对等连接;因此“9091 已放行”不能证明下载网络已经打通。若任务不连接,按顺序检查任务本身是否有可用来源、peer port 是否被主机防火墙或路由器拦截、Docker 是否同时映射 TCP/UDP、端口转发是否指向正确设备,以及 Transmission 是否启用了随机端口。官方端口与 RPC 配置字段 容器端口映射说明 github.com
常见故障分流:按现象处理
- 拒绝连接:确认 Transmission 或容器正在运行;确认浏览器使用的是运行主机的实际 IP;检查 9091 是否被改过;Docker 则运行
docker ps和docker logs transmission查看端口及启动错误。 - 401 或反复要求登录:检查用户名、密码和认证开关;容器镜像优先使用其文档提供的认证变量,不要在服务运行时手改密码字段。
- 404:分别尝试
http://IP:9091/与http://IP:9091/transmission/;如果是自定义 Web UI,再核对 Web UI 目录是否被正确挂载。 - 本机可访问,局域网不可访问:检查 RPC 绑定地址、IP 白名单、操作系统防火墙和路由器隔离设置;不要直接把白名单改成所有地址后长期保留。
- 页面能打开但下载目录不可写:在容器内检查目录是否存在,并核对宿主机目录的所有者、UID/GID 和读写权限。
- 修改 settings.json 不生效:先停止客户端或容器,备份后再改;检查当前版本使用的是旧 kebab-case 还是新 snake_case 字段,启动后再查看实际保存结果。
这些分流可以把问题分成“管理界面连接”“配置认证”“路径权限”和“对等网络”四类,避免一遇到下载慢就同时修改 DNS、MTU、代理和端口,导致无法判断是哪一步产生了变化。
远程访问的安全设置
Web UI 具备添加、删除、暂停任务和修改下载设置的管理权限,因此不建议把未认证的 9091 直接暴露到公网。更稳妥的顺序是:优先只在本机使用;需要局域网管理时限制局域网 IP;跨网络管理时优先使用受控的 VPN、SSH 隧道或带认证的反向代理,并保留强密码和主机白名单。
Transmission 官方配置支持认证、RPC 绑定地址、主机白名单和 IP 白名单;配置文件中还区分了 RPC 端口和对等端口。密码修改必须避开服务正在运行的状态,否则可能被旧进程覆盖。任何远程访问方案都应先在内网验证,再逐步放大访问范围。官方 RPC 安全相关字段 github.com
验证结果:怎样判断设置真正完成
- 浏览器能打开正确的 Web UI 页面,而不是只收到端口响应。
- 使用已设置的账号密码登录成功,未启用认证时也确认访问范围没有超出预期。
- 添加一个任务,下载目录显示为 Transmission 所在环境能够访问的路径。
- 暂停、继续、删除任务等控制操作能在页面和服务端同步生效。
- 如果页面能管理任务但任务没有连接,单独检查 peer port、路由器、防火墙、Docker TCP/UDP 映射和任务来源。
- 修改配置后重启服务,再确认端口、认证、路径和白名单仍保持预期状态。
截至 2026-10-31,官方文档仍将 9091 列为默认 RPC 端口,并明确说明 Web UI 用于远程控制 Transmission;但实际镜像、发行版和版本可能改变默认路径、绑定地址或字段保存格式,因此最终应以当前实例的配置文件、容器文档和日志为准。官方 Web UI 文档 github.com
常见问题
Transmission Web UI 默认访问地址是什么?
官方文档给出的默认管理端口是 9091,本机可先访问 http://127.0.0.1:9091/;服务器或 Docker 通常使用运行设备的 IP。若根路径返回 404,再尝试在地址末尾加入 /transmission/,实际路径以 rpc-url 和当前镜像配置为准。
Transmission Web UI 能打开,但为什么下载没有速度?
Web UI 使用的是 RPC 管理端口,页面能打开只说明管理接口可访问,不代表 peer port 已打通。应检查 peer-port、路由器端口转发、主机防火墙、Docker 的 TCP/UDP 映射、随机端口设置以及任务是否有可用来源。
Docker 里 Transmission 的下载目录应该填什么?
应填写容器内部路径,例如宿主机目录映射为 /downloads 后,在 Web UI 中使用 /downloads。不能直接填写宿主机路径;同时要确认 PUID、PGID 或容器运行用户对宿主机目录具有读写权限。
修改 settings.json 后 Transmission 设置没有变化怎么办?
先停止桌面客户端、daemon 或容器,再备份配置后修改。官方文档提醒,服务运行时修改可能被旧设置覆盖;另外 Transmission 4.1.0 起逐步转向 snake_case,旧版字段名与新格式不能不加判断地混用。
可以把 9091 直接暴露到公网吗?
不建议在未认证、无访问限制的情况下直接暴露。优先使用本机或局域网访问;跨网络管理时使用受控的 VPN、SSH 隧道或带认证的反向代理,并配置强密码、RPC 绑定地址和白名单。
相关阅读
- 继续看 Transmission Docker 部署、端口和容器网络排查
- 查看 Transmission Docker 的 Compose、权限与配置完整指南
- 如果遇到没速度或端口关闭,查看下载与网络排障步骤
- 需要中文界面时,查看 Transmission 中文界面设置方法
- 查看 Transmission 安装、下载与基础设置说明