feat: complete commercial control plane, billing, auth, and model catalog

- add PostgreSQL control-plane persistence with Redis-degraded hot reload
- implement prepaid balance, usage ledger, Stripe top-up and reconciliation
- add registration, email verification, password reset, invitations and RBAC
- support TOTP, Passkey MFA, device sessions, quotas and rate limits
- add tenant billing profiles, audit logs and operational readiness checks
- build authenticated admin console, Quickstart, Playground and usage analytics
- add public model catalog with pricing, filtering and cost estimation
- support OpenAI Responses providers and provider health failover
- validate real upstream usage reporting and balance settlement

1 files changed, 74 insertions, 14 deletions

diff --git a/README.md b/README.md
index fbf22a4..45bf077 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,32 @@
 # AIGW
 
-AIGW 是一个轻量、无状态的 AI API 中转后端。当前阶段聚焦上游接入与 API 分发：提供 OpenAI Chat Completions 和 Anthropic Messages 兼容入口，支持公开模型名映射、多上游路由、加权分流、故障转移、SSE 直通、客户密钥鉴权以及异步用量事件。
+AIGW 是一个轻量、无状态的 AI API 中转后端。当前阶段聚焦上游接入与 API 分发：提供 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 兼容入口，支持公开模型名映射、多上游路由、加权分流、故障转移、SSE 直通、客户密钥鉴权以及异步用量事件。
 
 它借鉴了 ZenMux 的双协议、`provider/model` 模型命名、统一错误、请求 ID、路由和可观测性边界，但没有复制其业务实现。
 
 ## 当前能力
 
-- OpenAI：`POST /v1/chat/completions`、`GET /v1/models`
+- OpenAI：`POST /v1/chat/completions`、`POST /v1/responses`、`GET /v1/models`
 - Anthropic：`POST /anthropic/v1/messages`、`GET /anthropic/v1/models`
 - ZenMux 风格别名：所有入口同时提供 `/api/...` 路径
 - 一个公开模型可配置多个同协议上游，低 `priority` 优先，同级按 `weight` 分流
+- 请求可用 `model-id:provider-slug` 固定到模型目录公开的某个供应商；固定后不会回退到其他供应商
 - 在 429、502、503、504 或连接失败时，于响应开始前自动尝试下一条路由
+- 每条模型/供应商 route 记录真实请求的近期可用率和响应头延迟；连续 3 次可重试失败后熔断 30 秒，冷却期间路由自动绕行
 - SSE 增量直通、主动断连传播、共享 HTTP/2 连接池
 - `Authorization: Bearer` 和 `x-api-key` 客户鉴权
 - 统一 JSON 错误、`X-AIGW-Request-ID`、Prometheus 文本指标
 - 非阻塞用量事件，包含租户、项目、模型、上游、尝试次数、耗时和 token 用量
 - PostgreSQL 预付余额、请求额度冻结、实际 token 结算和不可变账本
 - Stripe 托管 Checkout 充值、签名 Webhook 与事件/订单双重幂等
+- Stripe 托管支付方式保存与低余额自动充值，off-session PaymentIntent 失败会暂停自动充值并提示客户处理
 - PostgreSQL Usage Ledger、月度项目汇总和单请求成本追溯
 - 邮箱验证、邀请注册、密码重置、登录限流、可撤销设备会话和管理 API 审计日志
 - TOTP（含一次性恢复码）与 WebAuthn Passkey 注册、二次验证和无密码登录
 - 六种 RBAC 角色、租户数据隔离和 CSRF 防护
 - 项目级 RPM、估算 TPM、并发限制和月度消费配额
+- API Key 级模型白名单、月度消费上限、过期时间、标签和最后使用时间
+- 无需登录的 `/admin/models` 模型与价格目录，支持搜索、协议/输入/开发者筛选、详情和 token 成本估算
 
 ## 快速运行
 
