Cloudflare Workers

如果你准备把 Downcity 部署到 Cloudflare Workers，推荐做法不是等一个单独的 edge package，而是直接把 @downcity/city 接到 Workers runtime。

公开仓库里保留了 templates/edgefed 作为开发者快捷示例。Downcity 官方私有 Worker 实现维护在公开仓库之外。

这条路径解决什么

Cloudflare Workers 和 Node.js 最大的不同，不是 HTTP 入口，而是 runtime 资源模型不同：

• 数据库通常来自 env.DB 这类 binding
• 环境变量读取不再是本地 .env 文件
• request origin 可能需要在每次请求时同步到 service
• Worker isolate 会复用，所以 runtime cache 需要自己管理

这也是为什么这里更适合用 guide 解释接法，而不是再抽一个空的 npm 包。

最小接法

Federation 需要一个 D1 Database Adapter：

import { Federation } from "@downcity/federation";
import { Database } from "@downcity/database-d1";

export interface Env {
  DB: D1Database;
}

export default {
  async fetch(request: Request, env: Env) {
    const database = new Database({ binding: env.DB });
    const base = new Federation({ database });

    await base.health();
    return base.fetch(request);
  },
};

这里的重点是 Adapter 明确拥有 D1 的运行时差异：

• D1 binding 只传给 @downcity/database-d1
• Adapter 内部组合 Drizzle，并负责快照冲突重试与原子提交
• City 和 Service 都不会拿到原始 D1 binding
• 当前请求 origin 可以在请求前同步给需要 OAuth callback 的 service

从 templates/edgefed 快捷示例开始

仓库里的 templates/edgefed/src/index.ts 只保留 Worker 接入 Federation 必需的边界：

• 用 @downcity/database-d1 把 env.DB 接成 Federation 可用数据库
• 在 Worker isolate 内复用 Federation 实例
• 把 HTTP request 交给 Federation 处理

业务 Service、模型和 provider 应由产品按需组合，不属于 Edge runtime 模板。

和 Node 路线的边界

Worker 和 Node 是同一套心智模型：都创建对应的 Database Adapter，然后传给 new Federation({ database })。

• Node.js 本地使用 @downcity/database-sqlite
• Node.js 生产可使用 @downcity/database-postgresql
• Workers / D1 使用 @downcity/database-d1

下一步

• 如果你还没搭 City 本体，先读 Federation
• 如果你要管理 provider key，继续读 provider 环境变量
• 如果你需要最小 Worker 接入示例，直接看 templates/edgefed/src/index.ts