用 OnlyOffice 搭建本地协同文档服务器：Docker 安装、格式兼容与权限控制

如果你正在为团队寻找一套可以完全掌控数据、又不想为每个用户支付年费的在线文档方案，那么基于 Docker 自托管 ONLYOFFICE Document Server 是一个很实际的落地方案。它能在你自己的服务器上提供文档、表格和幻灯片的在线查看与协同编辑能力，核心功能对标商业云文档，但数据主权完全在你手里。接下来我会带你走一遍从容器部署、存储配置到与现有系统对接的完整流程，并处理几个最常见的坑。

部署前的准备与容器规划

在拉取镜像之前，先想清楚这台文档服务器要承担什么角色。ONLYOFFICE Document Server 本身是一个独立的文档处理引擎，它不提供文件存储或用户管理界面，而是通过 API 与你的网盘、知识库或协同平台对接。这意味着你需要有一个“宿主”系统，比如 Nextcloud、ownCloud、Confluence 或自研应用，由它来管理文件和权限，ONLYOFFICE 负责渲染和编辑。

硬件方面，官方建议至少 2 GB 内存和 2 核 CPU，如果你的团队经常同时编辑大型表格或演示文稿，建议翻倍。另外，服务器必须能访问外网，因为容器首次启动需要下载字体和语言包，后续的文档转换服务也可能需要联网验证许可证（社区版是免费的，但功能上有限制）。

使用 Docker 安装 ONLYOFFICE Document Server

最直接的安装方式是使用官方镜像。社区版（Community Edition）是免费的，功能上覆盖了日常协同办公的大部分需求，但连接数有 20 个的限制，且不包含集群和高可用特性。如果只是内部团队使用，社区版通常够用。

1. 拉取并启动容器

先创建一个用于存放配置和数据的目录，然后运行以下命令：

sudo mkdir -p /app/onlyoffice/{data,lib,db,logs}
sudo docker run -i -t -d 
  --name onlyoffice-document-server 
  --restart=always 
  -p 80:80 
  -v /app/onlyoffice/data:/var/www/onlyoffice/Data 
  -v /app/onlyoffice/lib:/var/lib/onlyoffice 
  -v /app/onlyoffice/db:/var/lib/postgresql 
  -v /app/onlyoffice/logs:/var/log/onlyoffice 
  onlyoffice/documentserver

这里有几个关键点需要解释：

-p 80:80 将容器的 80 端口映射到宿主机。如果你的服务器上已经有 Nginx 或其他服务占用 80 端口，改成 -p 8080:80 之类的映射，后续通过 http://你的服务器IP:8080 访问。
四个 -v 卷挂载是数据安全的核心。官方强烈建议将数据存放在容器外部，这样升级镜像或容器重建时不会丢失文档缓存、数据库和证书。特别是 /var/lib/postgresql，它存储了文档元数据，丢失会导致已上传文档的编辑历史无法找回。
--restart=always 保证服务器重启后容器自动拉起，避免服务长时间中断。

启动后，等待约 30 秒让容器完成初始化，然后访问 http://你的服务器IP，如果看到欢迎页面就说明安装成功了。如果页面无法访问，用 sudo docker logs onlyoffice-document-server 查看日志，最常见的问题是端口被占用或数据库初始化失败。

2. 验证服务状态

可以用一个简单的命令检查核心转换服务是否就绪：

sudo docker exec onlyoffice-document-server sudo supervisorctl status

正常情况下你会看到 ds:converter、ds:docservice 和 ds:postgresql 等进程处于 RUNNING 状态。如果某个进程反复重启，多半是卷挂载目录的权限问题，检查宿主机目录的所有者是否为 1000:1000（容器内运行用户）。

与现有系统对接：JWT 密钥配置

ONLYOFFICE Document Server 本身不处理用户认证，它通过 JWT（JSON Web Token）来验证请求是否来自你信任的前端系统。这一步是安全的关键，如果跳过，任何能访问你文档服务器端口的人都可以直接调用编辑接口。

1. 生成 JWT 密钥

在宿主机上生成一个随机密钥：

openssl rand -base64 32

把输出保存下来，后面会用到。

2. 在 ONLYOFFICE 中启用 JWT

编辑容器内的配置文件 /etc/onlyoffice/documentserver/local.json：

sudo docker exec -it onlyoffice-document-server bash
nano /etc/onlyoffice/documentserver/local.json

在文件中加入以下内容：

{
  "services": {
    "CoAuthoring": {
      "token": {
        "enable": {
          "request": {
            "inbox": true,
            "outbox": true
          },
          "browser": true
        },
        "secret": {
          "inbox": {
            "string": "你的密钥"
          },
          "outbox": {
            "string": "你的密钥"
          },
          "browser": {
            "string": "你的密钥"
          }
        }
      }
    }
  }
}

保存并退出，然后重启容器使配置生效：

