订阅转换搭建教程:Docker、HTTPS与安全验收完整指南
简答:订阅转换搭建的稳妥顺序是:先确认客户端确实需要转换,再用 Docker 部署后端,将服务仅绑定本机端口,最后通过 Caddy 反向代理提供 HTTPS。部署完成后,必须检查版本接口、转换结果、节点数量、协议类型和原始订阅凭据是否泄露。
定义:订阅转换是把一个或多个原始订阅地址读取、解析并重新输出为指定客户端所需配置格式的服务。
先判断:你是否真的需要搭建订阅转换
如果客户端原生支持你的订阅格式,优先使用原始订阅,不必额外增加转换服务。只有在客户端格式不兼容、需要合并多条订阅、需要按关键词筛选节点,或需要统一输出给不同客户端时,搭建转换后端才有实际意义。
本文是第三方指南站的技术整理,服务名称、镜像版本和具体兼容性应以项目仓库及本机实际返回结果为准。subconverter 的原始项目说明了 Docker 镜像、25500 端口和 /version 检查方式,参数实现则以项目源码为准。官方 Docker 说明 官方参数处理源码
| 方式 | 适合场景 | 优点 | 主要风险 |
|---|---|---|---|
| 在线转换 | 临时测试、低敏感订阅 | 不用维护服务器 | 原始订阅可能经过第三方服务,凭据暴露面更大 |
| 本机部署 | 个人电脑或局域网使用 | 订阅不必公开到公网 | 设备关机后服务不可用 |
| 公网自建 | 多设备、团队或长期使用 | 可统一入口和格式 | 必须处理 HTTPS、访问控制、日志和滥用请求 |
如果原始订阅已经能被目标客户端识别,直接导入通常比再增加一个转换环节更容易排查。若必须转换,建议先在本机完成验证,再考虑公网发布。
前置检查:服务器、域名与凭据保护
- 准备服务器:建议使用一台你有管理权限的 Linux 服务器,并确认可以执行 Docker 命令。Docker 官方文档列出了支持的平台及安装路径,Ubuntu 环境应优先按照官方软件源步骤安装 Docker Engine。Docker Engine Ubuntu 安装文档
- 准备域名:将用于访问转换服务的域名 A 或 AAAA 记录指向服务器。不要把原始订阅链接写入公开网页、聊天记录或截图。
- 检查端口:公网通常只需要让反向代理接收 80 和 443 端口,转换后端的 25500 端口不应直接暴露给所有访问者。Docker 官方提醒,发布容器端口可能绕过部分主机防火墙规则,因此应额外检查 Docker 与防火墙的组合行为。Docker 防火墙注意事项
- 准备回退方案:记录原始订阅地址的来源、当前客户端配置和服务器快照。不要把真实订阅令牌直接放进 shell 历史、公开仓库或反向代理日志。
截至 2026-11-13,项目公开资料中能核实的是 Docker 镜像、默认服务端口、版本检查接口及部分参数;具体镜像是否适合你的架构、当前构建是否包含某种新协议,需在本机拉取后核实,不应仅凭名称推断。
用 Docker 部署 subconverter 后端
以下示例把容器内部的 25500 端口映射到主机的 127.0.0.1:25500,使后端只接受本机反向代理访问。若你要先在局域网测试,可暂时改为服务器内网地址,但不建议直接绑定公网地址。
mkdir -p ~/subconverter
cd ~/subconverter
docker pull tindy2013/subconverter:latest
docker run -d --name subconverter --restart=always -p 127.0.0.1:25500:25500 tindy2013/subconverter:latest
docker ps
curl http://127.0.0.1:25500/version
官方 Docker 说明给出了容器启动、端口映射和 curl http://localhost:25500/version 检查方法;本文将端口绑定到 127.0.0.1,是为了减少后端直接暴露公网的范围。subconverter Docker 部署说明
如果返回类似项目说明中的后端版本文本,说明进程已响应;如果没有返回,先查看日志:
docker logs --tail=100 subconverter
docker inspect subconverter
ss -lntp | grep 25500
不要把 latest 当作长期固定版本。项目发布页可以用于查看可用版本和变更记录;生产环境如需固定版本,应先在测试环境验证,再替换为明确标签,具体标签以发布页实际存在的内容为准。subconverter 发布页
用 Caddy 配置域名与 HTTPS 反向代理
将转换后端放在本机端口后,再使用 Caddy 接收域名请求。Caddy 官方文档说明,域名解析到服务器、80 和 443 端口可访问,并且 Caddy 数据目录可写时,Caddy 可以自动申请和续期证书。Caddy Automatic HTTPS 文档
安装 Caddy 后,创建 Caddyfile:
convert.example.com {
reverse_proxy 127.0.0.1:25500
}
将 convert.example.com 替换为你自己的域名,然后检查并加载配置:
caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
Caddy 的反向代理快速入门也采用“域名反代到本机端口”的结构;如果使用公开域名,80 和 443 必须能从互联网访问,否则证书签发或 HTTP 到 HTTPS 跳转可能失败。Caddy 反向代理快速入门
公网服务不要直接把后端端口写成服务器公网地址,也不要在网页中展示包含真实订阅令牌的示例。若服务需要长期公开使用,应在反向代理层或上游网关增加访问控制、请求频率限制和最小化日志;具体鉴权方式取决于你选择的部署组件,未核实的参数不要照抄。
调用转换接口:target、url、config与筛选参数
subconverter 的调用通常围绕目标格式和原始订阅地址展开。项目源码中可以核实到 target、url、config、include、exclude、emoji、udp、rename 等参数的读取逻辑,但不同目标格式对节点字段的支持仍需以实际输出为准。参数读取与转换源码
| 参数 | 作用 | 使用建议 |
|---|---|---|
| target | 选择输出格式 | 先按客户端名称选择,再用客户端导入测试 |
| url | 提供一个或多个原始订阅地址 | 真实地址不要出现在公开文档和截图中 |
| config | 指定外部配置 | 确认配置地址可信、可访问且格式匹配 |
| include | 按正则或关键词保留节点 | 先使用简单关键词,避免正则写错导致节点为空 |
| exclude | 按正则或关键词排除节点 | 与 include 同时使用时,先核对最终剩余数量 |
| emoji | 控制节点名称中的图标处理 | 只影响名称显示,不等同于协议兼容 |
| udp | 请求输出 UDP 相关设置 | 客户端和节点协议都支持时再开启 |
示例请求应使用占位符,避免把真实订阅泄露到浏览器历史或服务器日志:
https://convert.example.com/sub?target=clashr&url=ENCODED_SUBSCRIPTION_URL
多个订阅合并、节点重命名和分组属于转换逻辑,不代表所有输出客户端都支持相同字段。若转换后节点减少,先去掉 include、exclude 和自定义 config,再重新转换,以区分筛选问题与协议解析问题。
面向不同客户端选择输出格式
| 客户端类型 | 先核对什么 | 常见失败表现 |
|---|---|---|
| Clash 或 Mihomo | 目标格式、代理字段、规则和策略组 | 配置能导入但部分节点消失 |
| sing-box | 输出是否包含客户端支持的 inbound、outbound 和传输字段 | JSON 能下载但启动时报字段错误 |
| Surge、Loon、Quantumult X | 目标格式及远程配置结构 | 订阅地址能打开但规则或策略组不完整 |
不要只看“文件能下载”就判断转换成功。真正的验收应包括:目标客户端能否解析、节点数量是否合理、协议名称是否仍然存在、服务器地址是否与原始订阅一致,以及规则和策略组是否来自你信任的来源。
项目配置说明中还涉及 API 模式、访问令牌、规则集、缓存和日志等配置项;这些字段在不同版本中的行为可能变化,部署时应以仓库中的配置示例和本机版本为准。subconverter 中文配置说明
部署完成后的5项验收清单
- 服务检查:执行
curl http://127.0.0.1:25500/version,确认后端能响应。 - HTTPS检查:通过域名访问时确认浏览器显示有效证书,并检查 HTTP 请求是否按配置跳转到 HTTPS。
- 节点数量检查:记录原始订阅可见节点数量,再与转换结果比较。数量变化时,先排除 include、exclude、config 和协议不兼容。
- 内容检查:核对节点名称、协议类型、服务器地址、端口和传输字段,不要只检查文件是否返回 200。
- 更新检查:等待一次客户端订阅更新,确认服务仍可访问,并查看 Docker 日志中是否出现原始订阅地址、令牌或完整请求参数。
如果日志中出现完整订阅链接,先停止公开访问,清理日志并到原服务商后台重置订阅链接,再重新导入新的地址。不要只删除浏览器记录,因为已经写入服务器日志的令牌仍可能被读取。
失败回退:按现象区分问题位置
| 现象 | 优先检查 | 回退动作 |
|---|---|---|
| 域名无法打开 | DNS、80/443端口、Caddy状态和证书日志 | 先用本机 127.0.0.1:25500 检查后端,再恢复反代 |
| /version 无响应 | 容器状态、端口映射和 Docker 日志 | 停止并删除容器后按已验证命令重新创建 |
| 转换返回空结果 | 原始订阅是否过期、include/exclude 是否过严 | 去掉筛选参数,先只保留 target 与 url |
| 节点数量明显减少 | 协议兼容、外部配置和解析错误 | 直接用原始订阅导入客户端,确认问题是否只发生在转换链路 |
| 订阅令牌出现在日志 | 访问日志、Docker 日志和代理层日志 | 立即到服务商后台重置订阅链接,并更换服务访问凭据 |
如果回退到原始订阅后客户端仍然无法连接,问题就不一定在转换服务,可能还涉及客户端格式、网络、DNS、MTU 或节点本身。此时应保留一份未经转换的原始配置,用于分段定位。
常见问题
订阅转换搭建一定要买服务器吗?
不一定。只给自己使用时,可以先在本机或局域网运行;需要多台设备长期访问时,才考虑公网服务器。公网部署会增加 HTTPS、访问控制、日志和滥用防护等维护工作。
为什么 Docker 容器运行了,但域名打不开?
先区分后端和反向代理:执行本机的 /version 检查后端,再检查域名 DNS、80 和 443 端口、Caddy 服务状态及证书日志。后端能响应而域名打不开,通常应优先检查反代和端口。
转换后节点变少,是服务坏了吗?
不一定。include、exclude、外部 config、协议解析失败或原始订阅已变化,都可能造成节点减少。先去掉筛选和自定义配置,只用 target 加 url 转换,再对比数量和协议类型。
可以把 25500 端口直接开放到公网吗?
不建议。更合理的结构是后端只绑定 127.0.0.1:25500,由 Caddy 或其他反向代理提供 HTTPS 入口。这样可以减少后端直接暴露,并便于集中处理证书、访问控制和日志。
订阅链接泄露后只改密码可以吗?
不能只改服务登录密码。订阅链接本身通常包含访问凭据,发现它进入日志、截图或公开页面后,应立即到原服务商后台重置订阅链接,再在转换服务和客户端中替换新地址。