Docker安装OnlyOffice后无法访问文档编辑界面？

Question

Docker安装OnlyOffice后无法访问文档编辑界面，常见原因包括：1）容器启动后未正确映射HTTP/HTTPS端口（如80/443或自定义端口），导致前端请求超时；2）Nginx反向代理配置缺失或错误（如未透传`X-Forwarded-*`头、未启用WebSocket支持），致使编辑器JS资源加载失败或实时协作断连；3）`JWT_SECRET`未配置或前后端不一致，触发`401 Unauthorized`静默拒绝；4）`documentserver`容器依赖的`redis`或`rabbitmq`服务未就绪，导致后台服务初始化失败，日志中频繁出现`Connection refused`；5）浏览器缓存了旧版JS/CSS或CORS策略拦截跨域资源。建议优先检查`docker logs onlyoffice-document-server`定位首条ERROR，验证`http://host:8000/healthcheck`是否返回`OK`，并确认`/etc/onlyoffice/documentserver/local.json`中`services.CoAuthoring.server.port`与实际暴露端口一致。

Answer 1

```html

一、端口映射与基础连通性验证（表层：网络可达性）

容器启动时若未正确映射 -p 8000:80 或 -p 4433:443，宿主机无法接收HTTP请求。常见误配包括：

• 仅映射内部端口（如 -p 80:80）但宿主机80被占用，导致绑定失败（docker ps 显示 PORTS 为空）；
• 使用 --network host 但忽略 SELinux/firewalld 阻断（RHEL/CentOS需执行 sudo setsebool -P container_connect_any 1）；
• 云服务器未开放安全组端口（如阿里云需手动放行 TCP 8000）。

验证命令：curl -v http://localhost:8000/healthcheck 应返回 HTTP/1.1 200 OK 及响应体 OK。

二、反向代理深度适配（中层：协议语义完整性）

Nginx 不仅是流量转发器，更是 OnlyOffice 协作能力的协议网关。缺失以下任一配置将导致编辑器白屏或协作中断：

配置项	必需值	作用说明
proxy_set_header X-Forwarded-Proto $scheme;	必须	确保文档服务器生成正确的 WebSocket URL（wss:// vs ws://）
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";	必须	启用 WebSocket 长连接，否则 co-authoring 实时同步失效

三、JWT 安全链路一致性（深层：认证上下文统一）

OnlyOffice 文档服务采用双向 JWT 校验机制：前端 SDK 初始化时携带 token，后端 documentserver 通过 JWT_SECRET 解密验证。常见陷阱：

• 环境变量 JWT_SECRET=secret 与前端 JS 中 new DocsAPI.DocEditor(..., {token: "..."}) 的签名密钥不一致；
• 容器内 /etc/onlyoffice/documentserver/local.json 中 "token": {"inbox": {"inbox": {"enable": true, "inbox": "secret"}}} 路径嵌套错误（应为 "inbox": {"enable": true, "inbox": "secret"}）；
• Secret 含特殊字符（如 $、{）未在 Docker Compose 中用单引号包裹：JWT_SECRET: 'my$ecr#t!'。

四、依赖服务健康拓扑（架构层：分布式协同就绪性）

OnlyOffice Document Server 是微服务架构，redis 和 rabbitmq 非可选组件：

graph LR
  A[documentserver] -->|Pub/Sub| B[redis]
  A -->|Task Queue| C[rabbitmq]
  B --> D[Cache for session & lock]
  C --> E[Convert tasks, co-authoring events]
  style A fill:#4CAF50,stroke:#388E3C
  style B fill:#2196F3,stroke:#0D47A1
  style C fill:#FF9800,stroke:#E65100

典型故障日志：Connection refused to redis:6379 表明 Redis 未启动或 network 隔离；AMQP connection failed 多因 RabbitMQ credentials 错误（默认用户 guest/guest 在 3.3+ 版本禁用远程访问）。

五、客户端资源可信链（终端层：浏览器信任域治理）

即使服务端完全正常，前端仍可能失败：

1. 强制清除缓存：Ctrl+Shift+R（Windows/Linux）或 Cmd+Shift+R（macOS），避免旧版 editor.bin.js 加载失败；
2. CORS 报错（Blocked by CORS policy）本质是 Nginx 未透传 Access-Control-Allow-Origin —— OnlyOffice 默认不开启 CORS，需在 local.json 中显式配置："services.CoAuthoring.server.cors": ["*"]；
3. HTTPS 环境下混合内容（Mixed Content）：若 Nginx 终止 HTTPS 但 upstream 用 HTTP，需确保 proxy_set_header X-Forwarded-Proto https; 且文档服务器识别该头。

六、诊断流程图与关键检查点（系统化排障路径）

flowchart TD
  S[Start] --> A[Check docker logs onlyoffice-document-server | grep ERROR]
  A --> B{Healthcheck OK?}
  B -->|No| C[Verify port mapping & firewall]
  B -->|Yes| D[Check /etc/onlyoffice/documentserver/local.json port match]
  D --> E[Validate JWT_SECRET consistency]
  E --> F[Inspect redis/rabbitmq container status]
  F --> G[Review Nginx proxy headers & WebSocket]
  G --> H[Clear browser cache & check DevTools Network tab]
  H --> I[End]

```