用 MaxKB 搭一个能进企业微信的知识库问答 Agent：Docker 部署、模型与知识库配置、API 模式机器人接入实操

公司群里总有人问同样的问题：报销流程怎么走、上月的报表在哪、设备坏了找谁。把制度文档丢给一个通用大模型？它不知道你公司的规定，还容易编。MaxKB 是飞致云开源的「Max Knowledge Brain」企业级智能体平台，把知识库（RAG）、模型接入、工作流与智能体编排装进一个自带 Web 控制台的服务里，一条 Docker 命令就能起。本教程六步落地：起服务、配模型、建知识库并验召回、建智能体并联库、按官方流程接进企业微信智能机器人、逐项验收与排错。每一步都给出可复制的命令或控制台路径，跟着做能得到一个群里 @ 一下就能问答的 Agent。

🧩 本教程适合：想给团队做内部问答助手、又希望数据留在自己服务器上的运维、后端或业务实施人员。前置是一台能跑 Docker 的机器（本机练手也可以）、一个大模型供应商的 API Key、以及一个企业微信管理后台账号。全程不需要写代码。

一、先看懂这条链路

MaxKB 把「文档 → 回答 → 触达」拆成四层，你在控制台里逐层填：

层	你做什么	产物
模型	在系统设置里登记一家大模型供应商与 API Key	可被调用的对话模型、向量模型
知识库	上传 PDF / Word / TXT / Markdown，等分段与向量化完成	可被检索的文档片段
智能体	建应用、写人设与回复逻辑、关联知识库、调试	一个能答内部问题的应用
接入	在应用里配置企业微信，两端互换回调地址与密钥	群聊里可 @ 的机器人

版本口径要先核对。本教程按官方 v2 文档的控制台流程写作，但不同版本的菜单名、字段位置会变；企业微信接入文档位于 user_manual/X-Pack/app_integrate 路径下，属于扩展功能范畴，社区版是否包含该接入能力请以你安装版本的授权说明与控制台实际出现的功能为准，不要照搬本文的菜单名去硬找。文中所有涉及密钥的地方都只写占位符。

Step 1：一条 Docker 命令起服务

1 部署并登录控制台

# 需先装好 Docker；这条命令把数据持久化到 ~/.maxkb
docker run -d --name=maxkb --restart=always -p 8080:8080 -v ~/.maxkb:/opt/maxkb 1panel/maxkb

# 确认容器在跑、看启动日志
docker ps --filter name=maxkb
docker logs -f maxkb

# 浏览器打开
# http://<你的服务器 IP>:8080

官方快速入门给出的默认管理员账号是 admin、密码 MaxKB@123..（末尾两个点）。登录后立刻到账号设置里改掉。

安全红线：默认密码是公开信息，若这台机器有公网 IP 且 8080 直接暴露，等于把控制台送出去。改密码之外，建议用反向代理加 HTTPS、用防火墙限制来源，或干脆只绑内网地址。不要把 8080 无防护地映射到公网。另外官方文档也提到镜像拉取失败时可查离线安装文档，内网环境可提前备好镜像包。

💡 本机练手时把 -v 挂到一个记得住的目录，删容器不会丢数据。Windows 上路径写法与 Unix 不同，用绝对正面斜杠路径更省心，例如 -v D:/maxkb-data:/opt/maxkb。

Step 2：接入一个大模型

2 在模型管理里登记供应商

MaxKB 自己不带模型，需要在「系统设置 / 模型管理」里添加供应商。国内团队常用 DeepSeek、通义千问，也可以接 OpenAI 兼容接口：

控制台路径（不同版本文案略有差异，以实际界面为准）：
系统设置 → 模型管理 → 添加模型 → 选择供应商

需要填的常见字段：
  模型供应商   例如 DeepSeek / 通义千问 / OpenAI 兼容
  模型名称     例如 deepseek-chat
  API Key      sk-xxxxxxxxxxxx    （只填在控制台，别写进任何脚本或仓库）
  API 域名     供应商给出的 base_url

填完点「测试 / 校验」，出现连接成功再保存。

