Linux服务器如何部署在线文档协作服务?从运行依赖到可用性验证

发布人:A5数据发布时间:2026-10-29 11:13阅读量:76

要在 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 安装命令
CPU4 vCPU 起文档转换和多人编辑会产生瞬时负载
内存8 GB 起具体容量取决于文档类型和并发量
磁盘可用空间 40 GB 以上包括镜像、日志、缓存和持久化数据
容器运行时Docker Engine、Compose V2用于拉取和管理服务容器
域名例如 docs.example.com用于反向代理和 HTTPS
网络端口80、44380 用于证书签发或跳转,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

该配置有几个重要边界:

三、创建服务目录和持久化配置配图

  1. 127.0.0.1:8080:80 表示容器服务只接受本机访问,公网用户不能直接访问 8080。
  2. JWT_ENABLED 保持开启,后续接入文件管理平台时,双方必须使用同一份 JWT_SECRET。
  3. 日志、数据、运行目录和数据库目录均采用宿主机绑定挂载,删除容器不会自动删除这些目录。
  4. 健康检查使用服务自身的 /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 完全一致。修改密钥后,已经接入的所有平台都必须同步修改,否则会出现鉴权失败。

建议使用一个测试账号完成以下操作:

  1. 新建一个空白文档。
  2. 输入一段文字并保存。
  3. 关闭后重新打开,确认内容仍然存在。
  4. 使用第二个浏览器会话打开同一文档。
  5. 在两个会话中分别输入内容,确认修改能够同步。
  6. 关闭其中一个会话后重新打开,确认文档没有损坏。

这组操作才能验证文档服务与存储平台之间的打开、回调、保存和协作链路。单独访问 /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与镜像支持情况匹配
Dockerdocker --versionDocker Engine 可执行
Composedocker compose versionCompose V2 可用
容器状态docker compose ps容器为 Up
健康检查curl http://127.0.0.1:8080/healthcheck返回 true
反向代理nginx -t语法检查成功
HTTPScurl -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

相关推荐