OnlyOffice 的文档服务包含多个后端组件，比如格式转换、协作同步、历史版本管理等。使用容器部署时，这些组件被封锁在镜像内部，不需要在宿主机上单独安装 Postgres、Redis 或消息队列。下面从最基础的启动命令开始，逐步加上数据持久化、安全密钥和反向代理，把整个部署流程走通。
容器化部署最大的好处是环境一致性和快速迁移。无论宿主机是 Ubuntu、Debian 还是 CentOS，只要 Docker 版本足够新，启动过程基本一致。镜像体积较大，首次拉取可能需要一些时间，建议使用明确的版本标签而不是 latest，避免大版本升级带来的配置不兼容。
一、获取镜像并启动基础容器
先从 Docker Hub 拉取 OnlyOffice DocumentServer 的官方镜像。镜像名称是 onlyoffice/documentserver，可以直接用 docker pull 命令获取。拉取完成后，可以先用最简单的命令把容器跑起来，验证服务是否能正常启动。容器内部默认监听 80 端口，因此需要把宿主机的某个端口映射到容器内部的 80 端口。
docker pull onlyoffice/documentserver:latest docker run -i -t -d -p 8080:80 --name onlyoffice onlyoffice/documentserver:latest
上面的命令把宿主机的 8080 端口映射到容器的 80 端口，这样通过 http://127.0.0.1:8080 就能访问 OnlyOffice 的欢迎页面。首次启动时，容器内部会初始化数据库、缓存和字体转换组件，通常需要几分钟时间。可以用 docker logs -f onlyoffice 实时查看启动日志，直到出现服务可用的提示。
这个基础启动方式没有挂载任何数据卷，容器删除后所有配置和文档都会丢失，仅适合快速验证。生产环境需要使用持久化存储，否则升级或重建容器时会丢失数据。另外，OnlyOffice 对内存要求较高，建议至少分配 4GB 内存，低于 2GB 时格式转换功能可能会频繁失败。
二、用 Docker Compose 管理数据卷与密钥
OnlyOffice 容器中有几个需要持久化的目录：日志在 /var/log/onlyoffice，证书和缓存数据在 /var/www/onlyoffice/Data，文档缓存和转换结果在 /var/lib/onlyoffice，内部数据库文件在 /var/lib/postgresql。把这些目录挂载到宿主机后，容器重建也不会丢失历史数据。
使用 Docker Compose 可以更清晰地管理环境变量和挂载关系。下面是一个完整的 compose 文件示例，包含端口映射、数据卷和 JWT 密钥配置。JWT 用来保护文档编辑接口，开启后外部集成系统必须携带正确的密钥才能调用编辑 API，能有效防止未授权访问。
services:
onlyoffice:
image: onlyoffice/documentserver:latest
container_name: onlyoffice
ports:
- "8080:80"
volumes:
- ./logs:/var/log/onlyoffice
- ./data:/var/www/onlyoffice/Data
- ./lib:/var/lib/onlyoffice
- ./db:/var/lib/postgresql
environment:
JWT_ENABLED: "true"
JWT_SECRET: "replace-with-a-long-random-string"
restart: unless-stopped上面的 JWT_SECRET 需要替换成足够长的随机字符串，可以用 openssl rand -base64 32 生成。如果后续要接入 Nextcloud、Seafile 或自研系统，这个密钥必须在各端保持一致，否则文档打不开或提示签名错误。数据卷路径建议使用相对路径，并在宿主机上预先创建对应目录，避免权限不足导致容器启动失败。
执行 docker compose up -d 后，容器会在后台启动。可以通过 docker compose ps 查看状态，或者继续用 docker logs onlyoffice 查看初始化进度。如果修改了 compose 文件，需要执行 docker compose down 停止并删除容器，再重新 up，但数据卷中的内容会保留。
三、配置 HTTPS 反向代理与安全访问
OnlyOffice 容器自身可以通过 HTTP 访问，但在生产环境中建议放在 Nginx 或 Traefik 后面做 HTTPS 终止。协同编辑依赖 WebSocket 长连接，如果反向代理没有正确升级协议，多人同时编辑时会出现连接断开或状态不同步的问题。因此代理配置需要显式处理 Upgrade 和 Connection 头。
下面给出一个 Nginx 反向代理的配置片段。假设容器映射到了宿主机 8080 端口，Nginx 监听 443 端口并把请求转发给 127.0.0.1:8080。证书路径需要根据实际情况修改，示例域名统一使用 docs.ipipp.com。
server {
listen 443 ssl;
server_name docs.ipipp.com;
ssl_certificate /etc/ssl/certs/docs.ipipp.com.pem;
ssl_certificate_key /etc/ssl/private/docs.ipipp.com.key;
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 $scheme;
client_max_body_size 100m;
}
}其中 proxy_set_header Upgrade $http_upgrade 和 proxy_set_header Connection "upgrade" 是 WebSocket 升级的关键配置，不能省略。client_max_body_size 需要根据实际上传的文档大小调整，默认 1m 会限制较大文件的上传。证书可以使用 Let's Encrypt 免费证书，通过 certbot 自动续期即可。
如果不需要对外提供服务，仅在局域网内部使用，也可以直接通过 http 访问，但要注意编辑链接中携带的 JWT 签名可能被截获。建议至少在内部也启用 HTTPS，或者使用 VPN 限制访问来源。反向代理和 OnlyOffice 之间的内网通信可以保持 HTTP，不必在容器内部再配置证书。
四、常见问题排查与性能优化
容器启动后反复重启，最常见的原因是端口冲突或内存资源不足。可以用 docker logs onlyoffice 查看具体报错，如果日志中提示数据库初始化失败，检查挂载目录的写权限。容器内部服务默认以非 root 用户运行，宿主机目录需要给对应 UID 写权限，通常用 chown -R 1000:1000 处理即可。
文档显示为方框或字体缺失，是中文场景下另一个常见问题。OnlyOffice 在转换文档时依赖系统字体，如果镜像内缺少中文字体，转换出的 PDF 会显示异常。可以把宿主机的中文字体目录挂载到容器内，例如把 /usr/share/fonts 挂载到容器的 /usr/share/fonts，然后重启容器使字体缓存生效。
docker run -i -t -d -p 8080:80 --name onlyoffice \ -v /host/fonts:/usr/share/fonts \ onlyoffice/documentserver:latest
性能方面，如果并发转换任务较多，容器内存占用会快速增长。可以通过 --memory 和 --cpus 参数限制资源使用，避免 OnlyOffice 抢占宿主机全部资源。对于小型团队，4 核 8GB 的配置通常可以支撑几十人同时在线编辑；大型并发场景则需要考虑横向扩展或使用独立数据库。
另外，定期清理缓存目录可以避免磁盘空间被无限制占用。OnlyOffice 会将转换后的临时文件存放在 /var/lib/onlyoffice/documentserver/App_Data/cache/files 中，可以通过定时任务清理超过一定时间的文件。建议在低峰期执行清理，并保留最近几天的文件，防止正在编辑的文档被误删。
OnlyOffice容器化Docker修改时间：2026-10-06 11:37:57