@@ -40,6 +45,11 @@ go run ./cmd/aigw -config config.json
 
 如果当前只有一种上游，从 `config.json` 删除未使用的 provider 和对应 model，避免启动时要求该密钥。
 
+控制面模式下，公开目录位于 `AIGW_PUBLIC_URL` 同源的 `/models`（本地默认
+`http://localhost:8081/admin/models`），匿名数据接口为
+`GET /admin/api/public/models`。公开响应只包含全局可用模型的公开 ID、能力、
+协议、价格与聚合可用性；租户/Key 限定模型和内部路由字段不会返回。
+
 不使用真实密钥的本地体验方式：
 
 ```bash
@@ -65,6 +75,21 @@ curl http://127.0.0.1:8080/v1/chat/completions \
   -d '{"model":"openai/gpt-4.1-mini","messages":[{"role":"user","content":"hello"}],"stream":true}'
 ```
 
+OpenAI Responses 供应商使用独立的 wire API 配置，不会与 Chat Completions 隐式互转：
+
+```bash
+export OPENAI_BASE_URL='https://your-provider.example/v1'
+export OPENAI_API_KEY='your-upstream-key'
+export AIGW_SERVER_ADDRESS='127.0.0.1:18081'
+export AIGW_API_KEYS='[{"key":"sk-local-change-me","key_id":"local-key","tenant_id":"tenant-demo","project_id":"project-default","scopes":["inference"]}]'
+go run ./cmd/aigw -config config.responses.example.json
+
+curl http://127.0.0.1:18081/v1/responses \
+  -H 'Authorization: Bearer sk-local-change-me' \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"openai/gpt-5.5","input":"Reply with OK.","max_output_tokens":32}'
+```
+
 Anthropic 调用示例：
 
 ```bash
@@ -77,7 +102,7 @@ curl http://127.0.0.1:8080/anthropic/v1/messages \
 
 ## 配置路由
 
-每条 route 把一个对外模型映射到一个上游模型：
+每条 route 把一个对外模型映射到一个上游模型。供应商的 `protocol` 表示 OpenAI/Anthropic 协议族，`wire_api` 表示实际调用 `chat_completions`、`responses` 或 `messages`。静态配置可为供应商设置唯一的公开 `slug`；省略时使用符合相同格式的 `id`：
 
 ```json
 {
@@ -93,14 +118,26 @@ curl http://127.0.0.1:8080/anthropic/v1/messages \
 
 这里 A/B 承担约 80/20 的首选流量，C 只作为更低优先级的后备。所有上游密钥仅通过 `api_key_env` 指向的环境变量读取。客户密钥从 `AIGW_API_KEYS` JSON 数组读取，进程内只保存 SHA-256 摘要。
 
+默认请求只传基础模型 ID，由网关自动进行权重分流、熔断绕行和故障转移。需要复现特定供应商行为时，可以先从 `GET /v1/models` 的 `providers` 字段读取公开 slug，再把它附加到模型名：
+
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+  -H 'Authorization: Bearer sk-local-change-me' \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"vendor/model-public:provider-b","messages":[{"role":"user","content":"hello"}]}'
+```
+
+指定供应商时，路由器只会尝试该 slug 下与当前 API 协议兼容的 route，不会静默切换到其他供应商。该供应商不存在时返回 `404 provider_not_found`，正在熔断冷却时返回 `503 provider_unavailable`。API Key 模型白名单仍按基础模型 ID 校验，用量与扣费也归集到基础模型，避免供应商后缀拆分账单。
+
 ## 生产边界
 
 当前版本可以作为带预付计费的数据面，并已把控制面、账务和运营入口拆开：
 
 - 控制面计费模式会把 UsageEvent、冻结记录和扣费流水同步、幂等写入 PostgreSQL；响应结束只负责把结算事件投递到持久化队列，worker 负责重试、过期冻结恢复和本地 JSONL spool 补偿。
 - 客户密钥和模型目录在控制面模式下从 PostgreSQL 载入到原子内存快照；Redis 只是可选的变更广播加速层，故障时通过 PostgreSQL generation 轮询收敛。
-- 当前只把 OpenAI 入口发给 OpenAI 兼容上游、Anthropic 入口发给 Anthropic 兼容上游，不做跨协议转换。
+- 当前只把 Chat Completions、Responses、Anthropic Messages 入口发给相同 wire API 的兼容上游，不做隐式跨协议转换。
 - 自动故障转移可能在极少数网络错误下造成上游重复执行。正式计费时需要上游幂等能力、请求去重策略和重复成本对账。
+- 供应商健康状态是每个网关实例基于真实流量维护的 100 次滑动窗口，不是主动探测、全局 SLA 或首 token 延迟；新 route 在首个请求前显示为未采样。熔断状态不写入 PG/Redis，实例重启后重新学习。
 - 计费上游必须返回 usage。OpenAI 流请求会强制请求 `stream_options.include_usage=true`；成功响应缺少 usage 时不会按零费用放行，也不会猜测 token，而是把授权保持为 `metering_failed`、触发 readiness/Prometheus 告警，直到运营切断或修复该上游。显式的零 token usage 仍可正常结算。
 - 默认生产配置使用独立的推理、管理、支付/邮件 Webhook 和 operations listener。`/healthz` 只表示进程存活，`/readyz` 会检查 PG、快照、Stripe 对账、Webhook、退款、未收款、缺失用量、结算队列和邮件积压；Redis 是可降级传播层。`/metrics` 应仅在内网暴露；公网 TLS、WAF 和连接层限速应放在负载均衡器或边缘代理。
 
@@ -122,19 +159,23 @@ curl http://127.0.0.1:8080/anthropic/v1/messages \
 ./scripts/stop-debug.sh
 ```
 
