OnlyOffice 社区版 Docker 部署及文档无法保存问题排查

OnlyOffice 社区版 Docker 部署及文档无法保存问题排查 | 极客日志

OnlyOffice 社区版 Docker 部署及文档无法保存问题排查

一、OnlyOffice 社区版 Docker 通用部署

以下是一份通用的 docker-compose.yml 配置，适合测试或内网场景。

version: '3'
services:
  onlyoffice-docs:
    container_name: onlyoffice-docs
    image: onlyoffice/documentserver:latest
    ports:
      - "19898:80"
    restart: always
    environment:
      - TZ=Asia/Shanghai
      - JWT_ENABLED=false
    volumes:
      - ./onlyoffice-logs:/var/log/onlyoffice
      - ./onlyoffice-data:/var/www/onlyoffice/Data
      - ./onlyoffice-lib:/var/lib/onlyoffice
      - ./onlyoffice-db:/var/lib/postgresql

启动命令：

# 新建挂载目录并赋权
mkdir onlyoffice
cd onlyoffice
mkdir logs data lib db

# 后台启动容器
docker-compose up -d

启动后访问 http://你的服务器 IP:19898，即可看到 OnlyOffice 的初始化页面。

二、测试时的致命报错：文档无法保存

按提示启动内置测试示例（验证编辑功能）：

docker exec 9a13fd45d2d6 sudo supervisorctl start ds:adminpanel

添加自动启动：

docker exec 9a13fd45d2d6 sudo sed 's,autostart=false,autostart=true,' -i /etc/supervisor/conf.d/ds-adminpanel.conf

检查是否启动：

docker exec -it onlyoffice sudo supervisorctl status ds:example

然后点击 GO TO ADMIN PANEL 打开测试示例新建 Word 文档，弹出警告：

The document could not be saved. Please check connection settings or contact your administrator.

查看容器日志（docker logs onlyoffice-docs），发现反复出现核心错误：

Error: DNS lookup 私有 IP 段 (如 192.168.x.x) is not allowed. Because, It is private IP address.

三、报错根源：主次问题要分清

1. 致命核心：OnlyOffice 的私有 IP 安全限制

OnlyOffice 为了防止恶意回调，默认禁止向私有 IP（192.168.x.x/10.x.x.x/172.x.x.x）发送请求。而测试示例会向宿主机私有 IP 发送'文档状态回调'，直接被拦截，导致保存失败。

四、分步解决：先破核心限制

步骤 1：解除私有 IP 访问限制（核心）

OnlyOffice 的精简镜像默认没有 vi/vim 编辑器，这里提供两种通用解决方法。

方法 A：安装 Vim 后手动改配置

进入容器并安装 Vim：

docker exec -it onlyoffice-docs bash
apt update && apt install -y vim

编辑配置文件 /etc/onlyoffice/documentserver/default.json：

vim /etc/onlyoffice/documentserver/default.json

在 services.CoAuthoring 节点下添加/修改配置（按 i 进入编辑模式）：

"request-filtering-agent": {
  "allowPrivateIPAddress": true,
  "allowMetaIPAddress": true
},

保存退出（按 ESC → 输入 :wq），最后退出容器，然后重启容器：

docker-compose restart

五、验证：文档保存功能恢复

重新访问测试示例（http://你的服务器 IP:19898/example），新建文档编辑后点'保存'，不再弹出报错——核心问题解决！

六、OnlyOffice 部署避坑提醒

测试示例仅用于验证：内置测试示例是 Demo 级功能，绝对不能用于生产环境，上线前需禁用（supervisorctl stop ds:example）。
生产环境安全配置：
- 必须开启 JWT 验证（修改 JWT_ENABLED=true 并配置密钥）；
- 私有 IP 限制（allowPrivateIPAddress）在生产环境建议关闭，改用'IP 白名单'控制回调地址。
镜像选择：优先用官方 onlyoffice/documentserver 镜像，避免第三方镜像的兼容性问题。

OnlyOffice 社区版 Docker 部署及文档无法保存问题排查