MiSub， 一个聚焦订阅翻墙节点管理、多客户端订阅生成、内置模板输出与转换链路编排的工具

功能特性 • 快速开始 • 部署指南 • 使用说明 • External API 使用说明 • Wiki 文档 • v2.5.0 升级指南 • 更新日志

---

📸 应用截图

登录界面	管理界面

---

✨ 功能特性

🎯 核心功能

• 🗂️ 订阅分组 (Profiles)

  • 自由组合机场订阅和手动节点
  • 为不同场景生成专属订阅链接
  • 支持全选/全不选,操作便捷
  • 自定义分组名称和订阅链接

• 📦 订阅与节点分离管理

  • 机场订阅和手动节点独立管理
  • 批量导入自动分类
  • 支持拖拽排序
  • 一键按地区自动排序

• 🧩 统一模板与链式处理

  • 操作符链 (Operator Chain)：支持过滤、重命名、脚本、排序与去重的流式管道
  • 统一模板模型输出 Clash、Sing-Box、Surge、Loon、QX
  • 支持按客户端自动适配模板策略
  • 内置 ACL4SSR 风格完整分流模板预设
  • 支持第三方转换后端接入，MiSub 先完成节点预处理再交给外部后端转换

• 🎨 精致的 UI/UX

  • 明亮/暗黑模式自动切换
  • 磨砂玻璃质感现代化设计
  • 完善的交互提示和加载状态
  • 响应式布局,支持移动端

• 🌍 公开主页 (Explore)

  • 访客模式：无需登录即可预览公开分享的订阅
  • 管理员分享：精选中转/直连机场订阅
  • 一键复制：访客可直接复制订阅链接
  • 客户端推荐：主流全平台客户端下载指引

🆕 v2.7.0 更新亮点

• 🚀 订阅生成链路增强

  • 第三方转换后端模式不再依赖外部服务回调 MiSub 节点链接，改为内联发送预处理后的节点
  • 多节点外部转换统一使用 | 分隔，兼容 FatSheep / subconverter 等后端
  • 修复 Clash / Party / Shadowrocket 等客户端导入链路与目标格式识别问题
  • 服务集成 Cron 同时支持兼容链接 /cron?secret=[REDACTED] 与更安全的 Bearer Token Header

• 🧱 内置模板与规则输出增强

  • 补强 ACL4SSR provider、IP-CIDR provider、远程规则集与 Sing-Box 规则源
  • 新增/优化自定义规则模板与模板变量辅助说明
  • 支持 Hysteria2 realm 等协议细节输出

• 🧰 节点刷新与缓存稳定性

  • 订阅保存与手动刷新时保留保护性节点缓存，降低临时抓取失败对可用节点的影响
  • 节点更新失败会在 API / UI 中展示更明确的错误结果
  • 空缓存与运行时信息同步逻辑更稳健

🧩 主要能力

• 📝 订阅备注

  • 为每个订阅添加备注信息
  • 记录官网、价格、到期时间等
  • 在订阅卡片上清晰显示

• 🌐 自定义 User-Agent

  • 为每个订阅设置独立的 UA
  • 10+ 常用客户端 UA 预设
  • 解决机场 UA 限制问题

• 🔧 Snell 协议完整支持

  • 支持 Snell v1-v5
  • 完整的参数支持 (reuse/tfo)
  • Surge 配置导入支持

• 📐 模板输出增强

  • Clash / Sing-Box / iOS 客户端统一走模板主线
  • 支持远程规则集、策略组与地区分组映射
  • 支持内置模板预设与客户端能力兼容表

• 📊 流量与到期时间显示

  • 订阅卡片显示已用/总流量
  • 到期时间提醒，颜色高亮
  • 自动更新节点数和流量信息

💾 双重存储支持

• Cloudflare KV 存储

  • 极快的查询速度
  • 适合轻度使用
  • 简单易配置

• Cloudflare D1 数据库

  • 不受 KV 每日写入次数限制
  • 适合频繁更新
  • 一键数据迁移

🔐 安全与定制

• 密码保护: 管理界面由自定义密码保护
• 高度可定制: 自定义输出文件名、模板来源、规则级别等
• 数据备份: 支持导出/导入备份
• TG 推送: 支持 Telegram 通知

🌍 多格式支持

支持主流代理客户端和格式:

