安全

Cordy Gateway 的信任模型——自托管、密钥哈希、凭据加密、按密钥限制、审计日志，以及关于合规的诚实声明。

本页明确说明 Cordy Gateway 保护什么、如何保护，以及它不声称什么。它是一款自托管、单租户产品：其安全态势在很大程度上取决于你如何部署与运维它。

信任模型

Cordy Gateway 完全运行在你的基础设施上：

  • 你的密钥。 上游供应商凭据存放在你的数据库中，静态加密。你签发并吊销客户端使用的 wnx_ 密钥。
  • 你的数据存储。 提示词经网关流向你所配置的上游供应商；它们不会发送给 Cordy 或任何第三方。配置与用量记录存于你自己的 PostgreSQL。
  • 请求路径中无第三方依赖。 推理没有任何回连（phone-home）。许可证离线校验（见下文）。

因为它是自托管的，信任边界就是你自己的网络、主机、数据库与密钥管理。

默认不捕获载荷

默认情况下，网关不捕获请求或响应载荷（你的提示词与补全）。用量记录只存储元数据——模型、令牌计数、成本、状态与时间——这正是计量与分析的依据。捕获内容的评估功能为选择性开启，且默认关闭。若你日后启用任何捕获内容的功能，那是你的明确选择，且数据仍留在你的存储中。

API 密钥

  • 客户端密钥以 wnx_ 为前缀，由密码学安全的随机部分生成。
  • 网关只存储每个密钥的 SHA-256 哈希。完整明文在创建时仅显示一次，此后无法恢复——请当时即复制。
  • 密钥通过 Authorization: Bearer 请求头或 X-API-Key 鉴权。URL 查询串中的密钥不被接受，因此绝不会泄漏进访问日志、代理或浏览器历史。
  • 密钥具有生命周期状态（active、inactive、revoked、expired）。吊销在下一个请求生效，且错误 code 区分已吊销、未激活与已过期，以便客户端正确应对。

按密钥的控制

每个密钥都可被独立约束：

控制作用
作用域将密钥限制到特定接口族（chat、completions、embeddings、models、balance、admin）。签发最小权限密钥。
令牌配额封顶月度令牌用量；超配额请求得到 429 quota_exceeded。
速率限制封顶每密钥每分钟请求数。
在途限制封顶每密钥并发请求数（GATEWAY_MAX_INFLIGHT_PER_KEY，默认 50）。
模型权限将某密钥的拥有者限制在公开模型的子集内。
过期设置过期日期，之后密钥停止工作。

静态凭据加密

上游供应商凭据（通道 API 密钥，以及 Bedrock 的 AWS secret）在数据库中以 Fernet 加密存储，绝不明文。它们仅在请求派发时于内存中解密。

  • 加密密钥来自 CHANNEL_ENCRYPTION_KEYS，它在生产中为必填——Admin 与 Gateway 缺少它都会拒绝启动。
  • 该变量接受逗号分隔的列表：第一个密钥加密新值；其余用于密钥轮换，无需一次性重新加密所有内容。
  • 请将密钥存放在版本控制之外的密钥管理系统中。客户端从不看到上游凭据——只看到自己的 wnx_ 网关密钥。

审计日志与 RBAC

  • 控制平面（Admin）保留管理操作的仅追加审计日志，并对运维人员强制执行基于角色的访问控制。
  • 配置后，审计 worker 可选择性地将审计证据发送到对象存储，并带服务端保留/不可变控制。
  • 面向客户端的日志记录请求元数据（而非载荷）；网关刻意记录不含查询串的请求路径，以避免泄漏密钥。

网络与传输

加固部署边界：

  • 在 nginx 或外层代理终止 TLS；保持 DJANGO_SECURE_SSL_REDIRECT=True。
  • 限制 CORS。 CLIENT_CORS_ORIGINS 默认为空（拒绝跨源浏览器访问）。字面量 * 在生产环境启动时被拒绝。仅当浏览器直接调用网关时，才列出显式源。
  • 显式信任代理。 设置 TRUSTED_PROXY_CIDRS，使转发的客户端 IP 仅从你真实的代理被采信，防止审计 IP 伪造。
  • 为指标设门禁。 除非配置了 GATEWAY_METRICS_TOKEN 或允许的 CIDR，否则生产环境中 /metrics/prometheus 被拒绝。
  • 让内部服务保持内部。 生产 compose 中 Postgres、PgBouncer 与 Redis 不对主机发布——请保持如此。

许可证

Cordy Gateway 使用离线的、HMAC 签名的许可证。没有网络许可校验。强制默认为 audit_only（fail-open——记录但绝不阻断）；若你希望其失败即关闭，也提供 strict 模式。许可证不会把任何用量数据传出主机。

合规

Cordy Gateway 不声称任何合规认证。 它未通过 SOC 2、ISO 27001、HIPAA、FedRAMP、PCI DSS 或任何类似标准的认证，本文档也不作此声称。

它确实提供的是你可据以构建的、诚实且可验证的属性：

  • 自托管、单租户——你的数据留在你的基础设施上。
  • 默认不捕获载荷。
  • 凭据静态加密；API 密钥仅以哈希存储。
  • 按密钥的作用域、配额与速率限制。
  • 带 RBAC 的仅追加管理审计日志。

某个具体部署是否满足特定监管要求，完全取决于你如何运维主机、网络、数据库与密钥——该责任由你承担。

加固清单

  • CHANNEL_ENCRYPTION_KEYS 在 Admin 与 Gateway 上一致设置，存于密钥管理系统。
  • 强而唯一的 DJANGO_SECRET_KEY 与 DB_PASSWORD。
  • 已终止 TLS；DJANGO_SECURE_SSL_REDIRECT=True；DJANGO_ADMIN_URL 取不显而易见的值。
  • CLIENT_CORS_ORIGINS 显式（生产环境绝不用 *）。
  • TRUSTED_PROXY_CIDRS 设为你真实的代理。
  • /metrics/prometheus 以令牌与/或 CIDR 设门禁。
  • API 密钥以最小权限签发（作用域、配额、过期）。
  • 内部服务（Postgres、Redis、PgBouncer）不对主机发布。
  • 备份已配置并测试；生产环境启用 PITR。

后续步骤

  • 配置——完整的安全相关变量。
  • 部署——把这些控制应用到生产拓扑。