# 重构进度 更新时间：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。 工程实现与本地生产等价验证已关闭。正式上线仍是外部发布门禁：拿到实际旧数据库脱敏快照和旧密钥迁移授权后执行领域转换，并在真实新旧双系统与生产等价流量下完成影子观察、容量验收及切换/回退演练；这些动作不会在缺少生产数据和授权时伪造为已执行。 ## 已完成：M8 基础设施层（P1 对象存储与文件管理） - 自托管 MinIO 对象存储入基线：`internal/platform/storage`（minio-go 适配层）剥离 scheme 推导 Secure，领域层不直接依赖 S3 客户端；`S3_*` 配置默认值 + Validate（1–512 MiB 上限、endpoint 无路径）。迁移 `000023` 建 `gateway.file_objects`（uuid/object_key 唯一/sha256/scope/owner 校验 + 部分索引）。 - 文件上传/下载全部经网关代理（MinIO 不暴露主机端口）：流式 multipart 上传（`http.MaxBytesReader` + `LimitReader` 超限即拒），`PutObject` 成功后才插元数据行、失败回滚对象；下载 io.Copy 流式 + RFC 5987 `filename*`；删除先删行再 best-effort 清对象（避免孤儿阻塞删除）。 - `FileService` 个人/系统双范围：admin 文件管理（`file:read|manage` RBAC + 管理端文件管理页）与 portal 个人文件仓（严格归属隔离，跨用户读返回 404）。 - Compose（dev + production）新增 `minio` 服务与 `minio-data` 卷；nginx `client_max_body_size` 32m→256m 盖过 128 MiB 上传上限；`.env.example` / `production.env.example` 补 `S3_*`。 - 端到端验证：上传→列表→下载往返一致→删除后桶无孤儿；admin 读 portal 文件 404；`TestFileObjectLifecycle` 集成测试连真实 MinIO+PostgreSQL 通过；`go build ./...`、`go vet ./...`、全量单测通过。 - 管理端"文件管理"与门户端"文件仓库"菜单由服务端动态菜单下发。 ## 已完成：M8 基础设施层（P2 向量化与语义检索） - PostgreSQL 换 `pgvector/pgvector:pg17` 镜像（数据卷兼容，先备份再切换）；迁移 `000024` `CREATE EXTENSION vector`、`knowledge_chunks.embedding vector(1024)` 列 + HNSW 余弦索引，并把 `retrieval_mode` CHECK 放宽为 `('postgres_fts','vector','hybrid')` 三态。 - 本地 Ollama（`bge-m3`，1024 维）生成嵌入，Compose 新增 `ollama` 服务与 `ollama-models` 卷；`OllamaEmbedder` 批量调 `/api/embed`，首见 404 惰性 `/api/pull` 重试一次，按批校验维度，超时 `EMBEDDING_TIMEOUT`；`EMBEDDINGS_ENABLED=false` 可整体关闭。 - `SemanticRetriever`（`embedding <=> $1::vector` 余弦距离 + `embedding IS NOT NULL` 过滤）与 `HybridRetriever`（FTS + 语义按 chunk 去重融合）实现；`NewRetriever(service, embedder)` 按知识库 `retrieval_mode` 分发，embedder 为 nil 时自动回退纯 FTS（不因缺少 Ollama 而报错）。 - 文档入库/重新分块时在 vector/hybrid 模式下同步批量计算向量（每文档一次 `/api/embed` 收数组）；Ollama 故障时优雅降级：文档照常入库、embedding 置 NULL，并在事务内发 `knowledge_document.embedding_failed` 事件。 - 踩坑并修复：pgx v5 `CopyFrom` 对未知 OID（vector）列走二进制编码，字面量随 COPY 上传会被 `vector_recv` 误读为维度数而报 `vector cannot have more than 16000 dimensions`；改为 COPY 仅基础列，随后在同一事务内用 `UPDATE ... FROM unnest($1::uuid[], $2::text[])` 批量回填向量，避免 2 MiB 文档上千条逐条 INSERT。 - 知识库列表新增 `vectorized_chunk_count`（`count(c.embedding)`），管理端展示"已向量化切片/总切片"覆盖率；创建/编辑知识库可三态选择检索模式，未向量化分块需重新处理才被语义召回。 - `EMBEDDINGS_*` 配置（`OLLAMA_BASE_URL` 默认 `http://ollama:11434`、`EMBEDDING_MODEL` bge-m3、`EMBEDDING_DIM` 须与 `vector(1024)` 一致、批大小、超时）写入两个 `.env.example` 与 compose anchor。 - 单测 `embedder_test.go`/`retrievers_test.go`（httptest 假 Ollama：批量切分、维度不符、404→pull→重试、降级分发）与集成 `TestKnowledgeVectorLifecycle`（真 pgvector+Ollama：导入即向量化、语义命中、embedder 失败时入库 + `embedding_failed` 事件）全部通过；`go build ./...`、`go vet ./...` 通过。