后台被问得最多的一类问题不是某个工具怎么用而是对接“知识库检索时好时坏是不是配置丢了”网络版让我登录单机版怎么不用这些疑问八成出在同一个地方——鉴权模式没搞清楚。察元AI文档助手的知识库能力是对接桌面版/网络版获得的两种形态的鉴权方式完全不同单机版免登录网络版带 JWT 登录系统级挂载走 HMAC 应用态对接。这篇用问答把三种模式讲透对接之前看一遍能少走不少弯路。问一单机版为什么不用登录察元桌面版的单机版跑在自己电脑上服务地址是http://127.0.0.1:62581免登录。这个设计和 MCP 端点的思路一脉相承MCP 服务监听http://127.0.0.1:62588/mcp只绑定本机回环地址本机即信任边界所以不需要 Token也不需要 stdio 转发。62581 管引擎侧的知识库62588 管智能体侧的工具调用两个端口各司其职但信任模型是同一个够得着这个端口的只有你这台机器上的进程。问二网络版为什么要 JWT 登录换成服务版情况就变了。Docker 部署的网络版是全科室共用的一份服务、一份知识库、几十号人访问这时候本机即信任边界不再成立必须区分你是谁。网络版带 JWT 登录登录换取令牌后续请求带着令牌访问服务端验证通过后放行。JWT 是业界成熟的做法无状态、好扩展对使用者来说体验就是登录一次期间不用反复输密码。多人共用一套知识库时谁检索了什么、谁写回了什么也都因为有身份而变得可归因。问三HMAC 应用态对接是给谁用的JWT 解决人的登录HMAC 解决系统的挂载。如果单位想把文档智能体能力嵌进自己的业务系统——比如 OA 里点一个按钮触发批量校对——用某个员工的登录令牌就不合适了登录态跟着人走人换了终端、离了岗链路就断。HMAC 应用态对接给的是应用级凭据第三方系统用它证明我这个应用有权调用不依赖任何个人的登录状态。一句话记忆人用 JWT系统用 HMAC。问四我该怎么选按使用规模对号入座。一个人一台机器装桌面版单机版免登录零配置心智负担一个科室十人以上共用上服务版管理员统一配模型端点和权限成员各自 JWT 登录要把能力挂进业务系统走 HMAC 应用态对接。再往上是至臻版面向数百到上万人的浏览器工作空间那是体系建设级别的事直接和出品方聊方案更高效。问五对接完怎么验证链路是通的两步。第一步看健康检查GET http://127.0.0.1:62588/healthz返回online说明智能体侧服务活着curlhttp://127.0.0.1:62588/healthz第二步做一次真实任务。配了 MCP 的 Claude Code 或 Cursor 里直接说需求让智能体经kb_retrieve检索知识库再干活比如这条经典提示词先跑一遍校对dryRun汇总问题列表不要先改正文我确认后再写成批注dryRun 只返回问题清单不动正文确认后才落批注。这个先看后写的习惯在知识库增强场景同样适用检索命中的依据段落先过目再让智能体动笔。如果想更直观地看到链路里到底发生了什么可以再用 MCP Inspector 连上来观察它会列出端点暴露的工具和调用过程npx modelcontextprotocol/inspector选 Streamable HTTP 类型、填上 62588 的地址、点 Connect46 个文档工具的清单和每次调用的报文一目了然对接排障时比看日志直观得多。三条边界提醒第一JWT 令牌和 HMAC 凭据都是密钥资产管理要求等同 API key不进代码库、不进群聊、按人按应用分开发放。第二鉴权管的是谁能访问数据边界由部署形态决定内网部署加本地模型才是全链路不出域的完整拼图。第三知识库检索结果是辅助参考引到正式文稿里的制度条文要回到原文核对AI 检索不替代人工查证定密定稿的责任始终在人。对接鉴权这层想明白剩下的都是顺水推舟。 JWT 与 HMAC：网络版和单机版的两种对接鉴权
后台被问得最多的一类问题不是某个工具怎么用而是对接“知识库检索时好时坏是不是配置丢了”网络版让我登录单机版怎么不用这些疑问八成出在同一个地方——鉴权模式没搞清楚。察元AI文档助手的知识库能力是对接桌面版/网络版获得的两种形态的鉴权方式完全不同单机版免登录网络版带 JWT 登录系统级挂载走 HMAC 应用态对接。这篇用问答把三种模式讲透对接之前看一遍能少走不少弯路。问一单机版为什么不用登录察元桌面版的单机版跑在自己电脑上服务地址是http://127.0.0.1:62581免登录。这个设计和 MCP 端点的思路一脉相承MCP 服务监听http://127.0.0.1:62588/mcp只绑定本机回环地址本机即信任边界所以不需要 Token也不需要 stdio 转发。62581 管引擎侧的知识库62588 管智能体侧的工具调用两个端口各司其职但信任模型是同一个够得着这个端口的只有你这台机器上的进程。问二网络版为什么要 JWT 登录换成服务版情况就变了。Docker 部署的网络版是全科室共用的一份服务、一份知识库、几十号人访问这时候本机即信任边界不再成立必须区分你是谁。网络版带 JWT 登录登录换取令牌后续请求带着令牌访问服务端验证通过后放行。JWT 是业界成熟的做法无状态、好扩展对使用者来说体验就是登录一次期间不用反复输密码。多人共用一套知识库时谁检索了什么、谁写回了什么也都因为有身份而变得可归因。问三HMAC 应用态对接是给谁用的JWT 解决人的登录HMAC 解决系统的挂载。如果单位想把文档智能体能力嵌进自己的业务系统——比如 OA 里点一个按钮触发批量校对——用某个员工的登录令牌就不合适了登录态跟着人走人换了终端、离了岗链路就断。HMAC 应用态对接给的是应用级凭据第三方系统用它证明我这个应用有权调用不依赖任何个人的登录状态。一句话记忆人用 JWT系统用 HMAC。问四我该怎么选按使用规模对号入座。一个人一台机器装桌面版单机版免登录零配置心智负担一个科室十人以上共用上服务版管理员统一配模型端点和权限成员各自 JWT 登录要把能力挂进业务系统走 HMAC 应用态对接。再往上是至臻版面向数百到上万人的浏览器工作空间那是体系建设级别的事直接和出品方聊方案更高效。问五对接完怎么验证链路是通的两步。第一步看健康检查GET http://127.0.0.1:62588/healthz返回online说明智能体侧服务活着curlhttp://127.0.0.1:62588/healthz第二步做一次真实任务。配了 MCP 的 Claude Code 或 Cursor 里直接说需求让智能体经kb_retrieve检索知识库再干活比如这条经典提示词先跑一遍校对dryRun汇总问题列表不要先改正文我确认后再写成批注dryRun 只返回问题清单不动正文确认后才落批注。这个先看后写的习惯在知识库增强场景同样适用检索命中的依据段落先过目再让智能体动笔。如果想更直观地看到链路里到底发生了什么可以再用 MCP Inspector 连上来观察它会列出端点暴露的工具和调用过程npx modelcontextprotocol/inspector选 Streamable HTTP 类型、填上 62588 的地址、点 Connect46 个文档工具的清单和每次调用的报文一目了然对接排障时比看日志直观得多。三条边界提醒第一JWT 令牌和 HMAC 凭据都是密钥资产管理要求等同 API key不进代码库、不进群聊、按人按应用分开发放。第二鉴权管的是谁能访问数据边界由部署形态决定内网部署加本地模型才是全链路不出域的完整拼图。第三知识库检索结果是辅助参考引到正式文稿里的制度条文要回到原文核对AI 检索不替代人工查证定密定稿的责任始终在人。对接鉴权这层想明白剩下的都是顺水推舟。