GoWind Admin风行 — 开箱即用的企业级全栈中后台框架AI 模块当接个大模型成为每个管理系统的标配需求多数团队的选择是在业务代码里散落一堆 SDK 调用密钥写死在配置文件、用量没人记账、租户之间无隔离、换一家模型供应商就要发版。风行GoWind Admin把 AI 当作平台的一等公民模块来做提供商是数据不是配置、对话走流式推送、用量进配额体系、知识库 RAG 开箱即用甚至自然语言问数也带四重安全护栏。本文带你完整过一遍这套 AI 能力的设计与实践。一、能力全景五个子域一张图看懂能力入口一句话说明模型提供商管理页「AI 提供商」一行 一个 OpenAI 兼容端点云端 API 或本地 Ollamaapi_key 加密落库流式对话分析页 → AI 助手SSE 实时推送增量 token同步响应携带完整回复知识库 RAG管理页「知识库」文档切片 → 向量化pgvector→ 检索注入对话上下文智能问数AI 助手 → 智能问数自然语言 → 只读 SQL → 结果表格 自然语言结论用量配额套餐配额AI_TOKENS每次调用记账月度配额超限拒绝安全与异常洞察分析页卡片规则预筛审计明细LLM 只写总评两张核心设计思路贯穿始终模型接入与业务解耦——提供商是数据库里的一行记录不是application.yaml里的一段配置。接 DeepSeek、通义还是本地 Ollama管理页新建一条即可业务零改动。告警/分析只产出结构化事实——文案归前端 i18n模型只生成指定部分多语言界面永远一致。二、模型提供商一次配置处处可用管理页「AI 提供商」新建一条记录就是接入一个模型云端模型填 OpenAI 兼容baseUrlapiKeyDeepSeek、通义等主流厂商均兼容本地模型填 Ollama 主机端口即可key 留空——政企/等保场景数据不出内网的关键api_key AES-GCM 加密落库读视图只有脱敏后的apiKeyHint更新时留空 不修改已存 Key勾选「默认提供商」后聊天与定时任务在未指定时都用它。// 后端内部链路脚本 ai 模块、定时任务、洞察共用同一条// provider 解析 → 密钥解密 → 客户端工厂链路不存在第二套接入逻辑三、流式对话SSE 推送的工程细节POST /admin/v1/ai/chat/completions是一个普通 POST同步返回完整回复生成过程中的增量 token 则通过 SSE 网关独立 :7789 端口以ai_chat_chunk事件实时推给发起用户前端逐帧渲染 markdown。几个值得抄走的工程决策chunk 是尽力而为SSE 缓冲满即丢帧TryPublish以 POST 同步响应为最终事实——推送从不阻塞主链路流式时长由 context deadline 控制5 分钟而不是http.Client.Timeout——后者会把长回复腰斩在 30 秒对话归属用户删除会话级联删除消息ASSISTANT 消息行带 tokens/耗时快照与用量流水互相印证。四、知识库 RAGpgvector 全链路链路上传纯文本或文件txt/md/docx/pdf后端抽取文本上限 10MB→ 切片500 字符/片50 重叠→ 调 provider 端点的 OpenAI 兼容/v1/embeddings批量向量化 → 落库 → 检索pgvector 余弦距离 topK→ chat 携带knowledgeBaseId时把命中片段注入 system 消息。部署侧只有一件事要做Postgres 换成pgvector/pgvector:pg16镜像。服务启动时自动CREATE EXTENSION IF NOT EXISTS vector并补列失败仅降级 RAG其余功能不受影响。规模化的后手也已备好切片表过 1 万行后启动迁移自动建 HNSW 索引并放开迭代扫描到十万级再建议把向量负载迁出主 OLTP 库——DSN 级部署改动无需改代码。换 embedding 模型「任务管理」创建ai_doc_reindex任务全量重算切片向量业务无感。五、智能问数自然语言查库四重护栏兜底「智能问数」是风行的特色能力自然语言提问 → LLM 生成只读 SQL → 只读事务执行 → 结果表格 可选自然语言结论。支持多轮追问“那只看 admin 的”、“换成按天分组”每轮 SQL 仍全量过检只读语句仅SELECT/WITH开头INSERT/UPDATE/DELETE/DROP、危险函数、多语句、SQL 注释一律拒绝表白名单FROM/JOIN涉及的每张表逐一对照白名单——租户用户只能查 6 张本租户数据表平台级表租户表、套餐表不可见租户谓词强制租户生成的 SQL 必须自带tenant_id 自身ID缺失即拒绝fail-closedLIMIT 钳制 只读事务缺失补 100、超限改写数据库层READ ONLY事务兜底。六、用量配额AI 消耗进 SaaS 计费体系每次成功调用对话、embedding、问数全部口径写入sys_ai_usage_logs用量流水按月聚合对照套餐配额AI_TOKENS超限返回 400未配置该维度 不限量平台管理员tenant_id0跳过检查租户能否用 AI由套餐模块白名单统一控制——套餐管理里勾选AI模块即可开通/停用一个租户的 AI 能力这就是 SaaS 化运营的商业开关。配合「用量统计」页摘要卡 流水列表同口径租户管理员对自己这个月的 token 消耗一目了然。七、安全与异常洞察规则筛事实模型只写总评分析页的「AI 安全与异常洞察」卡片思路是告警必须是确定性事实信号24h 窗口严重度规则疑似口令尝试HIGH单账号登录失败 ≥3 次非常规时段操作MEDIUM本地 0-6 点的操作操作失败集中MEDIUM单用户失败操作 ≥3 次敏感操作LOWDELETE/EXPORT/ASSIGN 明细规则预筛审计明细、输出结构化告警LLM 只生成总体评估措辞无告警时不调模型——既不浪费 token也不给模型编造异常的机会。后端只回结构化事实severity/type/facts告警标题与明细由前端 i18n 模板按界面语言渲染。八、集成到业务脚本与定时任务AI 能力不止于页面两条集成路径让它长进业务里脚本里调模型脚本JS/Lua内置ai模块——ai.chat(content)/ai.chatWith(providerId, content)。实体钩子、定时脚本里都能用例如user.after_create自动生成欢迎语每次调用自动记用量定时 AI 任务内置ai_audit_digest系统常驻任务每日 08:00聚合昨日操作审计生成中文日报并站内信投递自定义 AI 批处理任务可照此模式注册新的任务类型。九、本地开发与演示无真实 key 也能全链路开发仓库自带的 mock LLM 服务OpenAI 兼容echo 对话 可断言 embeddings可替代真实模型打通全部链路生产环境在管理页配置真实 provider 即可切换。结语把 AI 做成平台模块而不是业务代码里的胶水调用意味着换模型不发版、用量可审计、租户可管控、数据可出域也可不出域本地 Ollama。这套路由密钥管理 → 流式对话 → RAG → 配额计费的完整链路全部开箱即用。项目地址https://github.com/tx7do/go-wind-admin / https://gitee.com/tx7do/go-wind-admin在线演示https://demo.admin.gowind.cloud前端/ https://api.demo.admin.gowind.cloud/docs/后端 Swagger