OnlyOffice 私有化部署完全指南：从 Docker 安装到踩坑排查

OnlyOffice在线文档协作私有化部署

于 2026-10-02 05:35:03 修改

·本内容遵循CC 4.0 BY-SA版权协议

最近在社群里被问到最多的问题之一，就是“为什么越来越多人用 OnlyOffice”。作为一个给企业和开源社区做过多次办公套件部署的人，我可以负责任地说，OnlyOffice 的火不是营销推出来的，是需求逼出来的。它的核心场景非常清晰：把文档、表格、演示文稿放到自己的服务器上，打开浏览器就能编辑，还能多人同时协作，而这一切完全可控、可私有化。

这篇内容我不打算做功能罗列，而是从“为什么选它”“怎么装”“装完怎么配”“踩了哪些坑”几个角度，把 OnlyOffice 的实际使用体验和部署细节讲透。无论你是公司 IT 想给团队搭一套在线办公环境，还是个人用户想摆脱来回传文件的尴尬，这篇文章都值得看完。

1. OnlyOffice 为什么突然被这么多人盯上

1.1 它解决的是办公协同“最后一公里”的问题

先说一个很现实的场景：以前团队改一份方案，要么用微信传来传去，文件名后缀加“最终版”“最终版2”“打死不改版”，要么用网盘共享但编辑时要下载下来，改完再传回去，版本混乱到崩溃。OnlyOffice 做的事情，就是把文档直接放在网页里，大家打开同一个链接，实时改同一份内容，每个协作者的光标和选中区域都能实时可见。

这套能力听起来不稀奇，因为微软 Office 365 和 Google Docs 已经做了很多年。但问题在于，这两家的数据都在别人服务器上，对于很多企业来说，数据合规、本地化存储、离线容灾都是硬要求。OnlyOffice 的定位很清楚：可以部署到你自己的服务器，数据不出内网，代码开源，还可以和现有的网盘、 OA、知识库系统通过 API 集成。这就是它解决的核心问题——把在线协同能力拉回了“自托管”这个赛道上。

对个人用户来说，OnlyOffice 同样有吸引点。你不需要注册任何云端账号，不需要担心文档被平台扫描，在家里一台小服务器上跑起来，全家人、全宿舍都能用自己的账号访问。加上它的界面风格非常接近微软 Office，初次上手几乎不需要学习成本，这也是我敢直接推荐给非技术朋友的原因。

1.2 和微软 Office、LibreOffice 正面比一下

要理解 OnlyOffice 为什么“越来越多人用”，对比是最直观的方式。我用了很多年的 LibreOffice，也长期订阅过微软 Office，这里只从部署和技术角度说说差异：

维度	OnlyOffice	LibreOffice	微软 Office 365
部署方式	可私有化部署、有社区版	桌面版为主，也有 Collabora 在线版	仅云端订阅，无法自托管
在线协作	原生支持，实时协同编辑	需要额外搭配 Collabora Online	支持，但要求账号在微软体系内
格式兼容度	对 docx/xlsx/pptx 兼容性很好	兼容性良好但复杂排版偶有错位	原生格式，兼容性最好
API/集成能力	提供 Document Server API、JWT 鉴权	有限，需要通过 UNO 接口	有 API 但受限于云平台
成本	社区版免费，企业版按用户收费	免费	按席位订阅，长期成本高

这个表格已经很说明问题了。LibreOffice 强在桌面离线编辑，但在线协同部署复杂度高、协作体验一般；微软强在全家桶生态，但数据不在你手里。OnlyOffice 恰好卡在中间——既可以私有化，又有完整的协同体验，而且它和微软文档格式的兼容度在开源项目里属于第一梯队。我实测把一个带复杂表格、页眉页脚和批注的 docx 文件传上去，打开后基本不变形，这个体验已经很接近云端 Office 了。

1.3 从安装热词看用户结构