-关闭脚本保留 PostgreSQL/Redis 数据卷，下一次启动仍可继续使用已有控制面数据。需要测试 Stripe Checkout 时，把 `.env.debug` 中的 restricted key、Webhook signing secret、成功 URL 和取消 URL 设置为对应环境的值。JSON 配置只保存环境变量名称，不保存外部服务 URL 或密钥。
+关闭脚本保留 PostgreSQL/Redis 数据卷，下一次启动仍可继续使用已有控制面数据。默认 `AIGW_STRIPE_ENABLED=false`，预付余额、扣费账本和人工调账仍可使用，但 Checkout、Customer Portal、退款和 Stripe 对账关闭。需要测试 Stripe 时，把 `.env.debug` 中的 restricted key、Webhook signing secret、成功 URL 和取消 URL 设置为对应环境的值，再显式设置 `AIGW_STRIPE_ENABLED=true`。JSON 配置只保存环境变量名称，不保存外部服务 URL 或密钥。
 
 源码未变化时可跳过镜像构建以快速重启：`AIGW_DEBUG_SKIP_BUILD=1 ./scripts/start-debug.sh`。默认构建使用 Docker host network；特殊环境可以通过 `AIGW_DOCKER_BUILD_NETWORK=default` 覆盖。
 
-然后打开 `http://127.0.0.1:8081/admin/`，本地邮件在 `http://127.0.0.1:8025/` 查看；健康检查在 `http://127.0.0.1:9090/readyz`。Stripe CLI Webhook 转发到 `http://127.0.0.1:8082/billing/stripe/webhook`。启用注册时，新账号必须通过一次性邮件链接验证；团队成员由管理员邀请并自行设置密码。平台管理员也可以从权限为 `0600` 的环境文件读取 `AIGW_ADMIN_TOKEN`，将其作为 bootstrap/break-glass 凭证。日常操作使用邮箱/密码、TOTP 或 Passkey，服务端创建可逐设备撤销的数据库会话，所有写请求需要 CSRF token。第一套资源的创建顺序是：Tenant → Project → API key → Provider → Model route。客户 API Key 明文只在创建成功时返回一次；团队成员使用自己的账号，不共享管理员令牌。
+然后打开 `http://127.0.0.1:8081/admin/`，本地邮件在 `http://127.0.0.1:8025/` 查看；健康检查在 `http://127.0.0.1:9090/readyz`。开发者控制台的调用示例使用 `AIGW_INFERENCE_PUBLIC_URL` 作为网关地址，分离 listener 时不要把它误配成管理地址。Stripe CLI Webhook 转发到 `http://127.0.0.1:8082/billing/stripe/webhook`。启用注册时，新账号必须通过一次性邮件链接验证；团队成员由管理员邀请并自行设置密码。平台管理员也可以从权限为 `0600` 的环境文件读取 `AIGW_ADMIN_TOKEN`，将其作为 bootstrap/break-glass 凭证。日常操作使用邮箱/密码、TOTP 或 Passkey，服务端创建可逐设备撤销的数据库会话，所有写请求需要 CSRF token。第一套资源的创建顺序是：Tenant → Project → API key → Provider → Model route。客户 API Key 明文只在创建成功时返回一次；团队成员使用自己的账号，不共享管理员令牌。
+
+账号邮件先在 PostgreSQL outbox 中加密持久化，再由后台 worker 发送；SMTP 临时不可用不会回滚注册、邀请或重置请求。普通失败指数退避，10 次后进入 dead-letter。生产环境把 `AIGW_PUBLIC_URL` 设置为 HTTPS 控制台 URL，把 `AIGW_SMTP_ADDRESS`、`AIGW_SMTP_FROM_ADDRESS`、`AIGW_SMTP_USERNAME`、`AIGW_SMTP_PASSWORD` 和 `AIGW_MAIL_FEEDBACK_SECRET` 通过密钥管理服务注入，并将 `admin.mail.tls_mode` 改为 `starttls` 或 `tls`。邮件供应商的 bounce/complaint 事件应由边缘适配器规范化后签名发送到 `/mail/feedback`；永久退信和投诉地址会进入抑制表。worker 会按租户保存的阈值、按日幂等发送低余额通知，并发送异常消费通知；未配置租户继续使用 `admin.mail.low_balance_micros` 的全局默认值。域名 DNS 仍必须在邮件供应商处配置 SPF、DKIM 和 DMARC，这不是应用代码可以代替的步骤。WebAuthn 的 `AIGW_WEBAUTHN_RP_ID` 必须是控制台有效域名，`AIGW_WEBAUTHN_ORIGINS` 是逗号分隔的 HTTPS origin。
+
+租户登录后的 Quickstart 首屏会显示充值、密钥、可用模型和首次成功请求四步状态；模型目录按协议、输入模态和开发者筛选，并可按发布时间、名称、输入/输出价格和上下文长度排序，再生成使用 `AIGW_INFERENCE_PUBLIC_URL` 的 cURL、Python 和 Node.js 示例。新工作区可以在 Quickstart 直接为默认项目和当前模型创建 starter key，明文仍只显示一次，同时自动放入当前页面内存中的 Playground。连接面板集中列出 OpenAI/Anthropic SDK Base URL、Chat Completions、Responses、Messages、Models 端点，并可复制不含真实密钥的环境变量模板。每个模型都有客户安全的详情视图，展示协议、模态、上下文、最大输出、能力、生命周期和别名，并按当前价格版本实时估算输入、输出、缓存读取和缓存写入成本；逐供应商运行状态只暴露名称、协议、近期可用率、响应头延迟、样本量和熔断恢复时间，不暴露地址、凭证或上游模型。完全熔断的模型不能从快捷入口发起请求。API Playground 会直接从浏览器调用该推理地址，使用当前客户 API Key 经过完整鉴权、路由、余额冻结/结算和 Usage 链路；它只把 Key 保留在当前页面内存，刷新或退出立即清除。失败时页面保留结构化响应和请求 ID，并把权限、余额、模型、限流或上游错误引导到对应控制台页面。分离 listener 时推理服务只允许 `AIGW_PUBLIC_URL` 的精确 Origin，并且不带管理 Cookie。租户可把目录内可用模型保存为默认模型和不同的 fallback 模型，Quickstart 会立即采用该默认值；billing 成员可以单独启停低余额邮件并设置阈值。
 
