配置

Cordy Gateway 的环境变量参考——数据库、Redis、供应商密钥、安全、许可证与运行时行为。

Cordy Gateway 通过环境变量配置，通常放在由 Docker Compose 读取的 .env 文件中。本页按类别列出你可能设置的每个变量，附默认值与说明。请从 deploy/env.template 开始，它带占位符且不含真实密钥。

生产环境最少必填项

以下项没有安全默认值，生产部署必须设置：

DB_NAME、DB_USER、DB_PASSWORD
DJANGO_SECRET_KEY、DJANGO_ALLOWED_HOSTS、DJANGO_ADMIN_URL
CHANNEL_ENCRYPTION_KEYS（Admin 与 Gateway 服务使用相同的值）

生成密钥：

# DJANGO_SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(50))"

# CHANNEL_ENCRYPTION_KEYS（一个 Fernet 密钥）
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

数据库

变量	默认	说明
`DB_NAME`	—	数据库名。由 Gateway 数据平面直接读取。若未设置，Gateway 会回退到一个开发库名，从而无法连上你的生产库。
`DB_USER`	—	数据库用户。由 Gateway 直接读取。
`DB_PASSWORD`	—	数据库口令。由 Gateway 直接读取。
`DB_HOST`	`postgres`（Admin）/ `pgbouncer`（Gateway）	Gateway 经 PgBouncer 连接；Admin 直连 Postgres。
`DB_PORT`	`5432`
`DATABASE_URL`	—	仅由 Admin（及迁移/测试工具）使用。Gateway 数据平面不解析 `DATABASE_URL`；它从 `DB_*` 构建 DSN。请两者一致设置。

陷阱：Gateway 从 DB_NAME / DB_USER / DB_PASSWORD 构建 Postgres DSN，而非从 DATABASE_URL。若这些在 gateway 服务上缺失，它会默认到一个开发库名，无法连接，于是每个请求鉴权失败并返回 401。请把 Admin 的 DB_* 值同样配到 Gateway。

Redis

变量	默认	说明
`REDIS_URL`	`redis://localhost:6379/0`	Redis 连接 URL。在生产 compose 中为 `redis://redis:6379/0`。
`REDIS_POOL_SIZE`	`20`	连接池大小。`20` 是经调优的默认值；随附模板将其提高到 `500` 以应对高并发。

供应商密钥

供应商与通道凭据通常作为 Admin 中加密的 Channel 管理，而非放在环境变量中。以下环境键之所以存在，是因为底层 LiteLLM 集成会自动读取它们；它们是可选的，主要用于开发期播种。生产环境请优先使用按通道的加密凭据。

变量	供应商
`OPENAI_API_KEY`	OpenAI
`ANTHROPIC_API_KEY`	Anthropic
`OPENROUTER_API_KEY`	OpenRouter
`GEMINI_API_KEY`	Google Gemini
`AZURE_API_KEY`、`AZURE_API_BASE`、`AZURE_API_VERSION`	Azure OpenAI
`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_REGION_NAME`	AWS Bedrock
`COHERE_API_KEY`	Cohere
`GROQ_API_KEY`	Groq
`TOGETHERAI_API_KEY`	Together AI
`DEEPINFRA_API_KEY`	DeepInfra
`REPLICATE_API_TOKEN`	Replicate
`HUGGINGFACE_API_KEY`	Hugging Face

通道与凭据如何工作见供应商。

安全

变量	默认	说明
`CHANNEL_ENCRYPTION_KEYS`	—	逗号分隔的 Fernet 密钥，用于静态加密通道上游凭据。第一个为活跃（加密）密钥，其余用于轮换。生产必填——Admin 与 Gateway 缺少它都会拒绝启动，且两者必须使用相同的值。
`CLIENT_CORS_ORIGINS`	空	允许从浏览器调用 Gateway 的 Origin，逗号分隔。为空则拒绝所有跨源浏览器访问（服务器到服务器的调用方不使用 CORS）。字面量 `*` 在生产环境启动时被拒绝。
`CLIENT_CORS_ALLOW_WILDCARD_IN_PRODUCTION`	`false`	允许生产环境使用 `*` 客户端 CORS 源的不安全逃生阀。请保持关闭。
`TRUSTED_PROXY_CIDRS`	空	受信反向代理的 CIDR。仅当 socket 对端匹配其一时，才为记录的客户端 IP 采信 `X-Forwarded-For` / `X-Real-IP`；否则使用 socket 对端。防止审计 IP 伪造。
`GATEWAY_METRICS_TOKEN`	空	抓取器访问 `/metrics/prometheus` 必须出示的 bearer 令牌。生产环境中若此项与允许 CIDR 均未设置，该接口被拒绝。
`GATEWAY_METRICS_ALLOWED_CIDRS`	空	允许抓取 `/metrics/prometheus` 的 CIDR。
`DJANGO_SECRET_KEY`	—	Django 加密密钥（Admin）。生产必填。
`DJANGO_ALLOWED_HOSTS`	—	Admin 服务的主机名，逗号分隔。生产必填。
`DJANGO_ADMIN_URL`	—	Admin URL 路径前缀；必须以 `/` 结尾。取不显而易见的值。生产必填。
`DJANGO_CSRF_TRUSTED_ORIGINS`	空	TLS 代理之后允许向 Admin POST 的、带协议的源（例如 `https://admin.example.com`）。
`DJANGO_SECURE_SSL_REDIRECT`	`True`	强制 HTTP→HTTPS 跳转。仅本地无 TLS 测试才设 `False`。
`ADMIN_HTTP_PORT`	`8001`	Admin 发布的主机端口。
`GATEWAY_HTTP_PORT`	`8002`	Gateway（经 nginx）发布的主机端口。

