部署指南

本指南将帮助你将 IAM 项目部署到 Vercel。

Vercel 部署

前端部署 (apps/web)

1. 项目设置

在 Vercel 项目设置中配置：

• Root Directory: apps/web
• Framework Preset: Next.js
• Build Command: pnpm build
• Output Directory: .next（自动检测）
• Install Command: pnpm install

2. 配置 vercel.json（必做，否则接口无 session）

部署前端时必须根据你的后端地址修改 apps/web/vercel.json 中的 rewrites，把认证请求转发到你自己的 API 服务器。若不修改，前端会把 /api/auth/* 请求发到默认或错误地址，导致接口拿不到 session、登录态失效。

在 apps/web/vercel.json 中把 destination 改成你实际的后端地址，例如：

{
  "rewrites": [
    {
      "source": "/api/auth/:path*",
      "destination": "https://你的后端域名.vercel.app/api/auth/:path*"
    }
  ]
}

• destination 需与 NEXT_PUBLIC_SERVER_URL 或你实际部署的后端地址一致。
• 修改并部署后，前端的认证请求会正确转发到后端，session 才能生效。

3. 环境变量

在 Vercel 项目设置中添加以下环境变量：

• NEXT_PUBLIC_SERVER_URL: API 服务器地址（例如：https://api.yourdomain.com）
• 其他必要的环境变量

后端部署 (apps/server)

1. 项目设置

在 Vercel 项目设置中配置：

• Root Directory: apps/server
• Framework Preset: Other
• Build Command: pnpm build
• Output Directory: dist
• Install Command: pnpm install

2. 环境变量

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

• DATABASE_URL: PostgreSQL 连接字符串
• DATABASE_URL_DIRECT: 直接数据库连接（用于迁移）
• KV_REST_API_URL: Upstash Redis REST API URL
• KV_REST_API_TOKEN: Upstash Redis REST API Token
• BETTER_AUTH_SECRET: 认证密钥（至少 32 个字符）
• BETTER_AUTH_URL: 认证服务 URL
• CORS_ORIGIN: 允许的跨域来源
• NODE_ENV: 环境类型（production）

3. Turborepo 配置

在 turbo.json 中声明环境变量，确保构建时可用：

{
  "tasks": {
    "build": {
      "env": [
        "BETTER_AUTH_SECRET",
        "BETTER_AUTH_URL",
        "CORS_ORIGIN",
        "DATABASE_URL",
        "DATABASE_URL_DIRECT",
        "KV_REST_API_URL",
        "KV_REST_API_TOKEN",
        "NEXT_PUBLIC_SERVER_URL"
      ]
    }
  }
}

Hono 服务器配置

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

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

Vercel 会自动识别并作为 Serverless Function 部署。

构建和优化

构建命令

# 构建所有应用
pnpm run build

# 检查类型
pnpm run check-types

# 代码格式化和检查
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 优先处理

基础设施部署最佳实践

地区选择原则

重要提示：后端服务器、PostgreSQL 数据库和 Redis 缓存必须在同一个地区部署，避免跨洲部署。

为什么需要同地区部署？

1. 延迟问题

   • 跨洲网络延迟通常为 100-300ms，甚至更高
   • 同地区延迟通常 < 10ms
   • 每次数据库查询和 Redis 操作都会累积延迟
   • 跨洲部署会导致用户体验显著下降

2. 性能影响

   • 认证流程需要多次数据库和 Redis 操作
   • 跨洲延迟会显著增加响应时间
   • 可能导致超时和连接失败

3. 成本考虑

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

推荐部署方案

亚太地区示例：

后端服务器 (Vercel/其他云服务)
    ↓ < 10ms
PostgreSQL (例如：Neon, Supabase, AWS RDS)
    ↓ < 10ms
Redis (例如：Upstash, Redis Cloud)

推荐地区组合：

• 亚太地区：选择同一地区的服务

  • 后端：Vercel (亚太边缘节点)
  • PostgreSQL：Neon (ap-southeast-1) 或 Supabase (亚太区域)
  • Redis：Upstash (ap-southeast-1) 或 Redis Cloud (亚太区域)

• 其他地区：同样遵循同地区原则

  • 北美：us-east-1, us-west-1 等
  • 欧洲：eu-west-1, eu-central-1 等

如何验证地区配置

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

   # PostgreSQL 连接字符串应包含地区信息
   # 例如：postgresql://user:pass@host.ap-southeast-1.rds.amazonaws.com/db

2. 检查 Redis 配置

   # Upstash Redis URL 应包含地区
   # 例如：https://xxx-xxx-xxx.ap-southeast-1.upstash.io

3. 测试延迟

   # 从后端服务器 ping 数据库和 Redis
   # 延迟应该 < 20ms（同地区）
   # 如果 > 100ms，可能是跨洲部署

部署检查清单

在部署前，确认：

• 后端服务器部署地区：✅ / ❌
• PostgreSQL 数据库地区：✅ / ❌
• Redis 缓存地区：✅ / ❌
• 所有服务在同一地区：✅ / ❌
• 测试延迟 < 20ms：✅ / ❌

常见错误示例

❌ 错误配置：

后端：Vercel (美国)
PostgreSQL：Neon (欧洲)
Redis：Upstash (亚太)

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

✅ 正确配置：

后端：Vercel (亚太)
PostgreSQL：Neon (ap-southeast-1)
Redis：Upstash (ap-southeast-1)

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

部署检查清单

前端部署

• 设置正确的 Root Directory
• 修改 apps/web/vercel.json：将 rewrites 的 destination 改为你的后端地址，否则接口无 session
• 配置所有必要的环境变量
• 确保 NEXT_PUBLIC_SERVER_URL 指向正确的 API 地址
• 测试生产构建：pnpm run build

后端部署

• 设置正确的 Root Directory
• 配置所有服务器环境变量
• 确保数据库连接字符串正确
• 验证 CORS 配置允许前端域名
• 测试生产构建：pnpm run build

数据库

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

Redis

• 创建 Upstash Redis 实例
• 配置 KV_REST_API_URL 和 KV_REST_API_TOKEN
• 验证 Redis 连接正常

认证

• 生成安全的 BETTER_AUTH_SECRET
• 配置正确的 BETTER_AUTH_URL
• 确保 CORS_ORIGIN 包含前端域名

依赖分析与自动更新

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

常见问题

构建失败

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

运行时错误

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

类型错误

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

下一步

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