Docker部署OnlyOffice时突破文件大小限制的实战指南

1. 问题场景：当大文件遇上OnlyOffice的“拦路虎”

相信很多朋友在用Docker部署了OnlyOffice文档服务器后，都遇到过这样一个头疼的问题：平时处理几十兆的Word、Excel文件都好好的，但某天产品经理或者同事突然甩过来一个200多兆的PPT或者包含大量高清图片的文档，结果在OnlyOffice里一打开，直接弹出一个冷冰冰的错误提示——“文件大小超出了为服务器设置的限制”。

我最早遇到这个问题是在一个企业知识库项目中。团队用Nextcloud搭建了内部文件共享，然后集成了OnlyOffice来实现在线协作编辑。一开始大家用得挺开心，直到市场部同事上传了一份包含大量产品渲染图的年度报告PPT，足足有300多兆。点击编辑按钮后，页面转了几圈，然后就卡住了，最后只看到那个让人沮丧的错误提示。

更让人抓狂的是，当你去网上搜索解决方案时，会发现很多教程都是针对旧版本OnlyOffice的。比如很多文章会告诉你去修改/etc/onlyoffice/documentserver/default.json里的maxFileSize参数。我按照这些教程操作了一遍又一遍，重启容器，结果问题依旧。后来才发现，从OnlyOffice 7.2版本开始，单纯修改这个文件已经不够了，因为文件上传和处理的流程涉及到了多个组件和配置。

这个问题的本质在于，OnlyOffice文档服务器默认对上传文件的大小做了严格限制，主要是为了防止恶意上传超大文件耗尽服务器资源。默认限制通常是100MB左右，但对于现代办公场景来说，特别是设计、市场等部门制作的包含大量多媒体内容的文档，这个限制就显得有些捉襟见肘了。

注意：在开始修改之前，请务必备份你的容器数据。虽然下面的操作相对安全，但有备无患总是好的。如果你是通过Docker卷挂载的方式运行的OnlyOffice，那么配置文件可能已经在宿主机上，修改起来会更方便。

2. 理解限制：为什么修改一个配置不够？

在深入实操之前，我们先花点时间搞清楚，为什么在较新版本的OnlyOffice（特别是7.2+）中，只修改一个配置文件无法解决问题。这能帮你避免走弯路，也能在遇到其他类似问题时举一反三。

OnlyOffice文档服务器在处理文件上传和转换时，实际上是一个多层次的“关卡”系统。想象一下你要进入一个重要的办公大楼：第一道关卡是门卫（Nginx），他检查你的包裹大小；第二道关卡是前台（Document Server核心配置），他确认你的文件类型和基础大小；第三道关卡是各个部门的专员（不同的处理服务），他们各自有对文件解压后大小的限制。

第一层：Nginx的client_max_body_size 这是最外层的限制，由Nginx反向代理服务器控制。当你的浏览器上传文件到OnlyOffice时，请求首先经过Nginx。如果文件体积超过了client_max_body_size的设置（默认通常是1MB或更小），Nginx会直接拒绝这个请求，返回“413 Request Entity Too Large”错误。这一步甚至还没到OnlyOffice的应用逻辑。

第二层：Document Server的default.json 这个文件里确实有files.docservice.filetypes.maxFileSize这个参数，它控制着OnlyOffice应用层认可的最大文件大小。但请注意，这个值通常是以字节为单位的，比如默认的104857600就是100MB。然而，在7.2+版本中，仅仅修改这里，你会发现对于ZIP格式的Office文件（.docx, .xlsx, .pptx本质都是ZIP压缩包）仍然无效。

第三层：文件转换服务的深层限制 这才是关键所在。Office文件（.docx等）实际上是ZIP压缩包，里面包含了XML、图片等资源。OnlyOffice在转换文件时需要先解压。production-linux.json（或类似配置文件）和default.json中的FileConverter.converter.inputLimits部分，定义了每种文件类型解压后的最大体积限制。比如，一个100MB的.docx文件，解压后可能变成300MB甚至更大。如果解压后的体积超过了zip.uncompressed的限制，同样会被拒绝。

第四层：下载限制 FileConverter.converter.maxDownloadBytes这个参数限制了文档服务器从源地址（比如你的Nextcloud、Seafile）下载文件时的最大字节数。如果你的文件存储在另一个服务器上，OnlyOffice需要先下载它，这个限制就会生效。

所以你看，这是一个“木桶效应”——最终能处理的最大文件，取决于这四个环节中最低的那个限制。很多网上的旧教程只改了第二层，结果第一层、第三层、第四层的限制还在，问题自然无法解决。

3. 实战开始：进入容器找到所有“开关”

好了，理论讲清楚了，我们开始动手。首先，你需要进入正在运行的OnlyOffice Document Server容器。假设你的容器名字叫onlyoffice_ds（如果你用的是其他名字，记得替换）。

# 使用docker exec命令进入容器的bash环境
docker exec -it onlyoffice_ds bash

进入容器后，你会看到一个命令行提示符，通常类似 root@容器ID:/#。现在我们来找找那几个关键的配置文件都在哪里。

配置文件位置一览：

• /etc/onlyoffice/documentserver/default.json - 核心配置文件，控制应用层限制。
• /etc/onlyoffice/documentserver-example/production-linux.json - 生产环境配置文件，影响文件转换服务。
• /etc/nginx/nginx.conf - Nginx主配置文件，控制HTTP请求体大小。
• /etc/nginx/includes/ds-common.conf 或 /etc/onlyoffice/documentserver/nginx/includes/ds-*.conf - Nginx的OnlyOffice特定配置片段，通常也包含client_max_body_size设置。

我建议先使用cat或less命令查看一下这些文件的原始内容，了解默认值。比如：

# 查看默认文件大小限制
grep -n "maxFileSize\|maxDownloadBytes\|client_max_body_size" /etc/onlyoffice/documentserver/default.json

# 查看Nginx的请求体限制
grep -n "client_max_body_size" /etc/nginx/nginx.conf /etc/nginx/conf.d/* /etc/nginx/includes/* 2>/dev/null

在我的测试环境（OnlyOffice Document Server 7.5）里，默认的maxFileSize是104857600（100MB），而client_max_body_size在Nginx配置里可能根本没有显式设置，那就意味着是Nginx默认的1MB，或者在其他配置文件中被设置成了某个值。

4. 一劳永逸：使用脚本批量修改所有配置

手动一个个文件去查找和修改，既容易出错又麻烦。特别是当你有多个环境需要配置时，重复劳动很低效。下面我分享一个我一直在用的Bash脚本，它能够一次性修改所有相关的配置项。你可以把这个脚本内容复制下来，在容器内直接执行。

#!/usr/bin/env bash

# OnlyOffice Docker容器内一键修改文件大小限制脚本
# 适用于 7