ONLYOFFICE Docker文档服务器字体安装问题排查指南

问题背景

在使用ONLYOFFICE Docker文档服务器（Documentserver）与Nextcloud集成时，用户遇到了字体显示异常的问题。具体表现为：

1. 默认安装缺少常见字体（如Calibri、Arial、Times New Roman等）
2. 手动添加字体后出现字符显示异常
3. 问题在不同浏览器和设备上表现不一致

核心问题分析

默认字体缺失原因

ONLYOFFICE Docker镜像出于版权考虑，默认仅包含基础字体集。商业字体（如微软Office常用字体）需要用户自行添加。

字体显示异常的根本原因

经过排查发现，问题源于Nginx代理管理器的"缓存资源"功能。该功能会缓存文档服务器的静态资源（包括字体文件），导致：

1. 新添加的字体无法及时生效
2. 浏览器端可能加载到缓存的旧版本字体文件
3. 不同浏览器/设备的缓存策略差异导致表现不一致

解决方案

正确添加字体的步骤

1. 将字体文件（TTF格式）放入挂载目录：

   /media/onlyoffice_documentserver/fonts
   

2. 进入容器执行字体生成命令：

   documentserver-generate-allfonts.sh
   

3. 确保字体文件权限正确（建议644）

缓存问题处理

1. 禁用Nginx代理的静态资源缓存：

   • 在Nginx Proxy Manager中关闭"Cache Assets"选项
   • 或添加以下Nginx配置：

     location ~* \.(eot|ttf|woff|woff2)$ {
         add_header Cache-Control "no-cache";
     }
     

2. 浏览器缓存清理：

   • 使用隐私模式测试
   • 完全清除浏览器缓存（不只是Ctrl+F5）
   • 对于Firefox：设置→隐私与安全→清除数据→勾选"缓存"

技术要点说明

1. 字体替换机制：

   • 当文档使用服务器不存在的字体时，系统会自动选择近似字体
   • 手动输入字体名称会触发警告，但仍可工作

2. 字体目录结构：

   • 字体文件可直接放在/usr/share/fonts目录
   • 也可放在其子目录（如truetype/）中
   • 系统会自动扫描所有子目录

3. 多端表现差异：

   • 不同浏览器对字体缓存的策略不同
   • 移动端应用可能使用独立的缓存机制

最佳实践建议

1. 添加字体后，建议使用以下测试流程：

   • 在隐私窗口测试
   • 使用不同浏览器/设备验证
   • 检查控制台网络请求，确认加载的是最新字体文件

2. 对于生产环境：

   • 建立字体更新后的缓存清理流程
   • 考虑使用CDN时配置适当的缓存头
   • 文档化所使用的字体清单

3. 性能考量：

   • 大量字体添加会增加服务器启动时间
   • 建议仅添加业务必需的字体
   • 监控字体生成过程的资源使用

通过以上方法，可以确保ONLYOFFICE文档服务器正确显示和管理自定义字体，为用户提供一致的文档编辑体验。