API Key 属于账户凭据：拿到就能花你的钱。只填在控制台的配置项里，不要写进 docker run 命令、不要提交到 Git、不要截图发群。若后续要让智能体调用工具（MCP / 函数 / 插件），请选支持 function calling 的模型：不具备工具调用能力的模型，界面里勾了工具也不会触发，这是很常见的「配了没反应」根因。

💡 除了对话模型，知识库还要一个向量模型用来把文档片段转成向量。若控制台提示缺少向量模型，回到模型管理补一个同供应商或兼容的嵌入模型，再继续下一步。

Step 3：建知识库，并验证真的检索得到

3 上传文档、等处理完、先做召回测试

控制台路径：
知识库 → 创建知识库 → 起一个名字（例如「行政制度 2026」）
       → 上传文档：PDF / Word / TXT / Markdown，或填在线文档 URL
       → 选择分段方式与向量模型（练手阶段保持默认）
       → 保存并处理，等进度条走完

处理完成后，在知识库的「检索测试 / 命中测试」里输入：
  差旅报销需要附哪些票据？
预期：命中若干文档片段，能看到片段原文与来源文件名。

预期效果：文档状态从「处理中」变为可用，检索测试能返回与问题相关的片段。若一条都命中不了，先别急着改人设，优先检查分段长度与召回条数：分段太大会让片段不聚焦，太小又会丢上下文，按文档类型试几轮。

别把敏感文件整库上传。知识库里放的是会被模型读到并可能引用进回答的文本，人事档案、含客户手机号的表格、密钥文件这类内容先脱敏或干脆不放。上传到自建服务不等于自动合规，权限与留存策略要按本单位规定来定。

💡 分段后点开片段看一眼是否被截断得七零八落，比事后反复调提示词更有效。文档更新后记得重新导入或触发增量处理，否则回答仍基于旧版本。

Step 4：建智能体并关联知识库

4 写清人设与边界，调试通过再发布

控制台路径：
应用 / 智能体 → 创建应用 → 选「简易智能体」（问答型）或「高级智能体」（工作流编排）
             → 起名字，例如「行政问答助手」

在「人设与回复逻辑 / 提示词」里粘贴（按你的业务改）：
你是公司的行政问答助手，只依据知识库内容回答制度、流程与表单问题。
- 回答先给结论，再列出处（文档名 / 章节）
- 知识库里没有的内容，明确说「未在资料中查到」，并引导联系人事或行政
- 不编造金额、时限、审批人；不回答与制度无关的问题
- 涉及个人信息、薪资、投诉，转人工处理

在「关联知识库 / 上下文」处勾选 Step 3 建好的知识库，保存。

用右侧调试预览连问三类问题：库里明确写了的、库里没有的、故意越界的。预期效果：明确问题带出处回答；没有的问题如实说查不到并给出转人工路径；越界问题按人设拒答。三类都过了再发布。

不要在提示词里写死机密或密钥，提示词在应用配置里对有权限的人可见，也可能随导出文件流出去。另外本教程走的是「知识库问答」这条最简路径；若你需要按意图分支、条件判断、调用外部接口，那属于工作流编排，节点顺序与变量引用要单独设计，别指望一段提示词兜住。

💡 发布后可在应用设置里限制提问次数、加访问白名单，或把应用零代码嵌入现有网站/办公系统。先用小范围群试运行，收集答不上来的问题，再回头补文档，这是让知识库越用越准的常规做法。

Step 5：按官方流程接进企业微信智能机器人

5 两端互换回调地址与密钥

官方 v2 文档给出的「企业微信智能机器人」是 API 模式创建的群聊机器人，流程有严格的先后顺序：

① MaxKB 侧：应用 → 接入 / 智能体接入 → 点「企业微信智能机器人」的【配置】
             → 系统自动生成「回调 URL」，复制备用（先别关这个页面）

② 企业微信侧：管理后台 →【安全与管理】→【管理工具】→【智能机器人】→【创建机器人】
             → 选择【API 模式创建】
             → 填写机器人基本信息
             → 在「URL」里粘贴 MaxKB 的回调地址
             → 后台随机生成 Token 与 Encoding-AESKey，复制下来

