{"id":35559619,"url":"https://github.com/aethersailor/subconverter-extended","last_synced_at":"2026-07-08T05:00:32.102Z","repository":{"id":331417737,"uuid":"1115782640","full_name":"Aethersailor/SubConverter-Extended","owner":"Aethersailor","description":"基于 subconverter 二次开发的订阅转换后端 Mihomo 专用增强版：无需拉取远程订阅内容即可完成转换，规避订阅源访问屏蔽；接入 Mihomo 原生解析能力并自动跟随上游协议/参数变化，实现完美解析节点链接，同时兼容原版模板。增加仪表盘等有趣功能。","archived":false,"fork":false,"pushed_at":"2026-07-08T03:20:14.000Z","size":9762,"stargazers_count":796,"open_issues_count":7,"forks_count":88,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-07-08T03:26:17.158Z","etag":null,"topics":["clash","clash-meta","hysteria","hysteria2","mihomo","openclash","subconverter","vless","vless-reality"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Aethersailor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-profiles.zh-CN.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-13T14:44:38.000Z","updated_at":"2026-07-08T02:59:17.000Z","dependencies_parsed_at":"2026-04-09T05:00:55.032Z","dependency_job_id":null,"html_url":"https://github.com/Aethersailor/SubConverter-Extended","commit_stats":null,"previous_names":["aethersailor/subconverter-extended"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/Aethersailor/SubConverter-Extended","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aethersailor%2FSubConverter-Extended","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aethersailor%2FSubConverter-Extended/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aethersailor%2FSubConverter-Extended/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aethersailor%2FSubConverter-Extended/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Aethersailor","download_url":"https://codeload.github.com/Aethersailor/SubConverter-Extended/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Aethersailor%2FSubConverter-Extended/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35252324,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clash","clash-meta","hysteria","hysteria2","mihomo","openclash","subconverter","vless","vless-reality"],"created_at":"2026-01-04T10:15:00.267Z","updated_at":"2026-07-08T05:00:32.087Z","avatar_url":"https://github.com/Aethersailor.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cp\u003e\n  \u003cimg src=\"design/favicon-light-proposal.svg#gh-light-mode-only\" alt=\"SubConverter-Extended icon\" width=\"96\" height=\"96\"\u003e\n  \u003cimg src=\"design/favicon-dark-proposal.svg#gh-dark-mode-only\" alt=\"SubConverter-Extended icon\" width=\"96\" height=\"96\"\u003e\n\u003c/p\u003e\n\n# SubConverter-Extended\n\n**A Modern Evolution of subconverter**\n\n![GitHub Tag](https://img.shields.io/github/v/tag/Aethersailor/SubConverter-Extended?style=flat\u0026logo=github\u0026label=version\u0026color=blue)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/Aethersailor/SubConverter-Extended/build-dockerhub.yml?branch=master\u0026style=flat\u0026label=docker%20build\u0026logo=GitHub%20Actions)\n[![Docker Pulls](https://img.shields.io/docker/pulls/aethersailor/subconverter-extended?style=flat\u0026logo=docker)](https://hub.docker.com/r/aethersailor/subconverter-extended)\n[![License](https://img.shields.io/badge/license-GPL--3.0-orange?style=flat)](LICENSE)\n\n\u003ch3\u003e⚡ 现代化的订阅转换后端 | 深度适配 Mihomo 内核 ⚡\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-项目简介\"\u003e项目简介\u003c/a\u003e •\n  \u003ca href=\"#-立项原因\"\u003e立项原因\u003c/a\u003e •\n  \u003ca href=\"#-核心特性\"\u003e核心特性\u003c/a\u003e •\n  \u003ca href=\"#-快速开始\"\u003e快速开始\u003c/a\u003e •\n  \u003ca href=\"#-使用说明\"\u003e使用说明\u003c/a\u003e •\n  \u003ca href=\"#-配置说明\"\u003e配置说明\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## 📖 项目简介\n\n\u003e [!NOTE]\n\u003e **SubConverter-Extended** 是基于 [asdlokj1qpi233/subconverter](https://github.com/asdlokj1qpi233/subconverter) 深度二次开发的订阅转换后端增强版本，重点解决传统 subconverter 易被远程订阅服务商屏蔽、节点参数解析不完善、维护滞后等问题。\n\n它围绕 [Mihomo](https://github.com/MetaCubeX/mihomo) 内核的实际使用场景进行优化，提供更现代、更稳定的订阅转换能力。\n\n**核心定位**：SubConverter-Extended 不再充当客户端与远程订阅服务商之间的“中转站”，而是作为独立的 **配置融合器** 运行。它只与客户端通信，不再主动连接远程订阅服务器；同时在编译阶段自动跟进 Mihomo 的协议支持。\n\n**远程订阅链接处理流程对比：**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/readme-flow-legacy.svg\" alt=\"传统 subconverter 远程订阅链接处理流程\" width=\"820\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/readme-flow-extended.svg\" alt=\"SubConverter-Extended 远程订阅链接处理流程\" width=\"820\"\u003e\n\u003c/p\u003e\n\n**关键差异**：SubConverter-Extended 仅负责生成配置，不再直接连接远程订阅服务器。\n\n\u003e [!WARNING]\n\u003e 1. 本项目保持中立，不提供任何规避监管制度的功能。\n\u003e 2. 本项目仅用于计算机编程技术学习与研究，使用时请严格遵守当地法律法规，请勿用于任何非法用途。\n\u003e 3. 建议始终使用合法合规的第三方服务商。\n\n---\n\n## 💡 立项原因\n\n### 遇到的问题\n\n在长期使用 subconverter 的过程中，主要会遇到以下几个痛点：\n\n#### 1. 协议支持滞后 🐢\n\n原版 subconverter 对节点参数的支持高度依赖人工维护，其解析器的更新速度通常取决于开发者的时间与精力。\n\n许多新兴协议（如 `hysteria2`、`tuic`、`anytls` 等）往往无法在第一时间获得完善支持；一些老协议（如 `vless`）也会因为传输层参数持续演进，而长期存在转换不完整的问题。\n\n这一现象并非个别案例。在 subconverter 及其多个流行分支的仓库中，都能看到大量与协议支持相关的 issue。\n\n问题的根源并不在于开发者是否足够积极，而在于这类人工维护模式本身就需要持续投入大量测试和适配成本，长期来看很难稳定覆盖所有协议与参数变化。\n\n#### 2. 远程订阅服务商屏蔽问题 🚫\n\n原版 subconverter 需要主动连接远程订阅服务商的订阅服务器拉取节点，而部分远程订阅服务商出于安全策略，会采取如下限制：\n\n* 屏蔽海外 IP 访问\n* 屏蔽 subconverter 的 User-Agent\n* 限制非客户端发起的订阅请求\n\n这会直接导致许多用户无法正常使用订阅转换服务。\n\n对于按地区限制订阅访问的场景，原版 subconverter 无法从架构层面规避；对于 User-Agent 限制，虽然可以通过修改或删除特定 UA 进行绕过，但这本质上是在工具和服务商之间制造额外对抗，并不是稳妥的长期方案。\n\n#### 3. 新手友好度不足 🤯\n\n由于上述问题，subconverter 逐渐被一些开发者和内容创作者视为“过时方案”，转而推崇手动维护 YAML 配置。\n\n但对大量普通用户而言，他们并不希望研究 YAML 细节，更需要的是一套基于 UI、可直接使用、问题边界清晰的操作流程。\n\n现实情况是，在 subconverter 与远程订阅服务商限制叠加的情况下，用户经常会遇到无法解析节点、无法拉取节点、节点参数失效等问题；而新手用户通常也缺乏足够的排障能力。\n\n正因如此，正如 [Custom_OpenClash_Rules](https://github.com/Aethersailor/Custom_OpenClash_Rules) 项目一直坚持的理念：\n\n\u003e [!IMPORTANT]\n\u003e **最适合新手和普通用户、且最具普适性的操作流程，始终是基于 UI 的操作流程。**\n\n理想状态应当是：用户拿到订阅链接后，只需进行少量可视化操作，就能按自身场景生成合适配置，并自动获得后续规则更新。\n\n### 🎯 解决方案\n\n如果目标客户端本身基于 Mihomo 内核，那么订阅转换后端完全可以直接在配置文件中生成符合内核要求的 `proxy-provider` 字段，以取代过去“读取订阅内容 -\u003e 解析节点 -\u003e 回写节点参数”的旧流程。\n\n这样一来，工具自身无需再承担远程订阅抓取与节点参数适配的职责，从架构上同时规避了协议支持滞后和服务商访问限制这两类问题。\n\n对于本地节点链接解析，则可以直接引入 Mihomo 内核的解析器模块，替代原先需要人工维护的解析器逻辑，使订阅转换后端与 Mihomo 内核的解析能力保持一致。\n\n基于这一思路，本项目只需跟随 Mihomo 内核更新，即可在绝大多数场景下自动获得同步的协议与参数支持，而无需重复投入额外的人工适配成本。\n\nSubConverter-Extended 因此诞生。它是一款更贴合 Mihomo 使用场景的订阅转换工具，**服务于所有保留“订阅转换”接口且使用 Mihomo 内核的 Clash 客户端**。  \n\n---\n\n## ✨ 核心特性\n\n### 🚀 相对原版的重大改进\n\n| 功能 | 原版 Subconverter | SubConverter-Extended |\n| :--- | :--- | :--- |\n| **节点链接解析** | 🛠️ 人工维护解析器，支持有限 | 🤖 **集成 Mihomo 内核解析模块，自动对齐协议支持** |\n| **订阅链接处理** | 📥 拉取并解析订阅，容易被屏蔽 | 🔗 **生成 `proxy-provider`，由客户端 Mihomo 内核直接拉取订阅** |\n| **协议维护方式** | ⏳ 依赖人工新增和维护 | 🔄 **编译时自动扫描 Mihomo 源码，跟进新协议支持** |\n| **全局参数维护** | 📝 人工维护节点参数列表 | 🔍 **编译时自动识别硬编码参数和可覆写参数** |  \n\n\u003e [!WARNING]\n\u003e 1. 本项目优先适配 OpenClash，其次是各类 Clash 客户端；对其他客户端的支持不作保证。\n\u003e 2. 非 Mihomo 内核的客户端连接本项目，将继续调用继承自上游项目的人工维护解析器。\n\u003e 3. 开发者仅确保完美支持 Mihomo 内核，因代码调整造成的对其他内核客户端的支持范围缩减，原则上不单独回补。\n\n### 🔥 独特功能\n\n#### 1. Proxy-Provider 模式 🛡️\n\n**使用 Mihomo 的 Proxy-Provider 机制**\n\n项目不再下载并解析远程订阅内容，而是生成客户端可直接使用的配置，交由用户客户端内置的 Mihomo 内核自行拉取订阅：\n\n```yaml\n# SubConverter-Extended 生成示例内容\n\nproxy-providers:\n  Provider_A1B2C3:  # provider 名称可通过参数自定义\n    type: http\n    url: https://your-subscription-url  # 客户端实际拉取订阅的地址\n    interval: 3600\n    proxy: DIRECT  # 默认以直连方式拉取订阅\n    path: ./providers/Provider_A1B2C3.yaml\n    health-check:\n      enable: true\n      url: https://cp.cloudflare.com/generate_204\n      interval: 300\n    override:  # 将请求中附加的覆写参数透传给 provider\n      skip-cert-verify: true\n      udp: true\n```\n\n\u003e [!NOTE]\n\u003e * `proxy-provider` 名称默认自动生成，也可通过文档下方的自定义参数指定\n\u003e * 使用 `proxy-provider` 后，订阅由客户端内核以**直连**方式自行拉取\n\u003e * 订阅是否可访问，**与本后端无关，与规则无关**；效果等同于你手动编写 YAML 并填入订阅链接\n\u003e * 如内核使用 `proxy-provider` 拉取订阅失败，通常意味着订阅链接本身无效，或当前网络环境下无法直连访问该订阅地址，请与远程订阅服务商客服对线\n\n\u003e [!TIP]\n\u003e **优势：**\n\u003e\n\u003e * ✅ 不再干预用户节点，交由内核原生处理\n\u003e * ✅ 订阅更新由客户端控制，无需重新转换\n\u003e * ✅ 避免远程订阅服务商屏蔽转换服务带来的问题\n\n#### 2. Mihomo 内核模块集成 🧩\n\n对于本地节点链接（如 `vless://` 等格式）的处理，项目直接调用 Mihomo 的 Go 解析库，确保：\n\n* ✅ 原生支持 Mihomo 内核可解析的全部节点链接协议（包括但不限于 `hysteria2`、`tuic`、`anytls` 等）\n* ✅ 解析能力与 Mihomo 内核自动对齐，无需手动补丁式维护\n* ✅ 新协议可随 Mihomo 更新同步获得支持\n\n#### 3. GitHub 原生文件地址回落 🌐\n\n当远程外部配置、规则集或 `!!import` 引用的是 GitHub 原生文件地址时，后端会优先访问原始 GitHub 原始地址；当原始地址因网络问题无法正常获取时，自动改用 `cdn.jsdelivr.net` 加速地址重试。非 GitHub 地址不受影响。  \n\n此项改进旨在优化中国大陆地区的自部署用户使用托管在 GitHub 上的模板和规则时的访问性能。  \n\n支持的 GitHub 文件地址形式包括：\n\n```text\nhttps://raw.githubusercontent.com/\u003cowner\u003e/\u003crepo\u003e/\u003cref\u003e/\u003cpath\u003e\nhttps://github.com/\u003cowner\u003e/\u003crepo\u003e/raw/\u003cref\u003e/\u003cpath\u003e\nhttps://github.com/\u003cowner\u003e/\u003crepo\u003e/blob/\u003cref\u003e/\u003cpath\u003e\n```\n\n#### 4. 请求诊断台 🔎\n\n内置 `explain=true` 诊断模式和 `/inspect` 网页诊断台，方便在不改变实际转换逻辑的前提下排查请求：\n\n* ✅ 展示请求参数是否被识别、是否生效、是否被项目安全逻辑覆盖\n* ✅ 汇总外部配置、规则集、自定义组、Provider、输出大小等关键状态\n* ✅ 对订阅来源等敏感信息只展示预览、长度或短哈希，便于排障时降低泄露风险\n\n#### 5. 运行仪表盘 📊\n\n启用统计后，`/dashboard` 可展示服务运行期转换统计，适合公开服务部署者观察后端使用情况：\n\n* ✅ 展示本次启动、历史总计、最近 24 小时和滚动时间窗口统计、访问者地理位置分布\n* ✅ 按请求数和规则转换数展示国家 / 地区分布与排行\n* ✅ 支持统计数据持久化和可选 Basic Auth 验证，便于公网部署时限制访问\n\n#### 6. 兼容性保证 🤝\n\n* ✅ **无缝切换**：兼容常见传统 subconverter API 接口，客户端侧几乎无需学习成本即可迁移\n* ✅ **模板兼容**：继续沿用传统外部模板，由后端内置逻辑确保 `proxy-provider` 模式在分流规则中正确生成\n* ✅ **自动跟进**：编译时自动遍历 [Mihomo 内核源码仓库](https://github.com/MetaCubeX/mihomo/meta)，提取最新解析模块、协议格式与可覆写参数\n\n#### 7. 新手友好 👶\n\n* ✅ 使用 **[Custom_OpenClash_Rules](https://github.com/Aethersailor/Custom_OpenClash_Rules)** 远程配置模板，替代默认内置模板与自定义代理组功能\n* ✅ 锁定 API 模式，强制关闭相关接口，降低新手误配置带来的安全风险\n* ✅ 精简参数设计，聚焦高频核心场景\n\n---\n\n## 🚀 快速开始\n\n### 🌍 使用演示实例（无需部署）\n\n如果你不想自行部署，可以直接使用演示实例：\n\n\u003e [!TIP]\n\u003e **地址**：`https://api.asailor.org`\n\u003e\n\u003e ![Website](https://img.shields.io/website?url=https%3A%2F%2Fapi.asailor.org%2Fversion\u0026up_message=%E5%9C%A8%E7%BA%BF\u0026down_message=%E7%A6%BB%E7%BA%BF\u0026style=for-the-badge\u0026label=%E5%90%8E%E7%AB%AF%E6%9C%8D%E5%8A%A1%E5%BD%93%E5%89%8D%E7%8A%B6%E6%80%81)\n\nOpenClash 已内置该演示实例地址；在其他支持自定义后端的订阅转换网站或客户端中，也可以直接填入该地址进行调用。\n\n\u003e [!IMPORTANT]\n\u003e 默认输出为**最简配置**，不包含 DNS 参数，请在 Clash 客户端中启用 DNS 覆写功能。\n\u003e 例如：`OpenClash \u003e 覆写设置 \u003e 自定义上游 DNS 服务器`\n\u003e 否则将无法解析节点域名，导致全部节点无法连接。\n\n### 🚀 自行部署\n\n推荐优先使用 Docker 部署；如果部署环境不方便运行容器，可以根据 [Release](https://github.com/Aethersailor/SubConverter-Extended/releases/latest) 中的安装包类型选择便携包或 OpenWrt APK。\n\n\u003e [!IMPORTANT]\n\u003e 如果服务需要被其他设备访问，请将配置中的 `managed_config_prefix` 改为实际访问地址，例如 `http://192.168.1.10:25500` 或 `https://sub.example.com`。公网部署还建议在配置中启用 `public` 安全档位，详见下方“配置说明”。\n\n#### 安装包类型速查\n\n| 类型 | 文件 / 镜像 | 适用场景 |\n| :--- | :--- | :--- |\n| Docker 镜像 | `aethersailor/subconverter-extended`、`ghcr.io/aethersailor/subconverter-extended` | 服务器、NAS、软路由容器环境 |\n| Linux 便携包 | `SubConverter-Extended-\u003cversion\u003e-linux-amd64.tar.gz`、`linux-arm64.tar.gz`、`linux-armv7.tar.gz` | 不使用 Docker 的 Linux 主机 |\n| Windows 便携包 | `SubConverter-Extended-\u003cversion\u003e-windows-amd64.zip` | Windows x64 主机 |\n| OpenWrt APK | `SubConverter-Extended-\u003cversion\u003e-openwrt-\u003carch\u003e.apk` | 使用 `apk` 包管理器的 OpenWrt 25.12+ |\n| 校验文件 | `SHA256SUMS` | 校验 Release 下载文件完整性 |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDocker 部署（推荐）\u003c/strong\u003e\u003c/summary\u003e\n\nDocker 镜像支持以下平台：\n\n* `linux/amd64`\n* `linux/arm64`\n* `linux/arm/v7`\n\n#### 一键启动\n\n```bash\ndocker run -d \\\n  --name SubConverter-Extended \\\n  -p 25500:25500 \\\n  --restart unless-stopped \\\n  aethersailor/subconverter-extended:latest\n```\n\n访问 `http://localhost:25500/version` 验证服务是否正常启动。\n\n#### 自定义配置启动\n\n```bash\n# 删除可能存在的工作目录\nrm -rf /opt/SubConverter-Extended\n\n# 创建 SubConverter-Extended 工作目录\nmkdir -p /opt/SubConverter-Extended/base\n\ncd /opt/SubConverter-Extended\n\n# 下载配置文件\nwget -O base/pref.toml \\\n  https://gcore.jsdelivr.net/gh/Aethersailor/SubConverter-Extended@master/base/pref.example.toml\n\n# 如需外部访问，请修改 base/pref.toml 中的 managed_config_prefix\n\n# 启动容器并挂载配置\ndocker run -d \\\n  --name SubConverter-Extended \\\n  -p 25500:25500 \\\n  -v /opt/SubConverter-Extended/base/pref.toml:/base/pref.toml:ro \\\n  --restart unless-stopped \\\n  aethersailor/subconverter-extended:latest\n```\n\n也可以直接用环境变量覆盖常用配置：\n\n```bash\ndocker run -d \\\n  --name SubConverter-Extended \\\n  -p 25500:25500 \\\n  -e MANAGED_CONFIG_PREFIX=\"http://your-domain-or-ip:25500\" \\\n  -e SUBCONVERTER_SECURITY_PROFILE=public \\\n  -e SUBCONVERTER_ALLOW_PUBLIC_UPLOAD=false \\\n  --restart unless-stopped \\\n  aethersailor/subconverter-extended:latest\n```\n\n#### Docker Compose\n\n```bash\n# 删除可能存在的工作目录\nrm -rf /opt/SubConverter-Extended\n\n# 创建 SubConverter-Extended 工作目录\nmkdir -p /opt/SubConverter-Extended/base\n\ncd /opt/SubConverter-Extended\n\n# 下载 docker-compose 配置文件\nwget -O docker-compose.yml \\\n  https://gcore.jsdelivr.net/gh/Aethersailor/SubConverter-Extended@master/docker-compose.yml\n\n# 下载配置文件\nwget -O base/pref.toml \\\n  https://gcore.jsdelivr.net/gh/Aethersailor/SubConverter-Extended@master/base/pref.example.toml\n\n# 如需外部访问，请修改 docker-compose.yml 中的 MANAGED_CONFIG_PREFIX，\n# 或修改 base/pref.toml 中的 managed_config_prefix\n\n# 启动容器\ndocker compose up -d\n```\n\n常用维护命令：\n\n```bash\ndocker logs -f SubConverter-Extended\ndocker restart SubConverter-Extended\ndocker rm -f SubConverter-Extended\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eLinux 便携包部署\u003c/strong\u003e\u003c/summary\u003e\n\nLinux 便携包适用于不方便运行 Docker 的 Linux 主机。Release 提供 `amd64`、`arm64`、`armv7` 三类包，包内已包含启动脚本和运行时依赖。\n\n#### 选择架构\n\n```bash\nuname -m\n```\n\n常见对应关系：\n\n| `uname -m` 输出 | 选择的包 |\n| :--- | :--- |\n| `x86_64` | `linux-amd64.tar.gz` |\n| `aarch64` / `arm64` | `linux-arm64.tar.gz` |\n| `armv7l` / `armv7` | `linux-armv7.tar.gz` |\n\n#### 下载并解压\n\n```bash\n# 将 VERSION 替换为 Release 页面中的实际版本号，例如 v1.1.13\nVERSION=v1.1.13\nARCH=amd64\nINSTALL_DIR=/opt/SubConverter-Extended\n\nmkdir -p \"$INSTALL_DIR\"\ncd /tmp\n\ncurl -fLO \"https://github.com/Aethersailor/SubConverter-Extended/releases/download/${VERSION}/SubConverter-Extended-${VERSION}-linux-${ARCH}.tar.gz\"\ncurl -fLO \"https://github.com/Aethersailor/SubConverter-Extended/releases/download/${VERSION}/SHA256SUMS\"\nsha256sum -c SHA256SUMS --ignore-missing\n\ntar -xzf \"SubConverter-Extended-${VERSION}-linux-${ARCH}.tar.gz\" \\\n  -C \"$INSTALL_DIR\" \\\n  --strip-components=1\n```\n\n#### 启动服务\n\n```bash\ncd /opt/SubConverter-Extended\nchmod +x start.sh subconverter\n\n# 首次启动会自动从 base/pref.example.toml 创建 base/pref.toml\n./start.sh\n```\n\n访问 `http://localhost:25500/version` 验证服务是否正常启动。\n\n#### 使用 systemd 常驻运行\n\n```bash\ncat \u003e/etc/systemd/system/subconverter-extended.service \u003c\u003c'EOF'\n[Unit]\nDescription=SubConverter-Extended\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=/opt/SubConverter-Extended\nExecStart=/opt/SubConverter-Extended/start.sh\nRestart=on-failure\nRestartSec=5\n\n[Install]\nWantedBy=multi-user.target\nEOF\n\nsystemctl daemon-reload\nsystemctl enable --now subconverter-extended\nsystemctl status subconverter-extended\n```\n\n如需把配置文件放在其他位置，可以通过 `PREF_PATH` 指定：\n\n```bash\nPREF_PATH=/etc/subconverter/pref.toml /opt/SubConverter-Extended/start.sh\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWindows 便携包部署\u003c/strong\u003e\u003c/summary\u003e\n\nWindows 便携包适用于 Windows x64 环境，文件名为 `SubConverter-Extended-\u003cversion\u003e-windows-amd64.zip`。\n\n#### 部署步骤\n\n1. 从 [Release](https://github.com/Aethersailor/SubConverter-Extended/releases/latest) 下载 `windows-amd64.zip`。\n2. 解压到固定目录，例如 `C:\\SubConverter-Extended`。\n3. 双击运行 `start.bat`，或在 PowerShell 中运行：\n\n```powershell\ncd C:\\SubConverter-Extended\n.\\start.ps1\n```\n\n如果 PowerShell 执行策略阻止脚本运行，可以改用：\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\start.ps1\n```\n\n首次启动时，启动脚本会按顺序查找 `base\\pref.toml`、`base\\pref.yml`、`base\\pref.ini`；如果都不存在，会自动从示例配置创建 `base\\pref.toml`。\n\n访问 `http://localhost:25500/version` 验证服务是否正常启动。首次运行时如果 Windows 防火墙弹窗，请按实际访问范围放行。\n\n#### 使用自定义配置路径\n\nPowerShell：\n\n```powershell\n$env:PREF_PATH = \"D:\\subconverter\\pref.toml\"\n\u0026 C:\\SubConverter-Extended\\start.ps1\n```\n\nCMD：\n\n```cmd\nset PREF_PATH=D:\\subconverter\\pref.toml\nC:\\SubConverter-Extended\\start.bat\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOpenWrt APK 部署\u003c/strong\u003e\u003c/summary\u003e\n\nOpenWrt APK 包适用于使用 `apk` 包管理器的 OpenWrt 25.12+。该包未签名，安装时需要使用 `--allow-untrusted`。\n\n#### 选择架构\n\n```sh\napk print-arch\n```\n\n下载与输出完全匹配的 APK，例如：\n\n| `apk print-arch` 输出 | 选择的包 |\n| :--- | :--- |\n| `x86_64` | `openwrt-x86_64.apk` |\n| `aarch64_generic` | `openwrt-aarch64_generic.apk` |\n| `aarch64_cortex-a53` | `openwrt-aarch64_cortex-a53.apk` |\n| `aarch64_cortex-a72` | `openwrt-aarch64_cortex-a72.apk` |\n| `arm_cortex-*` | 对应同名 `openwrt-arm_cortex-*.apk` |\n\n#### 下载并安装\n\n```sh\n# 将 VERSION 替换为 Release 页面中的实际版本号，例如 v1.1.13\nVERSION=v1.1.13\nARCH=\"$(apk print-arch)\"\nPKG=\"/tmp/SubConverter-Extended-${VERSION}-openwrt-${ARCH}.apk\"\n\nwget -O \"$PKG\" \\\n  \"https://github.com/Aethersailor/SubConverter-Extended/releases/download/${VERSION}/SubConverter-Extended-${VERSION}-openwrt-${ARCH}.apk\"\n\napk add --allow-untrusted \"$PKG\"\n```\n\n#### 启动服务\n\n```sh\n/etc/init.d/subconverter-extended enable\n/etc/init.d/subconverter-extended start\n```\n\n访问 `http://路由器IP:25500/version` 验证服务是否正常启动。\n\nOpenWrt APK 的默认用户配置位于 `/etc/subconverter/pref.toml`。首次启动时会自动创建该文件，后续升级不会覆盖已有配置。\n\n常用维护命令：\n\n```sh\n/etc/init.d/subconverter-extended restart\n/etc/init.d/subconverter-extended stop\nlogread -e subconverter\n```\n\n\u003c/details\u003e\n\n---\n\n## 📚 使用说明\n\n整体使用方式与原版 subconverter 基本一致，常见客户端和订阅转换前端通常无需额外适配即可迁移。\n\n下方仅重点说明本项目的高频参数、特有能力，以及与原版 subconverter 行为不同的部分；未列出的兼容参数仍可按原版 subconverter 的使用习惯传入。\n\n\u003e [!IMPORTANT]\n\u003e 默认输出为**最简配置**，不包含 DNS 参数，请在各 Clash 客户端中启用 DNS 覆写功能，或在生成的配置文件中自行补全 DNS 配置。\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003e快速调用与常用参数\u003c/strong\u003e\u003c/summary\u003e\n\n### 常用参数一览\n\n| 参数 | 说明 | 示例 |\n| :--- | :--- | :--- |\n| `target` | 目标格式 | `clash`, `surge`, `quanx` |\n| `url` | 订阅链接或节点链接（`\\|` 分隔） | `https://sub.com\\|vless://...` |\n| `config` | 外部配置文件 | `https://config-url` |\n| `include` | 包含节点（正则） | `香港\\|台湾` |\n| `exclude` | 排除节点（正则） | `过期\\|剩余` |\n| `emoji` | 添加 Emoji | `true` / `false` |\n| `explain` | 返回本次转换的 JSON 诊断报告 | `true` |\n\n### 常见调用示例\n\n```text\nhttps://api.asailor.org/sub?target=clash\u0026url=https%3A%2F%2Fexample.com%2Fsub\u0026config=https%3A%2F%2Fexample.com%2Fconfig.ini\n```\n\n```text\nhttps://api.asailor.org/sub?target=clash\u0026url=provider%3AHK%2Chttps%3A%2F%2Fexample.com%2Fsub\u0026include=%E9%A6%99%E6%B8%AF\u0026emoji=true\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e诊断与排障\u003c/strong\u003e\u003c/summary\u003e\n\n### `explain=true` 诊断模式\n\n在 `/sub` 请求中追加 `explain=true` 后，后端会按同一组参数执行转换流程，但返回 JSON 诊断报告，而不是返回 Clash/Surge/QuanX 配置文件。\n\n示例：\n\n```text\nhttps://api.asailor.org/sub?target=clash\u0026url=https%3A%2F%2Fexample.com%2Fsub\u0026explain=true\n```\n\n这个模式适合排查“参数是否生效”“是否进入 `proxy-provider` 模式”“外部配置是否加载成功”“规则集和节点数量是否符合预期”等问题。报告会包含目标格式、模式开关、输入数量、外部配置状态、规则集统计、provider 数量和输出大小等信息。\n\n**说明：**\n\n* `explain=true` 只改变响应内容，不改变实际转换逻辑。\n* 如果同一请求里包含上传参数，诊断模式会抑制上传，避免排障时产生托管配置写入。\n* 诊断报告不会直接回显原始订阅地址；provider 来源会以短哈希形式显示，便于区分来源又避免泄露完整链接。\n\n### `/inspect` 请求诊断台\n\n如果不方便直接阅读 `explain=true` 返回的 JSON，可以访问 `/inspect` 打开网页诊断台：\n\n```text\nhttps://api.asailor.org/inspect\n```\n\n自部署环境可访问：\n\n```text\nhttp://localhost:25500/inspect\n```\n\n诊断台支持粘贴完整 `/sub?...` 链接、完整 URL，或仅粘贴查询参数。页面会自动补充 `explain=true` 并以只读方式发起诊断请求，然后展示摘要、已识别参数、未识别参数、生效配置、Provider 信息和原始 JSON。\n\n这个页面适合排查以下问题：\n\n* 某个请求参数是否被识别、是否生效、是否被覆盖或抑制\n* `list=true` 等参数是否被项目强制改写为 `proxy-provider` 模式\n* `include` / `exclude`、`emoji`、`new_name`、`config` 等外部参数最终是否参与转换\n* 外部配置、规则集、自定义组、Provider 是否按预期加载或生成\n\n**说明：**\n\n* `/inspect` 只是 `explain=true` 诊断报告的可视化界面，不会改变实际转换逻辑。\n* 页面会隐藏敏感输入的明文，仅展示预览、长度和短哈希等排障信息。\n* 请求诊断台会保留原始 JSON 区域，方便复制给维护者进一步分析。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e/dashboard 运行仪表盘\u003c/strong\u003e\u003c/summary\u003e\n\n### `/dashboard` 使用方法\n\n`/dashboard` 用于查看运行期转换统计。该功能默认关闭；只有在配置文件中启用 `statistics.enabled` 后，服务才会注册 `/dashboard` 和 `/dashboard/data` 路由。\n\n启用后可访问：\n\n```text\nhttp://localhost:25500/dashboard\n```\n\n公网或反代部署时，请替换为实际域名：\n\n```text\nhttps://sub.example.com/dashboard\n```\n\n`/dashboard/data` 会返回仪表盘使用的 JSON 数据，适合接入外部监控或自行排查：\n\n```text\nhttp://localhost:25500/dashboard/data\n```\n\n仪表盘主要展示：\n\n* 服务启动时间、本次运行时长、累计运行时长和启动次数\n* 成功 `/sub` 转换请求数与规则转换数\n* 最近 24 小时请求 / 规则转换柱状图\n* 按 1 小时、1 天、7 天、30 天、半年、1 年和历史总计统计的国家 / 地区分布与排行\n* 当可信边缘网关提供地区请求头时，展示中国地区请求 / 规则转换地图和排行\n\n**说明：**\n\n* 统计只在 `statistics.enabled=true` 后开始写入，启用前的历史请求不会回补。\n* 统计模块只记录成功的 `GET /sub` 转换请求和规则转换计数，不存储订阅链接、节点内容或访问者 IP。\n* 国家 / 地区来源于配置的国家码请求头；中国地区来源于配置的地区请求头；无法识别时会归为未知。\n* Docker 部署如需跨重启保留统计数据，请将 `data_dir` 对应目录挂载为卷，例如 `./stats:/base/stats`。\n\n### 启用示例（TOML）\n\n修改 `base/pref.toml` 后重启服务：\n\n```toml\n[statistics]\nenabled = true\ndata_dir = \"stats\"\nflush_interval = 5\n\n[statistics.geo]\nprovider = \"header\"\ncountry_headers = [\"CF-IPCountry\", \"X-Geo-Country\", \"X-Vercel-IP-Country\", \"CloudFront-Viewer-Country\"]\nchina_region_headers = [\"CF-Region-Code\", \"cf-region-code\", \"X-Geo-Subdivision\"]\n\n[statistics.dashboard_auth]\nenabled = true\nusername = \"admin\"\npassword = \"change-this-password\"\nmax_failures = 5\nwindow_seconds = 300\nlock_seconds = 900\n```\n\n### 新增配置项说明\n\n| TOML / YAML 配置项 | INI 配置项 | 默认值 | 说明 |\n| :--- | :--- | :--- | :--- |\n| `statistics.enabled` | `enabled` | `false` | 是否启用运行期统计和 `/dashboard`。关闭时不会注册 `/dashboard` 与 `/dashboard/data`。 |\n| `statistics.data_dir` | `data_dir` | `stats` | 统计数据目录，按程序工作目录解析；Docker 中可挂载 `/base/stats` 持久化。 |\n| `statistics.flush_interval` | `flush_interval` | `5` | 统计数据最小写盘间隔，单位为秒。 |\n| `statistics.geo.provider` | `geo_provider` | `header` | 国家 / 地区识别方式。`header` 表示读取国家码请求头，`none` 表示全部记为未知。 |\n| `statistics.geo.country_headers` | `country_headers` | `CF-IPCountry`, `X-Geo-Country`, `X-Vercel-IP-Country`, `CloudFront-Viewer-Country` | `provider=header` 时依次尝试读取的国家码请求头。 |\n| `statistics.geo.china_region_headers` | `china_region_headers` | `CF-Region-Code`, `cf-region-code`, `X-Geo-Subdivision` | 可信边缘网关注入中国地区码时依次尝试读取的请求头，用于中国地区地图和排行。 |\n| `statistics.dashboard_auth.enabled` | `dashboard_auth_enabled` | `false` | 是否为 `/dashboard` 和 `/dashboard/data` 启用 Basic Auth。 |\n| `statistics.dashboard_auth.username` | `dashboard_auth_username` | 空 | Basic Auth 用户名。启用认证后不能为空。 |\n| `statistics.dashboard_auth.password` | `dashboard_auth_password` | 空 | Basic Auth 密码。启用认证后不能为空；公网部署建议配合 HTTPS。 |\n| `statistics.dashboard_auth.max_failures` | `dashboard_auth_max_failures` | `5` | 在统计窗口内允许的失败登录次数。 |\n| `statistics.dashboard_auth.window_seconds` | `dashboard_auth_window_seconds` | `300` | 失败登录统计窗口，单位为秒。 |\n| `statistics.dashboard_auth.lock_seconds` | `dashboard_auth_lock_seconds` | `900` | 超过失败次数后的锁定时长，单位为秒。 |\n\n**提示：** `pref.yml` 使用同名嵌套字段；`pref.ini` 的上述 INI 配置项均写在 `[statistics]` 段内。\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProxy-Provider 自定义名称\u003c/strong\u003e\u003c/summary\u003e\n\n### `provider` 前缀（仅适用于 Clash/ClashR 订阅链接）\n\n`provider` 不是独立参数，而是写在 `url=` 列表中、放在订阅链接前，并以逗号分隔，用于自定义 `proxy-providers` 名称；对节点链接不生效。\n\n示例：\n\n```text\nurl=provider:HK,https://example.com/sub\nurl=provider:HK,https://a|provider:HK,https://b\nurl=provider%3AHK%2Chttps%3A%2F%2Fexample.com%2Fsub\n```\n\n**说明：** 在 OpenClash 这类预置“订阅地址”输入框的软件中，无需填写开头的 `url=`，直接填入等号后的内容即可。\n\n补充说明：\n\n* 支持中文名称；非法字符或空值会回退为默认 `Provider_\u003cMD5\u003e`\n* 重名时会自动追加 `_1`、`_2` 等后缀\n\n\u003c/details\u003e\n\n---\n\n## 🛠️ 配置说明\n\n### 主配置文件\n\n支持三种格式：`pref.toml`（推荐）、`pref.yml`、`pref.ini`。\n\n关键配置项：\n\n```toml\n[managed_config]\nmanaged_config_prefix = \"http://localhost:25500\"  # 托管配置前缀\n```\n\n非本机部署时，请将该项修改为 SubConverter-Extended 实际部署机的 IP 地址或域名。\n\n### 安全档位\n\n从本版本开始，主配置文件支持 `[security]` 安全档位，用于区分内网自用部署和公网暴露部署。\n\n默认值为 `lan`，保持历史行为不变，适合家庭内网、NAS、软路由、旁路由、Docker 内网等自用场景。该档位允许访问本地资源、私有网段资源和 fake-ip 资源，因此现有部署通常无需额外修改配置。\n\n公网部署建议显式切换为 `public`：\n\n```toml\n[security]\nprofile = \"public\"\nallow_public_upload = false\n```\n\nINI 配置示例：\n\n```ini\n[security]\nprofile=public\nallow_public_upload=false\n```\n\nDocker 环境变量示例：\n\n```bash\ndocker run -d \\\n  --name SubConverter-Extended \\\n  -p 25500:25500 \\\n  -e SUBCONVERTER_SECURITY_PROFILE=public \\\n  -e SUBCONVERTER_ALLOW_PUBLIC_UPLOAD=false \\\n  --restart unless-stopped \\\n  aethersailor/subconverter-extended:latest\n```\n\n| 配置项 / 环境变量 | 默认值 | 说明 |\n| :--- | :--- | :--- |\n| `security.profile` / `SUBCONVERTER_SECURITY_PROFILE` | `lan` | 可选值：`lan`、`public`、`strict` |\n| `security.allow_public_upload` / `SUBCONVERTER_ALLOW_PUBLIC_UPLOAD` | `false` | 仅 `public` 档位生效，用于显式允许公开请求触发上传 |\n\n档位说明：\n\n* `lan`：默认档位，保持旧行为，适合可信内网自用部署。\n* `public`：公网推荐档位。限制公开请求参数、远程外部配置、公开 `!!import` 等不可信来源访问本地、私网和 fake-ip 字面量；项目自带本地模板、部署者配置的默认模板与可信本地配置仍可正常使用。\n* `strict`：在 `public` 的基础上，始终禁止公开请求触发上传，即使设置 `allow_public_upload=true` 也不会放行。\n\n\u003e [!NOTE]\n\u003e `public` 档位不会阻止正常域名在 OpenClash fake-ip DNS 环境下解析到 `198.18.0.0/15` 后继续访问；但会阻止请求方直接传入 `127.0.0.1`、私有地址或 fake-ip 字面量作为抓取目标。\n\n---\n\n## 🔍 Docker Hub 镜像标签\n\n`latest` 与版本标签均为多架构镜像，当前支持 `linux/amd64`、`linux/arm64`、`linux/arm/v7`。\n\n| 标签 | 用途 | 更新频率 |\n| :--- | :--- | :--- |\n| `latest` | 🟢 **稳定版本**（`master` 分支） | 发布 Release 时更新 |\n| `dev` | 🟡 **开发版本**（`dev` 分支） | 每次 `dev` 分支推送后更新 |\n\n---\n\n## 🤝 致谢\n\n本项目使用或引用了以下开源项目，在此表示感谢：\n\n* [MetaCubeX/mihomo](https://github.com/MetaCubeX/mihomo) - Clash 内核，提供节点链接解析能力\n* [Aethersailor/Custom_OpenClash_Rules](https://github.com/Aethersailor/Custom_OpenClash_Rules) - OpenClash 订阅转换模板、规则集与教程项目\n* [asdlokj1qpi233/subconverter](https://github.com/asdlokj1qpi233/subconverter) - 原版 subconverter 项目\n\n---\n\n## 📄 开源协议\n\n本项目基于 [GPL-3.0](LICENSE) 协议开源。\n\n\u003e [!TIP]\n\u003e 内置的 Mihomo 解析器模块遵循 [MIT](https://github.com/MetaCubeX/mihomo/blob/Meta/LICENSE) 协议。\n\n---\n\n## ⭐ 记录\n\n\u003ca href=\"https://www.star-history.com/#Aethersailor/SubConverter-Extended\u0026Date\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=Aethersailor/SubConverter-Extended\u0026type=Date\u0026theme=dark\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=Aethersailor/SubConverter-Extended\u0026type=Date\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=Aethersailor/SubConverter-Extended\u0026type=Date\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## 📊 数据统计\n\n![Alt](https://repobeats.axiom.co/api/embed/c249ae5c34b99a067c78e9216600c1a5eac16c65.svg \"Repobeats analytics image\")\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**如果这个项目对你有帮助，欢迎给一个 ⭐ Star 支持。**\n\nMade with ❤️ by [Aethersailor](https://github.com/Aethersailor)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faethersailor%2Fsubconverter-extended","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faethersailor%2Fsubconverter-extended","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faethersailor%2Fsubconverter-extended/lists"}