🚀 使用 Docker Compose 部署 OnlyOffice（在线文档协作平台）

🚀 使用 Docker Compose 部署 OnlyOffice

本文是一篇关于使用 Docker Compose 部署 OnlyOffice 的详尽教程，旨在帮助您，特别是新手用户，轻松掌握这款功能强大的开源在线办公套件的部署和使用。

📝 项目简介

OnlyOffice 是一款功能丰富的免费开源在线 Office 协作办公套件，支持编辑处理文本文档、电子表格、演示文稿、可填写的表单和 PDF 等文件。更重要的是，它拥有强大的在线协作功能，可以实现实时共同编辑、审阅、批注和聊天互动等，可以作为 Microsoft Office、WPS Office 等办公软件的替代品。

核心特点：

与微软 Office 高度兼容：可以兼容微软 Office 和 Open Document 文档格式，如 DOCX、XLSX、PPTX、ODT、ODS、ODP 等。
软件完全开源，且支持扩展功能：作为开源软件，其源码发布于 GitHub，用户可以轻松集成到自己的平台，并通过第三方插件来扩展软件功能。
强大的在线协作功能：通过连接到云平台（如 Nextcloud、ownCloud 等），用户可以随时随地在浏览器中创建并编辑文档，并实现实时协作。
支持所有主流平台：拥有 Android、iOS、Windows、macOS、Linux 应用程式，可离线编辑文档。
一个窗口内可处理多文档：提升了多任务处理效率。

🔧 部署前准备

在开始部署之前，请确保您的环境满足以下要求，并完成必要的准备工作。

系统环境要求

操作系统：支持 Linux、Windows、macOS 等主流操作系统。本教程以 Linux 为例。
Docker 引擎：确保已安装并启动 Docker 服务。
Docker Compose：确保已安装 Docker Compose。
硬件资源：OnlyOffice 对资源有一定要求。
- 最低配置：CPU 2 核以上，内存 4GB 以上，磁盘 40GB 以上。
- 推荐配置：根据官方测试数据，支持 1000 个并发大约需要 16 核 / 32 GB RAM 的服务器配置。
防火墙端口：确保计划使用的端口（如教程中的 40156）在防火墙中是放行的。

环境检查

检查 Docker 服务状态： bash systemctl status docker 确保 Docker 服务处于 active (running) 状态。
检查 Docker Compose 版本： bash docker compose version 确认版本可用。

创建部署目录

建议创建一个独立的目录来管理您的 OnlyOffice 部署文件和数据：

mkdir -p /home/compose/onlyoffice && cd /home/compose/onlyoffice

此目录将作为您的工作目录，后续的 docker-compose.yml 等文件将放置于此。

⚙️ 配置 Docker Compose

接下来，我们需要创建 Docker Compose 配置文件。根据您提供的配置，以下是一个详细的解释和说明。

配置文件详解

在您的工作目录（例如 /home/compose/onlyoffice）下，创建以下配置文件。

1.创建 .env 环境配置文件这个文件用于定义容器运行时的环境变量，使得配置更加灵活。

# 容器名称（默认 onlyoffice，无需修改）
CONTAINER_NAME="onlyoffice"
# CPU 资源限制（0=不限制，按需改为 2/4 等，如 CPUS=2 限制 2 核）
CPUS=0
# 绑定主机 IP（空=监听所有网卡，外部可通过服务器任意 IP 访问）
HOST_IP=""
# JWT 密钥（关键！用于安全验证，建议用 openssl rand -base64 32 生成强密钥）
JWT_SECRET="BaLt42Ncd7s3XX6"
# 内存限制（0=不限制，按需改为 4G/8G 等，如 MEMORY_LIMIT=4G 限制 4GB）
MEMORY_LIMIT=0
# Web 访问端口（默认 40156，冲突时可改为 8080/80 等）
PANEL_APP_PORT_HTTP=40156

**关键配置说明**：
*   `CONTAINER_NAME`: 指定容器的名称。
*   `CPUS` 和 `MEMORY_LIMIT`: 设置容器的 CPU 和内存限制。默认值 `0` 表示无限制。您可以根据服务器实际情况进行调整，例如 `CPUS=‘1’` 和 `MEMORY_LIMIT=‘1024M’`。
*   `JWT_SECRET`: 用于保护文档编辑器的安全密钥，建议使用强密码并妥善保管。
*   `PANEL_APP_PORT_HTTP`: 定义宿主机映射的 HTTP 端口，此处为 `40156`。

2.创建 docker-compose.yml 文件这是 Docker Compose 的核心配置文件，定义了服务的各项参数。

#networks:
    #1panel-network:
        #external: true
