在飞牛上实现了集成onlyoffice打开office文档。

在飞牛系统上安装了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: ""  # 必须显式设置为空