ai-gateway-go/docs/旗舰版需求规划与完成情况.md

AI Gateway Go — 旗舰版(Ultra)需求规划与实现情况报告

• 报告日期: 2026-08-12
• 工程: AI Gateway 全量 Go 重构(替代原 Python/FastAPI 网关)
• 活跃工作树: /home/ben/ai-gateway-src/ai-gateway-go-deploy-0.10.0
• 当前版本: 0.10.0(Go 1.26,PostgreSQL 17+pgvector + 双 Redis + MinIO + Ollama,28 个迁移)

---

一、项目现状概览

项	状态
部署形态	Docker Compose(项目名 deploy),gateway-api :8080 / admin-web :8081 / portal-web :8082
数据层	PostgreSQL 17 + pgvector(权威配置 + 审计分区 + 向量列)+ critical/cache 双 Redis + MinIO + Ollama;28 个迁移已应用
迁移	000001…000028(含资源市场 000022、MinIO 000023、pgvector 000024、站内消息 000025、定时任务 000026、LLM Trace 000027、智能体节点 000028)
验证	go build ./...、go vet ./...、全套单测及资源市场/文件/向量/站内信/调度器/Trace/节点真实库集成测试 全部通过
前端	Art Design Pro 管理端 + 门户端,已构建进镜像并运行
版本控制	git(remote origin=Gitea superidou/ai-gateway-go),功能按阶段提交；推送由发布流程执行

---

二、已完成里程碑(M0–M8)

M0 工程基线

Go 1.26 模块、配置校验、结构化日志、优雅退出;pgx 连接池、双 Redis 客户端;带校验和/事务/advisory lock 的独立迁移器;OpenAI 兼容入口、bootstrap key、请求体限制、SSE 透传;healthz/readyz/Prometheus;outbox/API Key/Provider/审计分区首版 schema。

M1 身份、Provider 与配置面

管理员/门户用户 + PBKDF2 旧密码兼容升级;可撤销会话/账号锁定;admin/portal 登录、身份、菜单、退出;TOTP 两步验证 + 备用码;API Key 全生命周期 + Redis 即时撤销;Provider AES-256-GCM 凭据 + SSRF 校验 + 事务 outbox + 原子快照/路由/能力约束;KEK 版本化轮换;层级部门 CRUD;OIDC(PKCE/RS256/JWKS)与 SAML 2.0(SP-initiated/断言防重放/自动开户)端到端通过。

M2 流量治理与路由

API Key 级 RPM + UTC 月请求配额 + Token 配额(请求前预留、usage 回写校准),Redis Lua 原子准入,429/Retry-After/X-RateLimit-*;Provider 超时/退避/熔断(幂等安全重试);模型别名条件路由(确定性加权 + 失败关闭 + X-Gateway-Model);Art 管理端限流/路由页面。

M3 审计、usage、内容策略与成本

有界异步审计批量 COPY + 失败保留 + 优雅停机;按日 usage 聚合;audit/usage 权限隔离查询;outbox-worker(SKIP LOCKED 多实例 + Redis Stream 原子去重 + 死信重试);审计月分区维护(advisory lock 防多实例重复);内容策略(RE2 不可变快照,audit/block/redact,默认脱敏);时间版本模型定价 + 按日成本核算;Art 审计/用量/内容策略/定价页面。

M4 Prompt、知识、工具、应用编排和通知

Prompt 分类/模板/不可变版本/必填校验;知识库(2 MiB 有界正文、段落感知重叠分块、FTS+中文二元词片检索、Retriever 接口);声明式 HTTP 工具(JSON Schema 校验、KEK 加密头、双层 SSRF、禁止重定向、1 MiB 响应限制);AI 应用草稿 + 不可发布版本 → /v1/applications/{code}/chat/completions(仍过鉴权/配额/内容策略/路由/成本/审计);通知 worker(HMAC-SHA256 Webhook、精确/通配事件、失败重试)。

M5 契约、迁移与切换工程

旧 Python 网关 38 个持久化实体数据字典;确定性 UUIDv5 旧 ID 映射;201 条旧路由全覆盖/替代/退役决策,未决契约缺口为 0;OpenAPI 0.10.0 覆盖全部 Go 路由;legacy 导入工具 + cutover runbook + 路由契约矩阵 + 校验脚本。

M6 门户工作台与扩展治理

