部署指南

本指南将帮助你将 IAM 项目部署到 Cloudflare。当前生产架构中，公开前端域名为 https://iam.cq-i.cn。Hono 后端 iam-api 通过 Cloudflare Service Binding AUTH_API 被 Web Worker 调用，不必再走公网 URL。

Cloudflare 部署

前端部署 (apps/web)

1. OpenNext 配置

前端通过 @opennextjs/cloudflare 部署，apps/web/wrangler.jsonc 绑定自定义域名：

{
  "routes": [{ "pattern": "iam.cq-i.cn", "custom_domain": true }],
  "services": [{ "binding": "AUTH_API", "service": "iam-api" }]
}

2. API 代理（必做，否则接口无 session）

浏览器必须统一访问 https://iam.cq-i.cn/api/auth/*，再由 Web Worker 通过 Service Binding 转发到 Hono 后端。这样 Better Auth 下发的 HttpOnly Cookie 会保存到 iam.cq-i.cn，前端只通过 authClient.useSession() 获取会话状态。

生产环境不要把 iam-api 当作公开 issuer。OAuth/OIDC issuer 固定为 https://iam.cq-i.cn/api/auth。

3. 环境变量

前端生产不需要 AUTH_UPSTREAM_URL。该变量只用于本地 Next.js 回退到 http://localhost:8787。

后端部署 (apps/server)

1. Worker 配置

后端通过 Hono Worker 部署，生产环境变量在 apps/server/wrangler.jsonc 中固定公开 issuer：

{
  "BETTER_AUTH_URL": "https://iam.cq-i.cn/api/auth",
  "CORS_ORIGIN": "https://iam.cq-i.cn"
}

2. 环境变量

确保设置所有服务器环境变量：

• DATABASE_URL: PostgreSQL 连接字符串
• DATABASE_URL_DIRECT: 直接数据库连接（用于迁移）
• BETTER_AUTH_SECRET: 认证密钥（至少 32 个字符）
• BETTER_AUTH_URL: 公开认证服务 URL，生产固定为 https://iam.cq-i.cn/api/auth
• CORS_ORIGIN: 允许的前端来源，生产固定为 https://iam.cq-i.cn
• AUTH_EMAIL_FROM: 认证邮件发件人
• NODE_ENV: 环境类型（production）

后端还需要 R2 Binding UPLOADS 指向 iam 存储桶，以及 Cloudflare Email Binding EMAIL。生产发布请使用根目录 pnpm deploy：它会先部署 iam-api，成功后再部署 iam-web。

3. Secret 与 Binding

apps/server/wrangler.jsonc 的 secrets.required 是生产 secret 白名单。数据库、Better Auth 和企业微信凭据使用 wrangler secret put，不要写入 vars 或提交到 Git。

当前 Binding：

• UPLOADS：R2 bucket iam
• EMAIL：认证邮件发送
• AUTH_API：定义在 Web Worker，目标为 iam-api

BOOTSTRAP_ADMIN_WECOM_USER_IDS 建议作为 secret 配置；它非空时会成为企微用户平台管理员角色的权威名单。

Hono 服务器配置

确保 apps/server/src/index.ts 导出 Hono 应用：

// Worker 部署时导出 Hono 应用
export default app

Wrangler 会按 apps/server/wrangler.jsonc 将其作为 Worker 部署。

构建和优化

构建命令

# 构建所有应用
pnpm run build

# 检查类型
pnpm run check-types

# lint + 格式校验 + 类型检查（不修改文件）
pnpm run check

构建优化

1. 使用 Turborepo 缓存

   • 构建结果自动缓存
   • 只重新构建变更的包

2. 环境变量优化

   • 只在需要的地方使用环境变量
   • 使用 @IAM/env 包进行类型验证

3. 代码分割

   • Next.js 自动代码分割
   • 使用动态导入减少初始包大小

依赖分析与自动更新

部署后应持续监控依赖健康度，并自动修复有问题的依赖（安全漏洞、过时版本等）。推荐使用依赖分析机器人集成到仓库中。

为什么需要依赖分析机器人？

• 安全：及时发现并修复已知漏洞（CVE）
• 兼容性：避免依赖版本过旧导致的构建或运行时问题
• 维护成本：自动化 PR，减少人工巡检

推荐方案

1. GitHub Dependabot（推荐，GitHub 原生）

在仓库根目录创建 .github/dependabot.yml：

version: 2
updates:
  # 根 package.json（Monorepo 根）
  - package-ecosystem: 'npm'
    directory: '/'
    schedule:
      interval: 'weekly'
    open-pull-requests-limit: 10
    versioning-strategy: increase
    labels:
      - 'dependencies'

  # 前端
  - package-ecosystem: 'npm'
    directory: '/apps/web'
    schedule:
      interval: 'weekly'
    open-pull-requests-limit: 5
    labels:
      - 'dependencies'
      - 'apps/web'

  # 后端
  - package-ecosystem: 'npm'
    directory: '/apps/server'
    schedule:
      interval: 'weekly'
    open-pull-requests-limit: 5
    labels:
      - 'dependencies'
      - 'apps/server'

  # 文档站
  - package-ecosystem: 'npm'
    directory: '/apps/docs'
    schedule:
      interval: 'weekly'
    open-pull-requests-limit: 3
    labels:
      - 'dependencies'
      - 'apps/docs'

Dependabot 会自动：

• 按周检查各目录的 package.json
• 为有问题的依赖（含安全建议）创建 PR
• 在 GitHub 的 Security 标签页展示漏洞告警

2. Renovate（功能更细、可定制）

