ONLYOFFICE Docs 自托管在线办公套件搭建指南

前言

ONLYOFFICE Docs 是一套开源的在线办公套件，提供文档编辑器、表格编辑器、演示文稿编辑器以及 PDF 编辑器四大核心功能，完全兼容 Office Open XML 格式（.docx、.xlsx、.pptx），并支持多人实时协同编辑。与常规的在线文档工具不同，ONLYOFFICE Docs 可以完整部署在你自己的服务器上，文档数据完全由你掌控，不会经过任何第三方服务。社区版采用 AGPL v.3 许可证开源，免费使用，最多支持 20 个用户同时在线编辑。无论是为团队搭建内部协作平台，还是在自己的项目中嵌入文档编辑能力，ONLYOFFICE Docs 都是一个值得考虑的方案。

一、准备工作

1.1 准备一台具备公网IP的云服务器（推荐使用雨云）

优惠注册地址：https://www.rainyun.com/sn_

使用优惠码：sn

注: 使用优惠码注册后绑定微信可领取5折优惠券

服务器选购步骤：

注册后，在"总览"页面找到"云服务器"入口，进入后点击"购买云服务器"

2.根据需求选择合适的配置，建议选择国内的服务器，访问更快，选好后点击立即购买即可

3.选好后进入控制台，使用SSH客户端远程连接服务器即可，SSH客户端建议选择FinalShell

下面以 Ubuntu 22.04 为例，一步步来。

第一步：更新系统软件包

复制代码

sudo apt update && sudo apt upgrade -y

第二步：安装 Docker

可以用官方的一键安装脚本，省事：

复制代码

curl -fsSL https://get.docker.com | sudo sh

安装完成后启动 Docker 服务，并设置开机自启：

复制代码

sudo systemctl start docker
sudo systemctl enable docker

第三步：验证 Docker 安装

复制代码

docker --version

如果能正常显示版本号，比如 Docker version 24.0.7，说明安装成功了。

二、拉取镜像

ONLYOFFICE Docs 官方在 Docker Hub 上提供了两个版本：社区免费版（onlyoffice/documentserver）和开发者版（onlyoffice/documentserver-de）。社区版完全免费，最多支持 20 个用户同时编辑，适合大多数个人和小团队场景。拉取社区版的镜像：

复制代码

docker pull onlyoffice/documentserver

镜像大小大约 1.5GB，拉取时间取决于网络速度。完成后可以用 docker images 命令查看确认。

三、运行容器

拉取完成后，执行下面的命令启动容器：

复制代码

docker run -d \
  --name onlyoffice \
  -p 8080:80 \
  --restart=always \
  -e JWT_ENABLED=true \
  -e JWT_SECRET=你的秘钥 \
  onlyoffice/documentserver

来解释一下每个参数的作用：

-d：后台运行容器，不会占用当前终端。
--name onlyoffice：给容器取一个名字，后续管理起来方便。
-p 8080:80：把容器内部的 80 端口映射到服务器的 8080 端口。如果你想用别的端口，改左边那个数字就行。
--restart=always：容器如果意外停止，Docker 会自动重启它。
-e JWT_ENABLED=true：启用 JWT 身份验证，建议生产环境一定要开。如果只是本地测试，可以改成 false 临时关掉。
-e JWT_SECRET=你的秘钥：设置 JWT 签名用的秘钥，可以自己随便写一串复杂字符，比如 mySuperSecretKey123!。

四、验证服务是否正常运行

容器启动后稍等十几秒，让内部的服务（PostgreSQL、Redis、RabbitMQ 等）完全启动。然后在浏览器地址栏输入：

复制代码

http://你的服务器IP:8080/welcome/

如果看到 ONLYOFFICE 的欢迎页面，恭喜，服务已经跑起来了。

五、配置内网 IP 访问权限

这是一个非常容易踩坑的地方。默认情况下，ONLYOFFICE 出于安全考虑会拒绝来自私有 IP 地址（比如 192.168.x.x、10.x.x.x）的回调请求。如果部署在内网环境，必须手动开启这个权限，否则后续集成第三方系统时会报错。

进入容器内部：

复制代码

docker exec -it onlyoffice bash

编辑配置文件：

复制代码

vi /etc/onlyoffice/documentserver/default.json

在文件中找到 request-filtering-agent 这一节，把下面两项的值改为 true：