sudo docker restart onlyoffice-document-server

3. 在宿主系统中配置相同的密钥

接下来，你需要在你现有的网盘或协同系统中配置同样的 JWT 密钥。以 Nextcloud 为例，在 ONLYOFFICE 连接器设置中填入文档服务器的地址和密钥即可。如果是自研系统，需要在生成编辑器 URL 时用同样的密钥对请求参数进行签名。这个机制确保了只有你的应用能唤起编辑器，外部请求会被拒绝。

微软 Office 格式兼容与字体缺失排错

ONLYOFFICE 最大的卖点之一是对微软 Office 格式（.docx、.xlsx、.pptx）的高度兼容。但在实际使用中，你可能会遇到文档打开后排版错乱、字体显示为方块或替换字体的情况。这通常不是格式转换的问题，而是服务器上缺少对应的字体文件。

1. 安装微软核心字体

ONLYOFFICE 容器基于 Debian，默认不包含微软的专有字体。你可以在容器内安装 ttf-mscorefonts-installer 包来补齐：

sudo docker exec -it onlyoffice-document-server bash
apt-get update && apt-get install -y ttf-mscorefonts-installer

安装过程中会弹出 EULA 确认，按 Tab 键选择 OK 即可。安装完成后，需要清除字体缓存并重启文档服务：

sudo docker exec onlyoffice-document-server sudo documentserver-update-fonts
sudo docker restart onlyoffice-document-server

2. 挂载自定义字体目录

如果你的团队使用特定的中文字体或公司标准字体，更好的做法是把字体目录挂载到容器外部，方便统一管理。修改容器创建命令，增加一个卷：

-v /app/onlyoffice/fonts:/usr/share/fonts/custom

将你的字体文件（.ttf 或 .otf）放到宿主机的 /app/onlyoffice/fonts 目录下，然后执行字体更新命令。这样以后新增字体只需要往目录里丢文件，不需要进入容器操作。

3. 常见问题定位

如果文档中某些字体仍然显示异常，先用浏览器开发者工具检查文档页面的 CSS，看具体是哪个字体回退失败。也可以在容器内用 fc-list 命令查看已安装的字体列表：

sudo docker exec onlyoffice-document-server fc-list | grep "微软雅黑"

如果输出为空，说明字体没有正确安装，检查字体文件权限和格式。另外注意，ONLYOFFICE 的字体缓存更新可能需要几分钟，刚安装完不要立即测试。

权限控制与安全加固

自托管的优势在于你可以完全控制访问边界，但这也意味着安全责任在你身上。除了 JWT 之外，还有几个层面需要加固。

1. 网络层限制

如果你的文档服务器只服务于内网，建议不要将端口暴露到公网。在防火墙层面只允许内网 IP 访问，或者通过反向代理（如 Nginx、Caddy）增加一层 TLS 加密和访问控制。反向代理配置中还可以加入 IP 白名单、速率限制等规则。

2. HTTPS 强制启用

浏览器只有在 HTTPS 环境下才能调用某些高级功能（如剪贴板、全屏 API）。ONLYOFFICE 官方文档也建议在生产环境启用 HTTPS。你可以用 Caddy 自动申请 Let's Encrypt 证书，配置非常简单，只需要在 Caddyfile 中声明域名和反向代理目标。

3. 容器权限最小化

默认情况下容器以 root 用户运行，这存在一定的安全隐患。你可以在创建容器时指定 --user 参数，或者使用 Docker 的 --read-only 标志将文件系统挂载为只读（需要确保卷目录可写）。对于大多数团队来说，至少应该做到：宿主机目录权限收紧、容器不映射多余的端口、定期更新镜像。

升级与备份策略

ONLYOFFICE 的版本更新比较频繁，社区版每个季度左右会有大版本发布。升级流程很简单：拉取新镜像，用相同的卷挂载参数重新创建容器。由于数据都在宿主机上，容器重建不会丢失数据。

备份方面，重点备份三个目录：/app/onlyoffice/db（PostgreSQL 数据）、/app/onlyoffice/data（证书和密钥）、/app/onlyoffice/lib（文件缓存）。最简单的方案是用 cron 定期打包这些目录，或者用 restic、borgbackup 做增量备份到异地存储。

总结

通过 Docker 部署 ONLYOFFICE Document Server，你可以在半天内搭建起一套可用的协同文档服务。它的核心价值在于：用开源方案替代商业云文档，数据完全由你掌控，同时保持了对微软 Office 格式的高兼容性。部署过程中的关键点在于卷挂载的数据持久化、JWT 密钥的双端配置，以及字体缺失的及时处理。如果你已经有现成的网盘或协同系统，对接成本并不高；如果是全新搭建，可以考虑搭配 Nextcloud 或 ONLYOFFICE Workspace 使用，后者提供了更完整的文件管理和用户体系。