若需要更细粒度策略（如分组更新、自动合并小版本），可使用 Renovate。在根目录添加 renovate.json：

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "schedule": ["before 10am on monday"],
  "packageRules": [
    {
      "matchUpdateTypes": ["patch", "minor"],
      "groupName": "non-major dependencies",
      "automerge": true
    },
    {
      "matchDepTypes": ["devDependencies"],
      "groupName": "devDependencies"
    }
  ],
  "vulnerabilityAlerts": {
    "enabled": true
  }
}

可在 GitHub / GitLab 中安装 Renovate App，由机器人自动提交流量更新与安全修复 PR。

3. 仅安全更新（最小化打扰）

若只想自动处理有问题的依赖（漏洞），可：

• Dependabot：在仓库 Settings → Security → Dependabot alerts 中开启 “Dependabot security updates”，仅对存在漏洞的依赖自动开 PR。
• Renovate：依赖上述 vulnerabilityAlerts，并配合 matchUpdateTypes: ["patch"] 等规则，只自动合并补丁/安全更新。

部署流程中的配合

1. CI 必须通过才合并 依赖机器人开的 PR 需与普通 PR 一样跑 CI（build、test、lint）。在 GitHub 中为默认分支配置 Branch protection，要求状态检查通过后再合并。

2. 优先处理安全类 PR 对标记为 security / dependencies 的 PR 优先 Review 与合并，必要时先合安全更新再处理大版本升级。

3. 定期人工复核 每月查看一次依赖大版本与废弃通知，评估升级计划（如 Node 版本、React/Next 主版本），避免长期积压。

检查清单

• 已启用 Dependabot 或 Renovate，并覆盖根目录与各 apps/* 的 package.json
• 已开启“仅安全更新”或每周依赖更新（按团队偏好二选一或组合）
• 依赖更新 PR 需通过 CI 方可合并
• 团队约定：安全/依赖类 PR 优先处理

基础设施部署最佳实践

地区选择原则

重要提示：Cloudflare Worker 与 Neon 数据库应选择相近地区，避免跨洲往返。

为什么需要同地区部署？

1. 延迟问题

   • 跨洲网络延迟通常为 100-300ms，甚至更高
   • 同地区延迟通常 < 10ms
   • 认证流程包含多次数据库查询，延迟会累积
   • 跨洲部署会导致用户体验显著下降

2. 性能影响

   • 登录、授权码兑换和限流都会访问 Postgres
   • 跨洲延迟会显著增加响应时间
   • 可能导致超时和连接失败

3. 成本考虑

   • 跨洲数据传输可能产生额外费用
   • 同地区部署可以优化成本

推荐部署方案

亚太地区示例：

Cloudflare Workers (iam-web + iam-api，Service Binding)
    ↓ < 10ms
PostgreSQL（Neon ap-southeast-1）

推荐地区组合：

• 亚太地区：Workers 边缘执行 + Neon ap-southeast-1
• 其他地区：同样把 Neon 区域选在用户附近

如何验证地区配置

1. 检查数据库连接字符串

   # PostgreSQL 连接字符串应包含地区信息
   # 例如：ep-xxx.ap-southeast-1.aws.neon.tech

2. 测试延迟

   # 从 Worker 到 Neon 的往返延迟应该 < 20ms（同地区）
   # 如果 > 100ms，可能是跨洲部署

部署检查清单

在部署前，确认：

• Cloudflare Worker 部署地区：✅ / ❌
• PostgreSQL 数据库地区：✅ / ❌
• Workers 与 Neon 在相近地区：✅ / ❌
• 测试延迟 < 20ms：✅ / ❌

常见错误示例

❌ 错误配置：

Worker：Cloudflare
PostgreSQL：Neon（欧洲）

结果：每次请求延迟 200-400ms，用户体验极差

✅ 正确配置：

Worker：Cloudflare
PostgreSQL：Neon (ap-southeast-1)
双 Worker 通过 AUTH_API Service Binding 通信

结果：每次请求延迟 < 20ms，性能优秀

部署检查清单

前端部署

• 设置正确的 Root Directory
• apps/web/wrangler.jsonc 配置 AUTH_API Service Binding 指向 iam-api
• 配置所有必要的环境变量
• 测试生产构建：pnpm run build

后端部署

• 设置正确的 Root Directory
• 配置所有服务器环境变量
• 确保数据库连接字符串正确
• 创建 R2 存储桶 iam 并绑定 UPLOADS
• 配置 EMAIL Binding、发件地址和 AUTH_EMAIL_FROM
• 验证 CORS 配置允许前端域名
• 测试生产构建：pnpm run build

数据库

• 创建生产数据库
• 运行数据库迁移：pnpm run db:migrate
• 验证数据库连接

认证

• 生成安全的 BETTER_AUTH_SECRET
• 配置 BETTER_AUTH_URL=https://iam.cq-i.cn/api/auth
• 配置 CORS_ORIGIN=https://iam.cq-i.cn
• 复核 BOOTSTRAP_ADMIN_WECOM_USER_IDS 和企业微信 secret

依赖分析与自动更新

• 已配置 Dependabot 或 Renovate，覆盖 monorepo 各应用
• 已开启安全漏洞自动 PR 或每周依赖检查
• 依赖更新 PR 需通过 CI 方可合并

常见问题

构建失败

1. 检查环境变量是否在 turbo.json 中声明
2. 验证所有依赖都已安装
3. 查看构建日志中的错误信息

运行时错误

1. 检查环境变量是否正确设置
2. 验证数据库连接
3. 检查 CORS 配置

类型错误

1. 运行 pnpm run check-types 检查类型
2. 确保所有 workspace 依赖都已构建

下一步

• 查看 常见任务
• 了解 开发工作流
• 学习 认证系统