-账号邮件先在 PostgreSQL outbox 中加密持久化，再由后台 worker 发送；SMTP 临时不可用不会回滚注册、邀请或重置请求。普通失败指数退避，10 次后进入 dead-letter。生产环境把 `AIGW_PUBLIC_URL` 设置为 HTTPS 控制台 URL，把 `AIGW_SMTP_ADDRESS`、`AIGW_SMTP_FROM_ADDRESS`、`AIGW_SMTP_USERNAME`、`AIGW_SMTP_PASSWORD` 和 `AIGW_MAIL_FEEDBACK_SECRET` 通过密钥管理服务注入，并将 `admin.mail.tls_mode` 改为 `starttls` 或 `tls`。邮件供应商的 bounce/complaint 事件应由边缘适配器规范化后签名发送到 `/mail/feedback`；永久退信和投诉地址会进入抑制表。worker 会按日幂等发送低余额和异常消费通知。域名 DNS 仍必须在邮件供应商处配置 SPF、DKIM 和 DMARC，这不是应用代码可以代替的步骤。WebAuthn 的 `AIGW_WEBAUTHN_RP_ID` 必须是控制台有效域名，`AIGW_WEBAUTHN_ORIGINS` 是逗号分隔的 HTTPS origin。
+API keys 页面会展示每个 Key 当月已结算费用、待结算冻结、请求数、月度上限、剩余额度、过期时间和最后使用时间；月度统计直接读取 Usage Ledger 与 billing reservation，不在浏览器侧计算。
 