services:
    onlyoffice:
        container_name: ${CONTAINER_NAME}  # 从 .env 读取容器名（默认 onlyoffice）
        deploy:
            resources:
                limits:
                    # 从 .env 读取 CPU/内存限制（0=不限制）
                    cpus: ${CPUS}
                    memory: ${MEMORY_LIMIT}
                    #cpus: '1'
                    #memory: '1024M'
        environment:
            # 注入 JWT 密钥（与 .env 一致，确保安全验证生效）
            - JWT_SECRET=${JWT_SECRET}
        # 使用 9.0.2.1 稳定版（避免自动更新导致兼容性问题，更新需手动改版本号）
        image: onlyoffice/documentserver:9.0.2.1
        labels:
            createdBy: Apps  # 容器标签（1Panel 识别用，无实际功能）
        #networks:
            #- 1panel-network
        # 端口映射：主机端口（.env 中 PANEL_APP_PORT_HTTP）→ 容器 80 端口
        ports:
            - ${HOST_IP}:${PANEL_APP_PORT_HTTP}:80
        restart: always  # 容器退出后自动重启（保障服务稳定，避免意外中断）
        volumes:
            # 日志目录：主机 data/logs → 容器 /var/log/onlyoffice
            - ./data/logs:/var/log/onlyoffice
            # 核心数据目录：主机 data/data → 容器 /var/www/onlyoffice/Data（文档、配置）
            - ./data/data:/var/www/onlyoffice/Data
            # 应用依赖目录：主机 data/lib → 容器 /var/lib/onlyoffice（插件、字体）
            - ./data/lib:/var/lib/onlyoffice
            # 数据库目录：主机 data/db → 容器 /var/lib/postgresql（用户、协作数据）
            - ./data/db:/var/lib/postgresql

**关键配置说明**：
*   **镜像选择 (`image`)**：使用 `onlyoffice/documentserver:9.0.2.1`，这是一个特定版本，稳定性较好。您也可以根据需要选择 `latest` 标签或其他版本。
*   **端口映射 (`ports`)**：`${HOST_IP}:${PANEL_APP_PORT_HTTP}:80` 将容器的 80 端口映射到宿主机的 `40156` 端口（由 `.env` 文件定义）。`HOST_IP` 为空表示绑定到所有接口。
*   **数据持久化 (`volumes`)**：通过卷挂载，确保容器重启后数据不丢失。
    *   `./data/logs:/var/log/onlyoffice`: 日志目录。
    *   `./data/data:/var/www/onlyoffice/Data`: 应用数据目录。
    *   `./data/lib:/var/lib/onlyoffice` 和 `./data/db:/var/lib/postgresql`: 数据库和库文件目录。
*   **环境变量 (`environment`)**：配置 `JWT_SECRET` 环境变量，用于文档编辑器的安全通信。
*   **重启策略 (`restart: always`)**：确保容器在意外退出时自动重启，提高服务可用性。

3.创建 data.yml（1Panel 集成表单配置，新手可忽略）用于 1Panel 面板添加应用时的参数表单（非启动必需，仅集成 1Panel 时使用）：

additionalProperties:
    formFields:
        # HTTP 端口配置项
        - default: 40156
          edit: true
          envKey: PANEL_APP_PORT_HTTP
          labelEn: HTTP Port
          labelZh: HTTP 端口
          label:
            en: HTTP Port
            ja: HTTP ポート
            ms: Port HTTP
            pt-br: Porta HTTP
            ru: HTTP-порт
            ko: HTTP 포트
            zh: HTTP 端口
            zh-Hant: HTTP 埠
          required: true
          rule: paramPort
          type: number
          # JWT 密钥配置项
        - default: secret
          edit: true
          envKey: JWT_SECRET
          labelEn: JWT Secret
          labelZh: JWT密钥
          label:
            en: JWT Secret
            ja: JWT シークレット
            ms: Rahsia JWT
            pt-br: Segredo JWT
            ru: Секрет JWT
            ko: JWT 비밀
            zh: JWT密钥
            zh-Hant: JWT密鑰
          random: true
          required: true
          rule: paramComplexity
          type: password

关于 JWT 密钥的说明

JWT（JSON Web Token）用于保护 OnlyOffice 文档编辑器免受未经授权的访问。在您的配置中，JWT 密钥已在 .env 文件中设置。如果后续需要禁用 JWT（不推荐用于生产环境），可以在 docker-compose.yml 的 environment 部分添加 - JWT_ENABLED=false。

关键配置说明（新手必看）

