AI Gateway Go 0.10.0 源码快照 + 旗舰版需求规划报告
M0-M7 已完成:核心网关(身份/RBAC/TOTP/OIDC/SAML/Provider/配额/路由/内容策略/审计/定价)+ 资源市场(MCP/Skills/数字员工)。 含 22 个 PostgreSQL 迁移、管理端/门户端前端源码、OpenAPI 契约、部署 compose。 Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,115 @@
|
||||
# 重构进度
|
||||
|
||||
更新时间：2026-08-11
|
||||
|
||||
## 已完成：M0 工程基线
|
||||
|
||||
- Go 1.26 模块、配置校验、结构化日志和优雅退出。
|
||||
- PostgreSQL `pgx` 连接池、critical/cache 双 Redis 客户端。
|
||||
- 独立且带校验和、事务和 advisory lock 的数据库迁移器。
|
||||
- OpenAI 兼容入口、bootstrap key 鉴权、请求体限制、连接池和 SSE 透传。
|
||||
- `healthz`、依赖感知 `readyz`、基础 Prometheus 指标。
|
||||
- PostgreSQL outbox、API Key、Provider 与分区审计表的首版 schema。
|
||||
- 不包含 MinIO/S3、ClickHouse 的 Docker Compose 基线。
|
||||
- Art Design Pro v3.0.2 管理端与门户端，已执行官方精简流程并通过生产构建。
|
||||
- OpenAPI 运行时契约和共享 TypeScript 系统客户端起点。
|
||||
|
||||
## 已完成：M1 身份、Provider 与配置面
|
||||
|
||||
已完成：
|
||||
|
||||
- 管理员、门户用户 schema 和独立 bootstrap 命令。
|
||||
- 兼容 Python 版本 60 万轮/旧 12 万轮 PBKDF2-SHA256，并在成功登录时升级旧哈希。
|
||||
- critical Redis 可撤销不透明会话、数据库 active/role 复核、失败次数原子更新和账号锁定。
|
||||
- `/api/v1/admin/*`、`/api/v1/portal/*` 登录、身份、菜单、退出契约。
|
||||
- 管理端与门户端 TOTP 配置、二次登录、停用、备用码重置；含临时挑战令牌、时间步原子防重放和备用码一次性消费。
|
||||
- 两套 Art 登录页已接入动态验证码/备用码，并通过生产构建。
|
||||
- 数据库 API Key 创建、列表、scope、过期、Redis 共享缓存和即时撤销；明文只显示一次，创建/撤销与 outbox 同事务。
|
||||
- Art 管理端 API Key 页面、动态菜单入口及生产构建。
|
||||
- Provider AES-256-GCM 凭据、SSRF 地址校验、revision 和事务 outbox。
|
||||
- Provider 数据库运行时原子快照、默认/显式路由、能力约束、共享连接池、周期刷新和上一有效版本回退。
|
||||
- Art 管理端供应商页面及生产后端权限模式。
|
||||
- Provider 连接测试、模型目录同步、历史模型停用策略和 `provider.models_synced` 事务 outbox。
|
||||
- Art 管理端连接测试、同步结果和模型目录查看交互。
|
||||
- 版本化 KEK keyring、历史密钥解密、Provider 凭据事务轮换和管理端轮换入口。
|
||||
- PostgreSQL 权威 Provider 配置、critical Redis 多实例变更通知、进程内不可变快照与周期兜底刷新。
|
||||
- 管理员/门户账号管理、内置角色、直接权限字符串、权限感知动态菜单和即时数据库复核。
|
||||
- bootstrap API Key 显式关闭开关及兼容入口使用量指标。
|
||||
- 层级部门 CRUD、循环检测、在用停用保护、门户账号部门绑定和部门 outbox。
|
||||
- OIDC 配置面、加密 Client Secret、Authorization Code + PKCE、RS256/JWKS 校验、自动开户和一次性交换码。
|
||||
- SAML 配置面、SP metadata、SP-initiated Redirect/POST 流程、SHA-256+ XML 签名断言校验、RelayState/InResponseTo 绑定、断言防重放、自动开户和部门绑定。
|
||||
- 旧 Python 网关 38 个持久化实体字段字典、实体去向清单、确定性 UUIDv5 生成器和幂等旧 ID 映射表。
|
||||
- SAML 与 OIDC 均已通过 PostgreSQL + Redis + 本地模拟 IdP 的端到端登录、自动开户、一次性交换和重放拦截测试。
|
||||
|
||||
## 已完成：M2 流量治理与路由
|
||||
|
||||
已完成：
|
||||
|
||||
- API Key 级每分钟请求上限和 UTC 自然月请求配额，`0` 明确表示不限制。
|
||||
- critical Redis Lua 原子准入；限流返回 `429`/`Retry-After`/`X-RateLimit-*`，配置限制时 Redis 故障失败关闭。
|
||||
- API Key 限额的 PostgreSQL 权威配置、鉴权缓存传递、Art 管理表单与 OpenAPI 契约。
|
||||
- PostgreSQL + Redis + 模拟上游端到端测试：RPM=2 精确放行 2 次，月配额=3 精确放行 3 次。
|
||||
- API Key UTC 自然月 Token 配额：请求前按输入体积与最大输出预算原子预留，响应结束按上游 usage 原子校准。
|
||||
- OpenAI/Responses/Anthropic 的 JSON 与 SSE usage 增量提取；不缓冲完整流式响应，上游未返回 usage 时按预留预算保守计量。
|
||||
- Art 管理端展示当月 Token 用量并可即时调整 RPM、月请求和月 Token 配额；更新同时清除共享鉴权缓存并写入 outbox。
|
||||
- Provider 级响应头超时、有限指数退避和熔断；仅 GET/HEAD 或携带 `Idempotency-Key` 的可重放请求允许重试，所有阈值均可通过环境变量配置。
|
||||
- PostgreSQL 模型别名/路由规则、事务 outbox、管理 CRUD、Redis 多实例变更通知和进程内不可变路由快照。
|
||||
- 按 endpoint、API Key、tenant 条件匹配；最高优先级分组内使用请求 ID 做确定性加权选择，显式 Provider 作为候选约束。
|
||||
- 已登记的模型别名在条件不匹配、规则停用或显式 Provider 不属于候选集时失败关闭，避免把别名透传到默认上游绕过策略。
|
||||
- 代理在命中规则时改写上游模型并返回 `X-Gateway-Model`；未配置规则时不读取请求体，保持原代理热路径性能。
|
||||
- Art 管理端模型路由页面，可维护别名、上游模型、Provider、权重、优先级、条件和启停状态。
|
||||
|
||||
## 已完成：M3 审计、usage、内容策略与成本
|
||||
|
||||
已完成：
|
||||
|
||||
- 网关调用的有界异步审计队列、批量 PostgreSQL COPY、失败保留/重试、队列满降级和优雅停机排空。
|
||||
- 请求 ID、API Key、tenant、Provider、原始/目标模型、协议、HTTP 状态、延迟及输入/输出 Token 采集。
|
||||
- PostgreSQL 按日 API Key/Provider/模型 usage 聚合，不在请求热路径同步写数据库。
|
||||
- `audit:read`/`usage:read` 权限、筛选查询 API、Art 管理端审计与用量页面。
|
||||
- 审计 accepted/dropped/written/flush failures Prometheus 指标。
|
||||
- 独立 `gateway-outbox-worker`，使用 PostgreSQL `FOR UPDATE SKIP LOCKED` 租约支持多实例并行抢占。
|
||||
- Redis Lua 原子事件 ID 去重与 Stream 写入，数据库确认丢失后重投不会产生重复 Stream 消息。
|
||||
- 指数退避、最大尝试次数、死信状态、`outbox:read`/`outbox:manage` 权限、管理 API 与 Art 人工重试页面。
|
||||
- `event_consumptions` 与业务 handler 共用 PostgreSQL 事务的消费者幂等入口，handler 回滚时消费标记同步回滚。
|
||||
- 独立 `gateway-maintenance` 周期任务，按 UTC 月预创建审计分区，事务迁移 default 分区数据，并按配置直接丢弃完整过期分区、精确清理边界月和长期 usage。
|
||||
- 审计维护使用 PostgreSQL advisory lock 与表级事务锁，多副本启动时仍只有一个实例执行；重复运行保持幂等。
|
||||
- PostgreSQL 内容策略 CRUD、事务 outbox、`content_policy:read/manage` 权限与多实例周期刷新；运行时使用不可变 RE2 编译快照。
|
||||
- 内容策略支持 `audit`、`block`、`redact`，按 endpoint、模型和 API Key 限定范围；只遍历提示词文本字段，不改写工具 schema、图片/Base64 等非文本载荷。
|
||||
- 默认敏感信息脱敏策略、阻断响应、`X-Gateway-Content-Redacted` 响应头，以及不包含原始命中值的审计标签。
|
||||
- Art 管理端内容策略页面，可维护优先级、范围、规则、替换文本和启停状态。
|
||||
- 带生效/失效时间的模型价格版本，支持 Provider + 精确模型或末尾 `*` 前缀，精确规则优先并使用请求时刻选择版本。
|
||||
- 输入/输出价格均以“每百万 Token 的微货币单位”精确存储；usage 完成时核算请求成本，审计与按日聚合均保存 `cost_microunits`。
|
||||
- `pricing:read/manage` 权限、模型价格管理 API/Art 页面，审计与用量页面展示估算成本。
|
||||
|
||||
## 已完成：M4 Prompt、知识、工具、应用编排和通知
|
||||
|
||||
- Prompt 分类/模板和只增不改的版本，显式变量声明、必填/默认值校验、历史版本激活、管理端和 API Key 渲染接口。
|
||||
- PostgreSQL 知识库保存不超过 2 MiB 的提取文本，不依赖 MinIO/S3；段落感知重叠分块，FTS 与中文二元词片混合召回，并通过 `Retriever` 接口隔离未来向量实现。
|
||||
- 声明式 HTTP 工具、基础 JSON Schema 入参验证、KEK 加密请求头、注册及拨号时 SSRF 校验、禁止重定向、1 MiB 响应上限和工具调用记录。
|
||||
- AI 应用草稿、引用完整性校验、不可变发布版本和运行记录；应用入口组合 Prompt/RAG/OpenAI 工具调用循环，内部每个模型请求仍走原网关全治理链路。
|
||||
- 通知通道与可靠投递记录，独立 Worker 消费 outbox，精确/前缀事件订阅、HMAC-SHA256 签名、失败留痕与人工重试。
|
||||
- 内容策略命中由异步审计批处理在同一事务写入 `content_policy.matched` outbox，不在模型请求热路径同步投递 Webhook，也不包含原始敏感命中值。
|
||||
- Art Design Pro 管理端新增 Prompt、知识库、工具、应用和通知五个页面，权限与动态菜单均由服务端控制。
|
||||
- 独立前端多阶段镜像将 Art 管理端生产构建交付给 Nginx，并同源代理管理 API、模型 API、SSE 与健康检查；Compose 可直接启动完整管理面。
|
||||
|
||||
## 已完成：M5 契约、迁移与切换工程
|
||||
|
||||
- 通过 Python AST 自动盘点旧源码，确认实际为 201 个路由装饰器，而不是早期估算的 141 个；与 OpenAPI 生成可重复的覆盖/替代/退役/缺口矩阵。
|
||||
- 可选影子中间件只复制确定性采样的非流式 JSON POST，使用独立影子 Key，不转发生产凭据；异步比较状态码和 JSON 结构签名并输出 Prometheus 指标。
|
||||
- 独立 `gateway-loadtest` 支持并发、时长、超时、错误率和 p95 阈值，输出机器可读 JSON 并以退出码阻断不达标发布。
|
||||
- 原子 Nginx upstream 切换脚本在目标探活、`nginx -t` 和 reload 任一步失败时恢复备份；提供明确的回退触发条件与演练手册。
|
||||
- 旧 SQLite 只读 JSONL 导出、逐记录 SHA-256、确定性 UUIDv5 和 PostgreSQL 不可变暂存管道已完成；默认排除敏感列，相同快照幂等，旧记录变化失败关闭。
|
||||
- 201 条旧路由已全部形成明确决策：85 条同契约覆盖、112 条由新契约替代、4 条基于安全或架构 ADR 退役、未决缺口 0；OpenAPI 0.10.0 覆盖全部 146 条 Go 字面量路由。
|
||||
|
||||
## 已完成：M6 门户工作台与扩展治理
|
||||
|
||||
- 门户资产目录、Prompt 查看/搜索/收藏、个人审计/Token/成本统计、接入说明和模型访问申请；所有列表按登录用户与部门范围服务端过滤。
|
||||
- 管理端模型申请审批、事实核验 Provider 设置、作用域策略与核验事件页面；事实核验复用 Provider 加密凭据，不重复保存 API Key/Base URL。
|
||||
- 已发布应用的门户单轮入口和服务端托管会话；运行凭证使用独立 AEAD purpose 加密，明文不返回浏览器。
|
||||
- 会话串行租约避免并发回答交错，用户/助手消息以不可变顺序和 SHA-256 哈希链保存，重放前验证完整性，最多 200 条消息。
|
||||
- 应用目录/资产依赖分析、历史版本回滚、知识文档重新分块、Prompt 详情、运行时快照刷新、系统信息和 24 小时监控汇总。
|
||||
- Art Design Pro 管理端新增模型治理页面；门户端新增资产目录、Prompt 广场、个人用量与模型权限四个生产页面。
|
||||
- Compose 同时交付 API、管理端 `8081` 和门户端 `8082`；同一前端 Dockerfile 通过受限 build arg 构建两套独立 SPA。
|
||||
|
||||
工程实现与本地生产等价验证已关闭。正式上线仍是外部发布门禁：拿到实际旧数据库脱敏快照和旧密钥迁移授权后执行领域转换，并在真实新旧双系统与生产等价流量下完成影子观察、容量验收及切换/回退演练；这些动作不会在缺少生产数据和授权时伪造为已执行。
|
||||
Reference in New Issue
Block a user