150 lines
8.0 KiB
Markdown
150 lines
8.0 KiB
Markdown
# ai-customer-service 配置契约基线
|
||
|
||
> 来源：`internal/config/config.go` 当前实现
|
||
> 用途：作为 PM / QA / DevOps / 部署文档的唯一配置事实来源
|
||
> 状态：当前代码事实基线；production 下的关键运行约束已经由 `internal/config/config.go` 执行校验
|
||
|
||
---
|
||
|
||
## 0. 重要说明
|
||
|
||
当前代码已经实现了基础配置解析，并对 production 下的关键约束做了 fail-fast 校验。
|
||
|
||
这意味着：
|
||
- 本文档描述的是**当前代码真实读取和校验的配置契约**
|
||
- production 下缺少关键配置时，`Load()` 会直接返回错误
|
||
- readiness / 依赖可观测仍需结合运行态和部署层继续完善
|
||
|
||
---
|
||
|
||
## 1. 当前代码真实读取的环境变量
|
||
|
||
### 1.1 HTTP
|
||
|
||
| 变量名 | 默认值 | 含义 | 当前代码是否校验 | prod 是否应允许默认值 |
|
||
|---|---|---|---|---|
|
||
| `AI_CS_ADDR` | `:8080` | HTTP 监听地址 | 非空校验 | 视部署环境决定 |
|
||
| `AI_CS_READ_HEADER_TIMEOUT_SEC` | `5` | header 读取超时（秒） | 无额外校验 | 可 |
|
||
| `AI_CS_READ_TIMEOUT_SEC` | `10` | 请求读取超时（秒） | 无额外校验 | 可 |
|
||
| `AI_CS_WRITE_TIMEOUT_SEC` | `15` | 响应写超时（秒） | 无额外校验 | 可 |
|
||
| `AI_CS_IDLE_TIMEOUT_SEC` | `60` | 空闲连接超时（秒） | 无额外校验 | 可 |
|
||
| `AI_CS_MAX_HEADER_BYTES` | `1048576` | header 大小上限 | 无额外校验 | 可 |
|
||
| `AI_CS_MAX_BODY_BYTES` | `1048576` | body 大小上限 | 必须 > 0 | 需结合流量评估 |
|
||
|
||
### 1.2 Postgres
|
||
|
||
| 变量名 | 默认值 | 含义 | 当前代码是否校验 | prod 是否应允许默认值 |
|
||
|---|---|---|---|---|
|
||
| `AI_CS_POSTGRES_ENABLED` | `false` | 是否启用 Postgres store | 解析布尔值 | **不允许** |
|
||
| `AI_CS_POSTGRES_DSN` | 空 | Postgres 连接串 | 启用 PG 时必填 | **不允许为空** |
|
||
| `AI_CS_POSTGRES_MIGRATION_DIR` | `db/migration` | migration 目录 | 无路径存在性校验 | 需确认可用 |
|
||
| `AI_CS_POSTGRES_MAX_OPEN_CONNS` | `20` | 最大打开连接数 | 无额外校验 | 需容量确认 |
|
||
| `AI_CS_POSTGRES_MAX_IDLE_CONNS` | `5` | 最大空闲连接数 | 无额外校验 | 需容量确认 |
|
||
| `AI_CS_POSTGRES_CONN_MAX_LIFETIME_SEC` | `300` | 连接最大生命周期（秒） | 无额外校验 | 需容量确认 |
|
||
|
||
### 1.3 Webhook
|
||
|
||
| 变量名 | 默认值 | 含义 | 当前代码是否校验 | prod 是否应允许默认值 |
|
||
|---|---|---|---|---|
|
||
| `AI_CS_WEBHOOK_SECRET` | 空 | webhook HMAC secret | production 下必填 | **不允许为空** |
|
||
| `AI_CS_WEBHOOK_TIMESTAMP_HEADER` | `X-CS-Timestamp` | 时间戳请求头 | 无额外校验 | 可 |
|
||
| `AI_CS_WEBHOOK_SIGNATURE_HEADER` | `X-CS-Signature` | 签名请求头 | 无额外校验 | 可 |
|
||
| `AI_CS_WEBHOOK_MAX_SKEW_SECONDS` | `300` | 最大时钟偏差（秒） | 必须 > 0 | 需安全确认 |
|
||
|
||
### 1.4 Platform Adapters
|
||
|
||
| 变量名 | 默认值 | 含义 | 当前代码是否校验 | prod 是否应允许默认值 |
|
||
|---|---|---|---|---|
|
||
| `AI_CS_PLATFORM_ADAPTERS_ENABLED` | `false` | 是否启用平台适配入口 | 解析布尔值 | 视接入计划决定 |
|
||
| `AI_CS_PLATFORM_SUB2API_ENABLED` | `false` | 是否启用 `sub2api` 入站适配 | 解析布尔值 | 视接入计划决定 |
|
||
| `AI_CS_PLATFORM_SUB2API_INGRESS_SECRET` | 空 | `sub2api` 平台 webhook HMAC secret | 启用 `sub2api` 时必填 | **不允许为空** |
|
||
| `AI_CS_PLATFORM_SUB2API_CALLBACK_BASE_URL` | 空 | `sub2api` 回调基地址 | 当前仅解析，不强校验 | 视后续出站回调批次决定 |
|
||
| `AI_CS_PLATFORM_SUB2API_CALLBACK_SECRET` | 空 | `sub2api` 回调签名 secret | 当前仅解析，不强校验 | 视后续出站回调批次决定 |
|
||
| `AI_CS_PLATFORM_SUB2API_CALLBACK_TIMEOUT_MS` | `3000` | `sub2api` 回调超时（毫秒） | 必须 > 0（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_SUB2API_CALLBACK_MAX_RETRIES` | `5` | `sub2api` 回调最大重试次数 | 必须 >= 0（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_SUB2API_CALLBACK_POLL_INTERVAL_MS` | `5000` | `sub2api` callback worker 轮询间隔（毫秒） | 必须 > 0（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_SUB2API_CALLBACK_BATCH_SIZE` | `20` | `sub2api` callback worker 单轮最大投递数 | 必须 > 0（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_SUB2API_CALLBACK_RETRY_SCHEDULE_SEC` | `10,30,60,300,900` | `sub2api` callback 重试退避序列（秒） | 必须为正整数列表（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_NEWAPI_ENABLED` | `false` | 是否启用 `newapi` 入站适配 | 解析布尔值 | 视接入计划决定 |
|
||
| `AI_CS_PLATFORM_NEWAPI_INGRESS_SECRET` | 空 | `newapi` 平台 webhook HMAC secret | 启用 `newapi` 时必填 | **不允许为空** |
|
||
| `AI_CS_PLATFORM_NEWAPI_CALLBACK_BASE_URL` | 空 | `newapi` 回调基地址 | 当前仅解析，不强校验 | 视后续出站回调批次决定 |
|
||
| `AI_CS_PLATFORM_NEWAPI_CALLBACK_SECRET` | 空 | `newapi` 回调签名 secret | 当前仅解析，不强校验 | 视后续出站回调批次决定 |
|
||
| `AI_CS_PLATFORM_NEWAPI_CALLBACK_TIMEOUT_MS` | `3000` | `newapi` 回调超时（毫秒） | 必须 > 0（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_NEWAPI_CALLBACK_MAX_RETRIES` | `5` | `newapi` 回调最大重试次数 | 必须 >= 0（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_NEWAPI_CALLBACK_POLL_INTERVAL_MS` | `5000` | `newapi` callback worker 轮询间隔（毫秒） | 必须 > 0（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_NEWAPI_CALLBACK_BATCH_SIZE` | `20` | `newapi` callback worker 单轮最大投递数 | 必须 > 0（启用时） | 可 |
|
||
| `AI_CS_PLATFORM_NEWAPI_CALLBACK_RETRY_SCHEDULE_SEC` | `10,30,60,300,900` | `newapi` callback 重试退避序列（秒） | 必须为正整数列表（启用时） | 可 |
|
||
|
||
---
|
||
|
||
## 2. 当前代码已经执行的校验
|
||
|
||
来自 `internal/config/config.go`：
|
||
|
||
1. `AI_CS_ADDR` 不允许为空
|
||
2. `AI_CS_MAX_BODY_BYTES` 必须为正数
|
||
3. `AI_CS_POSTGRES_ENABLED=true` 时，`AI_CS_POSTGRES_DSN` 不允许为空
|
||
4. `AI_CS_WEBHOOK_MAX_SKEW_SECONDS` 必须为正数
|
||
5. `AI_CS_RUNTIME_ENV` 只允许 `production/development/test`
|
||
6. `AI_CS_RUNTIME_ENV=production` 时，`AI_CS_POSTGRES_ENABLED` 必须为 `true`
|
||
7. `AI_CS_RUNTIME_ENV=production` 时，`AI_CS_WEBHOOK_SECRET` 不允许为空
|
||
8. `AI_CS_PLATFORM_ADAPTERS_ENABLED=true` 且对应平台 `*_ENABLED=true` 时，`*_INGRESS_SECRET` 不允许为空
|
||
9. `AI_CS_PLATFORM_*_CALLBACK_TIMEOUT_MS` 在对应平台启用时必须为正数
|
||
10. `AI_CS_PLATFORM_*_CALLBACK_MAX_RETRIES` 在对应平台启用时不允许为负数
|
||
11. `AI_CS_PLATFORM_*_CALLBACK_POLL_INTERVAL_MS` 在对应平台启用时必须为正数
|
||
12. `AI_CS_PLATFORM_*_CALLBACK_BATCH_SIZE` 在对应平台启用时必须为正数
|
||
13. `AI_CS_PLATFORM_*_CALLBACK_RETRY_SCHEDULE_SEC` 在对应平台启用时必须是正整数列表，且不允许为空
|
||
|
||
---
|
||
|
||
## 3. 当前代码尚未自动保证、但生产必须满足的要求
|
||
|
||
以下要求目前仍需部署层和运行态共同保证：
|
||
|
||
1. **readiness 必须反映 DB / migration / 关键配置就绪状态**
|
||
2. **migration 目录必须真实可执行，且执行成功才能接流量**
|
||
3. **部署文档和环境模板必须只使用真实变量名**
|
||
|
||
---
|
||
|
||
## 4. 文档使用规则
|
||
|
||
后续所有文档若涉及配置、部署、上线前检查，必须以本文档和 `internal/config/config.go` 为唯一事实来源。
|
||
|
||
### 4.1 禁止继续使用的泛化写法
|
||
以下名称若未在代码中真实读取，不应继续写入正式部署文档：
|
||
- `DATABASE_URL`
|
||
- `POSTGRES_*`
|
||
- `WEBHOOK_SECRET`
|
||
- `AI_CS_PLATFORM_*`
|
||
- `RATE_LIMIT_*`
|
||
- `LOG_LEVEL`
|
||
- `OPENAI_API_KEY`
|
||
- `LLM_PROVIDER`
|
||
- `FEISHU_APP_ID`
|
||
- `FEISHU_APP_SECRET`
|
||
- `TELEGRAM_BOT_TOKEN`
|
||
|
||
### 4.2 允许的文档表达方式
|
||
正确方式：
|
||
- 直接写真实变量名
|
||
- 标明默认值
|
||
- 标明 prod 是否允许默认值
|
||
- 标明当前代码是否已强制校验
|
||
|
||
错误方式：
|
||
- 用泛化变量名代替真实变量名
|
||
- 把“生产要求”误写成“代码已经自动保证”
|
||
- 不区分 dev/test 与 prod 约束
|
||
|
||
---
|
||
|
||
## 5. 后续维护要求
|
||
|
||
若 `internal/config/config.go` 变更，必须同步更新：
|
||
1. `docs/CONFIG_CONTRACT_BASELINE.md`
|
||
2. `prd/PRODUCTION_CHECKLIST.md`
|
||
3. `test/QA_GATE_STATUS.md`
|
||
|
||
否则视为配置契约漂移。
|