1. 项目概述与核心价值最近在折腾一个内部文档协作平台核心需求是找一个能在线编辑Office文档的开源方案。市面上常见的要么功能太弱要么部署复杂要么对中文支持一塌糊涂。经过几轮筛选我把目光锁定在了OnlyOffice Docs上。这玩意儿名气不小号称是开源的“微软Office在线版”能深度兼容.docx、.xlsx、.pptx格式。但真把它搬到自己的Linux服务器上尤其是想让它完美支持中文排版时才发现从安装到调优每一步都可能藏着坑。网上教程要么过于简略要么版本老旧照着做十有八九会卡在字体显示或者服务启动上。所以我决定把这次从零开始在Linux以主流的CentOS 7/Rocky Linux 8为例上部署OnlyOffice Docs并彻底解决中文字体和字号显示问题的完整过程记录下来。这不仅仅是把服务跑起来更是要让它成为团队里真正可用的生产工具。你会发现官方文档没细说的依赖冲突、字体安装的“正确姿势”、以及如何让文档里的宋体、黑体不再显示成乱七八糟的方块或默认字体才是决定成败的关键。无论你是想搭建私有化的文档协同环境还是单纯对这类服务的部署感兴趣这篇踩坑实录都能给你一份可直接“抄作业”的指南。2. 部署环境规划与前期准备在动手安装之前理清环境和思路能避免后续很多不必要的麻烦。OnlyOffice Docs本质上是一个由多个微服务文档服务器、拼写检查、文件转换器等组成的套件对系统环境有一定要求。2.1 系统与资源要求官方推荐使用Red Hat系RHEL、CentOS、Rocky Linux或Debian系Ubuntu、Debian的现代版本。我个人更倾向于Rocky Linux 8或AlmaLinux 8它们作为CentOS的替代品软件源更新更及时。避免使用过于陈旧的系统如CentOS 6其内核和库版本可能导致依赖无法满足。硬件方面对于小团队20人以内的试用或轻度使用建议最低配置CPU: 2核以上。文档渲染特别是复杂格式和大型电子表格比较吃CPU。内存: 4GB RAM是底线推荐8GB。内存不足会直接导致服务崩溃或文档打开极慢。存储: 至少20GB空闲空间。除了系统和服务本身还需要考虑文档存储和日志增长。网络方面确保服务器有稳定的网络连接因为安装脚本会从官方仓库下载包。如果服务器在内网可能需要提前配置代理或搭建本地镜像源。2.2 关键依赖检查与冲突解决这是部署OnlyOffice的第一个“暗礁”。OnlyOffice Docs依赖于特定版本的libstdc、nginx和postgresql。如果你的系统已经安装了这些软件的其他版本很可能产生冲突。检查并处理现有Nginx# 查看当前nginx版本 nginx -v 21 | head -1 # 或者检查是否已安装 rpm -qa | grep nginx如果系统已有NginxOnlyOffice的安装包会自带一个定制版的Nginx两者端口默认都是80/443会冲突。强烈建议先卸载系统自带的Nginx或者确保其完全停止并禁用。使用OnlyOffice自带的Nginx是官方推荐的方式能减少配置复杂度。检查并处理现有PostgreSQL# 检查PostgreSQL systemctl status postgresql 2/dev/null || ps aux | grep postgresOnlyOffice需要PostgreSQL作为数据库。如果系统已有其他版本的PostgreSQL需要评估是否可以迁移或停用。安装脚本通常会处理数据库的初始化但混用版本可能导致数据连接问题。关闭SELinux和防火墙临时用于安装调试 为了避免权限和网络拦截问题在安装和初步调试阶段可以临时关闭它们。生产环境需另行配置规则。# 临时关闭SELinux setenforce 0 # 临时关闭防火墙Firewalld systemctl stop firewalld # 如需永久关闭SELinux编辑 /etc/selinux/config设置 SELINUXdisabled注意依赖冲突是安装失败的首要原因。一个干净的系统环境成功率最高。如果服务器已经运行了其他Web服务需要仔细规划端口和路径避免冲突。3. OnlyOffice Docs 核心安装流程解析解决了环境问题就可以进入正式的安装环节。OnlyOffice提供了多种安装方式这里我们选择最通用、管理方便的RPM包安装。3.1 配置仓库与执行安装首先我们需要将OnlyOffice的官方YUM仓库添加到系统中。# 导入GPG密钥用于验证软件包 sudo rpm --import https://download.onlyoffice.com/GPG-KEY-ONLYOFFICE # 对于Rocky Linux 8 / AlmaLinux 8 / RHEL 8 sudo cat /etc/yum.repos.d/onlyoffice.repo EOF [onlyoffice] nameonlyoffice repo baseurlhttps://download.onlyoffice.com/repo/centos/main/\$basearch enabled1 gpgcheck1 gpgkeyhttps://download.onlyoffice.com/GPG-KEY-ONLYOFFICE EOF添加仓库后更新YUM缓存并执行安装。安装的包名是onlyoffice-documentserver。sudo yum makecache sudo yum install -y onlyoffice-documentserver这个命令会自动安装所有必需的依赖包括其自带的Nginx、PostgreSQL等。安装过程可能需要几分钟取决于网络速度。3.2 安装后初始化与验证安装完成后服务并不会立即启动还需要进行一步关键的初始化配置。启动服务# 启动OnlyOffice Documentserver服务 sudo systemctl start ds-docservice # 设置开机自启 sudo systemctl enable ds-docservice # 同样启动其他相关服务如Nginx和PostgreSQL sudo systemctl start nginx postgresql sudo systemctl enable nginx postgresql验证安装是否成功 打开浏览器访问http://你的服务器IP地址。如果看到OnlyOffice的欢迎页面或者访问http://你的服务器IP地址/welcome/出现配置向导页面说明核心服务已经成功运行。 更直接的验证方法是访问其健康检查接口http://你的服务器IP地址/healthcheck如果返回true则表明所有微服务状态正常。查看服务状态与日志 如果访问不了第一时间查看服务状态和日志。# 查看核心服务状态 sudo systemctl status ds-docservice # 查看Nginx状态 sudo systemctl status nginx # 查看OnlyOffice相关日志通常在这里 sudo tail -f /var/log/onlyoffice/documentserver/*.log # 查看Nginx错误日志 sudo tail -f /var/log/nginx/error.log日志是排查问题的黄金钥匙常见的端口占用、权限错误、依赖缺失都会在这里体现。3.3 安装方式对比与选型建议除了RPM包OnlyOffice还提供Docker和手动编译安装。RPM/DEB包最适合大多数生产环境。优点是与系统集成度高服务管理方便systemctl升级路径清晰。缺点是依赖系统特定版本。Docker部署最快捷隔离性好不受宿主机环境影响。适合快速测试和云原生环境。但需要额外学习Docker管理数据持久化、性能调优和网络配置对新手有一定门槛。手动编译最灵活但过程极其复杂仅适用于有特殊定制需求或深度研究的用户不推荐普通部署。对于绝大多数寻求稳定、易维护的私有化部署场景RPM/DEB包安装是最佳选择。它减少了环境变量、挂载卷等容器特有的复杂度让运维重心更集中在应用本身。4. 中文字体支持从乱码到完美显示服务跑起来只是第一步。上传一个中文文档你可能会发现里面的宋体、楷体全部变成了等宽字体或者方框排版完全错乱。这是因为OnlyOffice的Docker镜像或安装包默认只包含有限的英文字体没有中文字体。解决字体问题是让OnlyOffice真正可用的核心步骤。4.1 字体问题的根源与原理OnlyOffice在服务器端渲染文档时需要找到文档中指定的字体文件。如果找不到就会使用一个默认的字体通常是Liberation Serif或DejaVu Sans进行回退显示这就导致了中文变“方块字”或样式丢失。因此我们需要将常用的中文字体文件安装到OnlyOffice服务能够识别的字体目录中。4.2 获取与准备中文字体文件首先你需要合法的中文字体文件。通常我们可以使用操作系统自带的字体或者从合法渠道获取如“思源”系列开源字体。从Windows系统提取适用于有Windows许可证的情况 在Windows的C:\Windows\Fonts目录下可以找到simsun.ttc宋体/新宋体、simhei.ttf黑体、simkai.ttf楷体、simfang.ttf仿宋等核心字体。将这些文件复制到Linux服务器上。使用开源字体推荐无版权风险思源系列Source Han Sans/Source Han SerifAdobe与Google合作开发的开源字体覆盖简繁中日韩质量极高。可以从GitHub仓库直接下载。文泉驿系列经典的开源中文字体。 这里以安装“思源黑体”和“思源宋体”为例# 创建临时目录并下载字体 mkdir -p /tmp/chinese_fonts cd /tmp/chinese_fonts # 下载思源黑体简体中文OTF格式 wget https://github.com/adobe-fonts/source-han-sans/releases/download/2.004R/SourceHanSansSC.zip # 下载思源宋体简体中文OTF格式 wget https://github.com/adobe-fonts/source-han-serif/releases/download/2.001R/SourceHanSerifSC_OTF.zip # 解压 unzip SourceHanSansSC.zip unzip SourceHanSerifSC_OTF.zip解压后你会在子目录中找到大量的.otf字体文件。4.3 安装字体到OnlyOffice系统OnlyOffice Documentserver有自己独立的字体目录。我们需要将字体文件复制进去并重建字体缓存。定位字体目录 对于RPM安装核心字体目录通常在/var/www/onlyoffice/documentserver/core-fonts。但更规范的做法是放入/usr/share/fonts/下的专属目录并让系统识别。不过OnlyOffice服务可能不直接读取系统字体。经过测试最可靠的方法是放入其自带的字体目录并更新其缓存。# OnlyOffice Documentserver 的字体目录 TARGET_FONT_DIR/var/www/onlyoffice/documentserver/core-fonts复制字体文件 将你准备好的所有.ttf、.ttc或.otf字体文件复制到目标目录。建议直接复制而不是移动保留原文件备份。# 假设你的字体文件在 /tmp/chinese_fonts/ 下 sudo cp /tmp/chinese_fonts/**/*.otf /tmp/chinese_fonts/**/*.ttf /tmp/chinese_fonts/**/*.ttc $TARGET_FONT_DIR/ 2/dev/null || true # 也可以单独复制关键字体如从Windows复制的 sudo cp simsun.ttc simhei.ttf $TARGET_FONT_DIR/复制完成后务必修改字体文件的权限让OnlyOffice服务进程通常以onlyoffice或ds用户运行有读取权限。sudo chown -R onlyoffice:onlyoffice $TARGET_FONT_DIR/ sudo chmod 644 $TARGET_FONT_DIR/*重建字体缓存最关键的一步 仅仅复制文件是不够的必须让OnlyOffice的字体服务重新扫描并建立索引。# 切换到OnlyOffice的脚本目录 cd /var/www/onlyoffice/documentserver/ # 执行字体缓存重建和服务重启脚本 sudo sudo -u onlyoffice bash -c npm run rebuild-fontcache # 或者使用工具脚本如果上述命令无效 sudo documentserver-generate-allfonts.sh这个过程会花费一些时间因为它需要解析所有字体文件并生成元数据。重启服务 重建缓存后重启OnlyOffice服务使更改生效。sudo systemctl restart ds-docservice sudo systemctl restart nginx4.4 验证字体安装效果如何确认字体安装成功了呢通过OnlyOffice欢迎页测试 再次访问http://你的服务器IP地址在欢迎页面通常有一个“Document Server is running”的提示。更有效的方法是如果你已经集成了Nextcloud、Confluence等可以直接上传一个中文文档测试。使用API接口查询最准确 OnlyOffice提供了一个API接口来列出所有可用字体。访问http://你的服务器IP地址/ds-vpath/字体列表接口注意接口路径可能随版本变化。一个更通用的方法是创建一个简单的测试文档。 你可以编写一个简单的HTML页面通过OnlyOffice的JavaScript API嵌入一个编辑器并在控制台查看字体列表。或者直接在其Demo页面如果安装时包含了进行测试。直接观察 上传一个指定了“宋体”、“黑体”、“楷体”等字体的.docx文档进行在线预览和编辑。如果字体名称正确显示在编辑器的字体下拉框中并且文档内容能按指定字体渲染说明安装成功。实操心得字体安装后服务重启不生效是最常见的问题。90%的情况是字体缓存没有成功重建或者重建后服务没有完全重启。务必确认sudo -u onlyoffice npm run rebuild-fontcache命令执行成功且无报错。另外.ttc字体集合文件有时识别会有问题如果遇到问题可以尝试使用.ttf格式的单一字体文件。5. 字号与排版深度调优实践解决了字体有无的问题接下来要解决“好不好看”的问题。中文排版与英文有显著差异默认的英文字号映射和行距可能让中文文档看起来稀疏或拥挤。5.1 中文排版的核心挑战OnlyOffice默认的排版引擎是针对西文字符优化的。这会导致几个典型问题字号感知差异西文字体的“磅值”(pt)与中文字体的实际视觉大小感受不同。同样的12pt中文字体可能看起来比西文字体小。行距与段落间距中文文档通常需要更大的行距如1.5倍行距才能有良好的可读性而默认模板可能更紧凑。标点挤压与避头尾专业的中文排版要求标点符号不能出现在行首避头部分符号不能出现在行尾避尾。OnlyOffice对此的支持程度需要测试。5.2 配置默认模板与样式最有效的调优方式不是事后修改每一个文档而是定制OnlyOffice使用的默认文档模板。定位模板文件 OnlyOffice的默认模板文件通常位于/var/www/onlyoffice/documentserver/sdkjs-word/下的某个模板目录中但直接修改并不总是被推荐因为升级可能被覆盖。更稳妥的方式是通过其配置或API在应用层指定默认模板。创建自定义中文模板在本地用Microsoft Office或OnlyOffice桌面编辑器创建一个新的空白文档。设置好你期望的默认样式正文样式字体设置为“思源宋体”或“宋体”字号“小四”12pt西文字体设为“Times New Roman”或“Arial”行距设为“1.5倍行距”。标题样式依次定义好“标题1”到“标题3”的字体、字号和加粗。默认段落设置段前段后间距为“0行”首行缩进“2字符”。将文档另存为.dotx格式Word模板。应用自定义模板 对于私有化部署可以通过修改OnlyOffice的集成配置指定这个模板文件作为所有新建文档的基准。这通常需要在你集成OnlyOffice的Web应用如Nextcloud、Seafile或自研系统中完成配置指定document.template的URL路径。5.3 通过CSS进行界面微调如果你发现编辑器界面本身的字体下拉框显示字号不合适或者预览区域整体缩放不舒服可以通过注入自定义CSS进行微调。这需要修改OnlyOffice Documentserver的Web前端文件。警告此操作涉及直接修改生产文件升级时可能会被覆盖务必做好备份。找到前端主题文件# 通常主题CSS文件在这里 find /var/www/onlyoffice/documentserver/web-apps -name *.css | grep -i theme常见的路径可能是/var/www/onlyoffice/documentserver/web-apps/apps/documenteditor/main/resources/theme/css/。备份并修改 备份原文件后你可以添加一些CSS规则来覆盖默认样式。例如增加字体下拉框的字体预览大小/* 示例增大字体选择列表的显示 */ .asc-fontlist-item { font-size: 14px !important; }修改后需要清除浏览器缓存才能看到效果。注意事项前端修改是最后的手段且风险较高。优先通过配置默认模板来解决文档内容本身的排版问题。界面字体大小问题有时也可以通过调整浏览器缩放比例来临时解决。6. 生产环境部署强化与性能调优让OnlyOffice在测试环境跑起来只是第一步要用于实际团队协作还需要考虑安全、性能和稳定性。6.1 安全配置要点启用HTTPS 绝对不要在公网或内网敏感环境中使用HTTP。使用Let‘s Encrypt免费证书或商业SSL证书配置Nginx。 OnlyOffice的Nginx配置文件通常位于/etc/nginx/conf.d/ds.conf。你需要修改它将监听80端口的服务器块重定向到443并配置SSL证书和密钥路径。server { listen 443 ssl http2; server_name your.domain.com; ssl_certificate /path/to/your/fullchain.pem; ssl_certificate_key /path/to/your/privkey.pem; # ... 其他OnlyOffice原有配置 ... } server { listen 80; server_name your.domain.com; return 301 https://$server_name$request_uri; }修改后运行sudo nginx -t测试配置无误后sudo systemctl reload nginx。配置防火墙 重新开启防火墙只开放必要的端口。sudo systemctl start firewalld sudo firewall-cmd --permanent --add-servicehttp sudo firewall-cmd --permanent --add-servicehttps sudo firewall-cmd --reload如果OnlyOffice需要与内部其他服务如Nextcloud通信还需确保它们之间的网络是连通的。限制访问IP可选但重要 如果OnlyOffice只供内部网络使用可以在Nginx配置中设置allow和deny规则限制仅特定IP段可以访问。6.2 性能与稳定性优化调整工作进程与连接数 编辑OnlyOffice相关的服务配置。对于文档转换服务可以调整其并发处理能力。配置文件可能在/etc/onlyoffice/documentserver/*.ini或/etc/onlyoffice/documentserver/default.json中。需要关注的参数如worker_processesNginx工作进程数通常设置为CPU核心数、文档处理服务的线程池大小等。修改前请查阅对应版本的官方文档。配置日志轮转与监控 默认日志会不断增长。配置logrotate来管理日志文件避免磁盘被撑满。sudo vi /etc/logrotate.d/onlyoffice-documentserver添加如下内容/var/log/onlyoffice/documentserver/*.log { daily missingok rotate 30 compress delaycompress notifempty create 640 onlyoffice onlyoffice sharedscripts postrotate systemctl reload ds-docservice /dev/null 21 || true endscript }同时建议配置基本的系统监控如node_exporterPrometheusGrafana关注服务器的CPU、内存、磁盘IO和网络流量特别是在多人同时编辑大文档时。数据备份策略 OnlyOffice的核心数据包括PostgreSQL数据库存储文档元数据、用户会话等。位置通常在/var/lib/pgsql/data/或/var/www/onlyoffice/Data/。文件存储目录存储缓存和临时文件。位置可能在/var/www/onlyoffice/Data/下。配置文件/etc/onlyoffice/documentserver/下的各种配置。 你需要制定定期备份计划可以使用pg_dump备份数据库用rsync或tar备份文件目录。6.3 与第三方应用集成配置OnlyOffice的强大之处在于与现有系统的集成。以Nextcloud为例集成后可以在Nextcloud中直接在线编辑Office文件。在Nextcloud中安装OnlyOffice应用 在Nextcloud的应用市场搜索“OnlyOffice”安装并启用。配置连接 在Nextcloud管理设置中找到OnlyOffice配置页面。关键配置项是“Documentserver address”填写你的OnlyOffice服务器地址必须是HTTPS且能被Nextcloud访问到的地址。例如https://onlyoffice.yourcompany.com。 然后点击“Verify connection”如果成功下方会显示OnlyOffice的版本信息。处理内部地址问题 这是集成中最常见的坑。如果你的Nextcloud和OnlyOffice都在内网且通过公网域名访问可能会遇到“地址不可达”的错误。需要在OnlyOffice的配置中指定允许访问的域名并配置内部解析。编辑OnlyOffice的配置文件/etc/onlyoffice/documentserver/local.json如果不存在则创建它并确保与default.json合并正确。添加或修改storage部分指定host和port确保其使用内部可访问的地址。踩坑实录集成失败十有八九是网络连通性或地址配置错误。务必确保Nextcloud服务器能通过你填写的地址无论是域名还是IP真正访问到OnlyOffice服务器的80/443端口可用curl或wget测试。OnlyOffice的配置中允许来自Nextcloud服务器IP的请求。如果用了反向代理或负载均衡代理设置要正确传递真实主机头。7. 故障排查与日常维护指南即使一切配置妥当在生产环境中运行也难免遇到问题。这里汇总一些常见故障及其排查思路。7.1 服务启动失败与日志分析问题现象sudo systemctl status ds-docservice显示服务状态为failed或inactive。排查步骤查看详细日志sudo journalctl -u ds-docservice -xe或查看/var/log/onlyoffice/documentserver/docservice.log、converter.log等。常见原因端口占用检查80、443、5432PostgreSQL、8080等端口是否被其他程序占用。sudo netstat -tlnp | grep :80。依赖缺失或冲突特别是libstdc、nginx版本冲突。回顾安装前的环境清理步骤。权限问题确保/var/www/onlyoffice/、/var/log/onlyoffice/等目录的所有者和组是onlyoffice且有读写权限。数据库连接失败检查PostgreSQL服务是否正常运行以及OnlyOffice配置中的数据库连接字符串是否正确。7.2 文档打开缓慢或编辑卡顿问题现象用户反映打开文档、输入内容或保存时速度很慢。排查步骤检查服务器资源使用top、htop、free -m命令查看CPU、内存、Swap使用情况。内存不足会导致频繁交换是性能杀手。检查网络延迟如果编辑器前端浏览器与文档服务器网络延迟高操作会明显卡顿。特别是在跨公网或跨地域访问时。分析文档复杂度含有大量高清图片、复杂图表或特殊格式的文档渲染和计算开销巨大。可以尝试打开一个纯文本文档对比测试。查看文档服务器日志关注docservice.log中是否有大量的错误或超时记录。调整配置如前文所述适当增加文档处理服务的线程数或JVM内存如果服务是Java写的。配置文件路径可能在/etc/onlyoffice/documentserver/docservice.ini。7.3 字体相关遗留问题问题现象字体已安装但部分文档仍显示异常或字体下拉框不显示中文字体名。排查步骤确认字体缓存已更新再次运行cd /var/www/onlyoffice/documentserver sudo -u onlyoffice npm run rebuild-fontcache观察是否有错误输出。检查字体文件格式某些.ttc字体集合文件可能兼容性不佳。尝试使用.ttf格式的单一字体文件。检查字体名称在Windows上“宋体”的字体家族名可能是SimSun而“新宋体”是NSimSun。在OnlyOffice中字体下拉框显示的是字体文件的“家族名”(Family Name)。你可以使用fc-list命令需安装fontconfig查看系统识别的字体名或者用工具如fontforge查看字体元数据。确保文档中使用的字体名与服务器上安装的字体家族名完全一致。浏览器缓存强制刷新浏览器缓存CtrlF5或者尝试在无痕模式下访问。7.4 定期维护任务为了系统长期稳定运行建议建立以下维护习惯日志清理借助配置好的logrotate防止日志占满磁盘。系统更新定期运行sudo yum update更新系统安全补丁但谨慎更新OnlyOffice本身除非确认新版本与你的集成应用兼容。升级前务必在测试环境验证并备份全部数据。磁盘空间监控监控/var/www/onlyoffice/Data目录的大小临时文件可能会积累。备份验证定期检查备份文件是否可成功恢复确保备份策略有效。部署和优化OnlyOffice是一个系统工程从安装、字体配置到生产调优每一步都需要耐心和细致的排查。整个过程的核心逻辑是先确保基础服务通畅再解决内容渲染字体最后优化体验和稳定排版、性能、安全。当你的团队能够流畅地在线协作编辑中文文档时这些前期的投入就都是值得的。如果在操作中遇到上面没覆盖的问题多查日志多从网络连通性、服务状态、文件权限这几个基础维度去分析大部分问题都能找到突破口。 Linux部署OnlyOffice Docs：解决中文字体与生产环境调优全攻略
1. 项目概述与核心价值最近在折腾一个内部文档协作平台核心需求是找一个能在线编辑Office文档的开源方案。市面上常见的要么功能太弱要么部署复杂要么对中文支持一塌糊涂。经过几轮筛选我把目光锁定在了OnlyOffice Docs上。这玩意儿名气不小号称是开源的“微软Office在线版”能深度兼容.docx、.xlsx、.pptx格式。但真把它搬到自己的Linux服务器上尤其是想让它完美支持中文排版时才发现从安装到调优每一步都可能藏着坑。网上教程要么过于简略要么版本老旧照着做十有八九会卡在字体显示或者服务启动上。所以我决定把这次从零开始在Linux以主流的CentOS 7/Rocky Linux 8为例上部署OnlyOffice Docs并彻底解决中文字体和字号显示问题的完整过程记录下来。这不仅仅是把服务跑起来更是要让它成为团队里真正可用的生产工具。你会发现官方文档没细说的依赖冲突、字体安装的“正确姿势”、以及如何让文档里的宋体、黑体不再显示成乱七八糟的方块或默认字体才是决定成败的关键。无论你是想搭建私有化的文档协同环境还是单纯对这类服务的部署感兴趣这篇踩坑实录都能给你一份可直接“抄作业”的指南。2. 部署环境规划与前期准备在动手安装之前理清环境和思路能避免后续很多不必要的麻烦。OnlyOffice Docs本质上是一个由多个微服务文档服务器、拼写检查、文件转换器等组成的套件对系统环境有一定要求。2.1 系统与资源要求官方推荐使用Red Hat系RHEL、CentOS、Rocky Linux或Debian系Ubuntu、Debian的现代版本。我个人更倾向于Rocky Linux 8或AlmaLinux 8它们作为CentOS的替代品软件源更新更及时。避免使用过于陈旧的系统如CentOS 6其内核和库版本可能导致依赖无法满足。硬件方面对于小团队20人以内的试用或轻度使用建议最低配置CPU: 2核以上。文档渲染特别是复杂格式和大型电子表格比较吃CPU。内存: 4GB RAM是底线推荐8GB。内存不足会直接导致服务崩溃或文档打开极慢。存储: 至少20GB空闲空间。除了系统和服务本身还需要考虑文档存储和日志增长。网络方面确保服务器有稳定的网络连接因为安装脚本会从官方仓库下载包。如果服务器在内网可能需要提前配置代理或搭建本地镜像源。2.2 关键依赖检查与冲突解决这是部署OnlyOffice的第一个“暗礁”。OnlyOffice Docs依赖于特定版本的libstdc、nginx和postgresql。如果你的系统已经安装了这些软件的其他版本很可能产生冲突。检查并处理现有Nginx# 查看当前nginx版本 nginx -v 21 | head -1 # 或者检查是否已安装 rpm -qa | grep nginx如果系统已有NginxOnlyOffice的安装包会自带一个定制版的Nginx两者端口默认都是80/443会冲突。强烈建议先卸载系统自带的Nginx或者确保其完全停止并禁用。使用OnlyOffice自带的Nginx是官方推荐的方式能减少配置复杂度。检查并处理现有PostgreSQL# 检查PostgreSQL systemctl status postgresql 2/dev/null || ps aux | grep postgresOnlyOffice需要PostgreSQL作为数据库。如果系统已有其他版本的PostgreSQL需要评估是否可以迁移或停用。安装脚本通常会处理数据库的初始化但混用版本可能导致数据连接问题。关闭SELinux和防火墙临时用于安装调试 为了避免权限和网络拦截问题在安装和初步调试阶段可以临时关闭它们。生产环境需另行配置规则。# 临时关闭SELinux setenforce 0 # 临时关闭防火墙Firewalld systemctl stop firewalld # 如需永久关闭SELinux编辑 /etc/selinux/config设置 SELINUXdisabled注意依赖冲突是安装失败的首要原因。一个干净的系统环境成功率最高。如果服务器已经运行了其他Web服务需要仔细规划端口和路径避免冲突。3. OnlyOffice Docs 核心安装流程解析解决了环境问题就可以进入正式的安装环节。OnlyOffice提供了多种安装方式这里我们选择最通用、管理方便的RPM包安装。3.1 配置仓库与执行安装首先我们需要将OnlyOffice的官方YUM仓库添加到系统中。# 导入GPG密钥用于验证软件包 sudo rpm --import https://download.onlyoffice.com/GPG-KEY-ONLYOFFICE # 对于Rocky Linux 8 / AlmaLinux 8 / RHEL 8 sudo cat /etc/yum.repos.d/onlyoffice.repo EOF [onlyoffice] nameonlyoffice repo baseurlhttps://download.onlyoffice.com/repo/centos/main/\$basearch enabled1 gpgcheck1 gpgkeyhttps://download.onlyoffice.com/GPG-KEY-ONLYOFFICE EOF添加仓库后更新YUM缓存并执行安装。安装的包名是onlyoffice-documentserver。sudo yum makecache sudo yum install -y onlyoffice-documentserver这个命令会自动安装所有必需的依赖包括其自带的Nginx、PostgreSQL等。安装过程可能需要几分钟取决于网络速度。3.2 安装后初始化与验证安装完成后服务并不会立即启动还需要进行一步关键的初始化配置。启动服务# 启动OnlyOffice Documentserver服务 sudo systemctl start ds-docservice # 设置开机自启 sudo systemctl enable ds-docservice # 同样启动其他相关服务如Nginx和PostgreSQL sudo systemctl start nginx postgresql sudo systemctl enable nginx postgresql验证安装是否成功 打开浏览器访问http://你的服务器IP地址。如果看到OnlyOffice的欢迎页面或者访问http://你的服务器IP地址/welcome/出现配置向导页面说明核心服务已经成功运行。 更直接的验证方法是访问其健康检查接口http://你的服务器IP地址/healthcheck如果返回true则表明所有微服务状态正常。查看服务状态与日志 如果访问不了第一时间查看服务状态和日志。# 查看核心服务状态 sudo systemctl status ds-docservice # 查看Nginx状态 sudo systemctl status nginx # 查看OnlyOffice相关日志通常在这里 sudo tail -f /var/log/onlyoffice/documentserver/*.log # 查看Nginx错误日志 sudo tail -f /var/log/nginx/error.log日志是排查问题的黄金钥匙常见的端口占用、权限错误、依赖缺失都会在这里体现。3.3 安装方式对比与选型建议除了RPM包OnlyOffice还提供Docker和手动编译安装。RPM/DEB包最适合大多数生产环境。优点是与系统集成度高服务管理方便systemctl升级路径清晰。缺点是依赖系统特定版本。Docker部署最快捷隔离性好不受宿主机环境影响。适合快速测试和云原生环境。但需要额外学习Docker管理数据持久化、性能调优和网络配置对新手有一定门槛。手动编译最灵活但过程极其复杂仅适用于有特殊定制需求或深度研究的用户不推荐普通部署。对于绝大多数寻求稳定、易维护的私有化部署场景RPM/DEB包安装是最佳选择。它减少了环境变量、挂载卷等容器特有的复杂度让运维重心更集中在应用本身。4. 中文字体支持从乱码到完美显示服务跑起来只是第一步。上传一个中文文档你可能会发现里面的宋体、楷体全部变成了等宽字体或者方框排版完全错乱。这是因为OnlyOffice的Docker镜像或安装包默认只包含有限的英文字体没有中文字体。解决字体问题是让OnlyOffice真正可用的核心步骤。4.1 字体问题的根源与原理OnlyOffice在服务器端渲染文档时需要找到文档中指定的字体文件。如果找不到就会使用一个默认的字体通常是Liberation Serif或DejaVu Sans进行回退显示这就导致了中文变“方块字”或样式丢失。因此我们需要将常用的中文字体文件安装到OnlyOffice服务能够识别的字体目录中。4.2 获取与准备中文字体文件首先你需要合法的中文字体文件。通常我们可以使用操作系统自带的字体或者从合法渠道获取如“思源”系列开源字体。从Windows系统提取适用于有Windows许可证的情况 在Windows的C:\Windows\Fonts目录下可以找到simsun.ttc宋体/新宋体、simhei.ttf黑体、simkai.ttf楷体、simfang.ttf仿宋等核心字体。将这些文件复制到Linux服务器上。使用开源字体推荐无版权风险思源系列Source Han Sans/Source Han SerifAdobe与Google合作开发的开源字体覆盖简繁中日韩质量极高。可以从GitHub仓库直接下载。文泉驿系列经典的开源中文字体。 这里以安装“思源黑体”和“思源宋体”为例# 创建临时目录并下载字体 mkdir -p /tmp/chinese_fonts cd /tmp/chinese_fonts # 下载思源黑体简体中文OTF格式 wget https://github.com/adobe-fonts/source-han-sans/releases/download/2.004R/SourceHanSansSC.zip # 下载思源宋体简体中文OTF格式 wget https://github.com/adobe-fonts/source-han-serif/releases/download/2.001R/SourceHanSerifSC_OTF.zip # 解压 unzip SourceHanSansSC.zip unzip SourceHanSerifSC_OTF.zip解压后你会在子目录中找到大量的.otf字体文件。4.3 安装字体到OnlyOffice系统OnlyOffice Documentserver有自己独立的字体目录。我们需要将字体文件复制进去并重建字体缓存。定位字体目录 对于RPM安装核心字体目录通常在/var/www/onlyoffice/documentserver/core-fonts。但更规范的做法是放入/usr/share/fonts/下的专属目录并让系统识别。不过OnlyOffice服务可能不直接读取系统字体。经过测试最可靠的方法是放入其自带的字体目录并更新其缓存。# OnlyOffice Documentserver 的字体目录 TARGET_FONT_DIR/var/www/onlyoffice/documentserver/core-fonts复制字体文件 将你准备好的所有.ttf、.ttc或.otf字体文件复制到目标目录。建议直接复制而不是移动保留原文件备份。# 假设你的字体文件在 /tmp/chinese_fonts/ 下 sudo cp /tmp/chinese_fonts/**/*.otf /tmp/chinese_fonts/**/*.ttf /tmp/chinese_fonts/**/*.ttc $TARGET_FONT_DIR/ 2/dev/null || true # 也可以单独复制关键字体如从Windows复制的 sudo cp simsun.ttc simhei.ttf $TARGET_FONT_DIR/复制完成后务必修改字体文件的权限让OnlyOffice服务进程通常以onlyoffice或ds用户运行有读取权限。sudo chown -R onlyoffice:onlyoffice $TARGET_FONT_DIR/ sudo chmod 644 $TARGET_FONT_DIR/*重建字体缓存最关键的一步 仅仅复制文件是不够的必须让OnlyOffice的字体服务重新扫描并建立索引。# 切换到OnlyOffice的脚本目录 cd /var/www/onlyoffice/documentserver/ # 执行字体缓存重建和服务重启脚本 sudo sudo -u onlyoffice bash -c npm run rebuild-fontcache # 或者使用工具脚本如果上述命令无效 sudo documentserver-generate-allfonts.sh这个过程会花费一些时间因为它需要解析所有字体文件并生成元数据。重启服务 重建缓存后重启OnlyOffice服务使更改生效。sudo systemctl restart ds-docservice sudo systemctl restart nginx4.4 验证字体安装效果如何确认字体安装成功了呢通过OnlyOffice欢迎页测试 再次访问http://你的服务器IP地址在欢迎页面通常有一个“Document Server is running”的提示。更有效的方法是如果你已经集成了Nextcloud、Confluence等可以直接上传一个中文文档测试。使用API接口查询最准确 OnlyOffice提供了一个API接口来列出所有可用字体。访问http://你的服务器IP地址/ds-vpath/字体列表接口注意接口路径可能随版本变化。一个更通用的方法是创建一个简单的测试文档。 你可以编写一个简单的HTML页面通过OnlyOffice的JavaScript API嵌入一个编辑器并在控制台查看字体列表。或者直接在其Demo页面如果安装时包含了进行测试。直接观察 上传一个指定了“宋体”、“黑体”、“楷体”等字体的.docx文档进行在线预览和编辑。如果字体名称正确显示在编辑器的字体下拉框中并且文档内容能按指定字体渲染说明安装成功。实操心得字体安装后服务重启不生效是最常见的问题。90%的情况是字体缓存没有成功重建或者重建后服务没有完全重启。务必确认sudo -u onlyoffice npm run rebuild-fontcache命令执行成功且无报错。另外.ttc字体集合文件有时识别会有问题如果遇到问题可以尝试使用.ttf格式的单一字体文件。5. 字号与排版深度调优实践解决了字体有无的问题接下来要解决“好不好看”的问题。中文排版与英文有显著差异默认的英文字号映射和行距可能让中文文档看起来稀疏或拥挤。5.1 中文排版的核心挑战OnlyOffice默认的排版引擎是针对西文字符优化的。这会导致几个典型问题字号感知差异西文字体的“磅值”(pt)与中文字体的实际视觉大小感受不同。同样的12pt中文字体可能看起来比西文字体小。行距与段落间距中文文档通常需要更大的行距如1.5倍行距才能有良好的可读性而默认模板可能更紧凑。标点挤压与避头尾专业的中文排版要求标点符号不能出现在行首避头部分符号不能出现在行尾避尾。OnlyOffice对此的支持程度需要测试。5.2 配置默认模板与样式最有效的调优方式不是事后修改每一个文档而是定制OnlyOffice使用的默认文档模板。定位模板文件 OnlyOffice的默认模板文件通常位于/var/www/onlyoffice/documentserver/sdkjs-word/下的某个模板目录中但直接修改并不总是被推荐因为升级可能被覆盖。更稳妥的方式是通过其配置或API在应用层指定默认模板。创建自定义中文模板在本地用Microsoft Office或OnlyOffice桌面编辑器创建一个新的空白文档。设置好你期望的默认样式正文样式字体设置为“思源宋体”或“宋体”字号“小四”12pt西文字体设为“Times New Roman”或“Arial”行距设为“1.5倍行距”。标题样式依次定义好“标题1”到“标题3”的字体、字号和加粗。默认段落设置段前段后间距为“0行”首行缩进“2字符”。将文档另存为.dotx格式Word模板。应用自定义模板 对于私有化部署可以通过修改OnlyOffice的集成配置指定这个模板文件作为所有新建文档的基准。这通常需要在你集成OnlyOffice的Web应用如Nextcloud、Seafile或自研系统中完成配置指定document.template的URL路径。5.3 通过CSS进行界面微调如果你发现编辑器界面本身的字体下拉框显示字号不合适或者预览区域整体缩放不舒服可以通过注入自定义CSS进行微调。这需要修改OnlyOffice Documentserver的Web前端文件。警告此操作涉及直接修改生产文件升级时可能会被覆盖务必做好备份。找到前端主题文件# 通常主题CSS文件在这里 find /var/www/onlyoffice/documentserver/web-apps -name *.css | grep -i theme常见的路径可能是/var/www/onlyoffice/documentserver/web-apps/apps/documenteditor/main/resources/theme/css/。备份并修改 备份原文件后你可以添加一些CSS规则来覆盖默认样式。例如增加字体下拉框的字体预览大小/* 示例增大字体选择列表的显示 */ .asc-fontlist-item { font-size: 14px !important; }修改后需要清除浏览器缓存才能看到效果。注意事项前端修改是最后的手段且风险较高。优先通过配置默认模板来解决文档内容本身的排版问题。界面字体大小问题有时也可以通过调整浏览器缩放比例来临时解决。6. 生产环境部署强化与性能调优让OnlyOffice在测试环境跑起来只是第一步要用于实际团队协作还需要考虑安全、性能和稳定性。6.1 安全配置要点启用HTTPS 绝对不要在公网或内网敏感环境中使用HTTP。使用Let‘s Encrypt免费证书或商业SSL证书配置Nginx。 OnlyOffice的Nginx配置文件通常位于/etc/nginx/conf.d/ds.conf。你需要修改它将监听80端口的服务器块重定向到443并配置SSL证书和密钥路径。server { listen 443 ssl http2; server_name your.domain.com; ssl_certificate /path/to/your/fullchain.pem; ssl_certificate_key /path/to/your/privkey.pem; # ... 其他OnlyOffice原有配置 ... } server { listen 80; server_name your.domain.com; return 301 https://$server_name$request_uri; }修改后运行sudo nginx -t测试配置无误后sudo systemctl reload nginx。配置防火墙 重新开启防火墙只开放必要的端口。sudo systemctl start firewalld sudo firewall-cmd --permanent --add-servicehttp sudo firewall-cmd --permanent --add-servicehttps sudo firewall-cmd --reload如果OnlyOffice需要与内部其他服务如Nextcloud通信还需确保它们之间的网络是连通的。限制访问IP可选但重要 如果OnlyOffice只供内部网络使用可以在Nginx配置中设置allow和deny规则限制仅特定IP段可以访问。6.2 性能与稳定性优化调整工作进程与连接数 编辑OnlyOffice相关的服务配置。对于文档转换服务可以调整其并发处理能力。配置文件可能在/etc/onlyoffice/documentserver/*.ini或/etc/onlyoffice/documentserver/default.json中。需要关注的参数如worker_processesNginx工作进程数通常设置为CPU核心数、文档处理服务的线程池大小等。修改前请查阅对应版本的官方文档。配置日志轮转与监控 默认日志会不断增长。配置logrotate来管理日志文件避免磁盘被撑满。sudo vi /etc/logrotate.d/onlyoffice-documentserver添加如下内容/var/log/onlyoffice/documentserver/*.log { daily missingok rotate 30 compress delaycompress notifempty create 640 onlyoffice onlyoffice sharedscripts postrotate systemctl reload ds-docservice /dev/null 21 || true endscript }同时建议配置基本的系统监控如node_exporterPrometheusGrafana关注服务器的CPU、内存、磁盘IO和网络流量特别是在多人同时编辑大文档时。数据备份策略 OnlyOffice的核心数据包括PostgreSQL数据库存储文档元数据、用户会话等。位置通常在/var/lib/pgsql/data/或/var/www/onlyoffice/Data/。文件存储目录存储缓存和临时文件。位置可能在/var/www/onlyoffice/Data/下。配置文件/etc/onlyoffice/documentserver/下的各种配置。 你需要制定定期备份计划可以使用pg_dump备份数据库用rsync或tar备份文件目录。6.3 与第三方应用集成配置OnlyOffice的强大之处在于与现有系统的集成。以Nextcloud为例集成后可以在Nextcloud中直接在线编辑Office文件。在Nextcloud中安装OnlyOffice应用 在Nextcloud的应用市场搜索“OnlyOffice”安装并启用。配置连接 在Nextcloud管理设置中找到OnlyOffice配置页面。关键配置项是“Documentserver address”填写你的OnlyOffice服务器地址必须是HTTPS且能被Nextcloud访问到的地址。例如https://onlyoffice.yourcompany.com。 然后点击“Verify connection”如果成功下方会显示OnlyOffice的版本信息。处理内部地址问题 这是集成中最常见的坑。如果你的Nextcloud和OnlyOffice都在内网且通过公网域名访问可能会遇到“地址不可达”的错误。需要在OnlyOffice的配置中指定允许访问的域名并配置内部解析。编辑OnlyOffice的配置文件/etc/onlyoffice/documentserver/local.json如果不存在则创建它并确保与default.json合并正确。添加或修改storage部分指定host和port确保其使用内部可访问的地址。踩坑实录集成失败十有八九是网络连通性或地址配置错误。务必确保Nextcloud服务器能通过你填写的地址无论是域名还是IP真正访问到OnlyOffice服务器的80/443端口可用curl或wget测试。OnlyOffice的配置中允许来自Nextcloud服务器IP的请求。如果用了反向代理或负载均衡代理设置要正确传递真实主机头。7. 故障排查与日常维护指南即使一切配置妥当在生产环境中运行也难免遇到问题。这里汇总一些常见故障及其排查思路。7.1 服务启动失败与日志分析问题现象sudo systemctl status ds-docservice显示服务状态为failed或inactive。排查步骤查看详细日志sudo journalctl -u ds-docservice -xe或查看/var/log/onlyoffice/documentserver/docservice.log、converter.log等。常见原因端口占用检查80、443、5432PostgreSQL、8080等端口是否被其他程序占用。sudo netstat -tlnp | grep :80。依赖缺失或冲突特别是libstdc、nginx版本冲突。回顾安装前的环境清理步骤。权限问题确保/var/www/onlyoffice/、/var/log/onlyoffice/等目录的所有者和组是onlyoffice且有读写权限。数据库连接失败检查PostgreSQL服务是否正常运行以及OnlyOffice配置中的数据库连接字符串是否正确。7.2 文档打开缓慢或编辑卡顿问题现象用户反映打开文档、输入内容或保存时速度很慢。排查步骤检查服务器资源使用top、htop、free -m命令查看CPU、内存、Swap使用情况。内存不足会导致频繁交换是性能杀手。检查网络延迟如果编辑器前端浏览器与文档服务器网络延迟高操作会明显卡顿。特别是在跨公网或跨地域访问时。分析文档复杂度含有大量高清图片、复杂图表或特殊格式的文档渲染和计算开销巨大。可以尝试打开一个纯文本文档对比测试。查看文档服务器日志关注docservice.log中是否有大量的错误或超时记录。调整配置如前文所述适当增加文档处理服务的线程数或JVM内存如果服务是Java写的。配置文件路径可能在/etc/onlyoffice/documentserver/docservice.ini。7.3 字体相关遗留问题问题现象字体已安装但部分文档仍显示异常或字体下拉框不显示中文字体名。排查步骤确认字体缓存已更新再次运行cd /var/www/onlyoffice/documentserver sudo -u onlyoffice npm run rebuild-fontcache观察是否有错误输出。检查字体文件格式某些.ttc字体集合文件可能兼容性不佳。尝试使用.ttf格式的单一字体文件。检查字体名称在Windows上“宋体”的字体家族名可能是SimSun而“新宋体”是NSimSun。在OnlyOffice中字体下拉框显示的是字体文件的“家族名”(Family Name)。你可以使用fc-list命令需安装fontconfig查看系统识别的字体名或者用工具如fontforge查看字体元数据。确保文档中使用的字体名与服务器上安装的字体家族名完全一致。浏览器缓存强制刷新浏览器缓存CtrlF5或者尝试在无痕模式下访问。7.4 定期维护任务为了系统长期稳定运行建议建立以下维护习惯日志清理借助配置好的logrotate防止日志占满磁盘。系统更新定期运行sudo yum update更新系统安全补丁但谨慎更新OnlyOffice本身除非确认新版本与你的集成应用兼容。升级前务必在测试环境验证并备份全部数据。磁盘空间监控监控/var/www/onlyoffice/Data目录的大小临时文件可能会积累。备份验证定期检查备份文件是否可成功恢复确保备份策略有效。部署和优化OnlyOffice是一个系统工程从安装、字体配置到生产调优每一步都需要耐心和细致的排查。整个过程的核心逻辑是先确保基础服务通畅再解决内容渲染字体最后优化体验和稳定排版、性能、安全。当你的团队能够流畅地在线协作编辑中文文档时这些前期的投入就都是值得的。如果在操作中遇到上面没覆盖的问题多查日志多从网络连通性、服务状态、文件权限这几个基础维度去分析大部分问题都能找到突破口。