生产部署

SAG 当前按本地单用户产品设计。生产部署的第一原则是：不要把 Web 与 API 端口直接暴露到公网。请使用 HTTPS，并在应用外增加 VPN、IP 白名单或反向代理认证。

推荐拓扑

trusted user
  -> HTTPS / access control
  -> SAG Web
  -> SAG API
  -> PostgreSQL + pgvector
  -> persistent upload/index volume

SAG JWT 负责应用内身份，但不替代公共互联网场景中的外围访问控制。

准备配置

cp .env.example .env
openssl rand -hex 32
openssl rand -hex 24

把第一个随机值写入 SAG_SECRET_KEY，第二个写入 POSTGRES_PASSWORD。同时设置真实域名：

SAG_ENVIRONMENT=prod
SAG_SECRET_KEY=<STRONG_RANDOM_VALUE>
POSTGRES_PASSWORD=<STRONG_DATABASE_PASSWORD>
SAG_CORS_ORIGINS=https://sag.example.com
NEXT_PUBLIC_API_BASE=https://sag-api.example.com

SAG_ENVIRONMENT=prod 会拒绝 Compose 中已知的开发弱密钥。

PostgreSQL 与 pgvector

仓库提供生产覆盖文件：

docker compose \
  -f compose.yaml \
  -f compose.postgres.yaml \
  config

docker compose \
  -f compose.yaml \
  -f compose.postgres.yaml \
  up -d --build

覆盖会将应用元数据与 SAG 关系数据放入 PostgreSQL，并使用 pgvector 作为向量后端。pgdata 保存数据库，sagdata 继续保存上传文件和引擎数据目录。

反向代理要求

代理至少需要：

• 为 Web 与 API 提供有效 HTTPS；
• 传递 Host、X-Forwarded-Proto 和客户端地址；
• 对 SSE 路由关闭响应缓冲并允许长连接；
• 为文档上传设置合理的请求体上限；
• 在 SAG 之前执行访问控制。

如果 Web 与 API 使用不同 Origin，SAG_CORS_ORIGINS 必须精确包含 Web Origin。不要用公共 * 代替明确来源。

构建期 API 地址

NEXT_PUBLIC_API_BASE 会内联到 Web 镜像。域名、协议或端口变化后必须重建 Web：

docker compose \
  -f compose.yaml \
  -f compose.postgres.yaml \
  up -d --build web

健康检查

编排系统应分别检查：

• Web：根路径返回小于 500 的状态；
• API：GET /api/v1/system/ready 返回 200；
• PostgreSQL：pg_isready 成功。

health 只说明进程可响应，ready 才表示关键依赖可接收业务流量。

数据保护

升级前同时备份 pgdata 与 sagdata。只备份数据库会丢失上传文件，只备份文件卷会丢失应用元数据和索引关系。

将模型密钥、数据库密码和 SAG_SECRET_KEY 作为 Secret 管理，不要写入镜像、公开仓库或前端环境变量。

上线检查

• 外部访问必须经过 HTTPS 与认证层；
• API ready、文档导入、快速/精确检索、对话引用和 MCP 都完成一次验收；
• SSE 经过代理后仍能持续输出；
• 备份可以恢复到独立环境；
• 3000、8000 与 5432 不直接面向公网。