Collabora Online迁移至21.11.3版本后无规律异常如何排查

你遇到的两类无规律故障是该版本原生缺陷叠加部署配置偏差共同导致的，不存在单一触发条件，对应原因和修复方式如下：

保存功能失效、PostMessage事件不触发 #

• 版本原生缺陷：21.11.3前端保存逻辑存在节流bug，当两次保存操作间隔小于内置的30秒阈值时，手动点击保存按钮会被直接拦截，既不会向WOPI host发起PutFile请求，也不会向外抛出PostMessage的Action_Save、Ui_Saved事件，该问题在21.11.5及之后的小版本中才被修复。
• 配置侧排查点：
  • 核对WOPI接口颁发的access_token有效期，当token剩余有效期不足10分钟时，Collabora前端会静默禁用保存逻辑，无任何前端提示
  • 检查前置反向代理的超时配置，若proxy_read_timeout小于300秒，WebSocket长连接偶发断连时会直接销毁前端保存事件的监听实例，后续操作不会触发事件回调
  • 校验PostMessage监听配置的targetOrigin是否与Collabora服务的访问地址完全匹配（包含协议头、端口号），跨域规则匹配失败时，事件捕获会出现随机失效的情况

文档加载随机报错 #

两类报错均和会话管理逻辑异常相关：

• 卡在「正在清理上一会话的文档」状态：
  21.11.3的会话回收逻辑存在缺陷，若用户直接关闭浏览器标签页、未正常触发页面卸载事件，服务端coolforkit进程不会自动释放对应文档的文件锁，默认锁过期时长为24小时，期间新会话访问会持续卡在清理状态。临时修复可执行coolconfig set cleanup.locked_files_interval 300将锁残留检查间隔调整为5分钟，彻底解决需要升级版本。若为多节点负载均衡部署，未开启会话粘滞导致的节点间会话数据不同步，也会高频触发该报错。
• 提示「无法建立与文档的连接」：
  首先检查反向代理是否正确配置了WebSocket升级透传规则，缺失Upgrade: websocket、Connection: Upgrade请求头时，连接会被代理随机拦截；其次21.11.3默认单文档最大并发会话数为10，残留僵尸会话占满配额后，新访问请求会被直接拒绝触发该报错。

临时规避方案 #

暂不具备升级条件时，可通过以下配置降低故障出现概率：

• 修改coolwsd.xml配置，将per_document.max_concurrency参数调整为20
• 调整自动保存逻辑，设置autosave.interval=60关闭短间隔节流
• 反向代理添加长连接超时配置：proxy_send_timeout 3600s; proxy_read_timeout 3600s，同时补全WebSocket升级头规则
• 多节点部署场景必须开启源IP会话粘滞，保证同一用户的请求始终调度到同一后端节点

21.11.x为非LTS分支，目前已停止维护，长期稳定运行建议升级到22.05及以上的LTS版本，上述所有原生逻辑缺陷在后续LTS分支中均已修复。

内容的提问来源于stack exchange，提问作者froehrle