Sub-Store Workers

Sub-Store 后端的 Cloudflare Workers 移植版

注意：一键部署按钮仅供参考，由于项目需要本地构建（esbuild + Sub-Store 源码），实际无法直接通过此按钮完成部署。请参照下方手动部署步骤。

自动部署：本仓库已内置 GitHub Actions 工作流，每天自动检测上游 Sub-Store 更新并部署到 Cloudflare。只需配置 Secrets 即可开启，无需本地操作。详见 GitHub Actions 自动同步上游。

简介

将 Sub-Store 后端部署到 Cloudflare Workers / Pages，无需服务器，免费使用。

• 零服务器：运行在 Cloudflare 边缘网络
• KV 持久化：数据存储在 Cloudflare KV
• 完整功能：复用原始后端全部业务逻辑（订阅管理、格式转换、下载、预览等）
• 预编译解析器：peggy 文法在构建时编译，避免运行时 eval()

目录

• 部署（核心流程，建议从这里开始）
• 进阶配置 / 平台说明（推送、环境变量、本地开发等，已折叠）
• FAQ
• 同步更新
• Surge 面板脚本
• 致谢 ｜ 许可证

sub-store-workers/src/        ← Workers 适配层（6 个文件）
Sub-Store/backend/src/        ← 原始后端源码（直接复用）
esbuild.js                    ← 构建脚本，通过插件桥接两者

部署

部署总览：1.准备 → 2.上传 Workers/Pages → 3.设密码（必做）→ 4.连接前端

为什么两个都要部？*.workers.dev 在国内被 GFW 封锁，*.pages.dev 走 Cloudflare CDN 通常可直连。

• 有自定义域名：只用 Workers 即可
• 无自定义域名：Pages 对外提供 API，Workers 在后台跑 Cron。

1. 克隆仓库

# 目录结构必须如下：
# parent/
#   ├── Sub-Store/          ← 原始后端源码
#   └── sub-store-workers/  ← 本项目

git clone https://github.com/sub-store-org/Sub-Store.git
git clone https://github.com/Yu9191/sub-store-workers.git

cd sub-store-workers
npm install

2. 登录 Cloudflare

npx wrangler login

3. 创建 KV 命名空间

npx wrangler kv namespace create SUB_STORE_DATA

将返回的 id 填入 wrangler.toml：

[[kv_namespaces]]
binding = "SUB_STORE_DATA"
id = "你的KV命名空间ID"

4. 构建 & 部署

两者都需要部署：

⚠️ 执行下方部署命令前，请先确认已完成「1. 克隆仓库」「2. 登录 Cloudflare」「3. 创建 KV 命名空间」三步，并完整阅读下文「5. 连接前端」「6. API 鉴权」两节。部署完未设密码前 Worker 是公开的，任何人都能管理你的数据。

# Workers 部署（含 Cron Triggers）
npm run deploy

# Pages 部署（国内可用，一条命令）
npm run deploy:pages

强烈建议部署后立即设置鉴权密码，否则任何人都能管理你的 Sub-Store 数据：

# Windows
npm run rotate-secret

# Linux / macOS
npm run rotate-secret:sh

脚本会生成随机 URL-safe 密码，写入 Cloudflare Worker Secret，并复制到剪贴板。详细说明见下文“6. API 鉴权”。

Pages 部署完成后还需要在 Cloudflare Dashboard 中：

1. 绑定 KV 命名空间 SUB_STORE_DATA
2. 设置鉴权密码 Secret SUB_STORE_FRONTEND_BACKEND_PATH

详细图文步骤见下文 6. API 鉴权 → 方式 A.2 Pages 端。配置完成后必须再跑一次 npm run deploy:pages 让绑定生效。

5. 连接前端

打开 Sub-Store 前端，后端地址格式：

你的域名/你的密码

例如：

https://sub-store-workers.your.workers.dev/aBc123XyZ
https://sub-store.your.pages.dev/aBc123XyZ

注意：末尾的 /密码 不能省略，否则 /api/... 会全部 401。

部署完后访问 https://你的域名/你的密码/api/utils/worker-status，应返回：

{ "kv": { "bound": true }, "auth": { "backendPathConfigured": true } }

6. API 鉴权（强烈建议 / 已在第 4 步完成可跳过）

默认 API 无密码保护。不设密码任何人都能管理你的订阅。第 4 步执行 npm run rotate-secret 已经设过的话，可以跳过本节。