-控制台角色分为：`platform_admin`、`platform_viewer`、`tenant_admin`、`tenant_billing`、`tenant_developer`、`tenant_viewer`。租户角色的查询条件在服务端下推到 PostgreSQL，不能读取其他租户的项目、密钥、余额、Usage 或审计事件；供应商凭证和路由管理只对平台角色开放。
+控制台角色分为：`platform_admin`、`platform_viewer`、`tenant_admin`、`tenant_billing`、`tenant_developer`、`tenant_viewer`。租户角色的查询条件在服务端下推到 PostgreSQL，不能读取其他租户的项目、密钥、余额、Usage 或审计事件；供应商凭证和路由管理只对平台角色开放。默认模型与财务告警使用独立写权限：developer 不能修改低余额阈值，billing 成员不能修改 API 默认模型。
 
 ## Usage、配额与限流
 
-每个完成上游尝试的请求都会按 `request_id` 幂等写入 `usage_events`，并更新 `usage_monthly_rollups`。Usage 持久化独立于预付费冻结记录，因此关闭计费也不会关闭用量账本。Admin WebUI 提供本月汇总、单请求状态、模型、token、成本、未收金额和延迟查询。
+每个完成上游尝试的请求都会按 `request_id` 幂等写入 `usage_events`，并更新 `usage_monthly_rollups`。Usage 持久化独立于预付费冻结记录，因此关闭计费也不会关闭用量账本。Admin WebUI 提供本月汇总、单请求状态、模型、token、成本、未收金额和延迟查询；同一时间、项目、API Key、模型、供应商 slug、协议、流式状态、错误类型与成功状态过滤会下推到模型成本排行和供应商性能聚合，展示本期/上期费用变化、成功率、缓存命中、P95 延迟和缺失 usage 请求。每条请求可以打开详情，查看完整 request ID、项目与 Key、路由上游、协议、流式状态、重试、吞吐量、缓存 token 和结算状态，并复制不含 prompt、响应正文或客户密钥的诊断 JSON。
 
 Limits 页面按项目配置：
 