配置项	作用与注意事项
`JWT_SECRET`	必须设置强密钥！默认值 `BaLt42Ncd7s3XX6` 易被破解，生成命令：`openssl rand -base64 32`，替换后需重启容器。
`volumes` 挂载目录	4 个目录均为核心！删除任意目录会导致对应数据丢失（如 `data/data` 丢失→文档丢失，`data/db` 丢失→用户数据丢失）。
`image: onlyoffice/documentserver:9.0.2.1`	固定版本为 9.0.2.1（稳定版），更新时需手动修改版本号（如 `10.0.0`），避免自动更新引发问题。
`CPUS=0`/`MEMORY_LIMIT=0`	0 表示不限制资源，若服务器内存≤4GB，建议设 `MEMORY_LIMIT=3G`（预留 1GB 给系统），避免内存溢出。

🚀 启动与验证

配置完成后，就可以启动 OnlyOffice 服务了。

启动服务

在包含 docker-compose.yml 文件的目录下，执行以下命令来启动服务：

docker compose up -d

参数 -d 表示在后台运行容器。

验证服务状态

检查容器状态：执行 docker ps 命令，查看名为 onlyoffice 的容器状态是否为 Up。
查看服务日志（可选）：如果无法访问，可以通过 docker compose logs 或 docker logs onlyoffice 查看容器日志以排查问题。
访问 OnlyOffice 欢迎页面：
- 在浏览器中输入 http://您的服务器IP地址:40156。
- 如果看到 OnlyOffice 的欢迎页面，说明服务已成功启动。
功能测试：
- 在欢迎页面，您可以找到测试示例链接，点击进入测试页面，尝试创建或上传文档进行编辑，以验证所有功能是否正常。

🔌 基础配置与使用

成功部署 OnlyOffice 后，您可以开始配置和使用它。

集成到现有系统

OnlyOffice 的一大优势在于可以集成到您现有的平台（如网站或其他应用）中。这通常需要通过开发“连接器”来实现。基本思路如下：

在您的网页中引入 OnlyOffice API 脚本： html <script type="text/javascript" src="http://您的服务器IP:40156/web-apps/apps/api/documents/api.js"></script>
准备编辑器配置：您需要编写一个 JavaScript 配置对象 (config)，其中包含文档信息、编辑器界面设置以及事件回调函数等。核心配置项包括：
- document: 定义文档标题、URL、文件类型等。
- editorConfig: 定义编辑器界面参数，如打开模式、语言、用户信息等。您可以配置 user 信息以实现协作时的用户身份识别。
- events: 定义事件回调，例如文档保存后的回调地址 (callbackUrl)。
初始化编辑器：使用 DocsAPI.DocEditor 方法将编辑器加载到指定的页面元素中。

界面个性化 (可选)

如果您需要自定义 OnlyOffice 的界面，例如更换 Logo 或调整界面元素，可以参考社区经验，通过修改容器内的相关文件（如 /web-apps/apps/api/documents/api.js 或 CSS 文件）来实现。请注意，直接修改容器内的文件在容器重启后会丢失，建议通过挂载自定义文件或构建自定义镜像的方式持久化您的修改。

🔌 基础配置与使用2

OnlyOffice 首次使用需完成基础设置，核心操作包括 “创建文档、协作编辑、导出文档”，新手可按以下步骤上手：

1. 步骤 1：首次访问设置（若有）

部分版本首次访问需创建管理员账号：

访问 http://服务器IP:40156，若弹出 “Admin Registration” 页面，填写：
- 用户名：自定义（如 admin）；
- 密码：强密码（如 OnlyOffice@2024!）；
- 邮箱：可选（用于密码重置）；
点击「Register」完成注册，后续登录需使用该账号。

2. 步骤 2：创建与编辑文档

登录后，点击主页「Create」按钮，选择文档类型（Document/Spreadsheet/Presentation，对应 Word/Excel/PPT）；
进入编辑界面，顶部为工具栏（格式、插入、评论等功能），左侧为文档结构（如表格的工作表、幻灯片的页面）；
编辑内容：输入文字、插入图片 / 表格，操作与本地 Office 一致，编辑过程自动保存（顶部显示 “Saved”）。

3. 步骤 3：多人协作编辑

点击编辑界面右上角「Share」→ 输入协作成员邮箱（需成员已注册账号），选择权限（Read/Edit/Comment，对应只读 / 编辑 / 评论）；
成员收到邀请后，登录 OnlyOffice 即可看到共享文档，点击进入后：
- 实时显示其他成员的光标位置（标注用户名）；
- 成员修改内容会实时同步，右侧「Comments」面板可添加评论、回复讨论。

4. 步骤 4：导出文档

编辑完成后，点击顶部「File」→「Download as」；
选择导出格式（如 DOCX/PDF/CSV 等），浏览器自动下载文档到本地。

🛠️ 维护与管理

日常维护

服务启停：

    # 停止服务
    docker compose down

    # 启动服务
    docker compose up -d

    # 重启服务
    docker compose restart

数据备份：定期备份工作目录下的 data 文件夹。这个文件夹包含了 OnlyOffice 的所有日志、应用数据、库文件和数据库。

    tar -czf onlyoffice-backup-$(date +%Y%m%d).tar.gz ./data

