moai-platform-deployment

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deployment Platform Specialist

部署平台专家指南

Comprehensive deployment platform guide covering Vercel (edge-first), Railway (container-first), and Convex (real-time backend).

全面覆盖Vercel(优先边缘)、Railway(优先容器)和Convex(实时后端)的部署平台指南。

Quick Platform Selection

快速平台选择

When to Use Each Platform

各平台适用场景

Vercel - Edge-First Deployment:
  • Next.js applications with SSR/SSG
  • Global CDN distribution required
  • Sub-50ms edge latency critical
  • Preview deployments for team collaboration
  • Managed storage needs (KV, Blob, Postgres)
Railway - Container-First Deployment:
  • Full-stack containerized applications
  • Custom runtime environments
  • Multi-service architectures
  • Persistent volume storage
  • WebSocket/gRPC long-lived connections
Convex - Real-Time Backend:
  • Collaborative real-time applications
  • Reactive data synchronization
  • TypeScript-first backend needs
  • Optimistic UI updates
  • Document-oriented data models

Vercel - 优先边缘部署:
  • 采用SSR/SSG的Next.js应用
  • 需要全球CDN分发
  • 对低于50ms的边缘延迟有严格要求
  • 用于团队协作的预览部署
  • 托管存储需求(KV、Blob、Postgres)
Railway - 优先容器部署:
  • 全栈容器化应用
  • 自定义运行时环境
  • 多服务架构
  • 持久化卷存储
  • WebSocket/gRPC长连接
Convex - 实时后端:
  • 协作型实时应用
  • 响应式数据同步
  • 优先TypeScript的后端需求
  • 乐观UI更新
  • 面向文档的数据模型

Decision Guide

决策指南

By Application Type

按应用类型选择

Web Applications (Frontend + API):
  • Next.js → Vercel (optimal integration)
  • React/Vue with custom API → Railway (flexible)
  • Real-time collaborative → Convex + Vercel
Mobile Backends:
  • REST/GraphQL → Railway (stable connections)
  • Real-time sync → Convex (reactive queries)
  • Edge API → Vercel (global latency)
Full-Stack Monoliths:
  • Containerized → Railway (Docker support)
  • Serverless → Vercel (Next.js API routes)
  • Real-time → Convex (built-in reactivity)
Web应用(前端+API):
  • Next.js → Vercel(集成最优)
  • React/Vue搭配自定义API → Railway(灵活性高)
  • 实时协作类 → Convex + Vercel
移动后端:
  • REST/GraphQL → Railway(连接稳定)
  • 实时同步 → Convex(响应式查询)
  • 边缘API → Vercel(全球低延迟)
全栈单体应用:
  • 容器化 → Railway(支持Docker)
  • 无服务器 → Vercel(Next.js API路由)
  • 实时功能 → Convex(内置响应式能力)

By Infrastructure Needs

按基础设施需求选择

Compute Requirements:
  • Edge compute → Vercel (30+ edge locations)
  • Custom runtimes → Railway (Docker flexibility)
  • Serverless TypeScript → Convex (managed runtime)
Storage Requirements:
  • Redis/KV → Vercel KV or Railway
  • PostgreSQL → Vercel Postgres or Railway
  • File storage → Vercel Blob or Railway volumes
  • Document DB → Convex (built-in)
Networking Requirements:
  • CDN distribution → Vercel (built-in)
  • Private networking → Railway (service mesh)
  • Real-time WebSocket → Convex (built-in) or Railway

计算需求:
  • 边缘计算 → 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

Common Deployment Patterns

常见部署模式

Pattern 1: Next.js with Database

模式1:带数据库的Next.js应用

Stack: Vercel + Vercel Postgres/KV
Setup:
  1. Deploy Next.js app to Vercel
  2. Provision Vercel Postgres for database
  3. Use Vercel KV for session/cache
  4. Configure environment variables
  5. Enable ISR for dynamic content
Best For: Web apps with standard database needs, e-commerce, content sites
技术栈: Vercel + Vercel Postgres/KV
设置步骤:
  1. 将Next.js应用部署到Vercel
  2. 配置Vercel Postgres作为数据库
  3. 使用Vercel KV存储会话/缓存
  4. 配置环境变量
  5. 为动态内容启用ISR
最佳适用: 有标准数据库需求的Web应用、电商网站、内容站点

Pattern 2: Containerized Multi-Service

模式2:容器化多服务应用

Stack: Railway + Docker
Setup:
  1. Create multi-stage Dockerfile
  2. Configure railway.toml for services
  3. Set up private networking
  4. Configure persistent volumes
  5. Enable auto-scaling
Best For: Microservices, complex backends, custom tech stacks
技术栈: Railway + Docker
设置步骤:
  1. 创建多阶段Dockerfile
  2. 为服务配置railway.toml
  3. 设置私有网络
  4. 配置持久化卷
  5. 启用自动扩缩容
最佳适用: 微服务、复杂后端、自定义技术栈

Pattern 3: Real-Time Collaborative App

模式3:实时协作应用

Stack: Convex + Vercel/Railway (frontend)
Setup:
  1. Initialize Convex backend
  2. Define schema and server functions
  3. Deploy frontend to Vercel/Railway
  4. Configure Convex provider
  5. Implement optimistic updates
Best For: Collaborative tools, live dashboards, chat applications
技术栈: Convex + Vercel/Railway(前端)
设置步骤:
  1. 初始化Convex后端
  2. 定义Schema和服务器函数
  3. 将前端部署到Vercel/Railway
  4. 配置Convex Provider
  5. 实现乐观更新
