在飞牛系统上安装了Hermes，本来是抱着试试的心态让智能体帮我管理飞牛，用了一周之后发现，这个智能体配上合适的模型简直太牛了，今天下午花了1个多小时的时间实现了飞牛系统文件管理集成onlyoffice，实现本地打开编辑office文档的功能。中间也折腾了很多次，只要把问题反馈给智能体就行了，查bug、测试都交给智能体就行了。这是部署过程中踩过的坑，跟大家分享一下！
这是我踩过的坑，大家如果有智能体可以喂给他。
📋 最终架构
飞牛文件管理器 → WatchCow (右键菜单) → Caddy (端口 9080)
**── /editor, /download, /callback, /static → Connector (端口 10099)
**── /doc-svr/* → Document Server (去掉前缀)
**── 其他所有请求 → Document Server (端口 80)
部署目录：/vol1/docker/onlyoffice-fnos/
🕳️ 踩坑记录
坑1：Nginx proxy_pass 导致 secure_link 签名验证失败
现象：编辑器打开后提示"下载失败"，但日志显示文件下载成功（200, 11553B）
原因分析：
- Document Server 使用 nginx
secure_link 模块保护缓存文件访问
- URL 中包含签名参数
md5=...&expires=...
- Nginx 的
handle_path 会去掉 /doc-svr/ 前缀，导致 URI 变化
- URI 变化后
secure_link_md5 计算的哈希不匹配 → 403
- Document Server 内部访问自己的缓存文件也返回 403
解决：
- 去掉 Nginx，改用 Caddy 作为反向代理
- Caddy 的
uri strip_prefix 行为更可控
- 或者在 Caddy 中用
handle /doc-svr* + uri strip_prefix /doc-svr
验证：
# 测试 Document Server 内部缓存访问
docker exec onlyoffice-doc-svr curl -s -o /dev/null -w "HTTP %{http_code}\n" \
"http://localhost:80/cache/files/data/.../Editor.bin/Editor.bin?md5=...&expires=..."
坑2：Connector 的 DOC_SERVER_PATH 环境变量不生效
现象：设置 DOC_SERVER_PATH="" 后，编辑器页面仍然加载 /doc-svr/web-apps/...
原因分析：
- Connector 镜像的默认模板中，
/doc-svr/ 前缀是硬编码的
DOC_SERVER_PATH 环境变量可能只影响部分 URL，不影响 <script src="..."> 标签- 编辑器页面的
<script src="/doc-svr/web-apps/apps/api/documents/api.js"> 始终使用 /doc-svr/ 前缀
解决：
- 保留
DOC_SERVER_PATH=/doc-svr（不改）
- 在 Caddy 中添加
/doc-svr* 路由，去掉前缀后转发给 Document Server
Caddy 配置：
handle /doc-svr* {
uri strip_prefix /doc-svr
reverse_proxy onlyoffice-doc-svr:80
}
坑3：Caddy v2 语法错误
现象：Caddy 容器不断重启，日志显示 Unexpected next token after '{' on same line
原因分析：
-
Caddy v2 的 handle 指令要求 { 必须在新行
-
handle /editor { ... } 是错误的语法
-
必须写成：
handle /editor {
reverse_proxy ...
}
解决：
:80 {
handle /editor* {
reverse_proxy onlyoffice-connector:10099
}
...
}
坑4：Caddy path matcher 不匹配 /editor（无斜杠）
现象：handle /editor/* 不匹配 /editor?path=...
原因分析：
- Caddy 的
handle /editor/* 只匹配 /editor/anything，不匹配 /editor
/editor?path=... 的路径部分是 /editor（无斜杠）- 所以
handle /editor/* 不会捕获这个请求
解决：
- 使用
handle /editor* 而不是 handle /editor/*
handle /editor* 匹配 /editor 和 /editor/* 所有变体
坑5：Document Server 的 /cache/ 路径返回 403
现象：编辑器打开后，Document Server 尝试访问 /cache/files/data/.../Editor.bin 返回 403
原因分析：
- Document Server 使用
secure_link 模块保护缓存文件
- 即使是 Document Server 自己访问自己的缓存，也需要有效的签名
- 签名验证失败时返回 403
- 这是 Document Server 的安全机制，不是配置错误
实际影响：
- 403 不影响编辑器正常使用（Editor.bin 是缓存文件，不是必须的）
- 编辑器会自动创建新的 Editor.bin
- 日志中的 403 是正常行为
坑6：JWT 配置不一致导致"下载失败"
现象：Nextcloud + OnlyOffice 集成时提示"下载失败"
原因分析：
- Document Server 的
JWT_ENABLED=true 时，会在回调中签名 JWT
- Connector 的
DOCUMENT_SERVER_SECRET 如果有值，会验证 JWT
- 如果两端配置不匹配，回调失败 → "下载失败"
解决（适用于内网环境）：
# Document Server
environment:
JWT_ENABLED: "false"
# Connector
environment:
DOCUMENT_SERVER_SECRET: "" # 必须显式设置为空
