当前位置：首页 > news >正文

OnlyOffice私有化部署实战：从Docker Compose到生产环境调优

news 2026/8/16 22:55:41

1. 项目概述：为什么我们需要一个独立的文档协作中心？

最近在帮一个团队做内部文档系统的升级，他们之前一直用着各种在线文档的免费版，协作起来总感觉差点意思。要么是格式兼容性有问题，导入一个复杂的Excel表格排版全乱；要么是担心数据安全，毕竟商业计划书、合同草案这类文件放在第三方平台上，心里总不踏实。他们问我有没有一个能自己掌控、功能又足够强大的方案，我第一个想到的就是OnlyOffice。

OnlyOffice 是什么？简单说，它是一个可以私有化部署的、功能堪比 Microsoft Office 的在线文档协作套件。它包含了文档、电子表格、演示文稿的在线编辑和查看器，支持多人实时协同编辑、评论、版本历史，还能与各种现有的网盘、CRM、OA系统集成。最关键的是，数据完全掌握在自己手里，这对于很多对数据敏感的企业、教育机构或开发团队来说，是刚需。

但“配置OnlyOffice”这个事，听起来简单，真做起来，从环境准备、安装部署、到性能调优、移动端适配，每一步都有不少门道。网上教程很多，但要么过于简略只给命令，要么环境不同直接踩坑。今天，我就结合最近这次实战，把 OnlyOffice 从零到生产环境可用的完整配置流程、核心参数调优以及那些官方文档里不会写的“坑”和技巧，给大家掰开揉碎了讲清楚。无论你是IT运维、项目负责人，还是对自建协作平台感兴趣的开发者，这篇近万字的详录都能给你一份可靠的“抄作业”指南。

2. 部署前的核心考量与方案选型

在动手敲下第一条安装命令之前，花点时间思考整体方案是绝对值得的。盲目照搬教程，很可能导致后期扩容困难、性能瓶颈或安全漏洞。

2.1 社区版 vs. 企业版：不只是并发的区别

首先面临的是版本选择。OnlyOffice 提供社区版和企业版。很多朋友可能听说过“社区版有20并发限制”，但根据最新的网络信息，从 Docs 9.4 版本开始，社区版已正式取消了20并发的硬性限制。这是一个重大利好。但这并不意味着两者没有区别。

社区版：完全免费，功能核心。包含文档、表格、幻灯片的编辑、协同、版本历史、插件支持等。适合中小型团队、个人项目或作为集成组件使用。其性能在优化后，支撑上百人同时在线编辑复杂文档也是可行的。
企业版：需要付费订阅。除了社区版功能，还提供了集群化部署支持、更全面的管理控制台、企业级技术支持、高级安全功能（如文档水印、访问时间限制）以及与特定企业系统（如SAP）的深度集成。

如何选？我的建议是：绝大多数情况下，从社区版开始。除非你的团队规模非常大（超过500人），需要极高的可用性（99.99% SLA）必须做集群，或者对文档安全有极其严格的合规性要求（必须用到水印等），否则社区版的功能和性能已经完全够用。先部署社区版，跑起来，根据实际压力再决定是否升级，这是最稳妥、最经济的路径。

2.2 部署架构：All-in-One 还是组件分离？

OnlyOffice 的核心由几个组件构成：

Document Server：文档编辑和转换的服务端核心，用 Node.js 编写。
数据库：用于存储文档元数据、用户信息等，支持PostgreSQL(推荐)、MySQL/MariaDB。
缓存：使用 Redis 来提升性能。
反向代理：通常用 Nginx 或 Apache，负责SSL、负载均衡和静态文件服务。

官方提供了两种主要的部署方式：

All-in-One 安装（使用官方脚本）：这是最快的方式，一个脚本会自动安装并配置所有组件（包括数据库和Redis）。适合快速体验、测试环境或个人使用。优点是省心，缺点是不够灵活，所有组件挤在一台服务器上，难以单独升级或优化。
手动安装 / Docker 部署：将各个组件分开部署。你可以用 Docker Compose 轻松编排，也可以分别在物理机或虚拟机上安装。这是生产环境的推荐方式。好处显而易见：
- 资源隔离：数据库、Redis、Document Server 可以放在不同服务器，避免资源争抢。
- 独立扩展：如果文档编辑压力大，可以单独横向扩展 Document Server 实例。
- 维护方便：可以单独升级或重启某个组件而不影响其他服务。
- 利用现有设施：如果你已经有在用的 PostgreSQL 或 Redis 集群，可以直接复用。