客户端	格式支持	自动识别
Clash / Clash Meta	✅	✅
Sing-Box	✅	✅
Surge	✅	✅
Shadowrocket	✅	✅
V2rayN / V2rayNG	✅	✅
Quantumult X	✅	✅
Loon	✅	✅

📡 支持的协议

• Shadowsocks (SS/SS2022)
• VMess
• VLESS（Quantumult X v1.5.5+ 支持 TLS / REALITY / XTLS Vision 输出）
• Trojan
• Hysteria2 / HY2
• TUIC
• Snell
• WireGuard
• AnyTLS（Quantumult X v1.6.0+ 支持）
• HTTPS
• SOCKS5 / SOCKS5-TLS

📦 内置格式说明

• clash：兼容性最好，适合主力导出
• surge：支持规则模板与地区分组
• loon：支持规则模板与地区分组
• quanx：支持统一模板输出与基础策略组、规则映射
• singbox：JSON 输出，支持统一模板模型与路由规则映射
• base64：兜底格式

---

🚀 快速开始

前置要求

• Cloudflare 账号
• GitHub 账号

一键部署

1. Fork 本仓库到你的 GitHub 账号
2. 登录 Cloudflare Dashboard
3. 进入 Workers & Pages → 创建应用程序 → Pages → 连接到 Git
4. 选择你 Fork 的仓库
5. 配置构建设置:
   • 框架预设: Vue
   • 构建命令: npm run build
   • 构建输出目录: dist
6. 点击 保存并部署

---

📚 部署指南

1. 绑定 KV 命名空间 (必需)

部署完成后,进入项目设置:

1. 设置 → 函数 → KV 命名空间绑定
2. 点击 添加绑定
3. 变量名称: MISUB_KV
4. KV 命名空间: 选择或创建一个 KV 命名空间

2. 绑定 D1 数据库 (可选,推荐)

创建 D1 数据库:

wrangler d1 create misub

绑定数据库:

1. 设置 → 函数 → D1 数据库绑定
2. 点击 添加绑定
3. 变量名称: MISUB_DB
4. D1 数据库: 选择刚创建的数据库

初始化表结构:

wrangler d1 execute misub --file=schema.sql --remote

💡 若无法初始化,可在 Cloudflare 控制台手动执行 schema.sql

说明 D1 表结构未更新，请在 D1 控制台执行最新 schema.sql。

3. 设置环境变量

在 设置 → 环境变量 中添加 生产环境 变量：

可选：

变量名	说明	示例
ADMIN_PASSWORD	管理员登录密码	your_secure_password (未设置则默认为 admin)
COOKIE_SECRET	Cookie 加密密钥	64位随机字符串 (推荐留空，系统自动生成)

可选（按需设置）：

变量名	说明	示例
CORS_ORIGINS	允许跨域访问的来源(逗号分隔)，同域可不填	https://example.com,http://localhost:5173
MISUB_PUBLIC_URL	站点对外访问的公开域名，用于生成订阅转换回调地址	https://your-domain.pages.dev
MISUB_CALLBACK_URL	订阅转换回调基础地址（优先级高于 MISUB_PUBLIC_URL），通常保持默认即可	https://your-domain.pages.dev

前端构建变量（可选）：

变量名	说明	示例
VITE_ERROR_REPORT_URL	前端错误上报地址，不需要上报可不填	/api/system/error_report

提示：启用错误上报后会发送页面地址与浏览器信息等运行数据，请根据隐私与合规要求进行评估与披露。

4. 重新部署

完成配置后,在 部署 选项卡重新部署项目。

---

💡 使用说明

登录管理界面

1. 部署完成后，公开页面默认 不开启（访问域名会显示伪装页）。
2. 请直接访问 您的域名/login 进入登录页面。
3. 输入设置的 ADMIN_PASSWORD 即可进入管理后台。
   • 注意：如果未设置 ADMIN_PASSWORD，默认密码为 admin。
   • 首次登录：使用默认密码登录后，系统会提示您立即在「设置」->「基础设置」中修改密码。

添加订阅

1. 点击 新增订阅
2. 填写订阅名称和链接
3. (可选) 设置自定义 UA
4. (可选) 添加备注信息
5. (可选) 设置操作符链（详情请参考 操作符指南）
6. 保存订阅

创建订阅组

1. 在右侧面板点击 新增订阅组
2. 选择要包含的订阅和节点
3. 设置分组名称
4. 保存并获取订阅链接

转换链路说明