最佳适用: 协作工具、实时仪表盘、聊天应用

Pattern 4: Hybrid Edge + Container

模式4:边缘+容器混合架构

Stack: Vercel (frontend/edge) + Railway (backend services)
Setup:
  1. Deploy Next.js frontend to Vercel
  2. Deploy backend services to Railway
  3. Configure CORS and API endpoints
  4. Set up edge middleware for routing
  5. Use private networking for Railway
Best For: High-performance apps, global distribution with complex backends
技术栈: Vercel(前端/边缘) + Railway(后端服务)
设置步骤:
  1. 将Next.js前端部署到Vercel
  2. 将后端服务部署到Railway
  3. 配置CORS和API端点
  4. 设置边缘中间件用于路由
  5. 为Railway配置私有网络
最佳适用: 高性能应用、全球分发搭配复杂后端

Pattern 5: Serverless Full-Stack

模式5:无服务器全栈应用

Stack: Vercel (frontend + API routes) + Convex (backend)
Setup:
  1. Build Next.js app with API routes
  2. Initialize Convex for data layer
  3. Configure authentication (Clerk/Auth0)
  4. Deploy frontend to Vercel
  5. Connect Convex client
Best For: Rapid prototyping, startups, real-time web apps

技术栈: Vercel(前端+API路由) + Convex(后端)
设置步骤:
  1. 构建带有API路由的Next.js应用
  2. 初始化Convex作为数据层
  3. 配置认证(Clerk/Auth0)
  4. 将前端部署到Vercel
  5. 连接Convex客户端
最佳适用: 快速原型开发、初创项目、实时Web应用

Essential Configuration

关键配置示例

Vercel Quick Start

Vercel快速入门

vercel.json:
json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "regions": ["iad1", "sfo1", "fra1"],
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}
Edge Function:
typescript
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 })
}
vercel.json:
json
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": "nextjs",
  "regions": ["iad1", "sfo1", "fra1"],
  "functions": {
    "app/api/**/*.ts": {
      "memory": 1024,
      "maxDuration": 10
    }
  }
}
边缘函数:
typescript
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 Quick Start

Railway快速入门

railway.toml:
toml
[build]
builder = "DOCKERFILE"
dockerfilePath = "Dockerfile"

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

[deploy.resources]
memory = "2GB"
cpu = "2.0"
Multi-Stage Dockerfile:
dockerfile
undefined
railway.toml:
toml
[build]
builder = "DOCKERFILE"
dockerfilePath = "Dockerfile"

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

[deploy.resources]
memory = "2GB"
cpu = "2.0"
多阶段Dockerfile:
dockerfile
undefined

Builder stage

Builder stage

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

Runner stage

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"]
undefined
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"]
undefined

Convex Quick Start

Convex快速入门

convex/schema.ts:
typescript
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 Integration:
typescript
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>
  )
}

convex/schema.ts:
typescript
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集成:
typescript
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 Integration

CI/CD集成

GitHub Actions - Vercel

GitHub Actions - Vercel

yaml
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 }}
yaml
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

GitHub Actions - Railway

yaml
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 }}
yaml
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

GitHub Actions - Convex

yaml
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 }}

yaml
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 }}

Advanced Patterns

高级模式

Blue-Green Deployment (Vercel)

蓝绿部署(Vercel)

Deploy new version, test on preview URL, then switch production alias using Vercel SDK for zero-downtime releases.
部署新版本,在预览URL测试后,使用Vercel SDK切换生产别名,实现零停机发布。

Multi-Region (Railway)

多区域部署(Railway)

Configure deployment regions in railway.toml:
toml
[deploy.regions]
name = "us-west"
replicas = 2

[[deploy.regions]]
name = "eu-central"
replicas = 1
在railway.toml中配置部署区域:
toml
[deploy.regions]
name = "us-west"
replicas = 2

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

Optimistic Updates (Convex)

乐观更新(Convex)

typescript
const sendMessage = useMutation(api.messages.send)

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

typescript
const sendMessage = useMutation(api.messages.send)

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

Platform-Specific Details

平台专属详情

For detailed platform-specific patterns, configuration options, and advanced use cases, see:
  • reference/vercel.md - Edge Functions, ISR, Analytics, Storage
  • reference/railway.md - Docker, Multi-Service, Volumes, Scaling
  • reference/convex.md - Reactive Queries, Server Functions, File Storage
  • reference/comparison.md - Feature Matrix, Pricing, Migration Guides

如需了解各平台的详细模式、配置选项和高级用例,请查看:
  • reference/vercel.md - 边缘函数、ISR、分析、存储
  • reference/railway.md - Docker、多服务、卷、扩缩容
  • reference/convex.md - 响应式查询、服务器函数、文件存储
  • reference/comparison.md - 功能矩阵、定价、迁移指南

Works Well With

搭配使用推荐

  • moai-domain-backend for backend architecture patterns
  • moai-domain-frontend for frontend integration
  • moai-lang-typescript for TypeScript best practices
  • moai-lang-python for Python deployment (Railway)
  • moai-platform-auth for authentication integration
  • moai-platform-database for database patterns

Status: Production Ready Version: 2.0.0 Updated: 2026-02-09 Platforms: Vercel, Railway, Convex
  • moai-domain-backend:后端架构模式
  • moai-domain-frontend:前端集成
  • moai-lang-typescript:TypeScript最佳实践
  • moai-lang-python:Python部署(Railway)
  • moai-platform-auth:认证集成
  • moai-platform-database:数据库模式

状态:生产可用 版本:2.0.0 更新时间:2026-02-09 支持平台:Vercel、Railway、Convex