我的选择与理由：对于生产环境，我强烈推荐使用 Docker Compose 进行部署。它兼具了手动部署的灵活性和 All-in-One 的简便性。一个docker-compose.yml文件就定义了所有服务、网络和卷，一键启停，迁移和备份也极其方便。下面的实操部分也将以 Docker Compose 方式为主线。

2.3 服务器资源规划：别让性能成为瓶颈

部署前，请根据你的预期用户量评估服务器资源。以下是一个参考基准（针对社区版，Docker部署）：

小型团队（< 50人）：
- CPU: 2核
- 内存: 4 GB (给 Document Server 至少分配 2GB)
- 存储: 50 GB SSD (文档存储空间另计)
- 带宽: 5 Mbps 上行（协同编辑对上行带宽要求较高）
中型团队（50 - 200人）：
- CPU: 4核
- 内存: 8 GB
- 存储: 100 GB SSD
- 带宽: 20-50 Mbps 上行
大型团队（> 200人）：
- 考虑将 Document Server、数据库、Redis 分离部署。
- Document Server 节点：4核8G起步，可水平扩展多个实例。
- 数据库服务器：单独配置，根据数据量规划。

重要提示：内存不足是 OnlyOffice 最常见的性能问题根源。Document Server 在转换大型文档（特别是含有大量图片的PPT）时非常吃内存。如果内存不够，会导致转换失败、服务崩溃。宁可CPU弱一点，也要保证足够的内存。

3. 生产环境部署实战：从零到可用

假设我们有一台干净的 CentOS 7 / Ubuntu 20.04 服务器，IP 为192.168.1.100，域名准备为office.your-company.com。我们将使用 Docker Compose 部署全套服务。

3.1 基础环境准备

首先，登录服务器，进行基础配置。

# 更新系统包 sudo apt update && sudo apt upgrade -y # Ubuntu # 或 sudo yum update -y # CentOS # 安装必要的工具 sudo apt install -y curl wget vim git # Ubuntu sudo yum install -y curl wget vim git # CentOS # 安装 Docker 和 Docker Compose # 这里以Ubuntu为例，CentOS请参考Docker官方文档 curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 将当前用户加入docker组，避免每次sudo newgrp docker # 刷新组权限 # 安装 Docker Compose (v2) sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose

3.2 创建项目目录与编写 Docker Compose 文件

为项目创建一个清晰的工作目录。

mkdir -p /opt/onlyoffice cd /opt/onlyoffice

接下来是核心步骤：编写docker-compose.yml。这个文件定义了三个服务：PostgreSQL、Redis、OnlyOffice Document Server。

version: '3.8' services: postgres: image: postgres:13 container_name: onlyoffice-postgres restart: always environment: POSTGRES_DB: onlyoffice POSTGRES_USER: onlyoffice POSTGRES_PASSWORD: YourStrongPassword123! # 务必修改！ volumes: - postgres_data:/var/lib/postgresql/data networks: - onlyoffice-network redis: image: redis:6-alpine container_name: onlyoffice-redis restart: always command: redis-server --requirepass YourRedisPassword123! # 务必修改！ volumes: - redis_data:/data networks: - onlyoffice-network documentserver: image: onlyoffice/documentserver:latest container_name: onlyoffice-documentserver restart: always depends_on: - postgres - redis environment: - DB_TYPE=postgres - DB_HOST=postgres - DB_PORT=5432 - DB_NAME=onlyoffice - DB_USER=onlyoffice - DB_PWD=YourStrongPassword123! # 与上面一致 - REDIS_SERVER_HOST=redis - REDIS_SERVER_PORT=6379 - REDIS_SERVER_PASS=YourRedisPassword123! # 与上面一致 - JWT_ENABLED=true # 强烈建议开启，用于安全通信 - JWT_SECRET=YourSuperSecretJWTKeyHere # 务必修改！建议用长随机字符串 - JWT_HEADER=AuthorizationJwt volumes: - ds_data:/var/www/onlyoffice/Data - ds_logs:/var/log/onlyoffice - ./fonts:/usr/share/fonts/truetype/custom # 挂载自定义字体目录 ports: - "8080:80" # 临时映射，后续会用Nginx代理 networks: - onlyoffice-network # 资源限制建议，根据服务器配置调整 deploy: resources: limits: memory: 2G reservations: memory: 1G volumes: postgres_data: redis_data: ds_data: ds_logs: networks: onlyoffice-network: driver: bridge

