Python · uvicorn / gunicorn 部署全景

场景 1 · gunicorn 生产配置文件(而非命令行堆参数)

参数进版本库, 命令行只留一个 -c:

# gunicorn.conf.py — 与代码同库评审
bind = "0.0.0.0:8000"
workers = 4                          # 起步 (2×CPU)+1, 压测修正
worker_class = "uvicorn.workers.UvicornWorker"   # ASGI 应用
timeout = 60                        # 看门狗: 比 P99 最长请求宽裕
graceful_timeout = 30              # TERM 后等存量请求的最长时间
max_requests = 2000                 # 防 worker 内存泄漏自愈
max_requests_jitter = 200           # 随机化, 防集体重启抖动
accesslog = "-"; errorlog = "-"     # 容器环境: 只写 stdout
forwarded_allow_ips = "*"            # 信任反代传来的 X-Forwarded-*

场景 2 · FastAPI 两种启动方式的取舍

# 方式 A: gunicorn 管理 (成熟, 配置项全)
gunicorn app.main:app -c gunicorn.conf.py

# 方式 B: uvicorn 自管 (轻量, 少一层依赖)
uvicorn app.main:app --host 0.0.0.0 --port 8000 \
    --workers 4 --timeout-keep-alive 5 \
    --proxy-headers --forwarded-allow-ips='*'
# 共同底线: 绝不带 --reload 进生产 (那是开发期热重载)

场景 3 · systemd 单元文件(裸机/VM 标准姿势)

# /etc/systemd/system/app.service
[Unit]
After=network-online.target postgresql.service
[Service]
User=app; WorkingDirectory=/opt/app
Environment=PATH=/opt/app/venv/bin
ExecStart=/opt/app/venv/bin/gunicorn app.main:app -c gunicorn.conf.py
ExecReload=/bin/kill -HUP $MAINPID      # reload = 平滑换 worker
Restart=on-failure; RestartSec=2
LimitNOFILE=65535                       # 高连接量的前提
KillSignal=SIGTERM; TimeoutStopSec=40      # ≥ graceful_timeout
[Install]
WantedBy=multi-user.target
# systemctl daemon-reload && systemctl enable --now app

场景 4 · Dockerfile: 信号直达 + 非 root + init

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt . && RUN pip install --no-cache-dir -r requirements.txt
COPY . .
RUN useradd -m appuser && chown -R appuser /app
USER appuser
# exec 形式: master 直接做 PID 1 前台进程, 信号直达
CMD ["gunicorn", "app.main:app", "-c", "gunicorn.conf.py"]
# 坑位: shell 形式 CMD gunicorn ... 会让 sh 抢占 PID1, TERM 永远到不了

场景 5 · docker-compose: 健康检查 + 优雅停窗口

services:
  api:
    image: registry/app:${TAG}
    init: true                          # tini 回收僵尸进程
    stop_grace_period: 40s             # 默认 10s 太短, 对齐 graceful_timeout
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"]
      interval: 10s; timeout: 3s; retries: 3
      start_period: 15s                # 给启动预热留时间
    deploy:
      resources:
        limits: { cpus: "2", memory: 1G }  # workers 数对齐这里, 不是宿主机

场景 6 · K8s Deployment: 探针 + preStop + 宽限期三件套

containers:
- name: api
  image: registry/app:${TAG}
  readinessProbe:
    httpGet: { path: /readyz, port: 8000 }   # 摘流量用
    periodSeconds: 5
  lifecycle:
    preStop:
      exec: { command: ["sleep", "5"] }   # 等 endpoint 摘除传播, 再收 TERM
  resources:
    requests: { cpu: "2" }                  # requests=limits 防 CPU 抖动
    limits:   { cpu: "2", memory: 1G }
terminationGracePeriodSeconds: 45       # > graceful_timeout + preStop
strategy:
  rollingUpdate: { maxUnavailable: 0, maxSurge: 1 }  # 滚动不断流

场景 7 · Nginx 反代: 转发头 + 超时 + upstream keepalive

upstream app { server 127.0.0.1:8000; keepalive 64; }
server {
  location / {
    proxy_pass http://app;
    proxy_http_version 1.1;
    proxy_set_header Connection "";            # 启用 keepalive 复用
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;   # 否则应用以为自己是 http
    proxy_read_timeout 60s;                   # 与 gunicorn timeout 对齐
  }
}

场景 8 · 平滑发布: 裸机 HUP vs K8s 滚动

# 裸机/VM: 拉新代码 → HUP 平滑换 worker (master 不断流)
cd /opt/app && git pull && systemctl reload app
# K8s: 换镜像即滚动, 新 Pod ready 才摘旧 Pod (配合场景 6 的 maxUnavailable=0)
kubectl set image deploy/api api=registry/app:v2 && kubectl rollout status deploy/api
# 回滚就是换回旧 tag, 不需要碰进程
kubectl rollout undo deploy/api

场景 9 · 内存缓涨的自愈配置与定位

# 现象: RSS 缓涨不降 → 先量化再自愈
# 1. 容器内存接近 limit 才是问题: 监控 container_memory_working_set_bytes
# 2. 自愈阀: worker 定期换新, 泄漏被定期清零
max_requests = 2000; max_requests_jitter = 200
# 3. 根治仍要 tracemalloc 定位(见内存管理页), max_requests 是止血不是治病

场景 10 · 多 worker 下的"只跑一次"初始化

迁移、种子数据、定时注册在 N 个 worker 里各跑一遍就是事故:

# 坏: 应用启动钩子里直接跑迁移 (N 个 worker 跑 N 遍, 并发 DDL 冲突)
# 好: 迁移独立成 K8s Job / initContainer, 完成后才起 web
initContainers:
- name: migrate
  image: registry/app:${TAG}
  command: ["alembic", "upgrade", "head"]
# 真要在 worker 间互斥: 文件锁/advisory lock 包住, 拿到锁的才执行
with fcntl.flock(open('/tmp/init.lock', 'w'), fcntl.LOCK_EX):
    run_once_migrations()