MiSub 默认使用内置转换器将订阅内容转换为目标格式，并支持按需接入第三方转换后端。

处理顺序统一为：机场订阅 / 手动节点 → MiSub 节点预处理（拉取、解析、过滤、重命名、去重、排序等）→ 内置模板输出或第三方后端转换。

当启用第三方转换后端时，MiSub 会把预处理后的节点以内联方式交给外部后端，避免外部后端再次回调 MiSub 节点链接造成 No nodes were found! 等抓取失败。多节点会使用 | 分隔，以兼容常见 subconverter / FatSheep 后端。

支持的目标格式：

• clash
• surge
• loon
• quanx
• singbox
• base64

内置转换说明：

• surge 会根据客户端或 URL 参数保留版本感知。
• singbox 会输出 JSON 配置。
• 不支持的目标格式会回退为 base64。
• 若在设置或订阅组中启用第三方转换，MiSub 会先完成节点预处理，再将节点交给第三方后端输出目标格式。

远端模板占位符

如果你在 transformConfig 中使用远端模板，可以在模板里放入以下占位符：

• <%proxies%>: 已渲染的代理块
• <%rules%>: 规则块
• <%fileName%>: 输出文件名
• <%interval%>: 刷新间隔
• <%managedConfigUrl%>: 模板地址
• <%targetFormat%>: 目标格式
• <%nodeCount%>: 节点数量
• <%regionGroups%>: 地区分组 JSON
• <%regionGroupNames%>: 地区分组名称列表
• <%regionGroupCounts%>: 地区分组及数量
• <%regionGroupList%>: 地区分组清单

示例

proxies:
<%proxies%>

proxy-groups:
  - name: 节点选择
    type: select
    proxies:
      - 自动选择
      - <%regionGroupNames%>

  - name: 自动选择
    type: url-test
    url: http://www.gstatic.com/generate_204
    interval: <%interval%>
    proxies:
      - <%regionGroupNames%>

rules:
<%rules%>

数据迁移 (KV → D1)

如果已在使用 KV 存储，想迁移到 D1:

1. 配置 D1 数据库 (参考部署指南)
2. 登录管理界面,进入 设置
3. 点击 迁移数据到 D1 数据库
4. 确认迁移,等待完成

服务集成 Cron

MiSub 提供 /cron 接口用于外部定时服务触发订阅刷新，适合 Cloudflare Pages 免费版无法直接使用 Cron Trigger 的场景。

• 兼容链接：在「设置」→「服务集成」复制 /cron?secret=[REDACTED] 链接，可直接配置到 UptimeRobot、Cron-Job.org 等外部监控服务。
• 推荐方式：如果定时服务支持自定义 Header，建议请求 /cron 并设置 Bearer Token Header，避免密钥出现在 URL、浏览器历史或第三方访问日志中。
• 安全提示：不要公开分享带 secret 的 Cron 链接；如果怀疑泄露，请在后台重置 Cron 密钥后更新外部定时任务。

🛰️ 代理抓取 (Vercel)

如果由于网络限制导致订阅内容抓取失败，可以额外部署一个用于抓取转发的 Edge Functions 代理：

• Vercel Fetch Proxy 部署指南

说明：该代理仅作为可选的辅助抓取组件，不属于 MiSub 主站部署方式。MiSub 主站仍然仅支持部署在 Cloudflare Pages。

📊 存储类型对比

特性	KV 存储	D1 数据库
写入限制	每日写入次数有限	不受 KV 每日写入次数限制
查询速度	极快	快
适用场景	读多写少	频繁更新
配置复杂度	简单	中等
推荐使用	轻度使用	重度使用

选择建议:

• 🔰 新用户: 建议直接配置 D1，避免 KV 写入额度限制
• 📈 现有用户: 遇到限制可使用迁移工具
• ⚡ 轻度使用: KV 完全够用,速度更快
• 🚀 重度使用: D1 是最佳选择

---

🛠️ 技术栈

• 前端: Vue 3 + Vite + Tailwind CSS
• 后端: Cloudflare Pages Functions
• 存储: Cloudflare KV + D1 数据库
• 部署平台: 仅 Cloudflare Pages

---

📚 文档索引

• External API 使用说明
• External API 接口总览
• External API OpenAPI 规范
• 操作符链指南
• v2.5.0 升级指南
• 架构说明
• 数据模型、

from  https://github.com/imzyb/MiSub/blob/main/README-zh.md