最近“onlyoffice安装问题”和“onlyoffice server 下载地址”这两个词的搜索量涨得很明显。搜索量高说明什么？说明有一大波人已经从“想用”进入“想装”的阶段了，但是拦在第一步的部署问题劝退了不少人。OnlyOffice 的安装并不算无脑，官网给的安装文档偏向企业级，涉及 PostgreSQL、RabbitMQ、Nginx 多个组件，新手很容易在依赖环节卡住。

这篇文章后面会专门讲安装实操和问题排查，目的就是把“用起来”这件事的门槛降下来。热词背后其实是一群真实用户的需求画像：想部署、卡在安装、找不到可靠的下载入口。这三个痛点正好对应本篇文章的第二、三、四章。

2. 部署方案选型：Docker 优先还是包管理器优先

2.1 先确认硬件和系统基础，别在一开始就踩坑

部署 OnlyOffice 前先回答一个最基本的问题：机器够不够用。OnlyOffice 的后端服务其实不止一个进程，包含文档转换服务、协同编辑服务、数据库、消息队列、缓存等。我自己的经验是，2 核 4G 内存的机器跑演示环境没问题，一旦有超过 10 个人同时在线编辑大文档，内存会明显吃紧。

如果做公司内部正式使用，建议至少 4 核 8G 起步，磁盘给 SSD，存储空间按文档增长量预留 100G 以上比较稳妥。操作系统方面，官方支持主流 Linux 发行版，Ubuntu 20.04/22.04 和 Debian 系最省心，CentOS 7 也能跑但依赖处理稍麻烦。Windows 和 macOS 上也可以通过 Docker Desktop 跑，但不建议生产环境这么做。

关于服务器系统，还有一点要提醒：不要用太老的系统内核版本。OnlyOffice 的容器镜像依赖较新的内核特性，我在一台内核 3.10 的旧服务器上装 Docker 版遇到过存储驱动兼容问题，换到 Ubuntu 22.04 后一切正常。如果机器系统太老，先升级系统再折腾 OnlyOffice，省下的时间够你多配两遍 nginx。

2.2 Docker Compose 一键部署的完整步骤

如果你是第一次接触 OnlyOffice，我强烈建议直接走 Docker Compose 路线。原因很简单：依赖组件全部封装在容器里，不会污染宿主机环境，卸载也干净。之前用 apt 安装方式折腾过一遍，依赖包多到头皮发麻，中途搞坏过系统 Python 环境，后来全部改为容器化部署，再没出过这类问题。

首先确认 Docker 和 Docker Compose 已安装：

BASH

docker --version

docker compose version

如果还没装，Ubuntu 下执行：

BASH

sudo apt update

sudo apt install docker.io docker-compose-v2 -y

sudo systemctl enable --now docker

然后找一个目录，比如 ~/onlyoffice，创建 docker-compose.yml：

YAML

services:

onlyoffice-documentserver:

image: onlyoffice/documentserver:latest

container_name: onlyoffice-documentserver

restart: always

ports:

- "8080:80"

environment:

- JWT_ENABLED=true

- JWT_SECRET=your-strong-secret-key

volumes:

- onlyoffice_data:/var/log/onlyoffice

- onlyoffice_data:/var/www/onlyoffice/Data

- onlyoffice_data:/var/lib/onlyoffice

- onlyoffice_data:/var/lib/postgresql

- onlyoffice_data:/var/lib/rabbitmq

- onlyoffice_data:/var/lib/redis

启动：

BASH

docker compose up -d

等日志稳定后，浏览器访问 http://你的服务器IP:8080，能看到欢迎页就说明安装成功。这个镜像里已经内置了 PostgreSQL、RabbitMQ、Redis 和 Nginx，一个容器包含全部依赖，这也是官方推荐的最简部署方式。需要注意的是，新版 Docker Compose 命令是 docker compose（中间有空格），旧版 docker-compose 也能用但建议升级。