门户资产目录、Prompt 查看/搜索/收藏、个人审计/Token/成本统计、接入说明、模型访问申请与管理员审批;事实核验(复用 Provider 凭据 + 作用域策略 + 事件契约);已发布应用门户单轮入口 + 服务端托管会话(独立 AEAD purpose 加密凭证、串行租约、SHA-256 哈希链、最多 200 条);Compose 同时交付 API/管理端 8081/门户端 8082。

M7 旗舰版资源市场(本次新增)

三类可发布资产 MCP 服务器 / Skills / 数字员工 + 共享分类与标签 + 市场安装(工作区绑定 + 权限):

• 数据层:6 张表(marketplace_categories / mcp_servers / skills / digital_employees / digital_employee_runs / marketplace_installations)
• 后端:管理端 CRUD + 在线编辑/发布(admin_marketplace.go);统一市场目录合并查询(marketplace.go);运行时渲染 skill、列出/调用 MCP 工具、运行数字员工(含知识检索 + 工具执行 + 访问控制,runtime_marketplace.go);MCP 客户端(SSE + JSON-RPC 工具发现/调用/缓存,mcp_client.go)
• 前端:管理端 4 页(市场总览 / MCP 服务器 / Skills / 数字员工)+ 门户资源市场页
• 测试:TestMarketplaceLifecycle / TestWorkbenchPostgreSQLLifecycle 连真实 PostgreSQL 通过

M8 基础设施层

MinIO 对象存储与管理端/个人文件仓库；pgvector + Ollama(bge-m3) 向量化与 vector/hybrid 检索；可靠站内消息、管理员广播、未读回执；独立定时任务 worker，支持标准五字段 Cron、时区、应用/数字员工目标、Skills/MCP 子集、会话上下文、指定通知通道、立即执行、启停和执行历史。调度队列使用 PostgreSQL SKIP LOCKED 租约、超时回收和有限重试，多副本安全。

M9 智能体与可观测（P1/P2/P3/P4）

应用/数字员工请求可追踪到模型、知识检索、工具/MCP span；管理端提供元数据 Trace 查询和详情时间线，并按会话聚合普通应用/数字员工请求；新增智能体节点登记、令牌轮换、心跳监控和只读节点池路由预览，配套 trace:read、agent_node:read/manage 权限。当前仍待补齐远程安装、任务下发/真实节点执行路由与 AI 助手。

---

三、旗舰版(Ultra)功能矩阵对照

状态图例:✅ 已完成 | ⚠️ 部分覆盖 | ❌ 未实现

管理平台

