它围绕 Mihomo 内核的实际使用场景进行优化，提供更现代、更稳定的订阅转换能力。

核心定位：SubConverter-Extended 不再充当客户端与远程订阅服务商之间的“中转站”，而是作为独立的 配置融合器 运行。它只与客户端通信，不再主动连接远程订阅服务器；同时在编译阶段自动跟进 Mihomo 的协议支持。

远程订阅链接处理流程对比：

关键差异：SubConverter-Extended 仅负责生成配置，不再直接连接远程订阅服务器。

在长期使用 subconverter 的过程中，主要会遇到以下几个痛点：

原版 subconverter 对节点参数的支持高度依赖人工维护，其解析器的更新速度通常取决于开发者的时间与精力。

许多新兴协议（如 hysteria2、tuic、anytls 等）往往无法在第一时间获得完善支持；一些老协议（如 vless）也会因为传输层参数持续演进，而长期存在转换不完整的问题。

这一现象并非个别案例。在 subconverter 及其多个流行分支的仓库中，都能看到大量与协议支持相关的 issue。

问题的根源并不在于开发者是否足够积极，而在于这类人工维护模式本身就需要持续投入大量测试和适配成本，长期来看很难稳定覆盖所有协议与参数变化。

原版 subconverter 需要主动连接远程订阅服务商的订阅服务器拉取节点，而部分远程订阅服务商出于安全策略，会采取如下限制：

• 屏蔽海外 IP 访问
• 屏蔽 subconverter 的 User-Agent
• 限制非客户端发起的订阅请求

这会直接导致许多用户无法正常使用订阅转换服务。

对于按地区限制订阅访问的场景，原版 subconverter 无法从架构层面规避；对于 User-Agent 限制，虽然可以通过修改或删除特定 UA 进行绕过，但这本质上是在工具和服务商之间制造额外对抗，并不是稳妥的长期方案。

由于上述问题，subconverter 逐渐被一些开发者和内容创作者视为“过时方案”，转而推崇手动维护 YAML 配置。

但对大量普通用户而言，他们并不希望研究 YAML 细节，更需要的是一套基于 UI、可直接使用、问题边界清晰的操作流程。

现实情况是，在 subconverter 与远程订阅服务商限制叠加的情况下，用户经常会遇到无法解析节点、无法拉取节点、节点参数失效等问题；而新手用户通常也缺乏足够的排障能力。

正因如此，正如 Custom_OpenClash_Rules 项目一直坚持的理念：

理想状态应当是：用户拿到订阅链接后，只需进行少量可视化操作，就能按自身场景生成合适配置，并自动获得后续规则更新。

如果目标客户端本身基于 Mihomo 内核，那么订阅转换后端完全可以直接在配置文件中生成符合内核要求的 proxy-provider 字段，以取代过去“读取订阅内容 -> 解析节点 -> 回写节点参数”的旧流程。

这样一来，工具自身无需再承担远程订阅抓取与节点参数适配的职责，从架构上同时规避了协议支持滞后和服务商访问限制这两类问题。

对于本地节点链接解析，则可以直接引入 Mihomo 内核的解析器模块，替代原先需要人工维护的解析器逻辑，使订阅转换后端与 Mihomo 内核的解析能力保持一致。

基于这一思路，本项目只需跟随 Mihomo 内核更新，即可在绝大多数场景下自动获得同步的协议与参数支持，而无需重复投入额外的人工适配成本。

SubConverter-Extended 因此诞生。它是一款更贴合 Mihomo 使用场景的订阅转换工具，服务于所有保留“订阅转换”接口且使用 Mihomo 内核的 Clash 客户端。

使用 Mihomo 的 Proxy-Provider 机制

项目不再下载并解析远程订阅内容，而是生成客户端可直接使用的配置，交由用户客户端内置的 Mihomo 内核自行拉取订阅：

# SubConverter-Extended 生成示例内容

