moai-platform-deployment

部署平台专家

全面的部署平台指南，涵盖 Vercel（边缘优先）、Railway（容器优先）和 Convex（实时后端）。

---

快速选择平台

何时使用各个平台

Vercel — 边缘优先部署：

• 使用 SSR/SSG 的 Next.js 应用
• 需要通过全球 CDN 分发
• 对低于 50 毫秒的边缘延迟有严格要求
• 需要预览部署以便团队协作
• 需要托管存储（KV、Blob、Postgres）

Railway — 容器优先部署：

• 完整的容器化应用
• 自定义运行时环境
• 多服务架构
• 持久化卷存储
• WebSocket/gRPC 长连接

Convex — 实时后端：

• 实时协作应用
• 响应式数据同步
• 需要以 TypeScript 为先的后端
• 乐观 UI 更新
• 面向文档的数据模型

---

决策指南

按应用类型选择

Web 应用（前端 + API）：

• Next.js → Vercel（集成最佳）
• 使用自定义 API 的 React/Vue → Railway（灵活）
• 实时协作应用 → Convex + Vercel

移动端后端：

• REST/GraphQL → Railway（连接稳定）
• 实时同步 → Convex（响应式查询）
• 边缘 API → Vercel（全球低延迟）

全栈单体应用：

• 容器化 → Railway（支持 Docker）
• 无服务器 → Vercel（Next.js API 路由）
• 实时应用 → Convex（内置响应式功能）

按基础设施需求选择

计算需求：

• 边缘计算 → Vercel（30 多个边缘节点）
• 自定义运行时 → Railway（Docker 灵活性）
• 无服务器 TypeScript → Convex（托管运行时）

存储需求：

• Redis/KV → Vercel KV 或 Railway
• PostgreSQL → Vercel Postgres 或 Railway
• 文件存储 → Vercel Blob 或 Railway 卷
• 文档数据库 → Convex（内置）

网络需求：

• CDN 分发 → Vercel（内置）
• 私有网络 → Railway（服务网格）
• 实时 WebSocket → Convex（内置）或 Railway

---

常见部署模式

模式 1：使用数据库的 Next.js

技术栈：Vercel + Vercel Postgres/KV

设置：

1. 将 Next.js 应用部署到 Vercel
2. 配置 Vercel Postgres 数据库
3. 使用 Vercel KV 存储会话/缓存
4. 配置环境变量
5. 为动态内容启用 ISR

适用场景：有标准数据库需求的 Web 应用、电商网站、内容网站

模式 2：容器化多服务

技术栈：Railway + Docker

设置：

1. 创建多阶段 Dockerfile
2. 为服务配置 railway.toml
3. 设置私有网络
4. 配置持久化卷
5. 启用自动扩缩容

适用场景：微服务、复杂后端、自定义技术栈

模式 3：实时协作应用

技术栈：Convex + Vercel/Railway（前端）

设置：

1. 初始化 Convex 后端
2. 定义架构和服务端函数
3. 将前端部署到 Vercel/Railway
4. 配置 Convex 提供程序
5. 实现乐观更新

适用场景：协作工具、实时仪表盘、聊天应用

模式 4：边缘 + 容器混合部署

技术栈：Vercel（前端/边缘）+ Railway（后端服务）

设置：

1. 将 Next.js 前端部署到 Vercel
2. 将后端服务部署到 Railway
3. 配置 CORS 和 API 端点
4. 设置边缘中间件以处理路由
5. 在 Railway 中使用私有网络

适用场景：高性能应用、需要全球分发且后端复杂的应用

模式 5：无服务器全栈

技术栈：Vercel（前端 + API 路由）+ Convex（后端）

设置：

1. 构建带有 API 路由的 Next.js 应用
2. 初始化 Convex 数据层
3. 配置身份验证（Clerk/Auth0）
4. 将前端部署到 Vercel
5. 连接 Convex 客户端

适用场景：快速原型开发、初创公司、实时 Web 应用

---

基本配置

Vercel 快速入门

vercel.json：

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "regions": ["iad1", "sfo1", "fra1"],
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}

边缘函数：

export const runtime = "edge"
export const preferredRegion = ["iad1", "sfo1"]

export async function GET(request: Request) {
  const country = request.geo?.country || "Unknown"
  return Response.json({ country })
}

Railway 快速入门

railway.toml：

[build]
builder = "DOCKERFILE"
dockerfilePath = "Dockerfile"

[deploy]
healthcheckPath = "/health"
healthcheckTimeout = 100
restartPolicyType = "ON_FAILURE"
numReplicas = 2

[deploy.resources]
memory = "2GB"
cpu = "2.0"

多阶段 Dockerfile：

# Builder stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Runner stage
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -g 1001 -S nodejs && adduser -S appuser -u 1001
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
USER appuser
EXPOSE 3000
CMD ["node", "dist/main.js"]