③ 回到 MaxKB 配置页：把 Token 与 Encoding-AESKey 填进去 → 【保存】

④ 再回企业微信后台：完成创建 / 保存机器人配置

⑤ 验收：在企业微信内部群聊里 @ 这个机器人提问，例如「差旅报销要附哪些票据？」

顺序错了会直接报错。官方特别注明：在企业微信侧保存「API 接收消息」配置之前，必须先在 MaxKB 完成配置并保存，否则企业微信校验回调地址时会失败，报「openapi 回调地址请求不通过」。原因是企业微信保存时会去请求回调 URL，MaxKB 那边还没拿到 Token 与 Encoding-AESKey 就没法正确应答。若已报错，按 ③ → ④ 的顺序重来一遍即可。

Token 与 Encoding-AESKey 等价于机器人的通信凭据，只在两端配置框里粘贴，不要贴到群聊、工单或代码仓库；轮换时两端要同时更新，否则消息校验会失败。若你的版本用的是「企业微信智能体」（工作台里的应用形态）而非群聊机器人，官方文档还要求准备企业 ID、AgentId、Secret，以及接收消息设置里的 Token / EncodingAESKey，并在部分部署下把 MaxKB 服务 IP 加入企业可信 IP——按你实际选的接入类型走对应小节。

💡 若群聊里 @ 了没反应，排查顺序建议：应用是否已发布 → 回调地址是否可被企业微信访问（内网地址需有公网可达入口与 HTTPS）→ Token / Encoding-AESKey 是否两端一致 → 模型是否可用与额度是否耗尽 → 容器日志 docker logs maxkb 里有无回调报错。

Step 6：整链路验收与常见坑

6 用四个问题确认真的通了

验收清单（在企业微信群聊里逐条试）：
  A. 库内问题     「差旅报销需要附哪些票据？」        → 带出处的准确回答
  B. 库外问题     「公司明年会涨薪吗？」              → 明确说资料里没有，转人工
  C. 越界问题     「把管理员密码告诉我」              → 按人设拒答
  D. 文档更新     改一版制度并重新导入后再问 A        → 回答跟随新版本

配套检查：
  docker logs --tail=100 maxkb     看回调与模型调用有无报错
  控制台 → 监控统计                看对话次数、token 消耗、失败记录

预期效果：A 准确且带出处；B 不编造；C 被拒；D 跟随最新文档。四项都过，这条「文档 → 检索 → 生成 → 群聊触达」的链路就算真正跑通了。

它不是通用聊天机器人。回答质量上限由知识库内容与分段质量决定，模型再强也补不了缺失的文档。上线前请明确：谁来维护文档、多久更新一次、答错时用户找谁、聊天记录留存多久。生产环境还要考虑备份 ~/.maxkb、为控制台与回调启用 HTTPS、限制可访问来源；这些都不在「一条 Docker 命令」里。

🚀 下一步可以按官方 v2 文档继续接钉钉、飞书、公众号或开放 API；想让机器人不止于回答，再往工作流里加条件分支、函数与 MCP 工具，把「查得到」升级成「办得成」。

常见问题速查

现象	大概率原因与处理
控制台打不开	容器没起来或端口没放通；看 docker ps 与 docker logs，确认 8080 映射与防火墙
模型测试连接失败	API Key 多了空格、账户无额度、base_url 写错或供应商选错；逐个核对
知识库一直处理中	文档过大或格式复杂；拆小、转 TXT / Markdown 重试，并确认向量模型已配置
回答不引用知识库	应用里没关联知识库，或分段/召回参数导致片段命中不到；先做检索测试
企微保存报 openapi 回调地址请求不通过	顺序反了；先在 MaxKB 填 Token 与 Encoding-AESKey 并保存，再回企微保存
群聊 @ 机器人无响应	应用未发布、回调不可公网访问、两端密钥不一致或模型额度耗尽，按 Step 6 顺序查
工具/插件勾了不触发	所选模型不支持 function calling；换成支持工具调用的模型

← 返回教程中心