@@ -147,9 +188,9 @@ Redis 可用时，RPM/TPM/并发通过 Lua 原子执行并在多实例间共享�
 
 ## 余额与 Stripe 充值
 
-模型价格在后台按“币种单位 / 100 万 token”配置，数据库使用 `amount_micros` 固定精度整数保存金额。Stripe 不直接为推理请求结账，只向 PostgreSQL 预付钱包充值；推理请求先按请求体字节数和 `max_tokens`/`max_completion_tokens` 保守冻结余额，成功响应按可信 usage 扣款，失败请求释放冻结。`request_id` 是用量与扣费幂等键，余额、冻结和不可变 ledger 都在同一个 PG 事务中更新。
+模型价格在后台按“币种单位 / 100 万 token”配置，数据库使用 `amount_micros` 固定精度整数保存金额。Stripe 不直接为推理请求结账，只向 PostgreSQL 预付钱包充值；推理请求先按请求体字节数和 `max_tokens`/`max_completion_tokens` 保守冻结余额，成功响应按可信 usage 扣款，失败请求释放冻结。计量层把 OpenAI 总 input 中的 `cached_tokens`/cache-write 子集归一化为互斥的非缓存输入、缓存读取和缓存写入桶，Anthropic 已独立报告的缓存字段则保持不变，避免按输入价和缓存价重复扣费。`request_id` 是用量与扣费幂等键，余额、冻结和不可变 ledger 都在同一个 PG 事务中更新。
 
-Stripe 使用托管 Checkout，服务端不会接触卡号，也没有硬编码支付方式；支付方式由 Stripe Dashboard 动态配置。充值只在签名校验通过的 Webhook 确认 `payment_status=paid` 后入账，成功跳转页不会直接修改余额。
+Stripe 使用托管 Checkout，服务端不会接触卡号，也没有硬编码支付方式；支付方式由 Stripe Dashboard 动态配置。租户可在 Billing 页面保存开票名称、邮箱和地址，资料用稳定幂等键创建或更新 Stripe Customer；Stripe 暂时不可用时本地资料标记为待修复，下一次充值、保存支付方式或打开客户门户会再次同步。本地不保存税号，启用且确认 Stripe Tax 注册后由 Checkout/Customer Portal 托管税号。手动充值只在签名校验通过的 Webhook 确认 `payment_status=paid` 后入账，成功跳转页不会直接修改余额。自动充值先通过 Checkout Setup Session 保存支付方式；余额低于客户阈值时，后台 worker 用订单 ID 作为幂等键创建并确认 off-session PaymentIntent。同步结果、Webhook 重放和周期对账都只能生成一笔钱包入账；需要客户认证或支付方式失效时会暂停自动充值，不会循环扣款。
 
 配置 Stripe 测试环境：
 
@@ -168,12 +209,28 @@ Webhook 至少订阅：
 - `checkout.session.async_payment_succeeded`
 - `checkout.session.async_payment_failed`
 - `checkout.session.expired`