关于 “onlyoffice server 下载地址”，这里明确一下：个人用户最靠谱的下载入口就是官方 GitHub Releases 页面和 Docker Hub 镜像仓库。Docker 方式直接写 onlyoffice/documentserver，系统安装包则在官网下载中心能找到对应发行版的 deb/rpm 包，不建议从第三方博客的私链下载，版本来源不明不说，还容易带上被修改的组件。

2.3 包安装方式与依赖注意事项

不使用 Docker 的情况下，OnlyOffice 官方提供 deb 和 rpm 包安装方式。这种方式的优点是不依赖容器环境，服务直接在宿主机上跑，适合对容器有顾虑的运维团队。但缺点也很明显：需要手动安装和配置一堆依赖，包括 PostgreSQL、RabbitMQ、Nginx、Node.js、Redis，还要处理它们之间的启动顺序。

Ubuntu 下的安装命令如下：

BASH

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys CB2DE8E5

sudo echo "deb https://download.onlyoffice.com/repo/debian squeeze main" | sudo tee /etc/apt/sources.list.d/onlyoffice.list

sudo apt update

sudo apt install onlyoffice-documentserver

安装过程中会让你配置 PostgreSQL 密码和 RabbitMQ 密码，务必记下来，后面改配置要用的。装完之后，服务会自动注册到 systemd，常用操作：

BASH

sudo systemctl status ds-example

sudo systemctl restart ds-example

这里提醒一个关键点：如果你没有独立部署 PostgreSQL 和 RabbitMQ，官方安装包会在本机自动装好一套。但如果你机器上已经存在 PostgreSQL 实例，安装脚本可能不会自动创建数据库，需要手动建库建用户，很多人在这一步卡住。包安装方式更适合有一定 Linux 运维经验的人，新手直接上 Docker 省心得多。

3. 配置里那些不配会踩坑的关键点

3.1 域名、端口与反向代理配置

默认情况下，OnlyOffice 容器监听 8080 端口，如果只是内网临时体验，直接 IP 访问没问题。但正式使用，特别是需要多人协作、对接其他系统的时候，域名和 HTTPS 几乎必须配。

原因很简单：OnlyOffice 的文档协同需要浏览器与服务器之间保持 WebSocket 长连接，而现代浏览器在 HTTPS 页面下默认禁止调用非 HTTPS 的 WebSocket 接口。如果你的 OnlyOffice 跑在 HTTP 上，而页面入口是在 HTTPS 域名下，协同功能会莫名其妙失效。

我通常的做法是用 Nginx 做反向代理，加上 Let’s Encrypt 证书。Nginx 配置示例：

NGINX

server {

listen 80;

server_name onlyoffice.example.com;

rewrite ^(.*) https://$server_name$1 permanent;

}

