让私有文档真正可调用：MinDoc、MCP 与 Dify 的分层接入方案

私有文档接入大模型应用时，最容易出现的误解是把“能搜到文档”和“模型能够安全调用文档工具”视为同一件事。前者关注内容存放与检索，后者还包含接口描述、身份认证、调用超时、结果裁剪和失败回退。MinDoc 负责文档的编写与权限管理，MCP 提供工具暴露方式，Dify 负责把工具放进 Agent 或工作流；三者各守一层，系统才不会变成一条难以审计的直连管道。

先画数据路径，再安装任何组件

一次问答至少经过用户输入、应用编排、模型决策、MCP 工具调用、文档查询和答案生成。部署前应标出每一跳的协议、信任边界和日志位置，并确定文档内容是否允许离开内网。如果模型服务位于外部平台，即使 MinDoc 与 Dify 都私有部署，检索片段仍可能被发送出去；这需要在数据分类和服务条款层面提前确认。

MinDoc

保存 Markdown 文档、目录与访问权限，提供可查询的知识源。

MCP 服务

把可执行能力描述成工具，并接受带认证的调用。

Dify

组织模型、工具、条件分支与最终输出，不替代文档治理。

工具返回值应尽量小而明确。与其把整本手册交给模型，不如让查询参数包含关键词或文档范围，并返回少量相关片段、标题与内部标识。这样既减少上下文占用，也让日志能回答“模型依据了哪份文档”。

MinDoc 侧的基线是可重复部署

资料中的方案采用源码编译：准备 Go 与 Git 环境，取得代码后生成 Linux 构建制品，再把制品和配置投放到目标主机。无论继续采用源码方式还是改用容器，都应固定经验证的代码提交或发布版本，保存构建日志与校验值，避免某次重新部署拉到不同内容。数据库、附件和配置应放在独立持久化位置，升级前先演练恢复。

MCP 服务默认不应暴露。启用相应配置项后，要立即替换示例密钥，并把密钥放入只允许服务账户读取的配置或密钥管理设施，不能提交进代码仓库。管理账号的默认口令也必须在首次登录时修改。若服务只供 Dify 使用，网络层应限制来源地址或置于同一私有网络，而不是把管理端口和工具端点一起开放给互联网。

enable_mcp_server = true
mcp_api_key = "由部署环境注入的高强度随机值"

数据库选型取决于规模与运维能力。轻量单机可以先用简单方案验证，但多人协作、备份恢复和并发增长后，应评估独立数据库。迁移不是只改连接字符串，还要验证字符集、事务、附件引用和回滚路径。服务启动成功的标准也不只是首页可访问，还包括重启后数据仍在、工具列表可读取、无权限请求被拒绝。

Dify 侧先确认容器健康，再做工具绑定

资料使用 Docker Compose 部署 Dify。目标主机需要提前检查端口占用、磁盘空间、容器网络与持久化目录。复制环境配置后，应逐项审查数据库口令、外部访问地址、代理与日志级别，再启动服务。首次初始化管理员账号时使用独立凭据，并为后续升级保存当前编排导出和数据库备份。

添加 MCP HTTP 服务时，端点必须从 Dify 容器的网络视角可达；把地址写成 127.0.0.1 往往只会指向当前容器，而不是 MinDoc 主机。服务器标识符应全局唯一，名称用于人读，标识符用于稳定引用，两者不要随意互换。连接和读取超时应依据文档查询的正常延迟设置，过短会制造假故障，过长则会让工作流长时间占用资源。

绿色授权状态只是连通性起点

控制台显示已授权，最多说明端点与凭据通过了一次握手。还要查看工具名称、参数模式和返回结构是否符合预期，随后用明确问题触发真实查询。测试问题应能在指定文档中找到唯一答案，并准备一个知识库中不存在的问题，检查 Agent 是否诚实说明缺少依据，而不是自行补全。

编排时限制模型的自由度

简单演示可以把工具直接交给 Agent，让模型判断何时调用；生产流程更适合把关键步骤写成 Workflow 或 Chatflow：先做输入分类，再调用文档工具，检查返回数量与权限标签，最后生成答案。对必须查文档的问题，可把工具调用设为显式节点，避免模型凭参数知识跳过检索。对返回为空、超时或格式错误分别建立分支，给用户可理解的结果。

不要让模型看到超出当前用户权限的文档，再指望提示词约束它不泄露。权限过滤必须发生在检索或工具服务层，并随请求传递可验证的用户身份。模型输出还需删除内部路径、密钥和调试字段，尤其是工具错误栈可能包含部署信息。

验收围绕答案之外的四组指标

• 正确性：相关文档能否命中，回答是否忠实于片段，缺失知识是否被承认。
• 可靠性：服务重启、数据库短暂不可用和网络抖动时，工作流是否有明确状态。
• 安全性：未认证、低权限和伪造参数的请求能否被阻止，日志是否泄露凭据。
• 运维性：延迟、错误率、工具调用次数、数据库容量和备份结果是否可观测。

上线前应完成 TLS 终止和证书验证，让 Dify 到 MinDoc 的链路也受到保护，而不仅是用户浏览器入口。密钥要支持轮换，轮换时允许短暂双密钥窗口或有序重启。文档更新后还要确认查询结果及时反映变更，并保留文档版本，便于追查某个答案在当时依据的内容。

这套方案的完成标志不是页面上出现一个可用工具，而是每次调用都有身份、有范围、有超时、有来源标识，并能在失败时安全收束。把文档系统、协议适配与应用编排保持为可独立替换的层，后续更换模型、扩展知识源或升级接口时，才不需要重建整条链路。