OnlyOffice连接器无法同步文档？

Question

**问题：OnlyOffice连接器无法同步文档，提示“文件锁定或网络超时”** 在集成OnlyOffice与Nextcloud或SharePoint等平台时，常出现文档无法同步并提示“文件锁定”或“网络超时”。该问题多因反向代理配置不当、WebSocket连接中断或缓存冲突导致。OnlyOffice依赖长连接实现实时协作，若Nginx/Apache未正确转发WebSocket请求（如缺少wss协议支持），协同编辑会话将失败，文档滞留于只读状态。此外，服务器时间不同步或JWT令牌验证异常也会中断通信。需检查日志文件（onlyoffice/documentserver/logs）、确认回调服务可达性，并确保所有组件版本兼容，以恢复同步功能。

Answer 1

1. 问题现象与初步排查

在集成 OnlyOffice 与 Nextcloud 或 SharePoint 等平台时，用户频繁反馈“文件锁定或网络超时”错误，导致文档无法同步。此问题表现为：打开文档后仅能查看，无法编辑；协同编辑会话未建立；刷新页面后提示“正在被其他用户编辑”。

• 客户端浏览器控制台报错：WebSocket connection failed
• OnlyOffice 文档服务器日志显示：error while sending request to storage
• Nextcloud 提示回调 URL 不可达或 JWT 验证失败

初步判断方向包括网络链路、反向代理配置、时间同步及身份验证机制。

2. 核心技术原理分析

OnlyOffice 实现协同编辑依赖于以下关键技术组件：

组件	作用	常见故障点
WebSocket (WSS)	维持客户端与 Document Server 的长连接	Nginx 未启用 proxy_http_version 1.1
Callback Service	Nextcloud 接收保存状态和版本更新	防火墙阻止 POST 请求
JWT Token	安全验证请求来源	密钥不一致或过期时间偏差
Time Synchronization	确保令牌有效性窗口对齐	服务器间时间差 > 5min

当任意一环断裂，文档将进入只读锁定状态。

3. 深度诊断流程图

```mermaid
graph TD
    A[用户报告“文件锁定”] --> B{检查浏览器控制台}
    B -->|WebSocket 错误| C[检查反向代理 WSS 支持]
    B -->|HTTP 401/403| D[验证 JWT 配置一致性]
    C --> E[Nginx/Apache 是否设置 Upgrade 头]
    D --> F[确认 secret 密钥匹配]
    E --> G[测试 wss://domain/coolwsd/connectioncheck]
    F --> H[检查时间同步 chrony/ntpd]
    G --> I{连接成功?}
    H --> I
    I -->|Yes| J[重启协同服务]
    I -->|No| K[排查防火墙、SELinux、端口占用]

4. 反向代理配置关键项（以 Nginx 为例）

以下是确保 WebSocket 正常转发的最小化 Nginx 配置片段：

location /websocket {
    proxy_pass http://documentserver;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# 必须开放 coolwsd 路径
location ~ ^/coolwsd/ {
    proxy_pass http://127.0.0.1:9980;
    include /etc/nginx/proxy_params;
    proxy_buffering off;
}

遗漏 Upgrade 和 Connection 头是导致 WSS 中断的最常见原因。

5. 日志分析路径与典型错误模式

OnlyOffice 日志位于：/var/log/onlyoffice/documentserver/logs，重点关注以下子目录：

1. docservice/out.log - 文档处理核心日志
2. converter/out.log - 文件格式转换记录
3. metrics.log - 性能与连接指标

典型错误示例：

[ERROR] socket.io | Failed to verify token signature
[WARN] services/CoAuthoring/editingSession - Session not found for key=abc123
[ERROR] postRequest | Cannot reach callback URL https://nextcloud.example.com/apps/onlyoffice/track

上述日志分别指向 JWT 验证失败、会话丢失和回调不可达。

6. 时间同步与 JWT 安全校验

OnlyOffice 默认允许 ±5 分钟的时间偏差。使用以下命令验证 NTP 同步状态：

timedatectl status
chronyc sources -v
ntpq -p

同时检查 OnlyOffice 与 Nextcloud 的 JWT 配置是否一致：

# /etc/onlyoffice/documentserver/local.json
{
  "token": {
    "enable": true,
    "inbox": { "header": "Authorization" },
    "outbox": { "header": "Authorization" }
  },
  "secret": { "browser": "your-shared-secret" }
}

Nextcloud 设置中必须填写相同的密钥。

7. 版本兼容性矩阵与升级建议

OnlyOffice DS	Nextcloud	SharePoint	推荐组合
v7.3	26-28	Online	✅ 稳定
v7.1	25	2019	⚠️ 需补丁
v6.4	>26	-	❌ 不兼容
v7.4	28+	Online	✅ 最佳实践

版本错配可能导致 API 调用失败或回调协议变更。