订阅转换本地部署教程:从启动后端到导入客户端
简答:订阅转换本地部署的核心,是让转换后端运行在自己的 Windows 电脑、Docker 主机或服务器上,再用本地地址生成目标客户端配置。新手建议先选“本机运行”验证流程,确认 /version 能返回后,再考虑局域网或公网访问。带有订阅凭据的 URL 不要直接粘贴到陌生公共服务,也不要把真实链接写进截图、日志或公开仓库。
定义:订阅转换本地部署,是在自己控制的设备或服务器上运行转换后端,把原始订阅转换成 Clash/Mihomo、sing-box、Surge 等客户端可读取的配置格式。
先看结论:三种部署方式怎么选
最快验证:本机运行,服务只监听本机地址,适合第一次部署和临时转换。
更易维护:Docker 运行,适合有 Docker 环境、需要重启策略或后续迁移的用户。
多人或多设备访问:VPS 公网部署,但必须补齐 HTTPS、访问控制、日志保护和防滥用设置;没有这些措施时,不建议直接开放公网端口。
| 方式 | 访问地址 | 适合场景 | 主要风险或限制 |
|---|---|---|---|
| Windows/macOS/Linux 本机 | 127.0.0.1:25500 | 个人测试、单台设备使用 | 电脑关机后服务不可用;局域网设备默认不能直接访问 |
| Docker 本地运行 | 主机映射端口,例如 25500 | 稳定运行、便于升级和迁移 | 需要确认镜像来源、端口映射和容器日志 |
| VPS 公网运行 | 域名或公网 IP | 多设备、远程访问 | 订阅凭据可能暴露;必须配置 HTTPS、认证和访问限制 |
传统 subconverter 项目说明列出了输入、输出格式和本地接口;其官方 Docker 文档使用容器内部端口 25500,并提供 /version 检查方式。具体版本、镜像标签和系统架构应以部署当天的仓库与 release 页面为准。github.com
主流程一:先在本机跑通后端
- 备份和隔离:先把现有客户端配置、规则文件和原始订阅入口备份到本地安全位置。真实订阅链接包含访问凭据,不要发到群聊、工单、公开 issue 或截图中。
- 获取程序:从项目的 release 页面选择与操作系统和 CPU 架构匹配的构建文件。下载前核对仓库名称、版本标签和文件名;页面没有明确说明的兼容性,不要自行推断。
- 启动后端:解压到单独目录,按压缩包或项目说明启动可执行文件。不要把程序目录放在会被同步到公开网盘、代码仓库或自动备份分享链接的位置。
- 确认服务:浏览器打开
http://127.0.0.1:25500/version,或在终端执行curl http://127.0.0.1:25500/version。如果返回版本或后端标识,说明端口已有服务响应;如果无法连接,先检查进程、端口和系统防火墙。 - 生成测试链接:使用
/sub接口,将目标格式写入target,将原始订阅 URL 写入url。例如:http://127.0.0.1:25500/sub?target=clash&url=已编码的订阅地址。 - 导入客户端:先在浏览器打开生成地址,确认返回内容像目标配置,而不是 404、403、HTML 页面或错误文本;再把该地址添加到支持对应格式的客户端中。
官方文档要求 target 指定目标类型,url 指定待转换订阅;如果参数中含有 :、/、?、& 或 |,应先进行 URL 编码。多个订阅通常按项目文档要求用 | 连接后再编码,不能直接把未编码的多个 URL 拼进查询参数。github.com
成功信号:本地 /version 可访问、转换地址返回目标格式内容、客户端能够读取配置并显示节点或配置条目。只满足其中一项,不能证明整个链路已经正常。
主流程二:用 Docker 部署并验证
如果设备已经安装 Docker,可以先使用项目文档中的最小运行方式验证容器。官方示例使用以下命令:
docker run -d --restart=always -p 25500:25500 tindy2013/subconverter:latest
启动后检查:
docker pscurl http://127.0.0.1:25500/version
官方 Docker README 说明,主机端口可以映射到容器的 25500 端口,也可以用 Compose 管理服务。若你把主机端口改成 15051,访问地址就应改为 http://127.0.0.1:15051/version,生成转换链接时也要使用同一个主机端口。github.com
建议把部署步骤拆成四个检查点:
- 镜像检查:确认镜像来自你实际查看过的项目或组织页面;不要只凭搜索结果中的同名镜像判断归属。
- 端口检查:如果启动时报端口占用,执行
docker ps查看已有容器,再改用其他主机端口,例如-p 15051:25500。 - 服务检查:先访问
/version,再测试/sub。不要直接把失败的转换结果导入客户端。 - 回滚:如果新镜像或自定义配置导致异常,先停止并删除测试容器,恢复此前可用的镜像标签或配置备份;不要在没有备份的情况下覆盖运行目录。
如需自定义 pref、规则或配置文件,官方 Docker 文档提供了挂载或构建自定义镜像的方向,但不同版本的目录结构可能变化,实际文件路径应以当前仓库目录和镜像说明为准。github.com
格式与参数:转换链接怎么写才容易排错
| 字段 | 作用 | 常见错误 |
|---|---|---|
target | 指定输出客户端格式,例如 clash、ss、ssr 或项目支持的其他目标名 | 把客户端名称直接当成目标值,或使用当前版本不支持的名称 |
url | 指定原始订阅地址、节点地址或项目支持的本地文件路径 | 没有 URL 编码;订阅 URL 中的 & 被浏览器当成新的查询参数 |
config | 指定外部配置或模板地址,是否可用取决于后端版本和配置 | 配置文件地址失效、格式错误或权限不足 |
emoji、udp、scv | 部分转换后端支持的附加选项 | 把一个项目的参数照搬到另一个实现,导致参数被忽略或返回错误 |
官方仓库列出的目标格式包括 Clash、Quantumult、Loon、Surge、V2Ray、SSR 等,但不同版本的支持范围和目标名称可能变化,部署时应以当前项目的 Supported Types 或配置说明为准。github.com
如果转换结果不是预期格式,按这个顺序检查:原始订阅能否在浏览器或命令行获取;target 是否使用项目支持的名称;url 是否完整编码;后端是否能访问原始订阅;最后再检查客户端是否支持该输出格式。
不要先修改十几个参数。先用最短链接验证 target 与 url,确认基础转换成功后,再逐个加入模板、节点筛选或其他选项。
局域网与公网访问:安全边界和回滚方法
本机访问:127.0.0.1 或 localhost 只用于当前设备,适合初次部署。若客户端和后端不在同一设备,不能直接假设本机地址可用。
局域网访问:需要让后端监听局域网地址,并在系统防火墙中放行对应端口。放行前先确认网络属于可信家庭或办公网络;测试结束后可以关闭端口或恢复仅本机监听。
公网访问:不要直接把带有真实订阅凭据的转换接口暴露在公网。至少应使用 HTTPS、访问令牌或认证、反向代理访问控制、限制来源和必要的日志脱敏。公网部署前先备份配置,记录域名、端口、证书和反向代理路径;回滚时恢复旧配置并撤销已暴露的订阅链接。
官方文档中,api_mode 与 api_access_token 用于限制部分接口访问;配置项是否存在、名称是否一致,应以当前版本的配置示例为准。不要把令牌写进公开仓库,也不要把它和订阅 URL 一起粘贴到故障报告中。github.com
如果使用带有管理界面或订阅库的其他自托管项目,也要查看其官方安全说明。例如 Sub-Store 官方仓库提醒,某些模块重写域名和推送 URL 可能涉及敏感数据,并说明了 CORS 白名单的配置边界;这类设置不能简单套用到其他项目。github.com
推荐的验证顺序:本机 /version → 本机转换 → 局域网访问 → HTTPS 反向代理 → 客户端自动更新。任一步失败,都先回到上一步,不要同时修改 DNS、端口、模板和客户端配置。
常见故障:按现象定位,而不是猜原因
- 访问 127.0.0.1:25500 失败:检查进程是否启动、Docker 容器是否运行、主机端口是否被占用,以及实际映射端口是否与访问地址一致。
- /version 正常,但 /sub 返回错误:先把问题拆成原始订阅获取、URL 编码、target 名称和输出格式四部分。浏览器能打开后端,不代表后端一定能访问原始订阅。
- 返回 403 或 404:检查是否访问了错误路径、反向代理是否改写了前缀、认证令牌是否缺失。不要把 403 直接判断为订阅失效。
- 客户端提示格式错误:将转换地址放入浏览器或命令行查看响应头和正文,确认返回的是 YAML、JSON、Base64 或目标客户端需要的文本,而不是 HTML 错误页。
- 容器启动后自动退出:执行
docker logs 容器名查看日志;先恢复默认配置,再逐项加入自定义文件。 - 生成链接很长或参数被截断:检查 URL 编码,尤其是
&、?、#和多个订阅之间的分隔符。不要手工删除看似多余的编码字符。 - 更新后突然不兼容:记录更新前的版本、镜像标签、配置文件和客户端版本;优先回滚到已验证的版本,再单独测试新版本。
常见问题
订阅转换一定要部署到 VPS 吗?
不一定。单台设备使用时,本机运行通常更简单;需要多台设备访问时再考虑局域网或 VPS。建议先在本机完成 /version、转换和客户端导入三步验证,再决定是否开放远程访问。
为什么本机能打开,手机却无法访问?
127.0.0.1 和 localhost 指向当前设备本身,手机访问时不会指向电脑。局域网使用需要确认后端监听地址、防火墙规则、电脑与手机是否在同一网络,以及访问时使用电脑的局域网地址和实际映射端口。
Docker 的 25500 端口必须固定吗?
不一定。容器内部端口通常按项目文档使用 25500,主机端口可以映射成其他值。例如映射为 15051 后,应访问主机的 15051 端口。端口变化后,健康检查地址、转换链接和反向代理配置都要同步修改。
转换地址放进客户端后提示 YAML 或 JSON 错误怎么办?
先不要继续改客户端参数。用浏览器或命令行查看转换地址实际返回的正文,确认不是 403、404、HTML 错误页或空响应;然后检查 target、原始订阅 URL 是否完整编码,以及输出格式是否被当前后端支持。
本地部署是否就一定不会泄露订阅?
不能绝对保证。自托管可以减少把订阅交给陌生公共转换服务的环节,但公网端口、反向代理日志、浏览器历史、备份文件、容器日志和公开仓库仍可能泄露凭据。部署后应限制访问、保护令牌、脱敏日志,并在怀疑泄露时及时更换订阅入口。