beatsad_Vault2Dify/docs/CONNECTION_TROUBLESHOOTING_ZH.md

连接失败排查手册

English | 中文

本文用于排查 Vault2Dify 在测试连接、刷新知识库、同步文件时出现的连接失败问题。

快速排查顺序

顺序	检查项	说明
1	API Key	确认已填写、复制完整、没有多余空格或换行。
2	Dify 服务地址	填写当前 Obsidian 设备可以访问的 Dify 服务地址；插件会自动规范化缺失的 http://、/v1 和 /v1/datasets。
3	浏览器访问	在浏览器访问 你的地址 + /v1/datasets。
4	返回内容	返回 JSON 通常说明地址正确；返回 HTML 通常说明地址或端口不对。
5	权限	如果地址正确但无知识库，检查 Key 所属工作区和知识库权限。
6	网络链路	检查端口、防火墙、Docker 映射、NAS 网络、Tailscale 和反向代理。
7	插件复测	回到设置页点击 测试连接。

错误提示对照表

错误提示	状态	代表原因	解决办法	如何确认已修复
请先填写 Dify API Key 和 Dify 服务地址。	missing_config	连接信息不完整。	填写 Dify API Key；填写当前设备可访问的 Dify 服务地址；保存后重新点击 测试连接。	状态不再显示 待配置，测试连接进入成功或明确失败原因。
API Key 无效，请检查密钥是否正确。	auth_failed	Dify 返回 401，密钥无法通过认证。	重新复制 Dify 知识库 API Key；确认没有多余空格、换行或缺失字符；确认 Key 来自当前 Dify 实例。	不再出现 API Key 无效提示，测试连接继续验证知识库访问权限。
API Key 没有知识库访问权限，请检查 Dify 权限配置。	permission_denied	Dify 返回 403，Key 有效但权限不足。	确认 Key 属于正确工作区；检查 Dify 知识库权限；换用具备知识库访问权限的 Key。	点击 测试连接 后能获取知识库数量。
未找到 Dify 知识库 API，请确认 Dify 服务地址、端口和反向代理转发正确。	not_found	Dify 返回 404，插件访问的 API 路径不存在。	使用当前设备可访问的服务地址，例如 http://dify-host.example.test:5000；NAS + Tailscale 可用 http://tailnet-device.example.test:5000；检查反向代理是否转发 /v1。	浏览器访问 地址 + /v1/datasets 不再返回 404。
当前接口路径不兼容，请将“Dify 文档接口路径”设为自动兼容后重试。	path_mismatch	Dify 文档接口路径和内部兼容策略不匹配。当前版本不再把该选项作为可见设置。	确认插件已升级到最新构建；重新点击 测试连接 后再同步；如果仍失败，开启调试日志并反馈实际 Dify 版本和错误信息。	同步文档时不再出现接口路径不兼容提示。
Dify 返回请求过多，请降低并发上传数或稍后重试。	rate_limited	Dify 返回 429，请求频率过高。	降低 并发上传；稍后重试；大目录可分批同步。	重新同步后不再出现请求过多提示，最近同步失败数下降。
Dify 服务异常，请检查 Dify 容器、服务日志或反向代理。	server	Dify 返回 5xx，服务端异常。	检查 Dify 服务状态；查看 Dify 容器日志；检查反向代理 upstream 配置。	浏览器访问 /v1/datasets 不再返回 5xx，插件测试连接成功。
请求超时，请确认当前设备能访问 Dify 服务地址。	timeout	请求在内部超时时间内没有响应。当前版本不再把超时时间作为可见设置。	确认运行 Obsidian 的设备能访问 Dify 服务地址；检查 Dify 服务负载、端口、防火墙、Tailscale 和反向代理；同步大量文件时先把并发上传降到 2 个文件 或分批同步。	测试连接能返回结果，同步不再频繁超时。
网络连接失败，请检查地址、端口、防火墙、Docker 映射或反向代理。	network	当前设备无法连接到目标地址。	检查 IP、域名和端口；检查 Docker 端口映射；检查防火墙、路由、Tailscale 和反向代理服务。	浏览器可以打开 地址 + /v1/datasets，插件测试连接不再提示网络失败。
当前地址返回的不是 Dify 知识库 API，请检查地址和端口是否指向 Dify 服务。	unexpected_response	插件访问到了网页、登录页、NAS 管理页、Dify 前端页面或其他非 Dify API 响应。	确认填写的是 Dify 服务根地址；不要填写 NAS 管理后台地址；检查端口是否转发到 Dify API 服务；确认 地址 + /v1/datasets 返回 JSON 而不是 HTML。	不再出现“不是 Dify 知识库 API”，测试连接显示知识库数量或进入权限类提示。
连接失败，请检查 Dify 配置后重试。	unknown	插件无法判断具体失败类型。	先按快速排查顺序检查 Key、地址、端口和反向代理；临时开启调试日志；重新测试连接并查看 Obsidian 开发者控制台。	找到更具体的错误提示，或测试连接成功。

地址填写规则

类型	示例	是否推荐	说明
Dify 服务地址	http://dify-host.example.test:5000	推荐	局域网、NAS、Docker 常见填写方式。
NAS + Tailscale	http://tailnet-device.example.test:5000	推荐	使用 tailnet 设备主机名或文档示例主机，并填写 Dify 映射端口。
Dify HTTPS 域名	https://dify.example.com	推荐	适合公网反向代理或云端 Dify。
粘贴 /v1 端点	http://dify-host.example.test:5000/v1	可接受	插件会自动规范化已知后缀，但直接填写服务地址更清楚。
粘贴 /v1/datasets 端点	http://dify-host.example.test:5000/v1/datasets	可接受	插件会自动规范化这个已知端点。
NAS 管理页	https://nas-admin.example.test/admin	错误	通常会返回网页，不是 Dify 知识库 API。
Docker 容器内部地址	http://api:5001	错误	Obsidian 所在设备通常无法访问容器内部地址。
非本机部署的 localhost	http://localhost:5000	通常错误	只有 Dify 和 Obsidian 在同一台电脑时才可使用。

浏览器验证方式

浏览器访问结果	含义	下一步
返回 JSON	地址大概率正确。	如果插件仍失败，继续检查 API Key 和知识库权限。
返回 HTML 页面	地址或端口指向了网页服务。	检查是否填到了 NAS 管理页、Dify 前端页或错误反向代理。
返回 404	API 路径不存在。	检查服务地址、端口，或反向代理是否转发 /v1。
返回 401	地址可能已正确路由到 Dify。	在插件中确认 API Key 是否正确。
返回 403	地址可达但权限不足。	检查 Key 权限和工作区。
打不开	网络不可达。	检查 IP、域名、端口、防火墙、Docker 映射、Tailscale 和反向代理。

同步失败时怎么查

现象	优先检查	处理方式
整次同步失败	先点击 测试连接。	如果测试连接失败，按本手册错误表排查。
部分文件失败	查看 最近失败文件。	根据失败原因检查权限、网络、超时或限流。
失败文件很多	并发、限流、服务负载。	降低并发上传，分批同步较大的目录。
测试连接成功但同步失败	映射和知识库权限。	检查路径映射是否启用，目标知识库是否可写。

什么时候开启调试日志

场景	建议
错误一直是 连接失败，请检查 Dify 配置后重试。	开启调试日志，查看更底层的响应信息。
浏览器访问正常，但插件仍失败	开启调试日志，对比插件实际请求地址。
NAS、Docker、反向代理链路复杂	开启调试日志，确认请求是否到达 Dify API。
需要反馈问题给开发者	截取必要日志，但不要公开 API Key 或完整敏感信息。