许可证

Cordy Gateway 使用离线的、HMAC 签名的许可证。许可证默认为仅审计（fail-open）；它不会阻断正常部署。

变量	默认	说明
`LICENSE_KEY`	空	HMAC 签名的许可证载荷。未授权/开发时留空。
`LICENSE_SIGNING_SECRET`	空	用于校验许可证的共享密钥，按客户提供。
`LICENSE_CUSTOMER_ID`	空	匹配载荷的预期客户 id；留空则跳过。
`LICENSE_NODE_ID`	`node-1`	用于节点数校验的当前节点 id。
`LICENSE_ENFORCEMENT_MODE`	`audit_only`	`audit_only`（fail-open，仅记录）或 `strict`（fail-closed）。

运行时行为

变量	默认	说明
`GATEWAY_DEFAULT_ROUTING_STRATEGY`	`weighted`	默认通道选择策略：`weighted`、`cheapest`、`fastest` 或 `region_aware`。可用 `X-Routing-Strategy` 按请求覆盖。
`GATEWAY_MAX_BODY_BYTES`	`10485760`（10 MiB）	请求体硬上限。更大的请求体得到 `413`。`<= 0` 关闭该上限。
`GATEWAY_MAX_INFLIGHT_PER_KEY`	`50`	每 API 密钥的最大在途并发请求数。`<= 0` 关闭。
`GATEWAY_DEFAULT_MAX_COMPLETION_TOKENS`	`4096`	当请求未设置 `max_tokens` 时，用于配额准入的补全令牌估算值。
`GATEWAY_PRICE_TTL_SECONDS`	`300`	成本快照所用有效价格缓存的每进程 TTL。
`GRANIAN_WORKERS`	`8`	每个 Gateway 容器的 Granian worker 进程数。
`IDEMPOTENCY_TTL_SECONDS`	`600`	已存幂等响应 / 锁的存活时间。

可观测性（OpenTelemetry）

追踪默认关闭。启用后可将 span 导出到 OTLP 端点。追踪后端见部署。

变量	默认	说明
`OTEL_TRACING_ENABLED`	`false`	为 Gateway 启用 OpenTelemetry 追踪。
`OTEL_SERVICE_NAME`	`cordy-gateway`	追踪中上报的 `service.name`。
`OTEL_EXPORTER_OTLP_ENDPOINT`	空	导出追踪的 OTLP HTTP 端点。
`OTEL_EXPORTER_OTLP_HEADERS`	空	逗号分隔的 OTLP 导出器请求头。
`OTEL_SHUTDOWN_TIMEOUT_SECONDS`	`2.0`	关闭时有界的 flush 超时。

扩展与基础设施

以下项用于调优 compose 技术栈与横向扩展。见部署。

变量	默认	说明
`SCALE_GRANIAN_WORKERS`	`4`	运行多个网关副本时的每副本 worker 数。
`ADMIN_WORKERS`	`3`	Admin 服务的 Gunicorn worker 数。
`PGBOUNCER_POOL_SIZE`	`100`	PgBouncer 默认池大小。
`PGBOUNCER_MAX_CLIENT_CONN`	`400`	PgBouncer 最大客户端连接数。
`REDIS_MAXMEMORY`	`512mb`	Redis 最大内存（采用永不触及资金键的 `volatile-lru` 驱逐）。

备份

变量	默认	说明
`BACKUP_DIR`	`/var/backups/cordy`	逻辑备份写入位置。
`BACKUP_RETENTION`	`7`	保留的备份数量。
`REQUIRE_PITR`	`0`	一旦启用 WAL 归档 / 时间点恢复，设为 `1` 以在验收检查中强制它。

后续步骤

部署——把这些设置应用到生产拓扑。
安全——安全相关变量的上下文。