proxy-providers:
  Provider_A1B2C3:  # provider 名称可通过参数自定义
    type: http
    url: https://your-subscription-url  # 客户端实际拉取订阅的地址
    interval: 3600
    proxy: DIRECT  # 默认以直连方式拉取订阅
    path: ./providers/Provider_A1B2C3.yaml
    health-check:
      enable: true
      url: https://cp.cloudflare.com/generate_204
      interval: 300
    override:  # 将请求中附加的覆写参数透传给 provider
      skip-cert-verify: true
      udp: true

对于本地节点链接（如 vless:// 等格式）的处理，项目直接调用 Mihomo 的 Go 解析库，确保：

• ✅ 原生支持 Mihomo 内核可解析的全部节点链接协议（包括但不限于 hysteria2、tuic、anytls 等）
• ✅ 解析能力与 Mihomo 内核自动对齐，无需手动补丁式维护
• ✅ 新协议可随 Mihomo 更新同步获得支持

当远程外部配置、规则集或 !!import 引用的是 GitHub 原生文件地址时，后端会优先访问原始 GitHub 原始地址；当原始地址因网络问题无法正常获取时，自动改用 cdn.jsdelivr.net 加速地址重试。非 GitHub 地址不受影响。

此项改进旨在优化中国大陆地区的自部署用户使用托管在 GitHub 上的模板和规则时的访问性能。

支持的 GitHub 文件地址形式包括：

https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>
https://github.com/<owner>/<repo>/raw/<ref>/<path>
https://github.com/<owner>/<repo>/blob/<ref>/<path>

内置 explain=true 诊断模式和 /inspect 网页诊断台，方便在不改变实际转换逻辑的前提下排查请求：

• ✅ 展示请求参数是否被识别、是否生效、是否被项目安全逻辑覆盖
• ✅ 汇总外部配置、规则集、自定义组、Provider、输出大小等关键状态
• ✅ 对订阅来源等敏感信息只展示预览、长度或短哈希，便于排障时降低泄露风险

启用统计后，/dashboard 可展示服务运行期转换统计，适合公开服务部署者观察后端使用情况：

• ✅ 展示本次启动、历史总计、最近 24 小时和滚动时间窗口统计、访问者地理位置分布
• ✅ 按请求数和规则转换数展示国家 / 地区分布与排行
• ✅ 支持统计数据持久化和可选 Basic Auth 验证，便于公网部署时限制访问

• ✅ 无缝切换：兼容常见传统 subconverter API 接口，客户端侧几乎无需学习成本即可迁移
• ✅ 模板兼容：继续沿用传统外部模板，由后端内置逻辑确保 proxy-provider 模式在分流规则中正确生成
• ✅ 自动跟进：编译时自动遍历 Mihomo 内核源码仓库，提取最新解析模块、协议格式与可覆写参数

• ✅ 使用 Custom_OpenClash_Rules 远程配置模板，替代默认内置模板与自定义代理组功能
• ✅ 锁定 API 模式，强制关闭相关接口，降低新手误配置带来的安全风险
• ✅ 精简参数设计，聚焦高频核心场景

如果你不想自行部署，可以直接使用演示实例：

OpenClash 已内置该演示实例地址；在其他支持自定义后端的订阅转换网站或客户端中，也可以直接填入该地址进行调用。

推荐优先使用 Docker 部署；如果部署环境不方便运行容器，可以根据 Release 中的安装包类型选择便携包或 OpenWrt APK。

docker run -d \
  --name SubConverter-Extended \
  -p 25500:25500 \
  --restart unless-stopped \
  aethersailor/subconverter-extended:latest

# 删除可能存在的工作目录
rm -rf /opt/SubConverter-Extended

# 创建 SubConverter-Extended 工作目录
mkdir -p /opt/SubConverter-Extended/base

cd /opt/SubConverter-Extended

# 下载配置文件
wget -O base/pref.toml \
  https://gcore.jsdelivr.net/gh/Aethersailor/SubConverter-Extended@master/base/pref.example.toml