server {

listen 443 ssl http2;

server_name onlyoffice.example.com;

ssl_certificate /etc/letsencrypt/live/onlyoffice.example.com/fullchain.pem;

ssl_certificate_key /etc/letsencrypt/live/onlyoffice.example.com/privkey.pem;

client_max_body_size 512m;

location / {

proxy_pass http://127.0.0.1:8080;

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 https;

}

重点在于 proxy_set_header Upgrade 和 Connection "upgrade" 两行，这是 WebSocket 能否正常转发到后端的关键。少了这两行，文档在多人同时打开时只会显示“可查看”，协作者列表拉不到人，光标同步失效，而且问题非常隐蔽，日志里什么都看不出来。另外，client_max_body_size 一定要加大，默认 1M 会让稍大的文档上传直接返回 413 错误。

3.2 JWT 密钥与第三方集成

OnlyOffice 默认开启了 JWT 鉴权，目的是保护文档编辑接口不被随意调用。如果你只用官方界面打开文档，JWT 是透明的，不需要额外处理。但如果你要通过 API 把 OnlyOffice 嵌入到自己的系统，或者用 Nextcloud、ownCloud、Alfresco 这些平台对接，就必须把 JWT 密钥配置成一致。

Docker 部署时，在环境变量里已经设置了 JWT_SECRET，第三方平台的插件设置页也需要填同一个值。这里要特别强调：不要用默认密钥，网上流传的默认值早就被扫描工具记录，一旦你的服务暴露到公网，任何人都可以伪造请求。

检查 JWT 是否生效，可以看 OnlyOffice 的日志：

BASH

docker logs onlyoffice-documentserver | grep -i jwt

出现 jwt is enabled 就是正常状态。如果第三方系统集成后报 401 错误，优先排查密钥是否完全一致，注意大小写和下划线。

3.3 存储卷与备份策略

容器部署的数据全在 volume 里，Docker 删除了容器不会自动删数据，但如果 volume 被误删，里面的文档就全没了。我见过不止一次运维手滑执行 docker compose down -v 把整个 Volume 清空的事故，所以备份策略必须在第一天就建立。

需要备份的数据包括：PostgreSQL 数据库里的文档元数据、用户信息，/var/www/onlyoffice/Data 下的文档实际内容和缩略图，以及 /var/log/onlyoffice 下的日志（这个可选）。Docker 场景下，最简单的方式是定期把整个 volume 打包拷走：

BASH

docker run --rm -v onlyoffice_data:/data -v /backup:/backup alpine tar czf /backup/onlyoffice_$(date +%F).tar.gz /data

也可以直接在宿主机上对 Docker 的 volume 目录做快照备份。但千万注意，数据库备份和文件备份要同步进行，否则恢复时元数据和文件对不上，文档打不开。我自己的做法是每天凌晨用 crontab 跑一次打包，保留最近 7 天副本，加上每周异地同步，目前还没因为备份问题丢过数据。

4. 常见安装问题与排查技巧实录

4.1 高频问题速查表：安装问题合集

把我在社群里看到和实际遇到的 OnlyOffice 高频问题整理成了一张速查表，直接照着排查：

问题现象	可能原因	解决方案
安装后访问 8080 端口无响应	容器启动失败或初始化未完成	`docker ps -a` 查看容器状态，`docker logs` 看具体错误
打开文档一直显示“正在加载”	服务首次初始化数据库，或磁盘空间不够	等待 2-3 分钟；检查 `df -h`，清理磁盘
上传大文件提示 413	Nginx `client_max_body_size` 太小	反代配置里加 `client_max_body_size 512m`
文档可以打开但无法编辑	JWT 密钥不一致或协同服务异常	检查环境变量和第三方插件密钥；查看日志中 `edit` 相关错误
中文显示为方块或乱码	系统缺少中文字体	安装 fonts-noto-cjk 或手动放入中文字体文件并重启服务
多人同时打开后光标互相不可见	WebSocket 被反代断开	检查反代配置是否包含 Upgrade 和 Connection 头
容器反复重启	内存不足或端口被占用	`free -h` 检查内存；`ss -lntp` 检查端口占用
文档转换格式时 CPU 100% 且卡死	单核 CPU 性能不足	至少 2 核；转换大文件时降低并发数

这张表里的每一个问题我都实际踩过或者帮别人远程排查过。最容易被忽略的是“容器反复重启”这个现象背后的内存问题，OnlyOffice 整套服务常驻内存占用不低，小水管服务器建议加 swap 兜底。

4.2 两个印象最深的排障过程

第一个是首次部署时“容器看起来活着，但页面永远打不开”。docker ps 显示端口映射正常，但浏览器访问一直转圈。我执行 docker logs onlyoffice-documentserver 发现服务还在初始化数据库，日志尾部一直有 CREATE DATABASE 和 Initializing... 的输出。这个阶段持续了 3 分钟左右，因为容器要生成密钥、初始化 PostgreSQL 数据库、创建默认表。耐心等首次初始化完成，问题就消失了。遇到这种情况别急着删容器重建，先看日志判断是否在初始化。

第二个坑藏得比较深，是在 Nextcloud 里集成 OnlyOffice 后，打开小文档没有任何问题，一上传几十 MB 的 PPTX 就提示转换失败。我检查了 OnlyOffice 容器日志没有任何报错，Nextcloud 日志也只显示上传成功，最后定位到是 Nginx 默认的 client_max_body_size 1m 在作祟。OnlyOffice 从 Nextcloud 拉取大文档时，初始请求体超过了限制，反代直接拒绝转发。加上 client_max_body_size 512m 后问题立刻解决。这类问题最迷惑人的地方在于报错不在服务端而在网关层，不熟悉反代机制的人很难想到。

5. 对外开放与安全加固：配置完不等于可以裸奔

5.1 端口暴露范围与防火墙策略

OnlyOffice 容器部署后默认监听 8080，很多教程直接让用户防火墙放行 8080，这是不安全的。正确的做法是：如果只用反代对外提供服务，防火墙只放行 80 和 443，8080 端口只允许本机或内网访问。这样即使 OnlyOffice 本身有漏洞，外部也无法直接触达。

用一个简单的 UFW 规则演示：

BASH

sudo ufw allow 80/tcp

sudo ufw allow 443/tcp

sudo ufw allow from 127.0.0.1 to any port 8080

sudo ufw enable

如果是云服务器，还要在安全组里做同样的限制。顺序上先改安全组再改服务端防火墙，避免把自己锁在外面。不要嫌这一步麻烦，我见过不少用户把容器端口直接映射到公网，几天后日志里爬满了来自全球的扫描请求，时间久了总能碰上一次利用漏洞的尝试。

5.2 用户认证与权限模型

OnlyOffice 社区版自带基础的用户管理和权限体系，管理员可以创建用户、分配文档访问权限。但它的定位是组件，不是完整的办公平台，如果要真正做到细粒度的权限控制，还是建议接到已有的统一身份认证体系里。

企业内部有 OpenLDAP 或 Active Directory 的话，OnlyOffice 支持对接，用户登录时自动验证，免去重复维护账号的麻烦。没有统一认证体系的小团队，可以先把用户控制在几十人规模，用内置账号管理就够了。真正要对外开放文档的话，一定要开启 JWT 并保证密钥强度，避免匿名编辑接口暴露。

我个人的建议是：OnlyOffice 对外开放之前，先把它当作内网应用跑一段时间，熟悉日志、熟悉配置，再考虑是否上公网。办公文档往往是敏感数据，宁可不方便，也不能裸奔。

5.3 关于 TLS 证书和后续升级的建议

证书方面，如果域名已经备案并且是公网访问，推荐使用 Let’s Encrypt 自动续期，一个月有效期的证书对运维反而友好，因为强迫你自动化。内网环境则可以直接自签证书，但浏览器会报警，团队内部可以接受；如果想省事，用 Nginx 把 HTTP 跳转 HTTPS，并在局域网 DNS 里解析域名到内网 IP，体验会和公网一致。

最后提一个版本升级的提醒：OnlyOffice 社区版更新节奏很快，功能迭代频繁，但大版本升级有时会引入配置格式变化。我上一次从 7.x 升到 8.x 时，JWT 配置的变量名有所调整，导致容器启动后无法认证。升级前务必先备份 volume，再看官方升级说明，不要在数据没备份的情况下直接拉最新镜像。

最后再分享一个小技巧

部署 OnlyOffice 之后，我最常用到的一个功能是“在浏览器里直接查看 PDF”。它的文档查看器对 PDF 的支持非常流畅，甚至能直接批注。很多团队只把它当 Office 在线编辑用，其实浪费了。配合网盘或者知识库系统，它完全能当一个轻量级的文档中台来用，文档预览、编辑、协同都在里面完成。我个人在实际操作中的体会是：OnlyOffice 的部署价值不在于“装了一个软件”，而在于你终于有了一套完全属于自己的、不受云厂商约束的办公基础件。从一个只能在本地打开文件的桌面工具，变成全员随时随地能协同的工作台，这种感觉用过一次就回不去了。