部署到 Cloudflare Workers — Downcity City SDK Docs

这页是 Federation 项目部署到 Cloudflare Workers 的正式操作路径。

如果你只是想理解 Federation 怎么接入 Workers，先读 Cloudflare Workers。这一页只讲上线步骤：federation.json、本地创建、本地部署、D1 / Queue / R2、admin key、env、OAuth callback 和健康检查。

前置条件

一个 Cloudflare 账号
已经在项目里安装依赖

Downcity 不会在 git push 后自动部署 Worker。部署是显式动作：

fed deploy

1. 创建 Federation 项目

开发者通常从一个空目录开始：

mkdir my-city
cd my-city
fed create .

fed create . 会交互式询问 Federation 名称和部署目标，并生成项目骨架：

federation.json
src/index.ts
package.json
tsconfig.json

生成后的 federation.json 只保存项目基本信息：

{
  "schema": 1,
  "type": "city",
  "name": "my-city",
  "target": "cloudflare-workers",
  "entry": "src/index.ts",
  "resources": {
    "d1": {
      "binding": "DB",
      "name": "my-city-db"
    },
    "queue": {
      "binding": "DOWNCITY_QUEUE",
      "name": "my-city-queue"
    },
    "storage": {
      "type": "r2",
      "binding": "DOWNCITY_STORAGE",
      "name": "my-city-storage",
      "public_url_prefix": "https://images.example.com"
    }
  }
}

type 表示这是一个 Federation 项目，target 表示部署目标。当前支持 cloudflare-workers，也就是部署到 Cloudflare Edge Worker。entry 和 resources 是可提交的部署意图；D1 database id、Cloudflare account、Worker URL 和 wrangler 配置都由 fed deploy 在部署时处理，不写进 federation.json。

如果项目模板已经在 Git 仓库里，先用 fed create 拉到本地：

fed create https://github.com/example/my-city.git
cd my-city

fed deploy 不直接部署远程 URL。它只部署本地 Federation 项目，这样 .env 和部署结果有明确归属。

2. 部署当前目录

在 Federation 项目目录里直接执行：

fed deploy

如果 federation.json 的 target 是 cloudflare-workers，fed deploy 会自动检查 Cloudflare 登录态。没有登录时会唤起 Wrangler 登录；已经登录但 Cloudflare 无法自动返回 account 时，会提示你刷新登录，或输入一次 Cloudflare account id。输入的 account id 会保存到项目 .env，后续部署会自动复用。

也可以显式传目录：

fed deploy ./my-city

3. 资源配置

Cloudflare Workers 目标当前支持三类资源：

{
  "resources": {
    "d1": {
      "binding": "DB",
      "name": "my-city-db"
    },
    "queue": {
      "binding": "DOWNCITY_QUEUE",
      "name": "my-city-queue"
    },
    "storage": {
      "type": "r2",
      "binding": "DOWNCITY_STORAGE",
      "name": "my-city-storage",
      "public_url_prefix": "https://images.example.com"
    }
  }
}

如果没有显式配置 D1 / Queue，fed deploy 会根据 federation.json.name 使用默认名称 ${name}-db 和 ${name}-queue。Storage 只有在 resources.storage 存在时启用。

部署时会复用同名 D1、Queue 和 R2 bucket；没有同名资源且不是 --dry-run 时会自动创建。D1 database id 是 Cloudflare 部署状态，不会写回项目配置。

Cloudflare account 不属于 Federation 项目配置。fed deploy 会优先复用 Wrangler 登录态；只有 Cloudflare 无法自动识别 account 时，才会引导你输入一次并保存到本地 fed CLI 状态。

也可以部署时临时传入 account id：

fed deploy --account-id <your-cloudflare-account-id>

4. Dry-run

正式发布前先检查 bundle 和 Wrangler 配置：

fed deploy --dry-run

如果部署别的目录：

fed deploy ./my-city --dry-run

5. 部署过程

fed deploy 会执行这些步骤：