# 如需外部访问，请修改 base/pref.toml 中的 managed_config_prefix

# 启动容器并挂载配置
docker run -d \
  --name SubConverter-Extended \
  -p 25500:25500 \
  -v /opt/SubConverter-Extended/base/pref.toml:/base/pref.toml:ro \
  --restart unless-stopped \
  aethersailor/subconverter-extended:latest

docker run -d \
  --name SubConverter-Extended \
  -p 25500:25500 \
  -e MANAGED_CONFIG_PREFIX="http://your-domain-or-ip:25500" \
  -e SUBCONVERTER_SECURITY_PROFILE=public \
  -e SUBCONVERTER_ALLOW_PUBLIC_UPLOAD=false \
  --restart unless-stopped \
  aethersailor/subconverter-extended:latest

# 删除可能存在的工作目录
rm -rf /opt/SubConverter-Extended

# 创建 SubConverter-Extended 工作目录
mkdir -p /opt/SubConverter-Extended/base

cd /opt/SubConverter-Extended

# 下载 docker-compose 配置文件
wget -O docker-compose.yml \
  https://gcore.jsdelivr.net/gh/Aethersailor/SubConverter-Extended@master/docker-compose.yml

# 下载配置文件
wget -O base/pref.toml \
  https://gcore.jsdelivr.net/gh/Aethersailor/SubConverter-Extended@master/base/pref.example.toml

# 如需外部访问，请修改 docker-compose.yml 中的 MANAGED_CONFIG_PREFIX，
# 或修改 base/pref.toml 中的 managed_config_prefix

# 启动容器
docker compose up -d

docker logs -f SubConverter-Extended
docker restart SubConverter-Extended
docker rm -f SubConverter-Extended

uname -m

# 将 VERSION 替换为 Release 页面中的实际版本号，例如 v1.1.13
VERSION=v1.1.13
ARCH=amd64
INSTALL_DIR=/opt/SubConverter-Extended

mkdir -p "$INSTALL_DIR"
cd /tmp

curl -fLO "https://github.com/Aethersailor/SubConverter-Extended/releases/download/${VERSION}/SubConverter-Extended-${VERSION}-linux-${ARCH}.tar.gz"
curl -fLO "https://github.com/Aethersailor/SubConverter-Extended/releases/download/${VERSION}/SHA256SUMS"
sha256sum -c SHA256SUMS --ignore-missing

tar -xzf "SubConverter-Extended-${VERSION}-linux-${ARCH}.tar.gz" \
  -C "$INSTALL_DIR" \
  --strip-components=1

cd /opt/SubConverter-Extended
chmod +x start.sh subconverter

# 首次启动会自动从 base/pref.example.toml 创建 base/pref.toml
./start.sh

cat >/etc/systemd/system/subconverter-extended.service <<'EOF'
[Unit]
Description=SubConverter-Extended
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/SubConverter-Extended
ExecStart=/opt/SubConverter-Extended/start.sh
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now subconverter-extended
systemctl status subconverter-extended

PREF_PATH=/etc/subconverter/pref.toml /opt/SubConverter-Extended/start.sh

cd C:\SubConverter-Extended
.\start.ps1

powershell -ExecutionPolicy Bypass -File .\start.ps1

$env:PREF_PATH = "D:\subconverter\pref.toml"
& C:\SubConverter-Extended\start.ps1

set PREF_PATH=D:\subconverter\pref.toml
C:\SubConverter-Extended\start.bat

apk print-arch

# 将 VERSION 替换为 Release 页面中的实际版本号，例如 v1.1.13
VERSION=v1.1.13
ARCH="$(apk print-arch)"
PKG="/tmp/SubConverter-Extended-${VERSION}-openwrt-${ARCH}.apk"

wget -O "$PKG" \
  "https://github.com/Aethersailor/SubConverter-Extended/releases/download/${VERSION}/SubConverter-Extended-${VERSION}-openwrt-${ARCH}.apk"

apk add --allow-untrusted "$PKG"