json 复制代码

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

保存并退出后，重启容器使配置生效：

复制代码

docker restart onlyoffice

六、配置域名和反向代理（可选）

如果你希望通过域名来访问 ONLYOFFICE，而不是每次都敲 IP 加端口号，可以配置 Nginx 反向代理。这一步不是必须的，但能让使用体验更好。

第一步：安装 Nginx

复制代码

sudo apt install nginx -y

第二步：创建 Nginx 配置文件

复制代码

sudo vi /etc/nginx/sites-available/onlyoffice

写入以下内容（把 your-domain.com 换成你自己的域名）：

复制代码

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

关于 WebSocket 的配置尤其重要。ONLYOFFICE 的实时协作功能依赖 WebSocket 连接来同步编辑操作，如果遗漏了这几行，多人同时编辑时会出现连接失败的问题。

第三步：启用配置并重启 Nginx

复制代码

sudo ln -s /etc/nginx/sites-available/onlyoffice /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

现在就可以直接用 http://your-domain.com/welcome/ 访问 ONLYOFFICE 了。

七、常见问题排查

问题一：启动后无法访问，浏览器打不开页面

先检查防火墙是否放行了端口：

复制代码

sudo ufw status

如果防火墙开着，执行：

复制代码

sudo ufw allow 8080/tcp

再检查 Docker 容器状态：

复制代码

docker ps -a

如果容器状态是 Exited，查看日志找原因：

复制代码

docker logs onlyoffice

问题二：编辑文档后保存时报错

这通常是因为集成的第三方系统（比如 Nextcloud）配置的回调地址用的是 localhost 或 127.0.0.1。ONLYOFFICE 容器内部无法通过这些地址访问到宿主机的服务，需要把配置里的地址改成服务器的实际 IP 地址。

问题三：内网环境回调失败

如果已经按照第五节的步骤配置了 allowPrivateIPAddress 和 allowMetaIPAddress，但还是有问题，检查一下回调地址中是否包含了正确的端口号。有时候 Nginx 转发请求时会丢失端口信息，需要在 Nginx 配置中明确设置 `proxy_set_header Host host:host:host:server_port。

问题四：想要关闭 JWT 验证快速测试

在运行容器的命令中把 -e JWT_ENABLED=true 改成 -e JWT_ENABLED=false 即可。注意，这只适合测试环境，生产环境强烈建议保持开启。

问题五：容器内的演示环境怎么用

镜像里自带了官方的演示程序，可以快速测试文档创建和协同编辑功能。执行下面的命令启动演示环境：

复制代码

docker exec onlyoffice sudo supervisorctl start ds:example

启动后访问 http://你的服务器IP:8080/example 就能看到了。

八、进阶配置建议

数据持久化：如果担心容器重启后配置丢失，可以把容器内的关键目录挂载到宿主机上：

复制代码

docker run -d \
  --name onlyoffice \
  -p 8080:80 \
  -v /app/onlyoffice/logs:/var/log/onlyoffice \
  -v /app/onlyoffice/data:/var/www/onlyoffice/Data \
  --restart=always \
  -e JWT_ENABLED=true \
  -e JWT_SECRET=你的秘钥 \
  onlyoffice/documentserver

启用 HTTPS ：如果域名配置了 SSL 证书，可以在 Nginx 配置中加入 SSL 相关参数，然后把 listen 80 改成 listen 443 ssl。证书可以在雨云免费申请，用 Certbot 工具自动配置就行。

结语

到这里，ONLYOFFICE Docs 就已经在你的云服务器上跑起来了。整个部署过程用 Docker 来操作确实省心很多，不用操心 PostgreSQL、Redis、RabbitMQ 这些依赖的安装和版本兼容问题，一条命令就能拉起一个完整可用的服务。ONLYOFFICE 本身不提供文件存储和管理功能，它更像一个文档编辑引擎，主要负责文件的渲染、编辑和协同同步。实际使用中通常需要搭配 Nextcloud、Seafile 这类云存储平台，或者通过官方提供的 API 集成到自己的应用里。后续如果需要更新版本，执行 docker stop onlyoffice && docker rm onlyoffice 删除旧容器，重新 docker pull 拉取新镜像后再运行即可，数据卷中的配置和日志不会丢失。希望这篇指南能帮你顺利完成部署，少踩几个坑。