关键参数解释：

JWT_ENABLED和JWT_SECRET：这是安全集成的关键。当你的前端（如Nextcloud、Confluence等）调用OnlyOffice时，需要通过JWT令牌进行身份验证和授权，防止未授权访问。JWT_SECRET必须是一个强密码，且与前端配置的密钥一致。
挂载卷：将数据、日志和字体目录挂载出来，避免容器删除后数据丢失。自定义字体挂载可以解决中文文档显示缺字的问题。
资源限制：给documentserver服务设置了内存限制，防止其占用过多资源影响宿主机。

3.3 启动服务与初步验证

保存好docker-compose.yml后，启动服务。

# 在 /opt/onlyoffice 目录下执行 docker-compose up -d

使用docker-compose ps和docker-compose logs -f documentserver查看状态和日志，等待所有服务状态变为Up，并且 Document Server 日志中出现"Server started"之类的信息。

然后，在浏览器访问http://你的服务器IP:8080/welcome/。如果看到 OnlyOffice 的欢迎页面，说明核心服务已经成功运行。

注意：这只是内部测试。生产环境绝不能直接暴露8080端口。我们需要配置域名和 HTTPS。

3.4 配置 Nginx 反向代理与 HTTPS

关闭临时的端口映射，改为通过 Nginx 代理。修改docker-compose.yml中documentserver的端口映射，去掉- "8080:80"，因为我们不再需要直接从主机访问。

安装并配置 Nginx：

sudo apt install -y nginx # Ubuntu sudo yum install -y nginx # CentOS

创建 Nginx 配置文件/etc/nginx/sites-available/onlyoffice(Ubuntu) 或/etc/nginx/conf.d/onlyoffice.conf(CentOS)：