Convex 快速入门

convex/schema.ts：

import { defineSchema, defineTable } from "convex/server"
import { v } from "convex/values"

export default defineSchema({
  messages: defineTable({
    text: v.string(),
    userId: v.id("users"),
    timestamp: v.number(),
  })
    .index("by_timestamp", ["timestamp"])
    .searchIndex("search_text", {
      searchField: "text",
      filterFields: ["userId"],
    }),
})

React 集成：

import { useQuery, useMutation } from "convex/react"
import { api } from "../convex/_generated/api"

export function Messages() {
  const messages = useQuery(api.messages.list)
  const sendMessage = useMutation(api.messages.send)

  if (!messages) return <div>Loading...</div>

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg._id}>{msg.text}</div>
      ))}
    </div>
  )
}

---

CI/CD 集成

GitHub Actions - Vercel

name: Deploy to Vercel
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.ORG_ID }}
          vercel-project-id: ${{ secrets.PROJECT_ID }}

GitHub Actions - Railway

name: Deploy to Railway
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g @railway/cli
      - run: railway up --detach
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

GitHub Actions - Convex

name: Deploy to Convex
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npx convex deploy
        env:
          CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}

---

高级模式

蓝绿部署（Vercel）

部署新版本，在预览 URL 上测试，然后使用 Vercel SDK 切换生产别名，实现零停机发布。

多区域（Railway）

在 railway.toml 中配置部署区域：

[deploy.regions]
name = "us-west"
replicas = 2

[[deploy.regions]]
name = "eu-central"
replicas = 1

乐观更新（Convex）

const sendMessage = useMutation(api.messages.send)

const handleSend = (text: string) => {
  sendMessage({ text })
    .then(() => console.log("Sent"))
    .catch(() => console.log("Failed, rolled back"))
}

---

平台特定详情

如需了解详细的平台特定模式、配置选项和高级用例，请参阅：

• reference/vercel.md - Edge Functions、ISR、Analytics、Storage
• reference/railway.md - Docker、多服务、卷、扩缩容
• reference/convex.md - 响应式查询、服务端函数、文件存储
• reference/comparison.md - 功能矩阵、定价、迁移指南

---

适用于

• moai-domain-backend，用于后端架构模式
• moai-domain-frontend，用于前端集成
• .claude/rules/moai/languages/typescript.md，用于 TypeScript 最佳实践（通过 paths frontmatter 自动加载）
• .claude/rules/moai/languages/python.md，用于在 Railway 上部署 Python（通过 paths frontmatter 自动加载）
• moai-platform-auth，用于身份验证集成
• moai-platform-database，用于数据库模式

---

状态：生产就绪 版本：2.0.0 更新日期：2026-02-09 平台：Vercel、Railway、Convex

常见借口

借口	事实
“我会等开发完成后再配置部署平台。”	部署配置会影响构建输出、环境变量和运行时行为。应尽早配置。
“预览部署是可选的。”	预览部署能在上线前发现特定于部署的问题。成本很低，却能避免大量问题。
“所有环境的环境变量都相同。”	生产、预发布和开发环境需要使用不同的数据库 URL、API 密钥和功能标志。使用同一组环境变量会带来安全风险。
“无服务器冷启动的影响可以忽略。”	首次请求的冷启动会增加 200-2000ms 延迟。对于面向用户的 API，这很重要。应进行测量并加以缓解。
“我不需要回滚策略，重新部署就行。”	重新部署需要几分钟，回滚只需几秒。生产环境出现故障时，每一秒都很重要。

警示信号

• 生产环境变量出现在构建日志中
• 未为拉取请求配置预览部署
• 预发布和生产环境共用一个环境
• 未记录或测试回滚机制
• 构建产物包含开发依赖或源映射

验证

• 按环境区分环境变量（开发、预发布、生产）
• 为拉取请求配置预览部署（显示平台配置）
• 记录并测试回滚流程（显示回滚命令或过程）
• 生产构建不包含开发依赖和源映射
• 从干净的 git 检出状态即可成功部署（不依赖本地状态）
• 测量无服务器函数的冷启动时间（显示计时数据）

重构说明

R4 审计结论（2026-04-23）：重构 — 将三平台组合精简为仅以 Vercel 为主；Railway/Convex 仅作为文档参考 SPEC：SPEC-V3R2-WF-001 §6.2 第 271 行 重构范围（推迟至未来的子 SPEC）：

• 将 Vercel 提升为主要平台并提供完整指导；将 Railway 和 Convex 降为仅供文档参考
• 将 Railway 和 Convex 的深入内容移至 Level-3 模块
• 添加 CI/CD 流水线模式章节（GitHub Actions、Vercel CI 集成）

此技能将在 v3.0 中保留，但其正文将在后续 SPEC 中重新组织。