推荐使用 Worker / Pages Secret（加密存储）。不要写到 wrangler.toml [vars] 里——那里是明文，会随 commit 泄漏，并且 wrangler deploy 会用它覆盖同名 Secret，与下面的流程冲突。

方式 A（推荐）：使用 Cloudflare Secret

A.1 Workers 端（项目自带脚本）

仓库提供了密钥轮换脚本，一行命令完成生成 + 写入 + 复制到剪贴板：

# Windows
npm run rotate-secret

# Linux / macOS
npm run rotate-secret:sh

脚本会：

• 用加密随机数生成 32 位 URL-safe 密码
• 自动加 / 前缀
• 通过管道写入 Cloudflare Worker Secret SUB_STORE_FRONTEND_BACKEND_PATH（密码不落盘、不显示在屏幕、不进入 shell 历史）
• 复制到剪贴板，方便粘贴到前端配置

执行成功后，请同步更新：

1. 前端后端地址：https://xxx.workers.dev<剪贴板里的新密码>
2. 如果使用 GitHub Actions 自动部署，还要更新仓库 Secret（如 SUB_STORE_PASSWORD_VALUE）

用完后建议清空剪贴板：

• PowerShell：Set-Clipboard -Value $null
• macOS：pbcopy </dev/null
• Linux：wl-copy --clear 或 xsel --clipboard --clear

也可以手动设置（提示输入时填带 / 开头的密码）：

npx wrangler secret put SUB_STORE_FRONTEND_BACKEND_PATH

A.2 Pages 端（在 Dashboard 配置）

wrangler.toml 的 [[kv_namespaces]] 与 [vars] 只对 Workers 生效。Pages 项目必须在 Cloudflare Dashboard 单独绑定 KV 与设置密码，否则 API 会因为缺少 KV 而 500，且任何人都可访问管理 API。

① 进入 Workers & Pages，点击 sub-store 项目

② 进入 设置 → 绑定，点击 + 添加 KV 命名空间

③ 选择 KV 命名空间

④ 变量名填 SUB_STORE_DATA，选择对应 KV，保存

⑤ 进入 设置 → 变量和机密，点击 + 添加

⑥ 变量名填 SUB_STORE_FRONTEND_BACKEND_PATH，值填 /你的密码（必须带 / 开头），类型选 Secret（加密），保存

保存后必须重新部署 npm run deploy:pages 才能生效。

Pages 不能跨项目共享 Worker Secret，建议把 Workers 与 Pages 的 SUB_STORE_FRONTEND_BACKEND_PATH 设为同一个值，方便前端切换。

方式 B（不推荐）：使用 wrangler.toml [vars] 明文变量

[vars]
SUB_STORE_FRONTEND_BACKEND_PATH = "/你的密码"

仅在临时调试时使用。明文写仓库文件容易随 commit 泄漏；同时 wrangler deploy 会用它覆盖 Secret，破坏方式 A 的 CI/Secret 流程。生产环境请使用方式 A。

分享链接（download/preview）不受鉴权影响，无需密码即可访问。

分享按钮：订阅列表里的“分享”按钮仅在通过密码前缀访问时显示（与上游 Docker/Node 部署的 be_merge 行为一致），未配置密码前缀的部署不会显示分享按钮。

进阶配置 / 平台说明

npm run dev

[vars]
SUB_STORE_PUSH_SERVICE = "https://api.day.app/你的BarkKey/[推送标题]/[推送内容]"

https://你的域名/你的密码/api/utils/worker-status

[triggers]
crons = ["55 15 * * *"]  # UTC 时间，+8 即北京时间

FAQ

同步更新

cd sub-store-workers
git pull
npm run deploy

cd Sub-Store
git pull

cd ../sub-store-workers
npm run deploy

每天 00:00（北京时间）自动触发
  ↓
拉取上游最新 commit，对比已部署版本
  ↓ 有更新
安装依赖 → 运行上游测试套件
  ↓ 测试通过
构建 → 部署 Workers → 部署 Pages → 健康检查
  ↓ 全部成功
记录已部署版本 + Bark 通知

任何环节失败 → Bark 通知"同步失败"，线上版本不受影响

Surge 面板脚本

https://raw.githubusercontent.com/Yu9191/sub-store-workers/main/surge/SubStorePanel.sgmodule

致谢

基于 Sub-Store 项目，感谢原作者及所有贡献者。

QuickJS WASM Script Operator 适配来自用户 PR，贡献者：0xPoker。

许可证

GPL V3