/etc/init.d/subconverter-extended enable
/etc/init.d/subconverter-extended start

/etc/init.d/subconverter-extended restart
/etc/init.d/subconverter-extended stop
logread -e subconverter

整体使用方式与原版 subconverter 基本一致，常见客户端和订阅转换前端通常无需额外适配即可迁移。

下方仅重点说明本项目的高频参数、特有能力，以及与原版 subconverter 行为不同的部分；未列出的兼容参数仍可按原版 subconverter 的使用习惯传入。

https://api.asailor.org/sub?target=clash&url=https%3A%2F%2Fexample.com%2Fsub&config=https%3A%2F%2Fexample.com%2Fconfig.ini

https://api.asailor.org/sub?target=clash&url=provider%3AHK%2Chttps%3A%2F%2Fexample.com%2Fsub&include=%E9%A6%99%E6%B8%AF&emoji=true

https://api.asailor.org/sub?target=clash&url=https%3A%2F%2Fexample.com%2Fsub&explain=true

https://api.asailor.org/inspect

http://localhost:25500/inspect

http://localhost:25500/dashboard

https://sub.example.com/dashboard

http://localhost:25500/dashboard/data

[statistics]
enabled = true
data_dir = "stats"
flush_interval = 5

[statistics.geo]
provider = "header"
country_headers = ["CF-IPCountry", "X-Geo-Country", "X-Vercel-IP-Country", "CloudFront-Viewer-Country"]
china_region_headers = ["CF-Region-Code", "cf-region-code", "X-Geo-Subdivision"]

[statistics.dashboard_auth]
enabled = true
username = "admin"
password = "change-this-password"
max_failures = 5
window_seconds = 300
lock_seconds = 900

url=provider:HK,https://example.com/sub
url=provider:HK,https://a|provider:HK,https://b
url=provider%3AHK%2Chttps%3A%2F%2Fexample.com%2Fsub

支持三种格式：pref.toml（推荐）、pref.yml、pref.ini。

关键配置项：

[managed_config]
managed_config_prefix = "http://localhost:25500"  # 托管配置前缀

非本机部署时，请将该项修改为 SubConverter-Extended 实际部署机的 IP 地址或域名。

从本版本开始，主配置文件支持 [security] 安全档位，用于区分内网自用部署和公网暴露部署。

默认值为 lan，保持历史行为不变，适合家庭内网、NAS、软路由、旁路由、Docker 内网等自用场景。该档位允许访问本地资源、私有网段资源和 fake-ip 资源，因此现有部署通常无需额外修改配置。

公网部署建议显式切换为 public：

[security]
profile = "public"
allow_public_upload = false

INI 配置示例：

[security]
profile=public
allow_public_upload=false

Docker 环境变量示例：

docker run -d \
  --name SubConverter-Extended \
  -p 25500:25500 \
  -e SUBCONVERTER_SECURITY_PROFILE=public \
  -e SUBCONVERTER_ALLOW_PUBLIC_UPLOAD=false \
  --restart unless-stopped \
  aethersailor/subconverter-extended:latest

档位说明：

• lan：默认档位，保持旧行为，适合可信内网自用部署。
• public：公网推荐档位。限制公开请求参数、远程外部配置、公开 !!import 等不可信来源访问本地、私网和 fake-ip 字面量；项目自带本地模板、部署者配置的默认模板与可信本地配置仍可正常使用。
• strict：在 public 的基础上，始终禁止公开请求触发上传，即使设置 allow_public_upload=true 也不会放行。

latest 与版本标签均为多架构镜像，当前支持 linux/amd64、linux/arm64、linux/arm/v7。

本项目使用或引用了以下开源项目，在此表示感谢：

• MetaCubeX/mihomo - Clash 内核，提供节点链接解析能力
• Aethersailor/Custom_OpenClash_Rules - OpenClash 订阅转换模板、规则集与教程项目
• asdlokj1qpi233/subconverter - 原版 subconverter 项目

本项目基于 GPL-3.0 协议开源。