读取目标目录的 federation.json
根据 federation.json.target 检查目标平台登录态；Cloudflare Workers 会自动唤起 Wrangler 登录或引导选择 account
如果不是 --dry-run，先把项目 package.json.version 自动做一次 patch 自增
如果 package.json 有 build，执行 pnpm build
如果 package.json 有 typecheck，执行 pnpm typecheck
对 cloudflare-workers target 按 resources.d1.name 查找 D1；不存在时自动创建
按 resources.queue.name 查找 Queue；不存在时自动创建
如果声明了 resources.storage，按 resources.storage.name 查找 R2 bucket；不存在时自动创建
临时生成 Wrangler 配置，不写入项目目录
执行 wrangler deploy --config <generated-wrangler.toml>
自动把部署出来的 Worker URL 注册成当前 Federation
在传入 --verify 时请求 Worker /health

部署输出会按阶段汇总显示：Project、Version、Build、Typecheck、D1 Database、Queue、Storage、Wrangler、Deployment 和 Active Server。

federation.json 只保留可提交的项目声明。业务密钥、provider keys 和 service env 应该写入 Federation 自己的 env 表，不写入 federation.json。

fed deploy --dry-run 和 fed deploy --verify-only 不会修改项目版本号。

6. 开发者 edge 快捷示例

Downcity 仓库里保留了 templates/edge 作为开发者快捷示例：

fed deploy templates/edge --verify

这个示例适合本地实验和自定义部署。Downcity 官方私有生产 Worker 实现维护在公开仓库之外。

7. 初始化 Federation

部署完成后，请求一次 /health。这会让 Worker 启动 Federation，并创建内置的 env / cities 表。

curl https://my-city.<your-subdomain>.workers.dev/health

返回大致如下：

{
  "ok": true,
  "services": ["env", "cities", "accounts", "balance", "payment", "usage", "ai"]
}

8. 取回 admin key

Federation 首次启动时会把 DOWNCITY_FEDERATION_ADMIN_SECRET_KEY 写入自己的 env 表。Workers + D1 部署下，可以从远程 D1 查询：

npx wrangler d1 execute my-city-db --remote \
  --command "SELECT value FROM env WHERE key='DOWNCITY_FEDERATION_ADMIN_SECRET_KEY'"

请把这个 key 存在可信位置。它是 Admin City、fed CLI 或直接调用 admin HTTP 接口时使用的管理凭证。

9. 写入 provider 和 service env

Provider API key 和服务密钥应该写入 Federation 自己的 env 表，不应该进入公开客户端。

示例：

curl -X POST https://my-city.<your-subdomain>.workers.dev/v1/env/upsert \
  -H "Authorization: Bearer <admin_secret_key>" \
  -H "Content-Type: application/json" \
  -d '{"key":"DEEPSEEK_API_KEY","value":"sk-..."}'

常见 key：

Key	用途
`DEEPSEEK_API_KEY`	edge 快捷示例默认使用的 provider key
`STRIPE_SECRET_KEY`	创建 Stripe Checkout 的 API key
`STRIPE_WEBHOOK_SECRET`	Stripe webhook 签名密钥
`DOWNCITY_CITY_BASE_URL`	City 对外访问地址，用于生成支付结果页
`CREEM_API_KEY`	创建 Creem Checkout 的 API key
`CREEM_PRODUCT_ID`	Creem 托管 Checkout 使用的 product
`CREEM_WEBHOOK_SECRET`	可选，Creem webhook 签名密钥
`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`	可选，Google OAuth 登录
`WECHAT_CLIENT_ID` / `WECHAT_CLIENT_SECRET`	可选，微信网站应用登录

10. 配置 OAuth callback

如果你开启 OAuth 登录，需要把 provider 的 callback URL 配成 Worker 对外地址：

https://my-city.<your-subdomain>.workers.dev/v1/accounts/oauth/callback

callback 域名必须和用户实际访问的公开域名一致。如果之后切到自定义域名，也要同步更新 OAuth provider 里的回调地址。

11. 验证

如果当前已经连接过 Federation，可以只执行健康检查：

fed deploy --verify-only

也可以手动检查：

curl https://my-city.<your-subdomain>.workers.dev/
curl https://my-city.<your-subdomain>.workers.dev/health

更新部署

修改代码后：

fed deploy --verify

运行时 env 保存在 D1 里，所以重新部署 Worker 不会丢失 provider key、OAuth secret、city、余额、usage 记录或 Stripe 支付记录。