功能模块	功能	社区 Free	专业 Pro	旗舰 Ultra	当前状态
管理平台	AI 助手:通过 AI 助手查看平台信息和权限控制	—	✓	✓	❌
管理平台	收藏:常用功能收藏	✓	✓	✓	❌
管理平台	概览:平台总览与基础看板	—	✓	✓	⚠️ 仅有 24h 监控汇总(monitoring/overview),非完整看板
管理平台	数据报表:token/工具/渠道/审批授权/安全事件汇总统计	—	✓	✓	❌(仅有 usage/stats 单维)
资源市场	自定义 MCP/Skills/数字员工资源	✓	✓	✓	✅ M7
资源市场	在线编辑和发布 MCP/Skills/数字员工	不支持	✓	✓	✅ 管理端 CRUD + publish 路由
资源市场	资源分类管理和标签管理	✓	✓	✓	✅ marketplace_categories
配置管理	平台配置敏感参数,skill/mcp 运行时动态注入环境变量	—	✓	✓	❌
智能体管理	智能体节点:运行监控/动态创建/裸机安装/节点池分配/公有私有池路由	—	✓	✓	⚠️ M9 P4：节点登记、令牌轮换、心跳、能力候选和只读稳定选路预览；远程安装/任务下发/真实执行路由待补齐
智能体管理	LLMTrace:会话中大模型调用、工具调用执行性能跟踪	—	✓	✓	✅ M9 P1：应用/数字员工 Trace + model/retrieval/tool span + 管理端查询
智能体管理	智能体会话:会话列表,区分普通会话与数字员工会话	—	✓	✓	✅ M9 P2：基于 Trace 元数据聚合会话，区分 application/digital_employee
模型管理	对接国内外主流大模型供应商	✓	✓	✓	✅ providers + 模型目录同步
模型管理	供应商中添加配置大模型	✓	✓	✓	✅
模型管理	对接本地模型(Ollama/vLLM)	不支持	✓	✓	✅ 走 OpenAI 兼容通用 provider
模型管理	不同大模型 Token 配额、使用量统计	不支持	✓	✓	✅ quota + usage 聚合
模型管理	大模型使用权限分级管控(用户/角色)	✓	✓	✓	✅ RBAC scope
知识库	外部文档导入、自动切分、向量化、语义匹配召回	—	✓	✓	✅ M8 P2:pgvector + 本地 Ollama bge-m3,vector/hybrid 三态,导入即同步向量化(失败自动降级 FTS)
记忆管理	记忆集合:个人/部门/全局多层记忆,提炼与语义匹配召回	—	✓	✓	❌
记忆管理	根据调用自动裁剪衰减片段	—	✓	✓	❌
记忆管理	记忆授权:提炼内容/沉淀经验授权给其他用户	—	✓	✓	❌
权限管理	完整 RBAC 角色权限管理	不支持	✓	✓	✅
权限管理	用户/部门/角色管理	✓	✓	✓	✅
权限管理	系统历史操作审计日志	—	✓	✓	✅ admin/audit-events
权限管理	资源(mcp/skills/数字员工)权限管控、资源授权	✓	✓	✓	✅ marketplace 访问控制
权限管理	资源/大模型/渠道使用申请审批	—	✓	✓	⚠️ 仅模型申请审批(model-requests);资源安装/渠道无审批流
API 集成	API Key 调用大模型/mcp/skills 组合或数字员工	—	✓	✓	✅ API Key + runtime marketplace
渠道管理	Web 聊天界面	✓	✓	✓	✅ portal
渠道管理	企业微信/个人微信/钉钉/飞书渠道	✓	✓	✓	❌
渠道管理	渠道权限管控、使用权限授权(用户/角色)	✓	✓	✓	❌
渠道管理	多渠道治理、审计、使用量统计	✓	✓	✓	❌
安装部署	x86_64 安装包	✓	✓	✓	⚠️ Docker Compose 交付,非传统安装包
安装部署	ARM64 安装包	—	✓	✓	❌
部署方式	单机 / 冷备 / 集群	单机	单机/冷备	单机/冷备/集群	⚠️ outbox 支持多实例 SKIP LOCKED(集群一部分);冷备/完整集群方案未做
租户管理	单租户使用	✓	✓	✓	✅
租户管理	平台管理员多租户管理	—	—	✓	❌
安全策略	运行时安全:网络/工具命令执行安全校验审批/工具调用频率限制	—	✓	✓	⚠️ 工具 SSRF/拨号防护 ✅;命令执行审批、工具限流 ❌
安全策略	供应链安全:skill/mcp 资源安全扫描	—	✓	✓	❌
安全策略	数据安全:工具数据输入输出脱敏 + 大模型回答隐私敏感信息拦截替换	—	✓	✓	⚠️ 提示词输入脱敏 ✅;工具输出/回答拦截替换 ❌
站内消息	平台推送站内消息与动态	—	✓	✓	✅ M8 P4:outbox 事件由通知 worker 物化为站内消息(幂等),admin 广播 + admin/portal 收件箱 + 已读回执 + 未读徽标
审批授权	资源/模型/渠道使用申请流程审批管理	—	✓	✓	⚠️ 仅模型申请
文件管理	平台文件资源与对象存储文件浏览管理	—	✓	✓	✅(M8 MinIO 已上线,admin 文件管理)
审计日志	系统全量历史操作审计日志查询	—	✓	✓	✅
企业报表	企业级运营数据报表统计分析	—	✓	✓	❌
License	平台 License 授权管理与有效期管控	✓	✓	✓	❌

工作台

