部署文档

这是交付给每位客户的 runbook 公开精简版。所有命令都在演示所用的开源网关栈上实际验证过；主机名与路径为示例值。

1 · Docker 部署

# docker-compose.yml（节选——完整文件见 GitHub 仓库）
services:
  gateway:
    image: ghcr.io/berriai/litellm:main-stable   # 或你选定的网关
    user: "10001:10001"            # 非 root
    read_only: true                # 只读根文件系统
    tmpfs: [/tmp]
    env_file: /srv/gateway/secrets.env   # 0600, root:root
    expose: ["4000"]               # 仅内部——不绑定公网
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:4000/health/liveliness"]
      interval: 30s
      retries: 3

基本原则：网关容器不直接发布宿主机端口，对外的永远只有反向代理。密钥放在 root 所有、权限 0600 的 env 文件中，以只读方式挂载。容器使用固定的非 root UID，根文件系统只读。

2 · HTTPS 与证书自动续期

# Caddyfile —— 8 行配齐 HTTPS、HSTS 与安全头
example.com {{
  encode gzip
  header {{
    Strict-Transport-Security "max-age=31536000; includeSubDomains"
    X-Content-Type-Options nosniff
    X-Frame-Options DENY
    Referrer-Policy strict-origin-when-cross-origin
  }}
  reverse_proxy 127.0.0.1:4000
}}

Caddy 自动签发并续期证书。如果选 nginx，则由 certbot 配合 systemd 定时器完成同样的工作，两套方案仓库里都有现成配置。

3 · 备份：能恢复的才算数

# 每夜执行：导出数据库与配置，加密归档，保留 14 天
sqlite3 /srv/gateway/data/gateway.db ".backup /tmp/gw.db"
tar czf - -C /srv/gateway config data | age -r "$BACKUP_PUBKEY" \
  > /backup/gateway-$(date +%F).tar.gz.age
find /backup -name "gateway-*.age" -mtime +14 -delete

从未做过恢复演练的备份，只是一份心理安慰。runbook 中固定了季度恢复演练：恢复到临时目录，在内部端口拉起第二个网关实例，跑一轮冒烟测试，确认无误后拆除。

4 · 升级流程

  1. 先读 release notes，确认有没有数据库 schema 迁移。
  2. 做快照：按上述方式备份，并记录当前镜像 digest。
  3. 拉取新镜像、重启服务，紧盯健康端点和错误率。
  4. 回归验证：跑冒烟套件（创建密钥 → 发起一次对话请求 → 确认产生用量记录）。
  5. 准备好回滚：上一个镜像 digest 加恢复后的数据库。因为演练过，回滚耗时是每套环境实测出来的数字，不是估计。

5 · 监控