部署

本项目是 Cloudflare Workers，提供两种部署方式，任选其一：

1. GitHub Actions 自动部署（推荐）—— push 到 master 后自动「测试 → 部署」；
2. 本地手动部署 —— 在自己机器上跑 wrangler deploy。

两种方式共用同一份配置（wrangler.jsonc）与同一组运行时 secret （API_KEY / CREDENTIAL_KEY），区别只在「谁执行 wrangler deploy」。

前置条件

• Node.js ≥ 22（wrangler 4.x 要求；Node 20 会在部署时报 Wrangler requires at least Node.js v22.0.0）
• Cloudflare 账号 —— Free 计划足够（Durable Objects 在 Free 计划可用，仅 SQLite 后端）
• 首次部署需要认证：npx wrangler login，或 export CLOUDFLARE_API_TOKEN=<token>（需「Edit Cloudflare Workers」权限）

本地部署（三步）

# 1. 安装依赖
npm install

# 2. 设置两个必须的 secret
openssl rand -base64 32 | npx wrangler secret put API_KEY        # 面板与 API 的口令
openssl rand -base64 32 | npx wrangler secret put CREDENTIAL_KEY # 凭据加密密钥

# 3. 部署
npm run deploy

secret	用途	漏设的后果
API_KEY	登录面板用的主密钥，也是 /v1/* 的管理口令	所有请求 401（fail-closed）
CREDENTIAL_KEY	凭据的 AES-GCM 加密密钥	拒绝写入凭据（不静默明文落盘）

GitHub Actions 自动部署

push 到 master 后自动走「测试 → 部署」链，无需本地环境。

工作流一览

文件	名称	触发	作用
test.yml	1 - Test	push / PR	依赖安装（多镜像回退）+ typecheck + 全量单测
deploy-cf.yml	2 - Deploy Cloudflare	仅 1 - Test 成功后 / 手动	wrangler deploy + 可选同步运行时 secrets
docs.yml	3 - Docs	push（docs/ 变更）/ 手动	构建 VitePress 文档站；部署目标二选一：GitHub Pages（默认）或 Cloudflare Pages（仓库变量 DOCS_DEPLOY_TARGET=cloudflare 切换，项目名默认 free-llm-router-doc）

为什么分成多个：test 用 workflow_run 串联 deploy，保证只有测试通过才上线； 手动触发 deploy 可跳过测试直接部署（方便应急）。

配置 Secrets

在 GitHub 仓库 → Settings → Secrets and variables → Actions 里配置：

Secret 名	值
CF_ACCOUNT_ID	Cloudflare 账户 ID（Dashboard 首页右侧，或 wrangler whoami）
CF_API_TOKEN	用官方模板 「Edit Cloudflare Workers」 创建的 API Token（不是 Global Key）

⚠️ 首次创建 Worker 需要 Admin 权限：模板里的 Edit 只能更新已存在的 Worker。 若 Worker 还不存在，要么给 Token 加 Workers Scripts: Admin，要么先在本地手动 wrangler deploy 一次把 Worker 建出来，之后 CI 用普通模板即可。

运行时口令 API_KEY / CREDENTIAL_KEY

这两个值是 Worker 运行时读的 secret，与「能否部署」无关。两种设法任选其一：

方式 A：放 GitHub Secrets（推荐，随 Action 自动同步）

GitHub Secret 名	值
API_KEY	面板口令（openssl rand -base64 32 生成）
CREDENTIAL_KEY	凭据加密密钥（同上生成）

deploy-cf.yml 会在部署后自动 wrangler secret put 到 Worker：

• 只在 Secret 非空时才同步（未配置则跳过，保留 CF 端已有的值）；
• 幂等，重复部署无副作用；改值 = 改 GitHub Secret + 手动 Run 一次部署。

方式 B：只在 Cloudflare 侧设

openssl rand -base64 32 | npx wrangler secret put API_KEY
openssl rand -base64 32 | npx wrangler secret put CREDENTIAL_KEY

⚠️ 两种方式不要同时用：方式 B 的情况下若配了同名 GitHub Secrets， 下一次部署会把它覆盖掉。

⚠️ 两个值必须稳定：API_KEY 变了面板会到处 401；CREDENTIAL_KEY 变了 已存的账号凭据解不开。定了就不要乱改。

文档站部署目标（二选一）

文档站（本站）支持两种部署目标，互斥，靠仓库变量切换：

目标	切换方式	地址
GitHub Pages（默认）	不设置变量，或设 DOCS_DEPLOY_TARGET=github	https://docs.llm-gate.de5.net/（自定义域）
Cloudflare Pages	仓库变量 DOCS_DEPLOY_TARGET=cloudflare	https://free-llm-router-doc.pages.dev/（项目名可在 yml 的 CF_PAGES_PROJECT 改；可在 CF Dashboard 绑自定义域）

⚠️ Cloudflare Pages 目标需要补权限：CF_API_TOKEN 用的「Edit Cloudflare Workers」 模板不含 Pages 权限 —— 需在 Cloudflare Dashboard 给该 Token 追加 Account → Cloudflare Pages → Edit，否则上传会 403。

两种目标的部署地址都是根路径（DOCS_BASE=/），无需按目标改 base。

部署后自检

BASE=https://<你的域名>
KEY=<你的 API_KEY>

curl -s "$BASE/healthz"                                              # {"ok":true}
curl -s -H "Authorization: Bearer $KEY" "$BASE/admin/pool?realm=cn"
curl -s -H "Authorization: Bearer $KEY" "$BASE/v1/models" | head -c 200

浏览器打开 https://<你的域名>/panel/，填 API_KEY 登录。「配置与状态」页可直接 确认各部件是否就绪（账号数、IP 级拦截状态、凭据加密方式、Cron 时点）。

/ 根路径返回 401 是刻意的，避免被扫到。

常见部署问题

• 2 - Deploy Cloudflare 失败，日志是认证/权限错误 → 检查 CF_ACCOUNT_ID / CF_API_TOKEN 是否已配、Token 是否用「Edit Cloudflare Workers」 模板；报「不能创建 Worker」见上文 Admin 说明。
• 部署成功但面板 401 / 写入凭据被拒 → Worker 端 API_KEY / CREDENTIAL_KEY 没设或值不对。
• 首次 push 后只有 1 - Test、没有 2 - Deploy → test 失败了（去 Actions 看日志）；或 test 成功但 deploy 需手动触发。
• 本地 npm ci 通过、CI 却报 ERESOLVE → CI 的 npm 版本更旧、peer 校验更严格。用同款版本复现：npx -y npm@10.9.2 ci。

域名绑定

域名绑定（Worker Route / Custom Domain / 优选 IP）、workers.dev 兜底、迁移步骤等 细节较多，见仓库 DEPLOY.md 的「当前线上状态」一节。

移除

npx wrangler delete free-llm-router
# 验证探针（不需要可删）
npx wrangler delete workbuddy-egress-probe