deployment-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deployment Patterns for Scientia Stack

Scientia Stack 部署模式

Deploy to Vercel, Railway, or Docker following proven patterns from 98+ projects.

遵循98+个项目验证过的成熟模式，将项目部署至Vercel、Railway或Docker平台。

Platform Selection

平台选择

Choose based on project type:

Project Type	Platform	Reason
Next.js frontend	Vercel	Native support, edge functions
Python backend	Railway	Nixpacks, health checks
ML/GPU workloads	RunPod	GPU access, vLLM
Local development	Docker	Consistent environment

根据项目类型选择合适平台：

项目类型	平台	选择理由
Next.js 前端	Vercel	原生支持、边缘函数
Python 后端	Railway	Nixpacks支持、健康检查
机器学习/GPU工作负载	RunPod	GPU访问、vLLM支持
本地开发	Docker	一致的开发环境

Vercel Deployment (19 projects)

Vercel 部署方案（19个项目实践）

Standard vercel.json for Monorepo

单体仓库标准vercel.json配置

json

{
  "framework": "nextjs",
  "installCommand": "cd frontend && npm install",
  "buildCommand": "cd frontend && npm run build",
  "outputDirectory": "frontend/.next"
}

json

{
  "framework": "nextjs",
  "installCommand": "cd frontend && npm install",
  "buildCommand": "cd frontend && npm run build",
  "outputDirectory": "frontend/.next"
}

Environment Variables

环境变量配置

Set in Vercel Dashboard or CLI:

bash

vercel env add VITE_SUPABASE_URL production
vercel env add VITE_SUPABASE_ANON_KEY production

For preview deployments, use
```
preview
```
scope.

可在Vercel控制台或CLI中设置：

bash

vercel env add VITE_SUPABASE_URL production
vercel env add VITE_SUPABASE_ANON_KEY production

预览部署请使用
```
preview
```
作用域。

SPA Routing

单页面应用路由配置

Add to

frontend/vercel.json

json

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/" }
  ]
}

在

frontend/vercel.json

中添加以下配置：

json

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/" }
  ]
}

Deploy Command

部署命令

bash

undefined

bash

undefined

Production

生产环境

vercel --prod

Preview

预览环境

vercel

undefined

vercel

undefined

Railway Deployment (2 projects)

Railway 部署方案（2个项目实践）

Standard railway.json

标准railway.json配置

json

{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "poetry install --no-dev"
  },
  "deploy": {
    "startCommand": "poetry run python -m src.vozlux.main",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 300,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}

json

{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "poetry install --no-dev"
  },
  "deploy": {
    "startCommand": "poetry run python -m src.vozlux.main",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 300,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}

Environment Variables

环境变量配置

Railway requires manual dashboard configuration for sensitive vars:

Go to: https://railway.com/project/{project-id}/settings
Add each variable under "Variables" tab

Common variables for Python backends:

SUPABASE_URL
SUPABASE_SERVICE_KEY
ANTHROPIC_API_KEY
GOOGLE_API_KEY
DEEPSEEK_API_KEY
TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN

Railway要求敏感变量需在控制台手动配置：

访问：https://railway.com/project/{project-id}/settings
在「Variables」标签页添加各变量

Python后端常用变量：

SUPABASE_URL
SUPABASE_SERVICE_KEY
ANTHROPIC_API_KEY
GOOGLE_API_KEY
DEEPSEEK_API_KEY
TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN

Health Check Endpoint

健康检查端点

Always implement

/health

python

@app.get("/health")
async def health():
    return {"status": "healthy", "timestamp": datetime.utcnow().isoformat()}

务必实现

/health

端点：

python

@app.get("/health")
async def health():
    return {"status": "healthy", "timestamp": datetime.utcnow().isoformat()}

Docker Deployment (5 projects)

Docker 部署方案（5个项目实践）

Multi-stage Dockerfile

多阶段构建Dockerfile

dockerfile

undefined

dockerfile

undefined

Build stage

FROM python:3.11-slim as builder WORKDIR /app COPY pyproject.toml poetry.lock ./ RUN pip install poetry && poetry export -f requirements.txt > requirements.txt

Runtime stage

FROM python:3.11-slim WORKDIR /app COPY --from=builder /app/requirements.txt . RUN pip install -r requirements.txt COPY src/ ./src/ CMD ["python", "-m", "src.main"]

undefined

FROM python:3.11-slim WORKDIR /app COPY --from=builder /app/requirements.txt . RUN pip install -r requirements.txt COPY src/ ./src/ CMD ["python", "-m", "src.main"]

undefined

docker-compose.yml for Development

开发环境docker-compose.yml配置

yaml

version: '3.8'
services:
  app:
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - ./src:/app/src

yaml

version: '3.8'
services:
  app:
    build: .
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - ./src:/app/src

Pre-Deployment Checklist

部署前检查清单

Before any deployment:

All tests passing (
```
npm test
```
or
```
pytest
```
)
No hardcoded API keys (grep for patterns)
Environment variables documented in
```
.env.example
```
CLAUDE.md updated with deployment status
Build succeeds locally (
```
npm run build
```
or
```
poetry build
```
)

部署前需完成以下检查：

所有测试通过（执行
```
npm test
```
或
```
pytest
```
）
无硬编码API密钥（可通过grep排查）
环境变量已在
```
.env.example
```
中记录
CLAUDE.md已更新部署状态
本地构建成功（执行
```
npm run build
```
或
```
poetry build
```
）

Debugging Deployment Failures

部署故障排查

Vercel Failures

Vercel部署故障

Check build logs:
```
vercel logs
```
Common issues:
- Missing env vars → Check Vercel dashboard
- Build timeout → Increase in project settings
- Module not found → Check package.json dependencies

查看构建日志：
```
vercel logs
```
常见问题：
- 缺失环境变量 → 检查Vercel控制台
- 构建超时 → 在项目设置中延长超时时间
- 模块未找到 → 检查package.json依赖

Railway Failures

Railway部署故障

Check logs in dashboard
Common issues:
- Health check timeout → Increase
```
healthcheckTimeout
```
- Missing env vars → Must set manually in dashboard
- Poetry lock issues → Delete poetry.lock and regenerate

在控制台查看日志
常见问题：
- 健康检查超时 → 延长
```
healthcheckTimeout
```
  配置
- 缺失环境变量 → 必须在控制台手动设置
- Poetry锁文件问题 → 删除poetry.lock并重新生成

Docker Failures

Docker部署故障

Build locally first:
```
docker build -t test .
```
Run with logs:
```
docker run -it test
```
Check for missing system dependencies

先在本地构建：
```
docker build -t test .
```
带日志运行容器：
```
docker run -it test
```
检查是否缺失系统依赖

CI/CD Integration

CI/CD集成

For GitHub Actions, use:

yaml

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

GitHub Actions集成示例：

yaml

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'