自建 ONLYOFFICE 文档服务:保姆级部署教程-夜雨聆风

自建 ONLYOFFICE 文档服务:保姆级部署教程

ONLYOFFICE 是一款开源的办公套件，支持在线编辑 Word、Excel、PPT 文档。它最大的优势是兼容性好——对微软 Office 格式的渲染几乎完美，不像 LibreOffice 那样经常出现排版错乱。

本文手把手教你用 Docker 部署 ONLYOFFICE Document Server，搭配 Nginx 反向代理和 HTTPS，最后与 Nextcloud 集成。全程可操作性，按步骤来就行。

一、方案对比：哪个版本适合你

ONLYOFFICE 提供了几个不同的部署形态，别搞混了：

本文以 Document Server + Nextcloud 集成为主线，这是最通用的方案。如果你只需要一个纯文档编辑服务，步骤完全一样。

二、前置条件

一台 Linux 服务器（Ubuntu 22.04 / Debian 12 最佳）
最低配置：2 核 CPU、4 GB 内存（生产环境建议 4 核 8 GB）
已安装 Docker 和 Docker Compose v2
一个域名（如 doc.example.com），解析到服务器 IP
开放防火墙端口：80 和 443

先确认 Docker 环境就绪：

# 检查 Docker 版本docker --versiondocker compose version

三、Docker Compose 部署（推荐）

3.1 创建目录结构

mkdir -p /opt/onlyofficecd /opt/onlyoffice

3.2 编写 docker-compose.yml

创建 docker-compose.yml：

version: '3.8'services: onlyoffice-documentserver: image: onlyoffice/documentserver:latest container_name: onlyoffice-ds restart: always ports: - ”127.0.0.1:8080:80” environment: JWT_SECRET: your-strong-jwt-secret-here JWT_ENABLED: true volumes: - ./data:/var/www/onlyoffice/Data - ./logs:/var/log/onlyoffice - ./lib:/var/lib/onlyoffice - ./db:/var/lib/postgresql networks: - onlyoffice-netnetworks: onlyoffice-net: driver: bridge

⚠️ 注意：端口只绑定到 127.0.0.1，不让服务直接暴露公网。后面通过 Nginx 反向代理访问，这是安全最佳实践。

3.3 启动服务

docker compose up -d

首次启动会拉取镜像，耗时 1-3 分钟。之后查看日志确认启动正常：

docker compose logs -f

看到类似 “ready to handle connections” 的日志就说明启动成功了。此时在服务器本地可以验证：

curl -s http://127.0.0.1:8080/healthcheck

返回 {“status”:0,”desc”:”service is running”} 表示服务正常。

四、配置 Nginx 反向代理 + HTTPS

ONLYOFFICE 要求通过 HTTPS 访问（因为浏览器安全策略），所以必须配 SSL 证书。我们使用 Certbot 自动申请 Let’s Encrypt 证书。

4.1 安装 Nginx 和 Certbot

# Ubuntu / Debiansudo apt updatesudo apt install -y nginx certbot python3-certbot-nginx

4.2 编写 Nginx 配置

创建 /etc/nginx/sites-available/onlyoffice：

upstream onlyoffice { server 127.0.0.1:8080;}server { listen 80; server_name doc.example.com; location / { proxy_pass http://onlyoffice; 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;# ONLYOFFICE 需要较大的请求体 client_max_body_size 100m;# WebSocket 支持 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection ”upgrade”; }}

4.3 启用站点并申请 SSL 证书

# 启用站点sudo ln -s /etc/nginx/sites-available/onlyoffice /etc/nginx/sites-enabled/# 测试配置sudo nginx -t# 申请证书（会自动修改 Nginx 配置启用 HTTPS）sudo certbot --nginx -d doc.example.com# 重载 Nginxsudo systemctl reload nginx

Certbot 会自动配置 SSL 证书和 HTTPS 重定向。完成后访问 https://doc.example.com，应该能看到 ONLYOFFICE 的欢迎页面。

💡 提示： Certbot 会自动添加定时任务续期证书。你也可以手动验证续期：sudo certbot renew –dry-run

五、集成 Nextcloud

这是最常用的场景——在 Nextcloud 中直接用 ONLYOFFICE 编辑文档。

5.1 安装 ONLYOFFICE 插件

在 Nextcloud 管理员界面操作：

# 进入 Nextcloud 安装目录cd /var/www/nextcloud/appssudo -u www-data php /var/www/nextcloud/occ app:install onlyoffice

5.2 配置插件

安装完成后，进入Nextcloud 设置 → ONLYOFFICE，填写以下信息：

⚠️ 重要： JWT 密钥必须一致，否则 Nextcloud 无法连接 ONLYOFFICE！如果部署后编辑文档时提示”文档服务不可用”，90% 是这个原因。

5.3 检查连接

配置完成后，保存设置。Nextcloud 会自动测试连接。如果看到绿色的”验证成功”提示，就搞定了。

现在在 Nextcloud 中打开任意 Office 文档，应该会直接在 ONLYOFFICE 编辑器中打开。

六、验证安装

部署完成后，做几个快速验证：

七、常见问题 & 排错

❌ “文档服务不可用”

检查 JWT 密钥是否一致
检查 ONLYOFFICE 容器是否正常运行：docker ps | grep onlyoffice
Nextcloud 的”内部服务器地址”是否配置正确（容器间通信用内网地址）
检查防火墙是否放行了 443 端口

❌ 文档打开空白或加载中

检查 Nginx 是否正确配置了 WebSocket 代理（proxy_set_header Upgrade 和 Connection “upgrade”）
检查浏览器控制台是否有跨域（CORS）错误
尝试用无痕模式打开

❌ 容器启动后立刻退出

检查日志：docker compose logs
最常见原因：内存不足。ONLYOFFICE 至少需要 4 GB 内存
检查端口 8080 是否被占用

❌ 证书续期失败

检查域名解析是否正确
检查 80 端口是否可访问（Let’s Encrypt 验证需要 80 端口）
手动续期测试：sudo certbot renew –dry-run

总结

部署完成后的架构：

用户浏览器 → HTTPS → Nginx (SSL 终止) → 127.0.0.1:8080 → ONLYOFFICE Document Server ↕ Nextcloud (ONLYOFFICE 插件)

整个部署流程大概 15-20 分钟就能完成。记住几个关键点：

JWT 密钥要一致（Nextcloud 和 ONLYOFFICE 都要配）
ONLYOFFICE 端口不要暴露公网，用 Nginx 反代
WebSocket 代理必须配置，否则文档打不开
内存至少 4 GB，别省

如果你在部署过程中遇到问题，先看日志——docker compose logs 和 nginx error.log 能解决 90% 的问题。

⭐ 如果本文对你有帮助，欢迎分享给更多需要的人！

⭐ 如果你觉得这个项目不错，去 GitHub 点个 Star 支持一下！

https://github.com/ONLYOFFICE/

有问题欢迎在评论区交流 👋