服务更新：要更新到新版本的 OnlyOffice Document Server，请在部署目录下执行：

    docker compose pull    # 拉取最新镜像
    docker compose down    # 停止并移除当前容器
    docker compose up -d   # 使用新镜像重新启动容器

注意：更新前请务必备份数据，并查阅新版本文档以了解可能的配置变更。

监控与日志

查看实时日志：

    docker compose logs -f onlyoffice

监控资源使用：

    docker stats onlyoffice

检查存储空间：

    df -h  # 检查磁盘空间
    du -sh ./data  # 查看数据目录大小

🐛 常见问题排查

在使用过程中，可能会遇到一些问题，以下是一些常见问题的排查思路：

无法通过浏览器访问 OnlyOffice
- 检查防火墙：确认服务器安全组和防火墙是否放行了您配置的端口（例如 40156）。
- 检查容器状态：使用 docker ps 确认 OnlyOffice 容器是否正常运行。如果状态异常，使用 docker logs onlyoffice 查看错误日志。
- 确认端口占用：检查宿主机端口是否被其他进程占用。可以尝试更换 .env 文件中的 PANEL_APP_PORT_HTTP 变量值。
文档打开或保存失败
- 检查文件访问权限：确保 OnlyOffice 服务能够访问到您配置的文档 URL。
- 检查回调接口：如果文档保存失败，请检查您在编辑器配置中设置的 callbackUrl 接口是否可访问，并能正确返回 {"error":0}。
- 查看容器日志：日志中通常会包含更详细的错误信息。
提示 "Download failed" (下载失败)
- 此错误通常发生在 OnlyOffice 尝试从您提供的 URL 下载文档时。请确保文档 URL 是 OnlyOffice 服务能够直接访问的。
JWT 令牌错误
- 确保您在 .env 文件中设置的 JWT_SECRET 与集成到您自己系统时在配置中使用的密钥完全一致。
- 如果遇到 JWT 鉴权失败问题，且暂时无法解决，可以考虑在 docker-compose.yml 中添加环境变量 - JWT_ENABLED=false 来禁用 JWT（请注意安全风险）。
性能问题
- OnlyOffice 对服务器资源有一定要求。如果遇到性能瓶颈，请考虑升级服务器配置，或参考官方文档进行性能调优。

希望这篇教程能帮助您顺利完成 OnlyOffice 的部署和使用。作为一款功能全面且支持高度自定义的在线办公套件，OnlyOffice 能显著提升团队协作效率。如果在使用中遇到更复杂的问题，可以参考 OnlyOffice 的官方文档或在相关技术社区寻求帮助。

🐛 常见问题排查2

1. 容器启动后，访问界面提示 “502 Bad Gateway”

原因：容器内部服务未初始化完成（首次启动需 5-10 分钟），或内存不足导致服务崩溃。
解决：
1. 等待 10 分钟后刷新页面；
2. 查看日志：docker compose logs -f onlyoffice，若显示 “out of memory”，修改 .env 增加内存限制（如 MEMORY_LIMIT=4G），重启容器。

2. 文档无法保存，提示 “Save failed”

原因：data/data 目录权限不足，容器无法写入文档文件。
解决：重新赋予目录权限：sudo chmod -R 777 data/data，重启容器后重试保存。

3. 协作时其他成员无法看到文档

原因 1：成员邮箱输入错误，或未收到邀请邮件。

解决：重新发送邀请，确认邮箱正确，检查垃圾邮件文件夹。 - 原因 2：服务器防火墙阻止了协作端口（OnlyOffice 协作依赖 80 端口外的临时端口，需开放所有出站连接）。

解决：Linux 执行 sudo ufw allow out 1024:65535/tcp，允许容器出站连接。

4. JWT 验证失败，提示 “Invalid token”

原因：.env 中 JWT_SECRET 与容器内配置不一致，或密钥含特殊字符（如 !@#$）。
解决：
1. 重新生成不含特殊字符的密钥：openssl rand -hex 16（生成 32 位十六进制字符串）；
2. 替换 .env 中的 JWT_SECRET，重启容器：docker compose restart。

5. 容器占用内存过高，导致服务器卡顿

原因：MEMORY_LIMIT=0 未限制内存，文档渲染或多用户协作时内存占用飙升。
解决：编辑 .env 设 MEMORY_LIMIT=4G（根据服务器内存调整，如 8GB 内存设 6G），重启容器，通过 docker stats 查看内存占用是否下降。

通过以上步骤，新手可快速搭建 OnlyOffice 在线文档协作平台，实现团队实时文档编辑、数据私有化管理。如需集成云存储（如 Nextcloud）或配置 HTTPS，可参考 OnlyOffice 官方文档进一步探索。