Cloudflare Workers 部署

该形态下：代理服务与管理后台各为一个 Worker，共享同一 D1（绑定名 DB）。这是 OctaFuse 的默认生产路径——个人与小流量通常可在 Workers / D1 免费额度内完成部署与日常使用。

一键运行引导脚本（推荐）

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
npm install
npx wrangler login
npm run bootstrap:cloudflare

脚本会：创建或复用 D1 → 执行远程迁移 → 部署代理服务 / 管理后台 → 写入 ADMIN_PASSWORD Secret → 打印下游 GATEWAY_* 配置提示。

本机先试用、不上云：见快速开始 · 本机启动。

如何更新版本

为已上线实例发布新版本时，请在 octafuse-gateway 仓库根目录操作。升级前先备份重要配置，并阅读该版本的发布说明（Release）和变更日志（Changelog）中的升级说明。

git pull --ff-only
npm ci

有新的 D1 迁移时（推荐：先迁移，再部署依赖新数据库结构的 Worker）：

npm run deploy:cloudflare -- <instance> --migrate

没有数据库变更时：

npm run deploy:cloudflare -- <instance>

也可只更新一侧：

npm run deploy:cloudflare -- <instance> --proxy-only
npm run deploy:cloudflare -- <instance> --admin-only

<instance> 对应 cloudflare-worker/<instance>.env（例如 production）。D1 迁移不会因为 Worker 重新部署而自动执行；Workers Builds（Connect to Git）同样不会自动跑迁移，有新 SQL 时仍须带 --migrate 或先 db:migrate:remote。

完整排障与清理说明见 OctaFuse Gateway Cloudflare 快速部署 · 后续升级。

配置模型（深入）

层级	说明
`packages/*/wrangler.base.jsonc`	已提交模板（无生产 `database_id`）
`packages/proxy/wrangler.jsonc` 等	生成产物（gitignore），由 `gen:wrangler` 写入
`cloudflare-worker/example.env`	开发演示的基准配置（可提交）
`cloudflare-worker/<instance>.env`	生产 / 私有（gitignore）；或仅使用 Cloudflare Dashboard 的构建变量（Build variables）

gen-wrangler 只读取环境变量（process.env），无论它们来自 Cloudflare Dashboard 还是 dotenv -e 文件。

其它路径

路径	何时用
本地开发	本机改代码、本地 D1（见快速开始）
开发演示	公共测试 `test-api.octafuse.dev`（`example.env` + CLI）
Workers Builds	通过连接 Git（Connect to Git）自动发布（D1 迁移仍需手动）

远程部署后回到本地开发

执行过 deploy:* 或 db:migrate:remote 后，本机生成的 wrangler.jsonc 可能带有远程 D1_DATABASE_ID。回到本地开发前，请在未导出 D1_DATABASE_ID 的 shell 中执行 npm run gen:wrangler，再重启 dev:proxy / dev:admin。

Workers Builds 命令（可选）

根目录（Root directory）留空（即 monorepo 根目录）。npm ci 的 postinstall 会运行 gen:wrangler。

Worker	Build command	Deploy command
Proxy	`npm ci && npm run gen:wrangler`	`npm run deploy -w @octafuse/proxy`
Admin	`npm ci && npm run gen:wrangler && npm run build:cf -w @octafuse/admin`	`cd packages/admin && npx opennextjs-cloudflare deploy`

Secret 与下游配置

ADMIN_PASSWORD：引导脚本会写入；也可执行 npx wrangler secret put ADMIN_PASSWORD --name <ADMIN_WORKER_NAME>。
下游门户：GATEWAY_URL（代理服务）、GATEWAY_MASTER_URL（管理后台）、GATEWAY_MASTER_KEY（D1 system_config.MASTER_KEY）。种子为 sk-dev-admin-key 时，须在管理后台的系统配置（Config）中轮换。

与 Docker 自建如何选

默认 / 边缘 / 免自备服务器 → 本页（Cloudflare）。
数据驻留、内网、BYO Postgres/MySQL → Docker 部署。