LLMGuardX Dev
d534865b33
- 节点任务:管理端向节点池下发(Prompt/HTTP/MCP/Skill/数字员工/自定义), 指定节点或池路由,认领 SKIP LOCKED + 15 分钟租约,认领令牌防重放上报, 失败 30s×次数退避重入队,达上限 failed,支持取消/重试,完成与失败站内信。 - 个人智能体安全策略:auto_approve_tools 跳过个人调用审批门; rate_limit_multiplier 按 (tool,user) 独立窗口放宽个人限流(全局额度不受影响)。 - 修复存量缺陷:/v1/agent/nodes/ 未挂 publicMux,节点心跳/认领端点在部署 拓扑下不可达。 - 迁移 000046;任务全链路集成测试连真实库通过,HTTP 端到端验证 (下发→认领→伪造令牌拒绝→上报→succeeded,列表不泄露认领令牌); 25 包测试通过,前后端构建通过。
19 KiB
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。 - 上线门禁未过:旧库脱敏快照迁移、影子观察、容量验收、切换/回退演练需真实生产数据与授权后方可执行。
八、0.11.2 完成情况（2026-08-13 第三轮完善）
| 功能 | 状态 | 说明 |
|---|---|---|
| 通用聊天 UI | ✅ | 门户「通用聊天」：选模型直接对话、会话管理、审批通过后自动开通用户级 Key |
| 企微/钉钉/飞书扫码登录 | ✅ | 身份源配置 + 登录页扫码 + 账号安全绑定/解绑 + 自动开户开关 |
| 个人安全策略 | ✅ | 登录设备管理/吊销、新设备登录提醒开关、登录通知站内信(security 类别) |
剩余依赖外部条件项（已有代码骨架，需真实企业凭据/数据后方可端到端验收）：
- 扫码登录与渠道(企微/钉钉/飞书)真实平台联调：协议实现已单测覆盖（mock 平台端点）， 需企业开放平台应用凭据完成冒烟。
- 多租户数据隔离重构：当前以部门(tenant_id)为租户维度，跨租户物理隔离（独立 schema/库） 需明确部署形态后实施。
九、0.11.3 完成情况（2026-08-13 第四轮完善）
| 功能 | 状态 | 说明 |
|---|---|---|
| 统一审批中心 | ✅ | 模型/资源/渠道/工具四类申请统一审批,通过自动开通,双向站内信 |
| 工具治理 | ✅ | 工具限流(RPM 固定窗口)+ 审批标记,端到端验证 |
| 平台环境变量 | ✅ | 平台级注入,个人可覆盖 |
| 数字员工会话入口 | ✅ | 门户列表/对话/调用记录 |
| 个人渠道 | ✅ | 个人 Webhook 渠道绑定已批准模型,令牌轮换 |
| 报表多维统计 | ✅ | 工具/审批/安全事件维度 |
| 租户配额 | ✅ | 部门 Key/月 Token 上限 + 概览展示 |
剩余依赖外部条件项:
- 企微/钉钉/飞书真实平台联调(扫码登录与渠道):协议已实现且单测覆盖, 需企业开放平台应用凭据完成冒烟。
- 多租户物理隔离(独立 schema/库):当前以部门(tenant_id)为租户维度的 逻辑隔离 + 配额管控已完成,物理隔离需明确部署形态后实施。
- 智能体节点远程安装/任务下发:节点登记/心跳/路由预览已完成,远程安装 与真实节点执行需部署 Agent 环境后验收。
十、0.11.4 完成情况（2026-08-13 第五轮完善）
| 功能 | 状态 | 说明 |
|---|---|---|
| 智能体节点任务下发 | ✅ | 池路由认领(SKIP LOCKED)/认领令牌上报/退避重试/取消/失败重试/管理端页面/站内信 |
| 个人智能体安全策略 | ✅ | 个人工具自动审批 + 个人限流倍数,运行时即时生效 |
至此旗舰版矩阵中可独立实施的功能已全部完成。剩余依赖外部条件项:
- 企微/钉钉/飞书真实平台联调(扫码登录与渠道):协议实现 + 单测覆盖, 需企业开放平台应用凭据冒烟。
- 多租户物理隔离(独立 schema/库):逻辑隔离(tenant_id)与配额管控已完成, 物理隔离需明确部署形态。
- 智能体节点远程安装/裸机部署脚本:任务下发与执行协议已就绪并端到端验证, 节点 Agent 安装包/注册脚本需在目标环境实施。