部署

生产拓扑、横向扩展、可观测性与追踪叠加层、备份与升级，以及 Kubernetes 清单的状态。

在生产环境运行 Cordy Gateway 的受支持方式是使用 docker-compose.prod.yml 的 Docker Compose。本页介绍生产拓扑、如何扩展、可选的可观测性叠加层，以及第二天运维。首次起栈请从快速开始开始。

生产拓扑

docker-compose.prod.yml 在一台 Docker 主机上运行完整技术栈：

   客户端 ──► nginx ──► gateway（1..N 副本）──► pgbouncer ──► postgres
                (LB / TLS)         │                                 ▲
                                   └──────────► redis                │
                                                                worker ┘
   管理员 ──► admin（Django）─────────────────► postgres, redis

服务	角色	暴露
`nginx`	负载均衡与 TLS 终止点；在网关副本间轮询	发布 `GATEWAY_HTTP_PORT`（默认 `8002`）
`gateway`	数据平面；可扩展到 N 副本	内部 `8002`，在 nginx 之后
`admin`	控制平面（Django）	发布 `ADMIN_HTTP_PORT`（默认 `8001`）
`pgbouncer`	网关热路径的事务池	仅内部
`postgres`	PostgreSQL 18 + `pg_cron`	仅内部
`redis`	速率限制、配额、缓存、冷却、幂等、缓冲	仅内部
`worker`	后台用量结算与审计上传	仅内部

Postgres、PgBouncer 与 Redis 绝不对主机发布。nginx 默认终止明文 HTTP——请在 docker/nginx/ 加入 443 server block 与证书，或用你自己的反向代理或负载均衡器置于技术栈之前。

起栈：

docker compose -f docker-compose.prod.yml --env-file .env up -d --build

横向扩展

网关服务没有固定的容器名，且位于 nginx 之后，因此你可以运行多个副本。用 Compose 扩容或缩容：

# 运行 4 个网关副本
docker compose -f docker-compose.prod.yml --env-file .env up -d --scale gateway=4

由于所有共享状态都存于 Redis 与 Postgres，增加副本是安全的：速率限制、配额、冷却与幂等都是集群级的。每个副本运行 GRANIAN_WORKERS 个 worker 进程（默认 8）；按主机 CPU 调节每副本的 worker 数。

容量规划

吞吐量在很大程度上取决于你的上游供应商时延、硬件、模型与载荷大小——务必测量你自己的工作负载。以下是来自单台测试主机内部基准测试的粗略参考：

一个有用的规划量级是：轻量工作负载下每个网关副本约 ~500 请求/秒。
在一次内部基准测试中，架构在 scale=4 下以零服务端错误持续承载 ~2,151 RPS，且随副本增加路由时延保持有界。

这些是在受限测试台上的基准观测，而非保证。请增加副本，并针对你真实的流量与供应商重新测量，同时关注下文的指标。

可观测性

网关暴露可供抓取的指标，并可导出追踪。两者均为可选的叠加层。

指标（VictoriaMetrics + Grafana）

网关在 /metrics/prometheus 提供 Prometheus 格式指标。在生产环境中，除非调用方出示 GATEWAY_METRICS_TOKEN，或来自 GATEWAY_METRICS_ALLOWED_CIDRS 中的 CIDR，否则此接口被拒绝——它暴露成本、供应商与熔断器内部信息，请保持门禁。

随附的监控叠加层运行 VictoriaMetrics（兼容 Prometheus 的时序数据库）、vmalert（告警规则）与 Grafana（仪表盘）：

docker compose \
  -f docker-compose.prod.yml \
  -f docker-compose.monitoring.yml \
  --env-file .env up -d

有用的指标族包括 gateway_requests、gateway_requests_error、gateway_tokens、gateway_cost_usd、gateway_failover_success_rate、gateway_routing_overhead_ms 与 gateway_provider_circuit_breaker_state。

追踪（OpenTelemetry）

设置 OTEL_TRACING_ENABLED=true，并把 OTEL_EXPORTER_OTLP_ENDPOINT 指向一个 OTLP collector，即可发出分布式追踪。提供两种后端作为叠加层：

经 docker-compose.tracing.yml 的 Grafana Tempo（OTLP → Tempo，在 Grafana 中查看）。
经 docker-compose.observability.yml 的自托管 Langfuse，用于聚焦大模型的追踪。

两者均为可选。OTEL_* 变量见配置。

备份与升级

第二天运维以包裹 compose 技术栈的 make 目标提供：

任务	命令	作用
备份	`make backup`	逻辑 `pg_dump` 到 `BACKUP_DIR`（默认 `/var/backups/cordy`，保留 `BACKUP_RETENTION`）。
灾备演练	`make dr-drill`	备份、还原到一个一次性数据库并验证——RTO/RPO 代理。
升级预检	`make preflight`	升级前的只读检查。
升级	`make upgrade`	预检 → 备份 → 迁移 → 验证。用 `DRY_RUN=1` 预览。
升级回滚	`make upgrade-rollback BACKUP=…`	从升级备份还原数据库。
健康自检	`make health-check`	客户侧检查 Postgres、Redis、网关与备份。
验收检查	`make acceptance-check`	运行部署验收清单并输出报告。

数据库迁移由 Admin 服务拥有，并在 Admin 启动时自动运行；升级会作为 make upgrade 的一部分应用新迁移。

Kubernetes：仅供参考

k8s/ 下的 Kubernetes 清单仅供参考且未经验证。它们未经端到端运行，不是受支持的部署路径。生产环境请使用 docker-compose.prod.yml。

若你为集群改编这些清单，请将其视为起点并自行验证完整路径——数据库接线（DB_*，而不仅是 DATABASE_URL）、Ingress 请求体大小限制、密钥与迁移。kubectl --dry-run=client 只检查 YAML 语法；它不证明服务能启动或能处理流量。

运维清单

在 nginx（或外层代理）终止 TLS，并设置 DJANGO_SECURE_SSL_REDIRECT=True。
在 Admin 与 Gateway 上一致地设置 CHANNEL_ENCRYPTION_KEYS，并存放于密钥管理系统。
用令牌或 CIDR 白名单为 /metrics/prometheus 设门禁。
若浏览器会调用网关，显式设置 CLIENT_CORS_ORIGINS；生产环境绝不使用 *。
上线前配置并测试备份；就绪后启用 WAL 归档/PITR 并设置 REQUIRE_PITR=1。
把网关副本扩展到你实测的吞吐量，并关注故障转移与错误指标。

后续步骤

配置——此处引用的每个变量。
安全——信任模型与加固。