MiSub 是一款部署在 Cloudflare Pages 上的轻量级代理订阅管理面板。它可以帮你管理多个上游订阅链接和手动节点，自由组合成不同场景的订阅配置，并通过可视化的算子链（Operator Chain）对节点进行过滤、重命名、排序、去重等处理，最终生成 Clash、Sing-Box、Surge、Loon、Quantumult X、Shadowrocket 等主流客户端可直接使用的订阅链接。

版本： v2.7.0 | 协议： MIT | 仓库： github.com/imzyb/MiSub

目录

功能概览

功能 说明
订阅管理 管理多个机场订阅链接，自动获取节点信息
手动节点 支持 Shadowsocks / VMess / VLESS / Trojan / Hysteria2 / TUIC 等十余种协议
节点分组 可将节点分组排序，添加备注、流量、到期时间等信息
场景配置（Profiles） 自由组合订阅源和手动节点分组，按场景产出不同配置
算子链（Operator Chain） 可视化流水线：过滤 → 正则重命名 → 脚本/DSL → 排序 → 智能去重
多客户端输出 Clash/Mihomo、Sing-Box、Surge、Loon、Quantumult X、Shadowrocket、V2rayN/Ng、base64
内置模板 ACL4SSR 风格规则集、区域分组、策略组、自定义规则模板
自定义公开页 发布公开浏览页或沉浸式伪装页，支持 HTML 渲染
存储可选 Cloudflare KV（简单）或 D1（高写入、结构化存储）
通知与运维 Telegram 通知、定时刷新、备份恢复、操作日志、系统诊断
现代 UI 响应式 Vue 3 界面，支持亮/暗主题、中/英文切换

前置准备

在开始部署之前，你需要准备好以下内容：

  1. 一个 GitHub 账号 — 用来 Fork 项目仓库
  2. 一个 Cloudflare 账号 — 用来部署 Pages 和创建 KV/D1
  3. 一个域名（可选） — 可在 Cloudflare 上绑定自定义域名

所有操作都可在免费额度内完成，Cloudflare Pages 的免费计划足够个人和小团队使用。

一键部署（Cloudflare Pages + Git）

这是官方推荐的部署方式，只需在 Cloudflare 控制台中点几下即可完成。

第 1 步：Fork 项目仓库

  1. 访问项目地址：https://github.com/imzyb/MiSub
  2. 点击右上角的 Fork 按钮，将仓库 Fork 到自己的 GitHub 账号下

第 2 步：连接到 Cloudflare Pages

  1. 登录 Cloudflare Dashboard
  2. 左侧菜单选择 Workers & Pages
  3. 点击 Create application → 选择 Pages 标签页
  4. 点击 Connect to Git

第 3 步：选择仓库

  1. 授权 Cloudflare 访问你的 GitHub 账号（首次需要）
  2. 在仓库列表中找到你刚才 Fork 的 MiSub 仓库
  3. 点击 Begin setup

第 4 步：配置构建设置

在 Set up builds and deployments 页面，填写以下内容：

配置项 值
Framework preset Vue
Build command npm run build
Build output directory dist
Root directory （留空，使用仓库根目录）

保持其他选项为默认值，点击 Save and Deploy。

第 5 步：等待首次部署

Cloudflare 会自动拉取代码、安装依赖并执行构建。首次部署大约需要 1-2 分钟。

部署完成后，你会得到一个 https://<project-name>.pages.dev 的域名。此时访问会看到登录页面，但还没有配置存储绑定，不要急着登录，继续下一步。

配置存储绑定

MiSub 需要至少一个 KV 命名空间来存储数据，同时强烈建议创建 D1 数据库以获得更好的性能和结构化存储。

KV 命名空间（必需）

创建 KV 命名空间

在 Cloudflare Dashboard 中：

  1. 左侧菜单选择 Workers & Pages → KV
  2. 点击 Create a namespace
  3. 命名空间名称填入 misub-kv（或你喜欢的名字）
  4. 点击 Create

绑定到 Pages 项目

  1. 进入你的 Pages 项目页面
  2. 点击 Settings → Functions → KV namespace bindings
  3. 点击 Add binding
  4. 填写：
    • Variable name: MISUB_KV
    • KV namespace: 选择刚才创建的 misub-kv
  5. 点击 Save

D1 数据库（推荐）

D1 是 Cloudflare 的原生 SQLite 数据库，写入性能优于 KV，适合订阅条目较多的场景。

创建 D1 数据库

有两种方式创建：

方式一：使用 Wrangler CLI（推荐）

1
2
3
4
5
6
7
8
9
10
11
# 安装 wrangler（如果还没有）
npm install -g wrangler

