订阅转换后端：API、格式选择与自建部署指南
简答：订阅转换后端负责读取原始订阅链接，并按目标客户端生成 Clash、mihomo、sing-box、Surge、Quantumult X、Loon、V2Ray 等格式；前端网页只是调用后端的操作界面。最稳妥的做法是先确认目标客户端，再使用本地部署的 API 转换，避免把带凭据的订阅链接直接交给不明公共服务。
定义：订阅转换后端，是接收原始订阅地址、解析节点或配置内容，并输出指定客户端格式文件或可持续更新链接的服务程序。
先判断：你需要的是前端网页，还是订阅转换后端？
如果你的目标只是“粘贴链接并生成配置”，你看到的网页通常是前端；真正完成解析、过滤、格式生成和接口响应的是后端。前端可以调用远程后端，也可以调用你自己电脑或服务器上的后端。
两者的关系可以简单理解为：前端负责填写参数，后端负责转换内容，客户端负责定时读取结果。因此，网页能打开并不代表后端一定可用；后端能返回文本，也不代表目标客户端一定兼容其中的协议。
本文不提供一个未经核验的公共转换入口，而是给出可复现的本地 API 方案。若使用公共服务，应先确认其域名、隐私政策、日志策略和数据处理边界。
| 部分 | 主要作用 | 常见问题 |
|---|---|---|
| 前端网页 | 输入订阅地址、目标格式、规则或过滤条件 | 页面打不开、参数丢失、生成链接失效 |
| 转换后端 | 读取订阅、解析节点、生成目标配置 | 超时、格式不支持、远程配置不可用 |
| 客户端 | 导入生成的文件或订阅链接并使用配置 | 格式不识别、协议不支持、版本差异 |
Sub-Store 文档说明，保存后的订阅可以转换为多种客户端格式，并可通过 target 参数强制指定输出目标；其输出列表包含 mihomo、sing-box、Surge、Loon、Quantumult X、V2Ray 等。可查看Sub-Store 订阅转换文档核对当前支持范围。
格式怎么选：先按客户端决定 target
不要先随意选择“Clash”或“通用格式”，应先确认客户端名称和配置类型。不同客户端可能要求 YAML、JSON、纯文本节点列表或专用配置文件；即使转换后端接受同一个输入，也不代表所有输出都能直接导入。
| 使用场景 | 优先尝试的目标 | 核对重点 |
|---|---|---|
| 使用 mihomo 或 Clash.Meta | mihomo、clashmeta 或项目指定的 Clash Meta 目标 | YAML结构、代理组、规则集和协议字段 |
| 使用 sing-box | sing-box 或 singbox | JSON结构、入站出站字段、协议支持情况 |
| 使用 Surge | surge 或对应版本目标 | Surge支持的协议、规则格式和版本差异 |
| 使用 Quantumult X | quanx 或 qx | 节点语法、策略组和远程规则格式 |
| 使用 Loon | loon | 节点类型、策略组和脚本引用 |
| 只需要节点链接 | v2ray、ss、ssr 等 | 输出是链接或节点文本，不一定是完整配置 |
subconverter 的项目文档列出了多种输入和输出类型，包括 Clash、Quantumult X、Loon、Surge、V2Ray、Surfboard 和 SSR，并明确说明目标名称需要按项目支持表填写。Shadowrocket 等客户端应根据其实际导入方式选择节点链接类目标，而不是盲目使用 Clash 配置。具体可核对subconverter 支持格式与接口说明。
最短可复现流程：本地启动后端并生成订阅链接
- 准备原始订阅地址。确认它能在浏览器或命令行中返回内容，并妥善隐藏其中的账号凭据。不要把真实订阅地址提交到公开工单、截图或聊天记录。
- 准备运行环境。如果使用 Docker，可按项目文档启动本地服务：
docker run -d --restart=always -p 25500:25500 tindy2013/subconverter:latest该项目的 Docker 文档给出的默认服务端口是 25500，并建议通过以下接口确认服务是否已启动：
curl http://localhost:25500/version当返回后端版本文本时，只能说明本地进程已响应，不代表你的订阅一定能被解析，也不代表目标客户端一定兼容。
- 选择目标格式并对订阅地址进行 URL 编码。后端接口通常要求把原始订阅地址作为
url参数传入。地址中的?、&、#、|等字符如果没有正确编码，可能导致参数被截断。 - 调用转换接口。基本结构如下：
http://127.0.0.1:25500/sub?target=clash&url=%E5%B7%B2%E7%BC%96%E7%A0%81%E7%9A%84%E8%AE%A2%E9%98%85%E5%9C%B0%E5%9D%80其中 target 是目标格式，url 是经过 URL 编码的原始订阅地址。若要使用远程配置，还可以按项目文档传入编码后的 config 参数。
- 先在浏览器或命令行查看返回内容。检查 HTTP 状态、内容类型、是否出现空配置、错误文本或未解析的原始链接。
- 再导入客户端。如果客户端支持远程订阅，使用本地服务所在设备可访问的地址；如果客户端运行在另一台设备上，不能直接使用只绑定到
127.0.0.1的地址，需要在确认访问控制后改为局域网或受保护的服务器地址。
对于只在本机使用的情况，绑定本地回环地址更安全；若必须开放到其他设备，应增加 HTTPS、访问令牌、防火墙限制和反向代理保护。不要把包含订阅凭据的接口直接暴露到公网。
API 参数怎么理解：url、target、config 与多订阅合并
常见后端接口的核心参数并不复杂，但每个参数都有适用边界。
| 参数 | 作用 | 使用注意 |
|---|---|---|
url | 指定原始订阅地址或输入文件 | 通常需要 URL 编码；真实凭据不要泄露 |
target | 指定输出格式 | 名称必须以当前后端支持表为准 |
config | 指定远程或本地配置文件 | 配置文件也可能包含远程规则和额外请求 |
filter、过滤参数 | 按名称保留或排除节点 | 不同后端参数名和匹配规则可能不同 |
| 多订阅地址 | 把多个输入合并后再转换 | 先用项目规定的分隔符组合，再统一编码 |
subconverter 文档给出的接口结构是 /sub?target=%TARGET%&url=%URL%&config=%CONFIG%，并说明多个订阅可以先用竖线连接，再进行 URL 编码。其示例还提醒，目标名称应从项目支持列表中取得，而不是自行拼写。
另一个可自建的开源实现 sub-store-convert 提供了类似的 GET /sub?target=&url= 接口，并支持本地服务、命令行、Docker 和 Cloudflare Workers 等部署方式。该项目文档列出 mihomo、sing-box、surge、qx、loon、v2ray 和 json 等目标名称，但实际输入能否解析仍取决于原订阅内容。
隐私与安全：公共后端和自建后端分别检查什么？
订阅地址通常不只是普通网页链接，可能包含账户标识、到期信息、流量信息或可直接获取配置的凭据。因此，转换后端的风险重点不是“格式能不能转”，而是“谁能看到输入、输出和访问日志”。
- 公共后端：先确认是否使用 HTTPS、是否说明访问日志、是否缓存请求参数、是否限制管理员查看，以及生成的结果是否可能被公开索引。无法核验时，不要提交真实订阅。
- 本地后端：优先绑定
127.0.0.1，只在确有需要时开放局域网访问；若部署到服务器，应配置防火墙、强随机访问令牌和 HTTPS。 - 日志：检查访问日志是否直接记录完整查询字符串。若 URL 中带凭据，日志可能成为额外泄露点。
- 缓存：确认反向代理、CDN或应用是否缓存带有个人订阅信息的响应；不需要缓存时应关闭或缩短缓存。
- 远程配置：规则文件和模板可能继续访问其他地址，使用前应确认来源、内容和更新方式。
- 恢复：如果怀疑订阅地址泄露，应在订阅提供方后台重置或重新生成，而不是只删除浏览器记录。
自建不等于自动安全。部署完成后，至少要用一条测试订阅验证响应，再检查公网端口、访问日志、容器环境变量和备份文件中是否出现完整订阅地址。
转换失败怎么排查：按顺序缩小问题范围
- 先测原始订阅。如果原始地址本身返回 401、403、超时、空内容或 HTML 登录页，后端无法正常转换。先处理账户、权限或网络访问问题。
- 再测后端健康状态。访问本地
/version或项目提供的健康检查接口，确认进程仍在运行。 - 检查编码。重点查看原始地址中的
&、问号、井号和多个订阅之间的分隔符是否被正确编码。 - 换成最简单目标。暂时移除远程配置、过滤和重命名参数，只保留
target与url，判断是输入解析失败还是模板处理失败。 - 核对协议支持。如果原订阅包含目标客户端不支持的协议，可能出现节点减少、空配置或导入后无法连接。Sub-Store 文档也提示，某些不被客户端原生支持的协议需要额外参数，且最终连通性仍取决于客户端和服务端能力。
- 检查配置大小与超时。节点数量多、远程规则多或服务器访问慢时，可能触发请求超时。可以先减少节点、去掉远程规则，再逐项恢复。
- 最后检查客户端。如果后端返回的是完整配置，但客户端提示格式错误，检查导入类型、文件扩展名、客户端版本和目标名称，不要直接重复生成同一条链接。
成功标准应分为三层：后端返回 HTTP 成功；返回内容结构正确；客户端导入后能识别节点或配置。只有三层都通过，才算完成转换。
自建前的核验清单
- 是否知道原始订阅的输入格式和有效期？
- 是否确认目标客户端与目标格式对应？
- 是否把订阅地址和远程配置地址分别进行 URL 编码？
- 是否先在本机验证，再开放局域网或公网访问？
- 是否限制管理端口、API端口和调试接口？
- 是否关闭不必要的访问日志、缓存和自动上传功能？
- 是否准备了原始订阅备份，但没有把备份提交到公开仓库？
- 是否记录了后端版本、目标格式和客户端版本，方便复现问题？
如果你不需要自动更新，只是偶尔转换一次，可以优先使用本地命令行或本地 HTTP 服务；如果需要客户端持续刷新，则应重点检查生成链接的访问权限、缓存和订阅地址泄露风险。
常见问题
订阅转换后端和在线订阅转换网页有什么区别？
在线网页通常是前端界面，负责收集订阅地址和目标格式；后端负责真正读取、解析和生成配置。网页可以调用公共后端，也可以调用你自己部署的本地后端。
订阅转换后端一定要部署在服务器上吗？
不一定。只在自己电脑上转换时，可以使用本地 Docker 或本地程序，并绑定 127.0.0.1；只有需要多台设备访问或客户端定时读取时，才考虑部署到局域网或服务器，并补充 HTTPS、访问控制和防火墙规则。
为什么转换成功，但客户端仍然不能使用？
后端成功只代表生成了文本或配置，不代表客户端支持其中的协议、规则或字段。应先检查输出格式，再核对客户端版本、导入类型、协议支持和远程规则是否可访问。
多个订阅地址如何合并？
要以当前后端文档规定的分隔符连接多个地址，再整体进行 URL 编码。subconverter 文档示例使用竖线连接多个订阅，但不同项目的参数实现可能不同，应以实际项目文档为准。
公共转换后端安全吗？
不能仅凭网页能打开就判断安全。订阅地址可能包含凭据，使用前应核对 HTTPS、日志、缓存、访问控制和数据保留说明；无法核验时，建议先用测试订阅或改为本地部署。
找不到适合的 target 名称怎么办？
不要自行猜测参数名。先查看后端的支持格式表，再根据客户端名称选择目标；例如同一类客户端可能存在不同版本或专用输出，名称和兼容范围应以当前项目文档为准。