安全与密钥管理手册

最后更新：2025-11-10 · 负责人：Security/DevOps

这是 Python/FastAPI + React 技术栈的安全指引单一事实源。

1. 威胁模型速览

Asset	Primary Risks	Mitigations
Provider API keys（静态加密存储）	数据库泄露、日志泄露、内存抓取	使用 AES-GCM 配合外置 `ENCRYPTION_KEY`；信封式密钥管理接入 HSM/vault；结构化日志进行 secrets 脱敏。
评测结果与数据集	未授权访问、篡改、去匿名化	角色权限控制（未来）、签名导出、访问日志、带完整性校验的备份。
控制面（FastAPI、Celery、CLI）	依赖漏洞导致 RCE、provider webhook 引发 SSRF、SSE 通道泄露	docs/toolchain 升级后保持 `uv.lock` 同步；锁定依赖；服务以非 root 的 `eval752` 用户运行；限制请求体大小和超时；通过反向代理限制 SSE 来源。
基础设施 secrets	Compose 与 K8s 配置漂移、人工复制粘贴出错	`.env.prod` 仅存放在 vault（AWS Secrets Manager、Doppler 等）中，通过 CI 或编排平台 secret store 注入，绝不提交进仓库。

存储：Provider API keys 在写入 Postgres 前先使用 AES-GCM 加密。ENCRYPTION_KEY 必须是 32-byte hex 字符串，并在 backend、Celery worker、Celery beat 之间保持一致。
轮换节奏：至少每月轮换一次，或在发生安全事件后立即轮换。通过 PATCH /providers/{id} 原子替换加密后的 payload，然后在上游 provider 侧吊销旧 key。
备份：ENCRYPTION_KEY 必须与数据库备份分开保存。一份存放在硬件密码管理器中，另一份放在云端 secret vault 中。每次轮换都记录到 specs/4_notes.md。
访问边界：只有 backend 和 celery-worker 容器应接触 provider secrets。前端构建绝不能嵌入 API keys；一律通过应用内 Provider manager 管理。

Scope	Variable(s)	Hardening Notes
Postgres	`DATABASE_URL`, `POSTGRES_PASSWORD`	使用强密码；可用时启用 TLS；仅允许来自应用子网的访问。
Redis / Celery	`REDIS_URL`	优先使用 `redis://:password@host:6379/0`，禁用匿名访问，在事件响应流程中轮换。
Hugging Face	`HF_TOKEN`	通过 secrets manager 注入；如怀疑泄露，应审计使用日志。
工作区运行时策略	`Settings` → runtime controls	Provider 凭据仅保留在数据库；超时 / 重试 / 取消策略现存于数据库，并作用于后续 run。
Prometheus 抓取	`PROMETHEUS_PASSWORD`	当 `/metrics` 对 localhost 之外暴露时，添加 basic auth 或 IP allow-list。
Telemetry 端点	`SENTRY_DSN`, `OTEL_EXPORTER_*`	可选，但在适用场景下也应视为 secrets。

新增变量时，请同步更新配置说明、.env.example 和 release notes。

分段隔离：通过反向代理（Traefik/Caddy/Nginx）暴露 FastAPI。除非必须，外部只开放 80/443（前端/代理）和 22（SSH）。禁止从公网直接访问 Postgres/Redis。
TLS：在代理层或 Kubernetes Ingress 上终止 HTTPS，并使用托管证书（ACM、Cert-Manager）。测试期至少启用 min-age ≥ 1 day 的 HSTS，稳定后在生产环境提升到 ≥ 6 months。
安全头：确保启用 Strict-Transport-Security、Content-Security-Policy 'self' data: blob:、X-Frame-Options DENY、Referrer-Policy strict-origin-when-cross-origin。在 specs/4_notes.md 中跟踪覆盖情况。
容器：所有 Docker 镜像都以 eval752 用户运行。Bind mount 目录应归该 UID 所有，或至少对所属组可写。如果编排平台支持，请为前端容器启用只读 root filesystem。

推送前在本地运行 uvx pre-commit run -a，确保 secret 扫描器与 lint 规则和 CI 使用同一份代码树。
CI 流水线必须从 repository/environment secrets 中获取所有敏感信息，不能把明文值写入 workflow YAML。
在任何非一次性环境中，必须先替换示例 .env 中的占位值，再存入真实 provider keys。
即使使用 Docker Compose，也优先使用基础设施 secret store（AWS Secrets Manager、Azure Key Vault、Doppler、1Password Connect）；通过自动化生成 .env 文件挂载到服务器，而不是手工编辑。