upstream onlyoffice_backend { server 127.0.0.1:8080; # 这里指向的是Docker容器在宿主机网络映射的端口 # 如果你在docker-compose中使用了host网络，或者容器有独立IP，请相应修改。 # 更可靠的方式是使用Docker内部网络名，但需要Nginx也在Docker中。这里用宿主机端口映射。 # 我们在下一步会修改docker-compose，将容器端口映射到宿主机的某个端口（如8081），但不对公网开放。 } server { listen 80; server_name office.your-company.com; # 你的域名 return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name office.your-company.com; ssl_certificate /path/to/your/fullchain.pem; # SSL证书路径 ssl_certificate_key /path/to/your/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # 提高上传文件大小限制 client_max_body_size 100M; location / { proxy_pass http://onlyoffice_backend; 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; proxy_set_header X-Forwarded-Host $host; # 重要：设置超时时间，避免长连接任务失败 proxy_read_timeout 3600s; proxy_send_timeout 3600s; } # 静态文件缓存优化 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ { proxy_pass http://onlyoffice_backend; expires 1y; add_header Cache-Control "public, immutable"; access_log off; } }

修改docker-compose.yml，将documentserver的端口映射改为仅映射到本地回环地址，避免公网直接访问：

ports: - "127.0.0.1:8081:80" # 只允许本机访问

然后更新 Nginx 配置中的upstream指向127.0.0.1:8081。

重新启动服务并启用 Nginx 配置：

cd /opt/onlyoffice docker-compose down docker-compose up -d sudo nginx -t # 测试配置 sudo systemctl reload nginx # 重载配置

现在，你应该可以通过https://office.your-company.com安全地访问 OnlyOffice 欢迎页面了。

4. 深度配置与性能调优

基础服务跑通只是第一步，要让其稳定、高效地服务于生产，还需要进行一系列深度配置。

4.1 解决中文与特殊字体显示问题

默认安装的 OnlyOffice 镜像缺少常见的中文字体（如宋体、黑体、楷体），这会导致打开或编辑含有这些字体的文档时，字体被替换，排版错乱。

解决方案：添加自定义字体。

在宿主机上准备字体文件。你可以从一台装有完整中文字体的 Windows 或 Linux 机器上拷贝，或者下载开源字体（如思源系列）。
在/opt/onlyoffice目录下创建fonts文件夹，并将所有.ttf或.ttc字体文件放入。
我们已经在上面的docker-compose.yml中配置了字体卷挂载：- ./fonts:/usr/share/fonts/truetype/custom。
重新启动 Document Server 容器，使其加载新字体。

docker-compose restart documentserver

为了验证字体是否生效，可以进入容器内部查看：

docker exec -it onlyoffice-documentserver bash fc-list | grep -i "simsun" # 查找宋体

4.2 性能调优：应对“打开预览慢”的挑战

“移动端使用OnlyOffice预览文件太慢”和“手机预览打开特别慢”是高频问题。这通常不是 OnlyOffice 本身慢，而是网络、服务器资源或配置问题。以下是一套组合拳：

1. 服务器端优化：

确保足够内存：如前所述，内存是关键。监控容器内存使用（docker stats），确保没有频繁交换（swap）。
使用 SSD 存储：文档的读取、写入、缓存都依赖磁盘IO，SSD能极大提升响应速度。
调整 Document Server 配置：编辑环境变量，可以调整一些内部参数。创建一个自定义配置文件local.json并挂载到容器中是一个更优雅的方式。但通过环境变量调整工作进程数是一个快速方法（在docker-compose.yml中为documentserver添加）：
```
environment: ... - SERVICES_PLUGIN_COUNT=2 # 插件服务进程数 - SERVICES_DOCSERVICE_COUNT=2 # 文档服务进程数 - SERVICES_CONVERTER_COUNT=2 # 转换服务进程数
```
这些值需要根据你的 CPU 核心数来调整，通常设置为 CPU 核心数或稍多一点。不要盲目设置过高，会增加内存消耗和进程切换开销。

2. 网络与前端优化：

启用并优化 HTTPS：使用 HTTP/2 和 TLS 1.3，减少连接开销。

启用 Gzip/Brotli 压缩：在 Nginx 配置中启用，减小传输体积。

gzip on; gzip_vary on; gzip_min_length 1024; gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;

配置浏览器缓存：如上面 Nginx 配置中对静态文件的缓存设置，可以极大减少重复加载。
使用 CDN：如果用户分布广泛，可以考虑将 OnlyOffice 的静态资源（JS、CSS、字体）托管到 CDN，但这需要修改 OnlyOffice 的配置，较为复杂。

3. 移动端特定优化：

前端集成时启用“紧凑工具栏”：在调用 OnlyOffice 的配置中，设置toolbarNoTabs: true或使用移动端专用的配置模式，可以减少初始加载的UI组件。
避免首次加载过大文档：对于移动端，可以考虑先提供文档的 PDF 预览链接，用户需要编辑时再加载完整的编辑器，这是一种体验上的折中。

4.3 安全加固配置

JWT 密钥保护：确保JWT_SECRET是足够长且复杂的随机字符串，并妥善保管。前端和后端的密钥必须一致。
数据库密码：修改默认的数据库密码，使用强密码。
限制访问来源：在 Nginx 层面，可以通过allow/deny指令限制只有特定的前端服务器 IP 可以访问/coauthoring/等API接口，防止 API 被滥用。
定期更新：关注 OnlyOffice 官方镜像的更新，定期（如每季度）更新到稳定版本，修复安全漏洞。
防火墙配置：确保服务器防火墙只开放 80/443 端口，关闭其他所有不必要的端口。

5. 高级功能配置与集成

5.1 配置文档对比（Side by Side Compare）

“onlyoffice可以做到side by side比对吗？” 答案是可以。OnlyOffice 内置了文档比较功能，但需要通过 API 调用来触发。

它并不是在编辑器界面上直接提供一个“比较”按钮，而是需要你的前端应用（例如你的网盘系统）实现这样的逻辑：用户选择两个文件 -> 前端调用 OnlyOffice 的转换 API 将两个文件都转换为可比较的格式 -> 再调用 OnlyOffice 的编辑 API，打开一个包含了比较结果的“合并文档”。

核心的 API 调用涉及diff方法。你需要参考 OnlyOffice 的 API 文档来在你的集成代码中实现。对于最终用户来说，体验就是在你的系统里点击“比较两个文档”，然后在一个 OnlyOffice 编辑器窗口里看到带有修订标记的对比结果。

5.2 与第三方应用集成（示例：Nextcloud）

OnlyOffice 最大的价值之一就是作为协作引擎嵌入其他系统。以 Nextcloud 为例：

在 Nextcloud 应用商店中安装 “OnlyOffice” 应用。
在 Nextcloud 管理设置中，找到 OnlyOffice 配置页面。
填写你的 OnlyOffice Document Server 地址：https://office.your-company.com。
在“Secret key”栏位，填入你在docker-compose.yml中设置的JWT_SECRET。
保存后，Nextcloud 会测试连接。成功的话，在 Nextcloud 中点击 Office 文件，就会直接调用你的 OnlyOffice 服务器进行在线编辑。

关键点：确保 Nextcloud 服务器能通过网络访问到你的 OnlyOffice 地址，并且 JWT 密钥完全一致。这是集成成功与否最常见的绊脚石。

6. 运维监控与故障排查

6.1 日志查看与监控

日志是排查问题的第一手资料。

Document Server 日志：docker-compose logs -f documentserver查看实时日志。错误信息通常在这里。
访问日志：Nginx 的访问日志 (/var/log/nginx/access.log) 和错误日志 (/var/log/nginx/error.log) 可以帮你分析请求是否到达、是否有4xx/5xx错误。
系统监控：使用docker stats监控容器资源使用情况。对于生产环境，建议集成 Prometheus + Grafana 来监控容器和服务的各项指标（CPU、内存、网络、文档转换队列长度等）。

6.2 常见问题与解决方案实录

以下是我在部署和运维中实际遇到过的坑及其解决方法：

问题1：上传大文件失败，提示“413 Request Entity Too Large”。

原因：Nginx 默认限制客户端上传文件大小为 1MB。
解决：在 Nginx 配置文件的server或location /块中增加client_max_body_size 100M;（值根据你需要调整）。

问题2：编辑文档时，提示“文档安全令牌无效”或“下载失败”。

原因：几乎可以肯定是JWT 配置错误。前端（如Nextcloud）发送的 JWT 令牌与 Document Server 验证使用的密钥不匹配，或者令牌已过期。
解决：
1. 检查 Document Server 环境变量JWT_ENABLED是否为true。
2. 检查JWT_SECRET是否与前端应用配置的密钥完全一致（注意首尾空格）。
3. 确保服务器时间同步。使用ntpdate或配置systemd-timesyncd。

问题3：文档转换（如PDF转Word）特别慢，或经常超时失败。

原因：转换服务进程 (libreoffice) 资源不足，或文档本身过于复杂。
解决：
1. 增加 Document Server 容器的内存限制。
2. 调整环境变量，增加转换服务进程数SERVICES_CONVERTER_COUNT。
3. 在 Nginx 和 Document Server 的调用链中，增加超时时间（如上面 Nginx 配置中的proxy_read_timeout）。
4. 检查宿主机磁盘 IO 是否成为瓶颈。

问题4：多人同时编辑时，部分用户的操作同步延迟高。

原因：网络延迟，或 Redis 性能瓶颈。
解决：
1. 确保 Redis 运行在内存充足的环境中，可以考虑将 Redis 数据持久化关闭以提升性能（如果允许数据短暂丢失）。
2. 检查服务器网络带宽，特别是上行带宽是否被占满。
3. 如果用户地理分布广，考虑在不同区域部署多个 Document Server 实例，并通过全局负载均衡调度。

问题5：如何备份与恢复？

备份：
1. 文档文件：位于 Docker 卷ds_data映射的宿主机目录（/var/lib/docker/volumes/...或你自定义的路径）。定期打包备份这个目录。
2. 数据库：使用pg_dump命令备份 PostgreSQL 数据库。docker exec onlyoffice-postgres pg_dump -U onlyoffice onlyoffice > backup.sql
3. 配置：备份你的docker-compose.yml和 Nginx 配置文件。
恢复：
1. 在新环境启动空服务。
2. 恢复数据库：cat backup.sql | docker exec -i onlyoffice-postgres psql -U onlyoffice
3. 将备份的文档文件目录覆盖到新的数据卷位置。
4. 重启服务。

部署和配置 OnlyOffice 就像搭建一个精密的数字车间，每个环节都需要仔细校准。从版本选择、架构设计到每一行环境变量的配置，都直接影响着最终用户的体验和系统的稳定性。这次为团队部署的经历，让我再次体会到“细节决定成败”的道理。尤其是 JWT 密钥和字体这两个看似小的问题，一旦忽略，就会导致集成失败和排版灾难，消耗大量排查时间。

对于想要上生产环境的朋友，我的最终建议是：先在一个非核心的测试环境里，严格按照流程走一遍，模拟各种操作（上传、编辑、协同、大文件转换），并做好压力测试。把该踩的坑在测试环境踩完，记录下所有配置参数和调整步骤，形成你自己的部署手册。这样，当你在真正的生产服务器上操作时，就会从容得多。OnlyOffice 一旦稳定运行起来，它带来的高效、安全的协作体验，绝对会让你觉得前期的这些投入是值得的。

查看全文

http://www.jsqmd.com/news/1407399/