subconverter
这一页说明订阅转换对接配置。当前实现同时支持外部转换后端,以及 builtin 模式下的本地内置转换。
subconverter
yaml
subconverter:
enable: false
mode: builtin
template:
backend: "http://$Host:$Port/sub?target=$Target&new_name=true&url=$EncodedURL"
defaults:
target: ClashMeta注意
builtin 模式和外部 subconverter / sub-store 不是同一条执行路径。外部模式主要靠 template.backend 拼 URL;builtin 模式则直接走 koipy 内部转换逻辑。
subconverter.enable
解释
- 这项配置决定是否启用订阅转换流程。
- 对外部模式来说,启用后会在真正拉取前用模板重写成转换后端地址。
- 对
builtin模式来说,启用后会直接在本地执行转换,不依赖额外转换服务进程。 - 对
vmess://、trojan://这类协议链接来说,只有启用后,koipy 才会尝试把它们转成可测试订阅。
特性
- 类型:
bool - 默认值:
false - 关闭时,HTTP(S) 订阅按原链接获取;协议链接则不会自动转成可测试订阅内容。
- 如果原始链接里已经包含
target=参数,外部模式下当前订阅采集器会把它视为“已经转换过”,不会再次重写。
配置示例
yaml
subconverter:
enable: true
mode: builtin
defaults:
target: ClashMetasubconverter.mode
解释
- 这项配置用于告诉 koipy 当前走哪一类转换模式。
subconverter/substore主要参与默认host、port、target的推断,并配合模板拼接外部转换地址。builtin代表走本地内置转换器,不需要额外转换服务进程。
特性
- 类型:
str - 默认值:
builtin - 当
mode=substore时,默认端口会倾向3000,默认target会倾向ClashMeta。 - 即使你没写
mode=substore,只要模板里出现/download/sub,当前实现也会按 sub-store 风格推断部分默认值。 - 当
mode=builtin时,本地转换默认目标也会优先落到ClashMeta。
配置示例
yaml
subconverter:
enable: true
mode: substore
template:
backend: "http://$Host:$Port/download/sub?target=$Target&url=$EncodedURL&fakeSub=true"subconverter.template.backend
解释
- 这是转换后端的完整 URL 模板。
- 当前实现会做非常直接的字符串占位符替换,不是复杂的模板引擎。
- 当你把原始订阅链接塞进 query 参数时,应该优先使用
$EncodedURL,而不是$URL。 - 同理,如果你的后端参数名习惯用
content,也可以使用$Content/$EncodedContent。 - 这项主要给外部模式使用;
builtin模式下不会靠它发起真正的远程转换请求。
特性
- 类型:
str - 模板为空时,转换结果会是空字符串,等价于“没有可用后端模板”。
- 模板里的 URL scheme 还会参与默认
scheme推断。 - 新协议是否能成功转换,外部模式取决于你对接的转换后端本身;
builtin模式则取决于 koipy 当前内置转换能力。
配置示例
yaml
subconverter:
enable: true
mode: substore
template:
backend: "http://$Host:$Port/download/sub?target=$Target&url=$EncodedURL&fakeSub=true"subconverter.defaults
解释
- 这是模板默认参数字典。
host、port、scheme、target可以在这里显式指定,覆盖自动推断。- 你也可以放任意自定义键,例如
ua、config、emoji,然后在模板里通过$UA、$Config、$Emoji这类占位符读取。 - 在
builtin模式下,这一组里最常用的是target,其余参数更多是为外部模式准备的。
特性
- 类型:
dict - 默认
host是127.0.0.1 - 默认
port是25500;如果mode=substore或模板里出现/download/sub,默认端口会改成3000 - 默认
scheme优先取模板本身的 scheme;模板没写时回退到http - 默认
target是clash;如果走 sub-store 风格或builtin模式,则默认会倾向ClashMeta
配置示例
yaml
subconverter:
enable: true
template:
backend: "http://$Host:$Port/sub?target=$Target&url=$EncodedURL&ua=$EncodedUA"
defaults:
host: "127.0.0.1"
port: 25500
target: "ClashMeta"
ua: "clash-verge"占位符与编码
解释
- 当前稳定可用的核心占位符包括:
$Mode、$Scheme、$Host、$Port、$Target、$URL、$Content - 它们都支持对应的 URL 编码版本:
$EncodedMode、$EncodedURL、$EncodedContent等。 defaults里的任意键,也会自动生成$Key和$EncodedKey版本。- 键名匹配不严格区分大小写,像
ua、UA、Ua、user_agent这类常见变体,当前都会尝试注册出可用占位符。 $Mode当前可能是subconverter、substore或builtin。
特性
- 协议链接和普通 HTTP 订阅都会走同一套占位符替换逻辑。
- 当原始值需要出现在 query 参数里时,优先使用
Encoded版本更稳妥。 - 如果模板后端要求的参数名不是
url,你可以自由改成content、src或其它名字,koipy 不做限制。
配置示例
yaml
subconverter:
enable: true
mode: substore
template:
backend: "http://$Host:$Port/download/sub?target=$Target&url=$EncodedURL&config=$EncodedConfig&fakeSub=true"
defaults:
config: "my-collection"生效时机
解释
- 如果用户输入的是普通 HTTP(S) 订阅链接,外部模式下 koipy 会在真正下载前决定是否按模板重写;
builtin模式下则会在下载后直接本地转换内容。 - 如果用户输入的是
vmess://...这类协议链接,且subconverter.enable=true,koipy 会先进入转换流程;外部模式是包装成远程转换 URL,builtin模式是直接本地转换。 - 如果原始 URL 里已经带有
target=,外部模式下当前实现会把它认作“已经是转换后链接”,不会二次转换。 - 如果单次任务设置了
runtime.disableSubCvt=true,则会跳过这套转换流程。
特性
- 这套逻辑既影响手动输入链接,也影响规则中的
url。 - 外部模式下,koipy 主要负责拼链接;最终仍要看目标转换服务返回的内容是否可解析。
builtin模式下,转换发生在 koipy 进程内部,省掉了额外服务进程,但当前仍应视为实验性路径。- 如果你对接的是 sub-store,而模板或 target 写成了不兼容的目标格式,最常见的表现就是“拉取成功但节点为空”。
配置示例
yaml
subconverter:
enable: true
mode: builtin
defaults:
target: ClashMeta关于单次任务里临时禁用订阅转换,可参考:
相关内容
