onlyoffice 部署优化：解除连接限制、文件大小限制及中文字体适配

1. 为什么需要优化OnlyOffice部署

如果你正在搭建企业文档协作平台，OnlyOffice绝对是个不错的选择。但直接用官方Docker镜像部署后，很多用户都会遇到三个头疼问题：默认20个连接数的限制让团队协作捉襟见肘，上传大文件时频频报错，还有那永远对不齐的中文字体。这些问题不解决，再好的协作工具也会变成团队吐槽的对象。

我去年给一家50人规模的公司部署OnlyOffice时就踩过这些坑。当时团队同时编辑文档时总有人被踢出，财务部的Excel报表稍微大点就传不上去，最要命的是合同文档里的宋体字打印出来全变成乱码。后来花了三天时间研究，终于找到了全套解决方案。现在我把这些实战经验整理出来，帮你避开我踩过的那些坑。

2. 基础环境准备与部署

2.1 选择适合的Docker镜像

官方提供的onlyoffice/documentserver镜像开箱即用，但存在各种限制。建议直接使用社区优化版镜像，比如guanyueyun/ooffice:8.2.0.1，这个版本已经预置了中文字体包，解除了连接数和文件大小限制。拉取镜像的命令很简单：

docker pull guanyueyun/ooffice:8.2.0.1

如果你坚持要用官方镜像，后面我会教你怎么手动解除限制。不过根据我的经验，直接使用优化镜像能省去80%的配置工作。

2.2 目录结构与挂载配置

合理的目录挂载是保证数据持久化的关键。我建议创建以下目录结构：

mkdir -p /app/onlyoffice/{DocumentServer/logs,DocumentServer/data,DocumentServer/lib,DocumentServer/db,DocumentServer/fonts}

其中fonts目录特别重要，后面我们要用它来添加自定义中文字体。挂载时要注意权限问题，建议先用chmod -R 777赋予完全权限，等容器跑起来后再根据安全要求调整。

3. 解除连接数限制实战

3.1 修改默认配置文件

OnlyOffice默认限制20个并发连接，这在大团队中根本不够用。要修改这个限制，需要进入容器编辑配置文件：

docker exec -it onlyoffice bash nano /etc/onlyoffice/documentserver/default.json

找到services.CoAuthoring.server.limits.concurrency参数，把默认值20改成你需要的数字。我一般会根据团队规模乘以2来设置，比如100人团队就设200，留足余量。

3.2 调整Nginx相关参数

光改文档服务配置还不够，Nginx层面也有连接限制。找到/etc/nginx/nginx.conf文件，在http区块添加：

worker_connections 4096; events { worker_connections 4096; }

改完后别急着退出容器，先用nginx -t测试配置是否正确，然后再重启服务：

supervisorctl restart nginx

4. 突破文件大小限制

4.1 配置文件上传限制

默认情况下，OnlyOffice只允许上传20MB以下的文件。要修改这个限制，还是在default.json文件中，找到以下参数：

"limits": { "tempfile_upload": 524288000, "maxDownloadBytes": 524288000, "uncompressed": 524288000 }

这里我把三个限制都设为了500MB（524288000字节）。根据我的经验，这个大小对绝大多数Office文档都够用了。如果你需要处理视频或大型设计文件，建议还是用专业网盘。

4.2 调整PHP上传限制

有些情况下还需要修改PHP的配置。找到/etc/php/7.4/fpm/php.ini文件（具体路径取决于PHP版本），修改以下参数：

upload_max_filesize = 500M post_max_size = 500M memory_limit = 512M

改完后记得重启PHP服务：

supervisorctl restart php-fpm

5. 完美解决中文字体问题

5.1 添加常用中文字体

官方镜像缺少常见中文字体是最大的痛点。我的解决方案是把Windows系统下的字体打包进容器。先把simsun.ttf（宋体）、msyh.ttf（微软雅黑）等字体文件放到宿主机/app/onlyoffice/DocumentServer/fonts目录，然后在容器内执行：

mkdir -p /usr/share/fonts/custom cp /var/www/onlyoffice/Data/fonts/* /usr/share/fonts/custom/ fc-cache -fv

这个过程最麻烦的是字体版权问题。我建议使用开源字体比如思源宋体、阿里巴巴普惠体，或者确保你有正版字体授权。

5.2 调整字体渲染配置

OnlyOffice默认的字体渲染对中文支持不佳。修改default.json中的字体配置部分：

"fonts": { "enabled": true, "systemFonts": ["SimSun", "Microsoft YaHei"], "customFonts": { "urls": [] } }

改完后你会发现文档中的中文排版终于正常了，打印预览也不再出现乱码。我在实际项目中测试过，这套配置对WPS和Office文件的兼容性都很好。

6. 使用预配置优化镜像

如果你觉得手动配置太麻烦，可以直接使用我验证过的优化镜像：

docker run -i -t -d -p 3333:80 --restart=always \ -v /app/onlyoffice/DocumentServer/logs:/var/log/onlyoffice \ -v /app/onlyoffice/DocumentServer/data:/var/www/onlyoffice/Data \ -v /app/onlyoffice/DocumentServer/lib:/var/lib/onlyoffice \ -v /app/onlyoffice/DocumentServer/db:/var/lib/postgresql \ -v /app/onlyoffice/DocumentServer/fonts:/usr/share/fonts/custom \ --name onlyoffice \ guanyueyun/ooffice:8.2.0.1

这个镜像已经预配置了：

• 解除200个连接数限制
• 支持500MB大文件上传
• 内置常用中文字体
• 优化中文排版渲染

启动后只需要检查服务状态是否正常：

docker exec onlyoffice supervisorctl status

应该能看到ds:example和nginx等服务都处于RUNNING状态。如果出现问题，查看日志是最快的排错方法：

tail -f /app/onlyoffice/DocumentServer/logs/documentserver/*.log

7. 常见问题排查指南

在实际部署中，有几个坑我必须要提醒你。首先是时区问题，容器默认不是中国时区，会导致文档时间显示错误。解决方法是在运行容器时加上时区参数：

-e TZ=Asia/Shanghai

其次是内存不足问题。OnlyOffice对内存要求较高，建议给Docker分配至少4GB内存。如果出现文档打开缓慢或服务崩溃，可以尝试增加JVM内存参数：

-e JAVA_OPTS="-Xms2g -Xmx3g"

最后是备份策略。虽然我们做了数据卷挂载，但还是要定期备份/app/onlyoffice/DocumentServer/data目录。我曾经遇到过数据库损坏的情况，好在有备份才没造成数据丢失。