diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 26 |
1 files changed, 19 insertions, 7 deletions
@@ -18,7 +18,9 @@ AIGW 是一个轻量、无状态的 AI API 中转后端。当前阶段聚焦上 - PostgreSQL 预付余额、请求额度冻结、实际 token 结算和不可变账本 - Stripe 托管 Checkout 充值、签名 Webhook 与事件/订单双重幂等 - PostgreSQL Usage Ledger、月度项目汇总和单请求成本追溯 -- 注册/登录账号、数据库会话、CSRF 防护、六种 RBAC 角色和管理 API 审计日志 +- 邮箱验证、邀请注册、密码重置、登录限流、可撤销设备会话和管理 API 审计日志 +- TOTP（含一次性恢复码）与 WebAuthn Passkey 注册、二次验证和无密码登录 +- 六种 RBAC 角色、租户数据隔离和 CSRF 防护 - 项目级 RPM、估算 TPM、并发限制和月度消费配额 ## 快速运行 @@ -28,7 +30,10 @@ AIGW 是一个轻量、无状态的 AI API 中转后端。当前阶段聚焦上 ```bash cp config.example.json config.json export AIGW_API_KEYS='[{"key":"sk-local-change-me","key_id":"local-key","tenant_id":"tenant-demo","project_id":"project-default","scopes":["inference"]}]' +export AIGW_SERVER_ADDRESS=':8080' +export OPENAI_BASE_URL='https://api.openai.com/v1' export OPENAI_API_KEY='your-upstream-key' +export ANTHROPIC_BASE_URL='https://api.anthropic.com/v1' export ANTHROPIC_API_KEY='your-upstream-key' go run ./cmd/aigw -config config.json ``` @@ -43,6 +48,8 @@ go run ./cmd/mockupstream # terminal 2 export MOCK_UPSTREAM_KEY='local-only' +export MOCK_UPSTREAM_BASE_URL='http://127.0.0.1:18080/v1' +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.local.json ``` @@ -109,17 +116,19 @@ curl http://127.0.0.1:8080/anthropic/v1/messages \ ./scripts/start-debug.sh ``` -脚本会首次生成仅当前用户可读的 `.env.debug`，构建并等待 PostgreSQL、Redis 和网关健康，然后打印后台地址和管理员 token。关闭调试服务： +脚本会首次生成仅当前用户可读的 `.env.debug`，其中包括随机 PostgreSQL 密码、凭证加密密钥和 bootstrap token；同时启动 Mailpit 作为本地 SMTP 收件箱。构建并等待 PostgreSQL、Redis 和网关健康后只打印后台与 Mailpit 地址和环境文件位置，不把密钥回显到终端。关闭调试服务： ```bash ./scripts/stop-debug.sh ``` -关闭脚本保留 PostgreSQL/Redis 数据卷，下一次启动仍可继续使用已有控制面数据。需要测试 Stripe Checkout 时，先把 `.env.debug` 中两个 Stripe 占位值替换成测试环境 restricted key 和 Webhook signing secret。 +关闭脚本保留 PostgreSQL/Redis 数据卷，下一次启动仍可继续使用已有控制面数据。需要测试 Stripe Checkout 时，把 `.env.debug` 中的 restricted key、Webhook signing secret、成功 URL 和取消 URL 设置为对应环境的值。JSON 配置只保存环境变量名称，不保存外部服务 URL 或密钥。 源码未变化时可跳过镜像构建以快速重启：`AIGW_DEBUG_SKIP_BUILD=1 ./scripts/start-debug.sh`。默认构建使用 Docker host network；特殊环境可以通过 `AIGW_DOCKER_BUILD_NETWORK=default` 覆盖。 -然后打开 `http://127.0.0.1:8080/admin/`。启用注册时，首次用户可直接创建组织和租户管理员账号；平台管理员也可以在 Operator 页面使用脚本打印的 `AIGW_ADMIN_TOKEN` 作为 bootstrap/break-glass 凭证。日常操作使用邮箱/密码登录，服务端创建可撤销的数据库会话，所有写请求需要 CSRF token。第一套资源的创建顺序是：Tenant → Project → API key → Provider → Model route。客户 API Key 明文只在创建成功时返回一次；团队成员使用自己的账号，不共享管理员令牌。 +然后打开 `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 明文只在创建成功时返回一次；团队成员使用自己的账号，不共享管理员令牌。 + +账号邮件先在 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。 控制台角色分为：`platform_admin`、`platform_viewer`、`tenant_admin`、`tenant_billing`、`tenant_developer`、`tenant_viewer`。租户角色的查询条件在服务端下推到 PostgreSQL，不能读取其他租户的项目、密钥、余额、Usage 或审计事件；供应商凭证和路由管理只对平台角色开放。 @@ -147,8 +156,9 @@ Stripe 使用托管 Checkout，服务端不会接触卡号，也没有硬编码 ```bash 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 --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:8080/billing/stripe/webhook docker compose up --build ``` @@ -161,15 +171,17 @@ Webhook 至少订阅： 当前没有默认启用 Stripe Tax，因为是否有有效税务注册不能由代码推断。确认注册和税务处理方案后再显式加入 `automatic_tax`。生产环境应把 Stripe restricted key 和 Webhook signing secret 放入云平台的密钥管理服务，并限制密钥权限和来源 IP，不要放进镜像或仓库。 +静态模式的上游 Base URL 与 API Key 分别使用 `base_url_env` 和 `api_key_env`；控制面、Redis、Stripe、SMTP、WebAuthn 和监听地址同样只通过环境变量或密钥管理服务注入。严格 JSON 解析会拒绝旧的 `address`、`base_url`、`success_url` 和 `cancel_url` 字面量字段，避免环境隔离被配置文件绕过。版本化配置只保存 `*_env` 名称，不保存外部服务密钥或部署域名。 + 生产环境建议把 `auto_migrate` 改为 `false`，先执行： ```bash AIGW_DATABASE_URL="postgres://..." go run ./cmd/migrate ``` -管理 API 支持账号密码会话和仅用于初始化/故障恢复的 bootstrap token。即使已经启用 RBAC，管理监听端口仍应放在内网、VPN 或身份感知反向代理后；生产环境应关闭公开注册、设置 HTTPS、配置 MFA/OIDC，并把 bootstrap token 存入密钥管理服务。 +管理 API 支持账号密码、TOTP、Passkey 会话和仅用于初始化/故障恢复的 bootstrap token。即使已经启用 RBAC，生产环境仍应设置 HTTPS、把推理端口和管理端口分离、按需关闭公开注册，并把 bootstrap token 存入密钥管理服务；企业部署可再接 OIDC/SAML 与强制 MFA 策略。 -完整的扩展边界见 [架构说明](docs/architecture.md)。 +完整的扩展边界见 [架构说明](docs/architecture.md)，与 ZenMux 模型目录对照后的上线缺口见 [商业化就绪清单](docs/commercial-readiness.md)。 ## 验证 |