-
-网关 restricted key 的最小权限按实际启用功能配置：Checkout Sessions Write（充值与对账读取）、Customer Portal Write、Customers Write、Charges and Refunds Write、Payment Intents Read 和 Invoices Read。不要给主网关 Debugging Tools 权限；Stripe CLI 使用独立的测试 key。Dashboard 保存权限时可能要求账户持有人完成二次验证。
+- `payment_intent.succeeded`
+- `payment_intent.payment_failed`
+- `payment_intent.canceled`
+- `charge.succeeded`
+- `charge.updated`
+- `charge.refunded`
+- `refund.created`
+- `refund.updated`
+- `refund.failed`
+- `charge.dispute.created`
+- `charge.dispute.updated`
+- `charge.dispute.closed`
+- `invoice.created`
+- `invoice.finalized`
+- `invoice.paid`
+- `invoice.payment_failed`
+
+网关 restricted key 的最小权限按实际启用功能配置：Checkout Sessions Write、Customer Portal Sessions Write、Setup Intents Read、Payment Intents Write、Refunds Write，以及 Customers、Charges、Disputes、Invoices 的 Read；如果 Dashboard 将 Checkout 自动创建 Customer 归入 Customers 写权限，再增加 Customers Write。不要给主网关 Debugging Tools 权限；Stripe CLI 使用独立的测试 key。Dashboard 保存权限时可能要求账户持有人完成二次验证。修改权限后必须在测试模式重新跑一次手动充值、保存支付方式、自动充值、客户门户、退款和对账。
 
 后台已覆盖 Checkout 重试、客户门户、退款队列、争议/发票/收据记录、失败重试、周期性 Stripe 对账和 CSV 财务导出。Stripe 已支付但本地 pending 的订单会自动补账且传播错误不会被忽略；Stripe 中不存在的未入账订单只能通过 RBAC/审计保护的 resolution 作废，已入账孤立充值只能用等额负向账本冲销，原记录不会删除或改写。退款与争议会先冻结/扣除本地余额，余额不足进入 `uncollected_micros`，不会静默丢账。当前没有默认启用 Stripe Tax，因为是否有有效税务注册不能由代码推断；确认注册和 canonical product tax code 后再显式打开。生产环境应把 Stripe restricted key 和 Webhook signing secret 放入云平台的密钥管理服务，并限制密钥权限和来源 IP，不要放进镜像或仓库。
 
-模型目录支持输入/输出模态、上下文窗口、最大输出、能力集合、生命周期、弃用替代模型、区域和租户/API key allowlist；价格在 `model_price_versions` 中按生效时间版本化。推理请求会在路由前执行区域、生命周期、能力和 allowlist 校验，旧 alias 只映射到 canonical model ID。
+模型目录支持输入/输出模态、上下文窗口、最大输出、能力集合、生命周期、弃用替代模型、区域和租户/API key allowlist；价格在 `model_price_versions` 中按生效时间版本化。每个客户 API Key 还可以独立设置模型白名单、月度消费上限和过期时间：限制随 PostgreSQL generation 热加载到鉴权快照，模型检查发生在路由前，金额上限在钱包行锁事务内和待结算冻结一起检查。旧 alias 只映射到 canonical model ID。
 
 静态模式的上游 Base URL 与 API Key 分别使用 `base_url_env` 和 `api_key_env`；控制面、Redis、Stripe、SMTP、WebAuthn 和监听地址同样只通过环境变量或密钥管理服务注入。严格 JSON 解析会拒绝旧的 `address`、`base_url`、`success_url` 和 `cancel_url` 字面量字段，避免环境隔离被配置文件绕过。版本化配置只保存 `*_env` 名称，不保存外部服务密钥或部署域名。
 
@@ -196,6 +253,9 @@ go test ./...
 go test -race ./...
 go vet ./...
 CGO_ENABLED=0 go build -buildvcs=false ./cmd/...
+
+# 在容器网络内运行真实 PostgreSQL 集成测试
+docker compose --env-file .env.debug --profile test run --rm integration-test
 ```
 
 设置 `AIGW_TEST_DATABASE_URL` 后，测试会强制执行 PostgreSQL Webhook/结算/迁移升级用例。CI 还构建容器镜像、生成 SPDX SBOM、以 Trivy 阻断 HIGH/CRITICAL 漏洞，并在 `v*` 标签发布时使用 OIDC keyless Cosign 签名。负载与 Redis 降级演练分别使用 `scripts/load-smoke.sh` 和 `scripts/redis-fault-drill.sh`；备份恢复演练使用 `scripts/backup-postgres.sh` 与 `scripts/restore-drill.sh`。