# Collabora 正确配置全流程 ## 1. 文档目标 本文档用于沉淀 LeAudit 当前 Collabora 集成的**正确配置全流程**，便于： - 本机继续维护 - 迁移到新服务器 - 上线前后按清单验收 - 遇到故障时快速排查 本文档同时包含两类信息： - 当前环境已经验证可用的实际配置 - 可迁移到其他服务器的模板化配置说明 当前已验证可用的主链路为： ```text http://172.16.0.59:5173 ``` 注意： **浏览器入口、前端生成的 WOPI 地址、Collabora iframe 地址、nginx 转发头、Collabora 白名单、CSP 的 host 必须完全一致。** 如果后续要改成域名方案，必须整套一起切换，不要域名/IP 混用。 --- ## 2. 参数模板 迁移到新服务器时，建议先把下面这些参数定义清楚，再开始修改配置： ```text LeAudit 项目根目录 Collabora 部署目录 浏览器实际访问的主机名或 IP 前端代理入口端口，默认 5173 Next 开发服务端口，默认 5193 后端服务端口，默认 8096 Collabora 容器端口，默认 9980 文档读写后端基础地址 ``` 当前环境对应值： ```text = /home/wren-dev/Porject/leaudit-platform = /home/wren-dev/Porject/collabora-backup = 172.16.0.59 = 5173 = 5193 = 8096 = 9980 = http://172.16.0.59:8096/docauditai/ ``` --- ## 3. 当前架构 当前链路如下： 1. 浏览器访问前端入口：`http://172.16.0.59:5173` 2. `5173` 上运行 nginx 代理 3. nginx 将普通前端请求转发到 Next：`127.0.0.1:5193` 4. nginx 将 Collabora 请求转发到容器：`127.0.0.1:9980` 5. 前端通过 `/api/collabora/config` 生成： - `iframeUrl` - `WOPISrc` 6. Collabora 再通过 `/wopi/files/...` 回调前端获取文件信息与文件内容 简化后的链路： ```text Browser -> 172.16.0.59:5173 -> nginx proxy -> 127.0.0.1:5193 (Next 前端) -> 127.0.0.1:9980 (Collabora) ``` --- ## 4. 关键目录与文件 ### 4.1 项目目录 ```text ``` 当前实际值： ```text /home/wren-dev/Porject/leaudit-platform ``` ### 4.2 Collabora 部署目录 ```text ``` 当前实际值： ```text /home/wren-dev/Porject/collabora-backup ``` ### 4.3 本次关键文件 - 前端环境变量 - `legal-platform-frontend/.env` - Collabora iframe 配置生成 - `legal-platform-frontend/lib/services/collabora.config.server.ts` - nginx 代理配置 - `deploy/collabora-proxy/conf.d/collabora.conf` - Collabora compose 配置 - `/home/wren-dev/Porject/collabora-backup/docker-compose.yml` - Collabora 主配置 - `/home/wren-dev/Porject/collabora-backup/coolwsd-config/coolwsd.xml` --- ## 5. 前置要求 开始前请确认： - Docker 可用 - Docker Compose 可用 - 前端、后端可正常启动 - 目标服务器开放需要的端口 - Collabora 镜像已准备好 如需重新导入镜像： ```bash docker load -i /collabora-image-v5.tar ``` 当前环境示例： ```bash docker load -i /home/wren-dev/Porject/collabora-backup/collabora-image-v5.tar ``` 需要重点确认的端口： - `` - `` - `` --- ## 6. 前端正确配置 文件：`legal-platform-frontend/.env` ### 6.1 当前已验证可用配置 ```env API_BACKEND_TARGET=http://172.16.0.59:8096 APP_URL=http://172.16.0.59:5173 DOCUMENT_URL=http://172.16.0.59:8096/docauditai/ COLLABORA_URL=http://172.16.0.59:5173 ``` ### 6.2 模板写法 迁移到新服务器时，替换为： ```env API_BACKEND_TARGET=http://: APP_URL=http://: DOCUMENT_URL=http://:/docauditai/ COLLABORA_URL=http://: ``` ### 6.3 每个变量的作用 - `APP_URL` - 决定 `WOPISrc` - 必须与浏览器实际访问入口一致 - `COLLABORA_URL` - 决定 iframe 中 `cool.html` 的主机与端口 - `API_BACKEND_TARGET` - 前端调用后端 API 的入口 - `DOCUMENT_URL` - WOPI 获取文件、写回文件时使用的后端文档基础地址 ### 6.4 为什么必须统一 如果浏览器入口是： - `http://172.16.0.59:5173` 但前端却生成： - `http://nas.7bm.co:5173/wopi/files/...` - `http://nas.7bm.co:5173/browser/dist/cool.html` 就会出现： - 父页面是 IP - iframe 是域名 - WOPI 又是另一个 host - 浏览器按跨源处理 - 最终触发 iframe 拒绝加载、CSP 冲突、`chrome-error://chromewebdata/` 所以前端配置必须与最终入口完全一致。 --- ## 7. Collabora iframe 参数生成 文件：`legal-platform-frontend/lib/services/collabora.config.server.ts` ### 7.1 当前逻辑 - `WOPISrc = ${APP_URL}/wopi/files/${encodeURIComponent(fileId)}` - `cool.html = ${COLLABORA_URL}/browser/dist/cool.html?...` ### 7.2 当前建议保留的 UI 默认项 ```ts const uiDefaults = [ "UIMode=compact", "TextRuler=false", "TextStatusbar=false", "TextSidebar=false", ].join(";") ``` ### 7.3 已移除的项 - `SavedUIState=false` 原因： - Collabora 会输出： - `unknown UI default's component SavedUIState` - 该项不是必须项，移除后可减少无关噪音日志 --- ## 8. nginx 代理正确配置 文件：`deploy/collabora-proxy/conf.d/collabora.conf` ### 8.1 必须代理的路径 以下路径必须明确代理： - `/wopi/` - `/browser/` - `/cool/` - `/coolws/` - `/hosting/` - `/loleaflet/` - `/` ### 8.2 路径作用 - `/wopi/` - 前端本地 WOPI 接口 - `/browser/` - Collabora 页面与静态资源 - `/cool/` - 文档会话相关路径 - `/coolws/` - websocket 子通道 - `/hosting/` - discovery 接口 - `/loleaflet/` - Collabora 相关资源 - `/` - 普通前端页面与 API ### 8.3 Collabora 相关转发头 对 Collabora 相关 location，必须统一： ```nginx proxy_set_header Host :; proxy_set_header X-Forwarded-Host :; proxy_set_header X-Forwarded-Proto $scheme; ``` 当前环境实际值： ```nginx proxy_set_header Host 172.16.0.59:5173; proxy_set_header X-Forwarded-Host 172.16.0.59:5173; proxy_set_header X-Forwarded-Proto $scheme; ``` ### 8.4 前端主路由需要补的头 ```nginx proxy_set_header X-Forwarded-Port $server_port; ``` ### 8.5 为什么 `/coolws/` 不能漏 如果遗漏 `/coolws/`，就会出现： - `WOPI` 文件接口已经返回 `200` - `cool.html` 也能打开 - 但 websocket 子通道建立失败 - 文档仍无法进入编辑状态 本次修复中，`/coolws/` 是一个关键缺失点。 ### 8.6 错误跳转修复 针对 Next 开发环境错误返回的绝对地址，需要增加： ```nginx proxy_redirect http://127.0.0.1:/ http://:/; proxy_redirect http://localhost:/ http://:/; ``` 当前环境实际值： ```nginx proxy_redirect http://127.0.0.1:5193/ http://172.16.0.59:5173/; proxy_redirect http://localhost:5193/ http://172.16.0.59:5173/; ``` 否则可能出现： - 浏览器跳到 `localhost:5193/login?...` - 远端用户直接无法访问 ### 8.7 迁移到新服务器时要替换的项 - `listen 5173;` - `proxy_pass http://127.0.0.1:5193` - `proxy_pass http://127.0.0.1:9980` - 所有 `Host :` - 所有 `X-Forwarded-Host :` - 所有 `proxy_redirect` --- ## 9. Collabora Docker Compose 正确配置 文件：`/docker-compose.yml` ### 9.1 当前关键配置 ```yaml services: collabora: image: docker-collabora:v5 container_name: collabora_code privileged: true ports: - "9980:9980" environment: - "domain=.*" - "extra_params=--o:ssl.enable=false --o:ssl.termination=false --o:logging.level=warning --o:security.seccomp=false" ``` ### 9.2 不要再保留旧参数 不要再使用： ```text --o:net.frame_ancestors=http://* ``` 原因： - 这是过时配置 - 会污染最终 `Content-Security-Policy` - 会让 `frame-ancestors` 混乱 - 浏览器会直接拦 iframe ### 9.3 当前正确做法 - 删除 `net.frame_ancestors` - 在 `coolwsd.xml` 中显式设置 `content_security_policy` ### 9.4 新服务器迁移要点 迁移时需要确认： - 镜像已导入 - `docker-compose.yml` 中挂载目录存在 - 插件目录存在： - `mycustom_collabora_plugins` - 脚本目录存在： - `custom_python_scripts` - `` 未被占用 --- ## 10. Collabora 主配置正确写法 文件：`/coolwsd-config/coolwsd.xml` ### 10.1 WOPI 白名单 模板写法： ```xml http://: ``` 当前环境实际值： ```xml http://172\.16\.0\.59:5173 ``` ### 10.2 CSP 配置 模板写法： ```xml frame-ancestors http://:; ``` 当前环境实际值： ```xml frame-ancestors http://172.16.0.59:5173; ``` ### 10.3 不推荐写法 不要再使用复杂 alias 正则，例如： ```xml http://172\.16\.0\.[0-9]{1,3}(:[0-9]{1,5})? ``` 这在当前环境中已经实测触发过： - `Invalid regular expression for allowed host` - `Bad URI syntax` 因此当前方案统一改为显式 host。 --- ## 11. 正确重启顺序 ### 11.1 前后端 ```bash cd ./leaudit.sh restart ``` ### 11.2 代理 ```bash docker restart leaudit-collabora-proxy ``` ### 11.3 Collabora 推荐直接强制重建，而不是简单 restart： ```bash cd docker-compose up -d --force-recreate collabora ``` ### 11.4 为什么要 force-recreate 如果只执行： ```bash docker restart collabora_code ``` 旧容器里的环境变量可能仍保留，尤其是： - `extra_params` 本次就遇到过： - compose 文件已经删掉了 `net.frame_ancestors` - 但旧容器环境里仍残留该参数 - 只有 `--force-recreate` 之后才真正清理干净 ### 11.5 推荐标准重建流程 ```bash cd ./leaudit.sh restart docker restart leaudit-collabora-proxy cd docker-compose up -d --force-recreate collabora ``` --- ## 12. 正确验证步骤 ### 12.1 验证前端入口 ```bash curl -I http://:/ ``` 期望： - 返回 `307` - 跳转到 `http://:/login?...` 当前环境示例： ```bash curl -I http://172.16.0.59:5173/ ``` ### 12.2 验证 discovery ```bash curl -I http://:/hosting/discovery ``` 期望： - `200 OK` ### 12.3 验证 Collabora 页面 ```bash curl -I http://:/browser/dist/cool.html ``` 期望： - `200 OK` - 响应头包含 `Content-Security-Policy` - `frame-ancestors` 围绕当前 `:` 收口 ### 12.4 验证 WOPI 文件接口 通过页面实际访问时，日志里应看到： ```text GET /wopi/files/... 200 ``` ### 12.5 验证 websocket 子通道 Collabora 日志中应能看到类似： - `/coolws/forkit` - `/coolws/newchild` - `Upgrading to WebSocket` 这说明文档会话已建立。 ### 12.6 上线验收清单 上线到新服务器后，至少完成以下验收： - 能打开登录页 - 能成功登录 - 能打开 2~3 个不同文档 - 能进入编辑态 - 能保存并再次打开 - 浏览器控制台不再出现： - `refused to connect` - `chrome-error://chromewebdata/` - `Framing ... violates Content Security Policy` - Collabora 日志不再出现： - `Invalid regular expression for allowed host` - `Bad URI syntax` - `No authorized hosts found` --- ## 13. 浏览器侧正确测试方式 如果浏览器之前已经打开过： - `nas.7bm.co` - 或旧的失败 iframe 页面 即使后端已经修好，也可能继续残留： - `chrome-error://chromewebdata/` - 错误 iframe 上下文 - 跨源错误 ### 正确做法 1. 关闭旧标签页 2. 打开无痕窗口 3. 只访问： - `http://:/login` 4. 登录后直接进入文档页面 5. 不要从旧域名页面跳转到新 IP 页面 当前环境示例： - `http://172.16.0.59:5173/login` --- ## 14. 本次实际修复过的问题 ### 问题 1：错误跳转到 `localhost:5193` 原因： - 代理头不完整 - Next 在开发环境生成了错误绝对地址 修复： - 增加 `X-Forwarded-Host` / `X-Forwarded-Port` - 增加 `proxy_redirect` ### 问题 2：`/coolws/` 未代理 原因： - 只代理了 `/cool/`，漏了 websocket 子通道 修复： - 增加 `/coolws/` 到 Collabora 容器的代理 ### 问题 3：Collabora 白名单正则错误 原因： - 复杂 alias 正则不兼容当前 coolwsd 解析 修复： - 改为显式 host ### 问题 4：CSP / frame-ancestors 冲突 原因： - 旧的 `net.frame_ancestors=http://*` - 域名与 IP 混用 修复： - 删除旧参数 - 使用 `content_security_policy` 显式配置 - 强制重建容器 ### 问题 5：`SavedUIState` 无关告警 原因： - `ui_defaults` 里传了 Collabora 当前不识别的项 修复： - 从 `legal-platform-frontend/lib/services/collabora.config.server.ts` 中移除该项 --- ## 15. 回切域名方案时的注意事项 如果后续要恢复域名方案，不能只改其中一项，必须一起改： - 前端 `.env` - nginx 代理头与 `proxy_redirect` - Collabora 白名单 - Collabora CSP `frame-ancestors` ### 15.1 推荐原则 上线时只选一种主链路： - 全域名 或 - 全 IP 不要混合： - 父页面域名 - iframe IP - WOPI 又是另一个 host 否则最终还是会回到浏览器跨源与 iframe 拦截问题。 --- ## 16. 推荐日常运维命令 ### 查看前后端状态 ```bash cd ./leaudit.sh doctor ``` ### 重启前后端 ```bash ./leaudit.sh restart ``` ### 重建 Collabora ```bash cd docker-compose up -d --force-recreate collabora ``` ### 查看 Collabora 日志 ```bash docker logs --tail 200 collabora_code ``` ### 查看代理日志 ```bash tail -n 200 /deploy/collabora-proxy/logs/error.log ``` --- ## 17. 新服务器迁移 Checklist ### 17.1 准备阶段 - [ ] 准备好项目代码目录 `` - [ ] 准备好 Collabora 部署目录 `` - [ ] 准备好 Collabora 镜像 tar 或镜像仓库访问方式 - [ ] 确认 `` - [ ] 确认 ``、``、`` 不冲突 ### 17.2 配置阶段 - [ ] 修改 `legal-platform-frontend/.env` - [ ] 修改 `deploy/collabora-proxy/conf.d/collabora.conf` - [ ] 修改 `docker-compose.yml` - [ ] 修改 `coolwsd.xml` ### 17.3 启动阶段 - [ ] 导入 Collabora 镜像 - [ ] 启动前后端 - [ ] 重启代理 - [ ] 强制重建 Collabora 容器 ### 17.4 验证阶段 - [ ] `curl -I http://:/` - [ ] `curl -I http://:/hosting/discovery` - [ ] `curl -I http://:/browser/dist/cool.html` - [ ] 浏览器无痕访问登录页 - [ ] 打开并保存至少一个文档 ### 17.5 故障定位阶段 若失败，优先检查： - [ ] 前端 `.env` 与实际入口是否一致 - [ ] nginx 是否代理了 `/coolws/` - [ ] `proxy_redirect` 是否仍指向旧地址 - [ ] `coolwsd.xml` 白名单是否与实际 host 一致 - [ ] compose 是否仍残留旧 `extra_params` - [ ] Collabora 是否已 `force-recreate` --- ## 18. 当前结论 当前这套正确配置的核心原则只有一句话： **浏览器入口、前端生成的 WOPI 地址、Collabora iframe 地址、代理转发头、Collabora 白名单、CSP 来源，必须全部使用同一个 host。** 本次已经验证可用的 host 为： ```text 172.16.0.59:5173 ``` 如果迁移到新服务器，请先替换 `` 等参数，再按本文档的重启与验证步骤执行。