# 登录 Cloudflare
wrangler login

# 创建 D1 数据库
wrangler d1 create misub

# 初始化表结构
wrangler d1 execute misub --file=schema.sql --remote

方式二：在 Cloudflare Dashboard 中创建

  1. 左侧菜单选择 Workers & Pages → D1
  2. 点击 Create database
  3. 名称填入 misub，点击 Create
  4. 创建完成后，进入数据库页面
  5. 点击 Console（控制台）标签页
  6. 将 schema.sql 中的 SQL 语句复制粘贴到控制台中执行：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
CREATE TABLE IF NOT EXISTS subscriptions (
    id TEXT PRIMARY KEY,
    data TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS profiles (
    id TEXT PRIMARY KEY,
    data TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS settings (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX IF NOT EXISTS idx_subscriptions_updated_at ON subscriptions(updated_at);
CREATE INDEX IF NOT EXISTS idx_profiles_updated_at ON profiles(updated_at);
CREATE INDEX IF NOT EXISTS idx_settings_updated_at ON settings(updated_at);

绑定 D1 到 Pages 项目

  1. 进入你的 Pages 项目 → Settings → Functions → D1 database bindings
  2. 点击 Add binding
  3. 填写：
    • Variable name: MISUB_DB
    • D1 database: 选择刚才创建的 misub
  4. 点击 Save

设置环境变量

环境变量在 Pages 项目的 Settings → Environment variables 中设置。

必需的环境变量

变量名 说明 建议值
ADMIN_PASSWORD 管理员登录密码 设置一个强密码，留空则默认密码为 admin
COOKIE_SECRET Session 签名密钥 生成一个随机字符串，如 openssl rand -hex 32

推荐设置的环境变量

变量名 说明 建议值
MISUB_PUBLIC_URL 公开访问地址，用于生成订阅转换回调 URL https://你的项目名.pages.dev
MISUB_CALLBACK_URL 回调 URL 基础地址，优先级高于 MISUB_PUBLIC_URL 同上或自定义域名
CRON_SECRET 外部 Cron 触发器的密钥 生成一个随机字符串
CORS_ORIGINS 允许跨域访问的来源（逗号分隔） 一般留空

Cron 相关环境变量（可选）

变量名 默认值 说明
ENVIRONMENT production 运行环境标识
ENABLE_CRON true 是否启用 Cron 定时同步
CRON_TYPE hourly-subscription-sync Cron 任务类型
CRON_MAX_SYNC_COUNT 50 每次 Cron 最多同步的订阅数
CRON_SYNC_TIMEOUT 30000 单个订阅同步超时时间（毫秒）
CRON_ENABLE_PARALLEL true 是否启用并行同步

设置步骤

  1. 进入 Pages 项目 → Settings → Environment variables
  2. 在 Production 标签下，点击 Add variable
  3. 逐个添加上述变量名和值
  4. 添加完成后，点击 Save

注意： 修改环境变量后，需要重新部署才能生效。可以在 Pages 项目页面点击 Deployments → Deploy latest commit 来触发重新部署。

配置 Cron 定时任务

Cron 触发器可以让 MiSub 定时自动同步订阅内容，保持节点数据最新。

方式一：Cloudflare Cron Triggers（推荐，需付费计划）

Cloudflare Pages 的 Cron Triggers 功能需要 Paid Plan（Workers Paid 计划）。

  1. 进入 Pages 项目 → Settings → Functions → Cron Triggers
  2. 点击 Add Cron Trigger
  3. 输入 Cron 表达式：
    • 0 * * * * — 每小时同步一次（推荐）
    • */30 * * * * — 每 30 分钟同步一次
    • 0 8 * * * — 每天早上 8 点同步一次
  4. 点击 Save

方式二：外部 Cron 服务（免费）

如果不想升级到付费计划，可以使用免费的第三方 Cron 服务来触发同步：

支持的触发方式：

1
GET https://你的项目.pages.dev/cron?secret=你的CRON_SECRET

或带 Bearer Token 的请求：

1
curl -H "Authorization: Bearer 你的CRON_SECRET" https://你的项目.pages.dev/cron

推荐的外部 Cron 服务：

  • UptimeRobot — 免费计划支持 5 分钟间隔的监控/请求
  • Cron-Job.org — 免费计划支持每分钟执行
  • EasyCron — 免费计划支持一定数量的定时任务

完成部署与登录

所有配置完成后，访问你的 Pages 项目地址（如 https://misub.pages.dev）：

  1. 页面会自动跳转到登录页 /login

  2. 使用你设置的管理员密码登录（默认密码为 admin）

  3. 登录后进入仪表盘，即可开始配置：

    • 订阅管理 — 添加你的机场订阅链接
    • 手动节点 — 添加手动搭建的节点
    • 场景配置 — 组合订阅源和节点分组，生成订阅配置
    • 算子链 — 配置节点过滤、重命名、排序规则
    • 系统设置 — 配置公开页、回调地址、Telegram 通知等

绑定自定义域名（可选）

如果你有自己的域名，可以将它绑定到 Cloudflare Pages：

  1. 在 Cloudflare Dashboard 中将你的域名接入 Cloudflare（DNS 托管）
  2. 进入 Pages 项目 → Custom domains → Set up a custom domain
  3. 输入你的域名（如 misub.example.com）
  4. Cloudflare 会自动添加 DNS 记录并下发 SSL 证书
  5. 等待证书生效（通常 1-2 分钟）
  6. 将 MISUB_PUBLIC_URL 环境变量更新为你的自定义域名
  7. 重新部署

本地开发（选读）

如果你想在本地开发和调试 MiSub，可以按以下步骤操作。

环境要求

  • Node.js 20 或更高版本
  • npm 或 pnpm

安装依赖

1
2
3
git clone https://github.com/imzyb/MiSub.git
cd MiSub
npm install

配置本地环境变量

在项目根目录创建 .dev.vars 文件：

1
2
3
ADMIN_PASSWORD=admin123
JWT_SECRET=supersecretkey123
COOKIE_SECRET=supersecretkey123

启动开发服务器

需要同时启动两个终端：

终端 1 — 后端（Cloudflare Pages Functions）：

1
npm run dev:server -- --ip 0.0.0.0 --kv MISUB_KV --persist-to .wrangler/state-local

后端将在 http://localhost:8787 运行。

终端 2 — 前端（Vite 开发服务器）：

1
npm run dev

前端将在 http://localhost:5173 运行，Vite 会自动将 /api 和 /sub/ 路径的请求代理到后端。

生产构建预览

1
2
npm run build     # 构建生产版本到 dist/
npm run preview   # 本地预览生产构建

运行测试

1
2
npm test -- --run        # 运行所有测试
npm run test:coverage    # 运行测试并生成覆盖率报告

常见问题

Q1：部署完成后访问页面空白或报错？

  • 确认 KV 命名空间绑定 已正确配置，变量名必须是 MISUB_KV
  • 检查 环境变量 是否已保存并重新部署
  • 查看 Cloudflare Pages 的 Functions 日志 排查错误

Q2：如何更新到最新版本？

如果你的部署是连接 Git 仓库的方式，只需在 Fork 的仓库中同步上游代码：

  1. 在 GitHub 上同步 upstream 的最新代码
  2. Cloudflare Pages 会自动检测到新的提交并重新部署
  3. 也可以在 Pages 项目页面手动点击 Deploy latest commit

也可以配置 GitHub Actions 自动同步上游（项目已自带 fork-sync.yml 工作流）。

Q3：KV 和 D1 应该选哪个？

对比项 KV D1
写入性能 一般（最终一致性） 较高（强一致性）
查询能力 按键查询 完整 SQL 查询
免费额度 每天 1000 次写入 每月 500 万行读取
推荐场景 订阅少、使用频率低 订阅多、频繁刷新

建议： 大多数用户同时绑定 KV 和 D1。MiSub 会优先使用 D1，D1 不可用时回退到 KV。

Q4：订阅链接无法获取节点？

  • 检查网络环境，上游订阅链接是否可访问
  • 可在系统设置中配置 外部抓取代理（Vercel Fetch Proxy）来解决网络限制问题
  • 查看操作日志中的详细错误信息

Q5：如何导入外部订阅转换器？

MiSub 支持对接 subconverter 或 FatSheep 等外部转换后端，在 系统设置 → 订阅设置 中配置外部转换器地址即可。

总结

MiSub 的部署流程可以概括为以下几步：

1
2
3
Fork 仓库 → Cloudflare Pages 连接 Git → 创建 KV 绑定
→ （可选）创建 D1 数据库并初始化 → 设置环境变量
→ （可选）配置 Cron 触发器 → 重新部署 → 登录使用

整个部署过程在 Cloudflare 免费计划内即可完成，不需要购买任何付费服务。部署完成后，你就能拥有一个功能完整的私有订阅管理面板，随时随地管理你的代理节点和订阅配置。

如果你在部署过程中遇到任何问题，欢迎在项目 GitHub Issues 中提出。

本文档最后更新于 2026 年 6 月，对应 MiSub v2.7.0 版本。