diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 28 |
1 files changed, 19 insertions, 9 deletions
@@ -95,14 +95,14 @@ curl http://127.0.0.1:8080/anthropic/v1/messages \ ## 生产边界 -当前版本可以作为带预付计费的数据面，但上线前仍需完成业务侧对账： +当前版本可以作为带预付计费的数据面，并已把控制面、账务和运营入口拆开： -- 控制面计费模式会把 UsageEvent、冻结记录和扣费流水同步、幂等写入 PostgreSQL；异步结构化日志只是可观测副本，丢弃不会影响账本。 +- 控制面计费模式会把 UsageEvent、冻结记录和扣费流水同步、幂等写入 PostgreSQL；响应结束只负责把结算事件投递到持久化队列，worker 负责重试、过期冻结恢复和本地 JSONL spool 补偿。 - 客户密钥和模型目录在控制面模式下从 PostgreSQL 载入到原子内存快照；Redis 只是可选的变更广播加速层，故障时通过 PostgreSQL generation 轮询收敛。 - 当前只把 OpenAI 入口发给 OpenAI 兼容上游、Anthropic 入口发给 Anthropic 兼容上游，不做跨协议转换。 - 自动故障转移可能在极少数网络错误下造成上游重复执行。正式计费时需要上游幂等能力、请求去重策略和重复成本对账。 -- 上游必须返回 usage 才能按 token 结算；未返回 usage 的成功响应当前记为零费用，应在上生产前为每个供应商做账单对账或补充 token 计算器。 -- `/metrics` 应仅在内网暴露；公网 TLS、WAF 和连接层限速应放在负载均衡器或边缘代理。 +- 计费上游必须返回 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 和连接层限速应放在负载均衡器或边缘代理。 ## PostgreSQL + Redis 控制面 @@ -126,9 +126,9 @@ curl http://127.0.0.1:8080/anthropic/v1/messages \ 源码未变化时可跳过镜像构建以快速重启：`AIGW_DEBUG_SKIP_BUILD=1 ./scripts/start-debug.sh`。默认构建使用 Docker host network；特殊环境可以通过 `AIGW_DOCKER_BUILD_NETWORK=default` 覆盖。 -然后打开 `http://127.0.0.1:8080/admin/`，本地邮件在 `http://127.0.0.1:8025/` 查看。启用注册时，新账号必须通过一次性邮件链接验证；团队成员由管理员邀请并自行设置密码。平台管理员也可以从权限为 `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`。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 临时不可用不会回滚注册、邀请或重置请求，worker 会重试并记录失败。生产环境把 `AIGW_PUBLIC_URL` 设置为 HTTPS 控制台 URL，把 `AIGW_SMTP_ADDRESS`、`AIGW_SMTP_FROM_ADDRESS`、`AIGW_SMTP_USERNAME`、`AIGW_SMTP_PASSWORD` 通过密钥管理服务注入，并将 `admin.mail.tls_mode` 改为 `starttls` 或 `tls`。WebAuthn 的 `AIGW_WEBAUTHN_RP_ID` 必须是控制台有效域名，`AIGW_WEBAUTHN_ORIGINS` 是逗号分隔的 HTTPS origin。 +账号邮件先在 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。 控制台角色分为：`platform_admin`、`platform_viewer`、`tenant_admin`、`tenant_billing`、`tenant_developer`、`tenant_viewer`。租户角色的查询条件在服务端下推到 PostgreSQL，不能读取其他租户的项目、密钥、余额、Usage 或审计事件；供应商凭证和路由管理只对平台角色开放。 @@ -147,7 +147,7 @@ Redis 可用时，RPM/TPM/并发通过 Lua 原子执行并在多实例间共享 ## 余额与 Stripe 充值 -模型价格在后台按“币种单位 / 100 万 token”配置，数据库使用 `amount_micros` 固定精度整数保存金额。推理请求会先按请求体字节数和 `max_tokens`/`max_completion_tokens` 保守冻结额度；成功响应按上游返回的输入、输出和缓存 token 结算，失败请求释放冻结。`request_id` 是用量与扣费幂等键。 +模型价格在后台按“币种单位 / 100 万 token”配置，数据库使用 `amount_micros` 固定精度整数保存金额。Stripe 不直接为推理请求结账，只向 PostgreSQL 预付钱包充值；推理请求先按请求体字节数和 `max_tokens`/`max_completion_tokens` 保守冻结余额，成功响应按可信 usage 扣款，失败请求释放冻结。`request_id` 是用量与扣费幂等键，余额、冻结和不可变 ledger 都在同一个 PG 事务中更新。 Stripe 使用托管 Checkout，服务端不会接触卡号，也没有硬编码支付方式；支付方式由 Stripe Dashboard 动态配置。充值只在签名校验通过的 Webhook 确认 `payment_status=paid` 后入账，成功跳转页不会直接修改余额。 @@ -158,7 +158,7 @@ cp .env.control.example .env # 将 AIGW_STRIPE_API_KEY 设为最小权限的 rk_test_ restricted key # AIGW_STRIPE_CLI_API_KEY 使用另一把仅有 Debugging Tools Write 的测试 key # 本地转发会显示 whsec_...，填入 AIGW_STRIPE_WEBHOOK_SECRET -stripe listen --api-key "$AIGW_STRIPE_CLI_API_KEY" --forward-to http://127.0.0.1:8080/billing/stripe/webhook +stripe listen --api-key "$AIGW_STRIPE_CLI_API_KEY" --forward-to http://127.0.0.1:8082/billing/stripe/webhook docker compose up --build ``` @@ -169,7 +169,11 @@ Webhook 至少订阅： - `checkout.session.async_payment_failed` - `checkout.session.expired` -当前没有默认启用 Stripe Tax，因为是否有有效税务注册不能由代码推断。确认注册和税务处理方案后再显式加入 `automatic_tax`。生产环境应把 Stripe restricted key 和 Webhook signing secret 放入云平台的密钥管理服务，并限制密钥权限和来源 IP，不要放进镜像或仓库。 +网关 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 保存权限时可能要求账户持有人完成二次验证。 + +后台已覆盖 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。 静态模式的上游 Base URL 与 API Key 分别使用 `base_url_env` 和 `api_key_env`；控制面、Redis、Stripe、SMTP、WebAuthn 和监听地址同样只通过环境变量或密钥管理服务注入。严格 JSON 解析会拒绝旧的 `address`、`base_url`、`success_url` 和 `cancel_url` 字面量字段，避免环境隔离被配置文件绕过。版本化配置只保存 `*_env` 名称，不保存外部服务密钥或部署域名。 @@ -177,6 +181,8 @@ Webhook 至少订阅： ```bash AIGW_DATABASE_URL="postgres://..." go run ./cmd/migrate +# 查看当前迁移版本和 checksum +AIGW_DATABASE_URL="postgres://..." go run ./cmd/migrate -status ``` 管理 API 支持账号密码、TOTP、Passkey 会话和仅用于初始化/故障恢复的 bootstrap token。即使已经启用 RBAC，生产环境仍应设置 HTTPS、把推理端口和管理端口分离、按需关闭公开注册，并把 bootstrap token 存入密钥管理服务；企业部署可再接 OIDC/SAML 与强制 MFA 策略。 @@ -187,5 +193,9 @@ AIGW_DATABASE_URL="postgres://..." go run ./cmd/migrate ```bash go test ./... +go test -race ./... go vet ./... +CGO_ENABLED=0 go build -buildvcs=false ./cmd/... ``` + +设置 `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`。 |