Linux服务器如何部署在线文档协作服务?从运行依赖到可用性验证
要在 Linux 服务器上运行在线文档协作服务,不能只启动一个容器就结束。至少需要确认服务器架构、容器运行时、持久化目录、反向代理、HTTPS 和健康检查均可用。下面以 ONLYOFFICE Docs Docker 镜像为部署对象,演示从依赖检查、首次启动到可用性验证的完整过程。
该服务主要负责文档编辑与协作能力,本身不是完整的网盘、账号系统或文件管理平台。实际使用时,通常由 Nextcloud、Seafile 或其他兼容平台调用它。本文先完成文档服务端的可靠部署,再说明如何验证其是否具备被上层平台调用的条件。
面向在线文档编辑、协作与文件平台接入场景,A5idc数据提供香港、美国、日本、韩国、中国台湾、新加坡及马来西亚等地区的物理服务器资源,覆盖常规建站、AMD计算、存储及多带宽线路方案。产品可配备大内存、SSD或NVMe存储,适配文档服务容器、数据库、缓存与多任务运行;大容量存储系列也可承载文件归档和备份数据,为不同访问地区的在线协作平台提供服务器基础。
一、明确部署边界与准备条件
1. 示例环境
以下命令以 Ubuntu 22.04 或 Ubuntu 24.04 的 x86_64 服务器为例。若使用 Debian、Rocky Linux 或 ARM 服务器,需要根据发行版的软件源和镜像支持情况调整,不建议直接复制 Ubuntu 的 Docker 软件源命令。
建议准备以下条件:
| 项目 | 示例要求 | 说明 |
|---|---|---|
| 操作系统 | Ubuntu 22.04/24.04 x86_64 | 用于匹配后续 Docker 安装命令 |
| CPU | 4 vCPU 起 | 文档转换和多人编辑会产生瞬时负载 |
| 内存 | 8 GB 起 | 具体容量取决于文档类型和并发量 |
| 磁盘 | 可用空间 40 GB 以上 | 包括镜像、日志、缓存和持久化数据 |
| 容器运行时 | Docker Engine、Compose V2 | 用于拉取和管理服务容器 |
| 域名 | 例如 docs.example.com | 用于反向代理和 HTTPS |
| 网络端口 | 80、443 | 80 用于证书签发或跳转,443 用于正式访问 |
| 管理权限 | root 或可使用 sudo 的账号 | 安装软件、创建目录和配置 Nginx |
这里的 CPU、内存和磁盘是首次部署的参考起点,不代表所有业务场景的固定要求。大量在线预览、复杂表格、PDF 转换或同时编辑人数增加后,应通过监控结果再调整规格。
2. 确认服务器信息
先确认系统版本、CPU 架构、磁盘空间和端口占用情况:
cat /etc/os-release
uname -m
nproc
free -h
df -h /
sudo ss -lntp | grep -E ':(80|443|8080)\b' || true
预期结果中,系统应为 Ubuntu,架构通常为 x86_64,根分区还应有足够可用空间。
如果 80 或 443 端口已经被其他网站使用,不要直接停止现有服务。应先确认现有 Nginx、Apache 或控制面板的配置方式,再决定是否共用反向代理。本文会让文档容器仅监听本机 127.0.0.1:8080,避免将内部服务端口直接暴露到公网。
3. 确认域名和防火墙策略
将 docs.example.com 的 DNS A 记录指向服务器公网 IPv4 地址。如果使用 IPv6,还应确认 AAAA 记录确实指向可访问的 IPv6 地址,否则部分客户端可能优先访问错误地址。
如果服务器启用了 UFW,先查看当前规则:
sudo ufw status numbered
确认 SSH 管理端口已经放行后,再开放 Web 端口:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status
防火墙变更会影响公网访问。若需要回滚,可使用与规则完全匹配的删除命令,例如:
sudo ufw delete allow 80/tcp
sudo ufw delete allow 443/tcp
不要在未确认 SSH 已放行的情况下重置 UFW 规则,否则可能导致远程管理连接中断。
二、安装并验证 Docker 运行环境
1. 先判断是否已经安装
docker --version
docker compose version
sudo systemctl is-active docker
如果 Docker Engine 和 Compose V2 已经存在,且服务状态为 active,可以跳过安装步骤,继续执行运行验证。
如果命令不存在,下面以 Ubuntu 官方 Docker 软件源为例安装:
sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
| sudo tee /etc/apt/keyrings/docker.asc > /dev/null
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
验证 Docker 是否能正常启动容器:
sudo docker run --rm hello-world
如果看到包含 Hello from Docker! 的输出,说明 Docker Engine、镜像拉取和容器启动链路基本正常。
2. Docker 安装异常的处理边界
如果安装过程中提示软件包冲突,先检查系统中是否存在旧版 docker.io、旧版 Compose 或其他容器运行时:
dpkg -l | grep -E 'docker|containerd|podman'
不要直接批量删除所有匹配软件包。旧环境中可能已经运行着其他业务容器。应先确认容器列表和业务影响:
sudo docker ps -a
sudo systemctl list-units --type=service | grep -E 'docker|containerd|podman'
首次部署不建议为了安装新版本而覆盖正在运行的容器环境。若该服务器已有生产容器,应安排维护窗口,完成容器配置备份后再处理冲突。
三、创建服务目录和持久化配置
1. 建立目录结构
创建专用目录,不要把服务数据与网站源码或其他容器混放:
sudo mkdir -p /opt/onlyoffice/{data,logs,lib,db}
sudo chown -R root:root /opt/onlyoffice
sudo chmod 755 /opt/onlyoffice
这些目录的用途如下:
data:文档服务运行数据和相关数据文件。logs:服务日志。lib:服务运行时持久化数据。db:容器内部数据库相关数据。.env:镜像标签和 JWT 密钥等敏感配置。
在修改配置前,可以先保存一份目录清单和配置备份:
sudo find /opt/onlyoffice -maxdepth 2 -type d -print
2. 生成环境变量文件
JWT 用于上层文件平台与文档服务之间的身份校验。不要把密钥写进公开网页、代码仓库或聊天记录中。
sudo sh -c 'umask 077; printf "ONLYOFFICE_TAG=latest\nJWT_SECRET=%s\n" "$(openssl rand -hex 32)" > /opt/onlyoffice/.env'
sudo chmod 600 /opt/onlyoffice/.env
sudo cat /opt/onlyoffice/.env
这里的 latest 适合首次验证镜像是否可以运行,但正式环境建议替换为已经确认可用的固定版本标签。部署固定标签前,可先检查镜像标签是否存在:
sudo docker manifest inspect onlyoffice/documentserver:latest > /dev/null
echo $?
输出 0 表示当前 Docker 客户端能够找到该标签。固定版本时,将命令中的 latest 替换为实际存在的版本标签。
3. 编写 Compose 配置
进入服务目录:
cd /opt/onlyoffice
创建 compose.yaml:
sudo tee /opt/onlyoffice/compose.yaml > /dev/null <<'EOF'
services:
documentserver:
image: onlyoffice/documentserver:${ONLYOFFICE_TAG}
container_name: onlyoffice-documentserver
restart: unless-stopped
ports:
- "127.0.0.1:8080:80"
environment:
JWT_ENABLED: "true"
JWT_SECRET: "${JWT_SECRET}"
JWT_HEADER: "AuthorizationJwt"
volumes:
- ./logs:/var/log/onlyoffice
- .//var/www/onlyoffice/Data
- ./lib:/var/lib/onlyoffice
- ./db:/var/lib/postgresql
healthcheck:
test:
[
"CMD-SHELL",
"wget -qO- http://127.0.0.1/healthcheck | grep -q true"
]
interval: 30s
timeout: 10s
retries: 10
start_period: 120s
EOF
该配置有几个重要边界:

127.0.0.1:8080:80表示容器服务只接受本机访问,公网用户不能直接访问 8080。JWT_ENABLED保持开启,后续接入文件管理平台时,双方必须使用同一份JWT_SECRET。- 日志、数据、运行目录和数据库目录均采用宿主机绑定挂载,删除容器不会自动删除这些目录。
- 健康检查使用服务自身的
/healthcheck接口,检查结果只能说明服务进程可响应,不能代替完整的文档编辑验证。
检查 Compose 文件是否能被正确解析:
cd /opt/onlyoffice
sudo docker compose config
如果命令输出展开后的 YAML 且没有报错,说明 .env 中的变量已经被正确读取。若提示 JWT_SECRET 或 ONLYOFFICE_TAG 未定义,应检查 .env 文件是否位于 /opt/onlyoffice,以及文件权限和变量名称是否拼写正确。
四、拉取镜像并启动文档服务
1. 拉取镜像
cd /opt/onlyoffice
sudo docker compose pull
首次拉取可能需要较长时间,具体取决于服务器带宽和镜像大小。拉取过程只会更新本地镜像,不会修改已经挂载的数据目录。
如果出现网络超时,可以先测试 Docker Hub 或镜像仓库的解析和访问:
getent hosts docker.io
sudo docker info
不要在不清楚来源的情况下随意替换为第三方镜像仓库。若企业网络必须使用镜像加速或私有仓库,应先确认镜像来源和同步策略。
2. 启动容器
cd /opt/onlyoffice
sudo docker compose up -d
查看容器状态:
sudo docker compose ps
正常情况下,服务会处于 Up 状态,健康检查完成后可能显示为 healthy。首次启动需要初始化运行目录,不能只根据刚启动几秒时的状态判断失败。
3. 验证容器内部健康状态
sudo docker inspect \
--format '{{.State.Status}} health={{if .State.Health}}{{.State.Health.Status}}{{else}}not-configured{{end}}' \
onlyoffice-documentserver
示例结果:
running health=healthy
再从宿主机访问服务:
curl -fsS http://127.0.0.1:8080/healthcheck
echo
预期结果通常为:
true
这一步验证了容器端口映射、服务进程和健康检查接口。若返回连接失败,先不要修改 Nginx,应直接检查容器日志:
sudo docker compose logs --tail=100 documentserver
五、配置 Nginx 反向代理
1. 创建站点配置
确认域名已经解析到服务器后,安装 Nginx:
sudo apt update
sudo apt install -y nginx
sudo systemctl enable --now nginx
创建站点配置文件:
sudo tee /etc/nginx/sites-available/onlyoffice.conf > /dev/null <<'EOF'
server {
listen 80;
listen [::]:80;
server_name docs.example.com;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
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 Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}
EOF
将配置启用:
sudo ln -s /etc/nginx/sites-available/onlyoffice.conf \
/etc/nginx/sites-enabled/onlyoffice.conf
如果提示同名文件已经存在,不要直接覆盖,先查看现有配置:
sudo ls -l /etc/nginx/sites-enabled/
sudo nginx -T | grep -n 'docs.example.com'
检查配置语法:
sudo nginx -t
预期结果应包含:
syntax is ok
test is successful
确认无误后重新加载:
sudo systemctl reload nginx
2. 验证 HTTP 反向代理
在服务器本机执行:
curl -fsS -H 'Host: docs.example.com' \
http://127.0.0.1/healthcheck
echo
预期仍为:
true
如果本机访问正常,但外部访问失败,重点检查 DNS、公网安全组和防火墙。如果 Nginx 返回 502 Bad Gateway,则重点检查 127.0.0.1:8080 是否仍在监听,以及容器是否已经退出。
3. 配置 HTTPS
在线文档协作涉及账号凭据、文档内容和 JWT 请求,不建议长期使用明文 HTTP。域名已经解析且 80 端口能够从公网访问时,可以使用 Certbot 申请证书:
sudo apt install -y certbot python3-certbot-nginx
sudo cp /etc/nginx/sites-available/onlyoffice.conf \
/etc/nginx/sites-available/onlyoffice.conf.before-certbot
sudo certbot --nginx -d docs.example.com
Certbot 可能会修改 Nginx 配置并增加证书路径。执行完成后重新检查:
sudo nginx -t
sudo systemctl reload nginx
curl -fsS -L https://docs.example.com/healthcheck
echo
预期结果为 true。如果证书签发失败,常见原因是 DNS 尚未生效、80 端口未开放、服务器存在错误的 AAAA 记录,或域名实际指向了另一台服务器。
六、验证“可用”而不只是“容器在运行”
仅看到容器状态为 Up,不能说明在线协作已经可用。建议按以下层级检查。