功能	功能说明	当前状态
聊天	新建会话、授权大模型对话	✅
聊天	删除会话、会话重命名	✅
定时任务	创建定时任务(配置提示词/渠道/mcp/skills/数字员工/会话ID)	✅ M8 P3：应用/数字员工目标、Skills/MCP 子集、会话 ID、通知通道、加密 API Key
定时任务	启动/修改/立即执行/删除定时任务配置	✅ 标准五字段 Cron + IANA 时区，支持启停、编辑、手动入队和删除
定时任务	查看定时任务执行历史	✅ 成功/失败状态、重试次数、响应与错误历史
个人渠道	配置个人微信/企业微信/钉钉/飞书	❌
个人渠道	个人微信/企业微信快速扫码对接	❌
个人渠道	绑定特定大模型执行对话	❌
我的资源	查看被授权资源(mcp/skills/数字员工)详细信息	✅ portal/marketplace
我的资源	从被授权数字员工进入会话	⚠️ runtime 可跑,无会话列表入口
我的资源	通过权限申请从插件市场安装 MCP/Skills/数字员工	✅ marketplace install
我的资源	查看被授权大模型使用量	✅ portal/stats
我的资源	查看插件资源权限等级(可查看/仅使用/管理)	⚠️ 有访问控制,三档等级未成体系
我的资源	申请大模型/token量/skill/mcp/数字员工/渠道权限	⚠️ 仅模型申请
配置管理	个人配置环境变量,供 skill/mcp 使用	❌
个人文件仓库	对话产生的报告/文件存入个人仓库	✅(M8 个人文件仓,经网关上传/下载)
安全策略	个人智能体安全策略(网络/工具命令校验审批/限流/脱敏/隐私拦截)	❌
个人中心	账号信息、密码修改、登录记录查看	✅
消息通知	系统消息、审批待办、任务执行结果提醒	⚠️ 系统事件、模型审批和定时任务结果已支持 Webhook + 站内信；完整审批待办体系待补齐

---

四、差距汇总

• 完全未实现(❌):AI 助手、收藏、数据报表/企业报表、配置管理(env 注入)、智能体节点的远程安装/任务路由、记忆管理三项、渠道管理全项、多租户、供应链安全扫描、完整审批流、License、个人渠道、个人安全策略、ARM64。
• 部分覆盖需补齐(⚠️):平台概览看板、资源/渠道审批、工具输出脱敏与大模型回答拦截替换、工具命令审批与工具限流、完整集群部署方案、审批待办体系、数字员工会话入口、资源权限等级三档、全类型权限申请。

---

五、后续里程碑规划(M8–M13)

里程碑	内容	依赖
M8 基础设施层	对象存储(MinIO)、向量化(pgvector)、定时任务调度器、站内消息	✅ P1–P4 全部完成
M9 智能体与可观测	LLMTrace、智能体会话、智能体节点(监控/节点池/路由)、AI 助手	M8
M10 记忆管理	多层记忆集合、语义召回、裁剪衰减、记忆授权	M8(pgvector)
M11 渠道与审批	渠道管理(企业微信/个人微信/钉钉/飞书)、个人渠道、完整审批流、资源权限等级	M8
M12 数据安全与供应链	知识库向量化、输出脱敏/回答拦截、工具命令审批/限流、供应链扫描、个人安全策略	M8(pgvector)
M13 平台运营	数据报表/企业报表、完整看板、收藏、多租户、License、ARM64/集群部署	M8

已建任务跟踪:#4–#9。

---

六、验证情况(当前基线)

• go build ./... ✅、go vet ./... ✅
• 全套单测(全部包)✅;资源市场/文件/向量化/Cron/资源绑定单测✅
• 集成测试 TestMarketplaceLifecycle、TestWorkbenchPostgreSQLLifecycle、TestFileObjectLifecycle、TestKnowledgeVectorLifecycle、TestInboxMaterializeAndBroadcast、TestSchedulerPostgreSQLLifecycle、TestTracePostgreSQLLifecycle 连真实依赖 ✅
• 部署冒烟:healthz/readyz ✅、admin :8081 / portal :8082 302 ✅、28 个迁移应用 ✅、vector 模式知识库语义检索、定时任务执行链路、Trace 存储与节点心跳 ✅

七、部署与已知坑

• 活跃工作树:/home/ben/ai-gateway-src/ai-gateway-go-deploy-0.10.0;compose 项目名 deploy,workdir 在 deploy/ 下。
• 重启恢复:postgres/redis restart 策略为 no,重启后需进 deploy/ 执行 docker compose up -d;若容器 networks 为空需 --force-recreate。
• 旧 Python 网关:llm-gateway.service(systemd)监听 8080 已 systemctl disable,不再开机抢占。
• 本机无 go 工具链:编译/测试用 docker run --rm -v $PWD:/src -w /src -e GOCACHE=/tmp/gocache golang:1.26.5-alpine sh -c 'go build ./...';集成测试加 --network deploy_default + WORKBENCH_TEST_DATABASE_URL=postgres://gateway:gateway@postgres:5432/gateway?sslmode=disable。
• 上线门禁未过:旧库脱敏快照迁移、影子观察、容量验收、切换/回退演练需真实生产数据与授权后方可执行。