1. 进程和端口层
sudo docker compose ps
sudo ss -lntp | grep -E ':(8080)\b'
curl -fsS http://127.0.0.1:8080/healthcheck
应满足:
- 容器状态为
Up。 - 本机 8080 端口由 Docker 监听。
- 健康检查返回
true。
2. 反向代理和 TLS 层
curl -sS -o /dev/null -w 'HTTP=%{http_code}\n' \
https://docs.example.com/healthcheck
预期返回:
HTTP=200
如果 HTTPS 返回 301,说明仍在执行 HTTP 到 HTTPS 的跳转,可以加上 -L 继续验证最终响应:
curl -fsS -L https://docs.example.com/healthcheck
echo
浏览器访问:
https://docs.example.com/
应能打开文档服务页面,而不是出现证书错误、网关错误或无限跳转。
3. 上层平台接入层
如果准备通过文件管理平台使用协作功能,需要在平台端填写文档服务地址:
https://docs.example.com/
平台端的 JWT 配置必须与 /opt/onlyoffice/.env 中的 JWT_SECRET 完全一致。修改密钥后,已经接入的所有平台都必须同步修改,否则会出现鉴权失败。
建议使用一个测试账号完成以下操作:
- 新建一个空白文档。
- 输入一段文字并保存。
- 关闭后重新打开,确认内容仍然存在。
- 使用第二个浏览器会话打开同一文档。
- 在两个会话中分别输入内容,确认修改能够同步。
- 关闭其中一个会话后重新打开,确认文档没有损坏。
这组操作才能验证文档服务与存储平台之间的打开、回调、保存和协作链路。单独访问 /healthcheck 只能证明服务端程序可以响应。
七、常见失败情况与处理顺序
1. 容器启动后反复重启
先查看状态和最近日志:
cd /opt/onlyoffice
sudo docker compose ps
sudo docker compose logs --tail=200 documentserver
重点检查:
- 磁盘空间是否耗尽:
df -h
- 内存是否不足:
free -h
sudo dmesg -T | grep -i -E 'oom|out of memory' | tail
.env中的镜像标签是否存在。- 挂载目录是否可写。
- 8080 是否已经被其他进程占用。
如果日志显示初始化尚未完成,应先等待一段时间。不要因为第一次启动较慢就立即删除 data、lib 或 db 目录。
2. 本机健康检查失败
按由外到内的顺序检查:
sudo docker ps -a
sudo docker inspect onlyoffice-documentserver \
--format '{{json .State}}'
sudo docker compose logs --tail=200 documentserver
如果容器是 Exited,说明问题在容器内部,应以日志为准。如果容器是 Up,但健康检查失败,可能是服务仍在初始化、容器内检查命令不可用,或服务内部组件尚未就绪。
可暂时从宿主机直接执行:
curl -v http://127.0.0.1:8080/healthcheck
如果宿主机能返回 true,但 Compose 健康状态仍不是 healthy,应检查 Compose 中的 healthcheck 命令,而不是反复重启服务。
3. Nginx 返回 502
检查上游端口:
sudo ss -lntp | grep ':8080'
curl -v http://127.0.0.1:8080/healthcheck
sudo tail -n 100 /var/log/nginx/error.log
不同结果的含义:
- 8080 没有监听:容器未启动或端口映射失败。
- 8080 可访问,Nginx 返回 502:检查
proxy_pass是否写成了正确地址。 - 本机访问正常,公网访问失败:检查 DNS、安全组和防火墙。
- 页面能打开,但编辑过程中断开:重点检查 Nginx 的
Upgrade、Connection和超时配置。
4. 接入平台提示 JWT 或权限错误
确认两端的以下内容:
- JWT 是否同时启用。
JWT_SECRET是否完全一致。- 平台使用的 JWT Header 是否与服务端约定一致。
- 修改
.env后是否重新创建了容器。 - 服务器和上层平台的系统时间是否相差过大。
修改环境变量后,必须重新加载容器:
cd /opt/onlyoffice
sudo docker compose up -d --force-recreate documentserver
此操作会短暂中断文档服务。执行前应确认没有正在编辑的重要文档,并保留原配置备份。
5. 数据目录权限错误
先查看目录归属和权限:
sudo ls -ld /opt/onlyoffice /opt/onlyoffice/*
sudo docker compose logs --tail=200 documentserver
不要直接对整个目录执行递归 chmod 777。这会扩大敏感文档和运行数据的访问范围。应根据日志中明确指出的路径处理权限,并在修改前保存目录权限信息:
sudo stat -c '%A %U:%G %n' /opt/onlyoffice/*
八、验收清单与回滚方案
1. 部署验收清单
| 验收项 | 检查命令或动作 | 通过标准 |
|---|---|---|
| 系统架构 | uname -m | 与镜像支持情况匹配 |
| Docker | docker --version | Docker Engine 可执行 |
| Compose | docker compose version | Compose V2 可用 |
| 容器状态 | docker compose ps | 容器为 Up |
| 健康检查 | curl http://127.0.0.1:8080/healthcheck | 返回 true |
| 反向代理 | nginx -t | 语法检查成功 |
| HTTPS | curl -fsS -L https://docs.example.com/healthcheck | 返回 true |
| 浏览器访问 | 打开域名首页 | 无证书和网关错误 |
| 文档操作 | 新建、编辑、保存、重新打开 | 内容保持一致 |
| 协作能力 | 两个会话打开同一文档 | 修改能够同步 |
| 持久化 | 重启容器后重新打开测试文档 | 数据未丢失 |
2. 配置和数据备份
首次部署完成后,至少备份 Compose 文件、环境变量和 Nginx 配置:
sudo mkdir -p /root/onlyoffice-backup
sudo cp -a /opt/onlyoffice/compose.yaml \
/root/onlyoffice-backup/compose.yaml
sudo cp -a /opt/onlyoffice/.env \
/root/onlyoffice-backup/.env
sudo cp -a /etc/nginx/sites-available/onlyoffice.conf \
/root/onlyoffice-backup/onlyoffice.conf
sudo chmod 600 /root/onlyoffice-backup/.env
如果已经有真实文档数据,还应对 /opt/onlyoffice/data、lib 和 db 做独立备份。备份前应确认磁盘空间和备份目标可用,不要把备份文件放在同一块可能损坏的系统盘上。
3. 回滚到上一个镜像版本
只有在已经保留旧镜像标签和数据备份时,才执行版本回滚。先停止当前服务,避免回滚期间产生新的写入:
cd /opt/onlyoffice
sudo cp -a .env /root/onlyoffice-backup/.env.before-rollback
sudo docker compose down
将 .env 中的 ONLYOFFICE_TAG 修改为已确认可用的旧版本,然后重新拉取并启动:
sudoedit /opt/onlyoffice/.env
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
curl -fsS http://127.0.0.1:8080/healthcheck
echo
docker compose down 会停止并删除容器,但不会删除上述绑定挂载目录。不要使用 docker compose down -v,也不要执行 docker system prune 或删除 /opt/onlyoffice,除非已经完成数据备份并明确接受数据丢失风险。
如果回滚后仍无法启动,不要继续反复切换版本。应停止服务、保留现场日志,并根据备份恢复配置和数据目录。对于已经发生数据结构变化的版本,直接降级可能不兼容,恢复完整备份通常比强行覆盖更安全。
4. 回滚 Nginx 配置
如果 HTTPS 或反向代理配置修改后导致网站异常,先恢复备份文件:
sudo cp -a /root/onlyoffice-backup/onlyoffice.conf \
/etc/nginx/sites-available/onlyoffice.conf
sudo nginx -t
sudo systemctl reload nginx
最后重新执行本机健康检查、HTTPS 检查和浏览器访问检查。只有当容器、健康接口、Nginx 和实际文档保存流程全部通过时,才可以将首次部署标记为完成。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/6359.html



