1. 为什么选择在 Ubuntu 上部署 ONLYOFFICE 文档 8.0如果你正在为团队寻找一个能自己掌控的在线文档协作平台或者想为你开发的应用集成一个功能强大的文档编辑器那么把 ONLYOFFICE 文档 8.0 装在自己的 Ubuntu 服务器上绝对是一个值得认真考虑的选择。我自己在几年前就开始接触这个方案从最初的版本一路用到现在的 8.0可以说它已经从一个“不错的替代品”成长为一个非常成熟、可靠的企业级工具。简单来说ONLYOFFICE 文档就是一个“网页版的 Office”。但它又不止于此。你可以在浏览器里直接创建、编辑 Word、Excel、PPT 文档而且支持多人同时编辑谁修改了哪一行、哪个单元格都能实时看到。最新的 8.0 版本还加强了对 PDF 表单的处理甚至集成了 AI 功能来帮你写东西、做总结。最吸引技术人的一点是它的社区版是免费的你可以把它部署在自己的服务器或云主机上所有数据都在自己手里安全和隐私完全由自己把控。那为什么偏偏是 Ubuntu 呢原因很简单稳。Ubuntu Server 长期支持版LTS在服务器领域的普及度极高文档丰富社区活跃遇到问题很容易找到解决方案。ONLYOFFICE 官方对 Debian/Ubuntu 系列的支持也是最到位的安装包和依赖管理都非常顺畅。所以无论你是个人开发者想搭建一个私人文档库还是公司的运维要为团队部署协作平台Ubuntu ONLYOFFICE 这个组合都能让你省心不少。接下来我就把自己在 Ubuntu 上多次安装和配置 ONLYOFFICE 文档 8.0 的经验包括一些官方文档里没细说、但实际踩过坑的地方整理成这份详细的攻略。我会尽量用大白话把每一步讲清楚确保即使你是第一次接触 Linux 服务器的新手也能跟着一步步成功搭起来。2. 动手前的准备理清需求与备好环境在真正敲命令之前花几分钟时间做好规划能避免后面很多麻烦。这一步主要搞清楚两件事你的服务器够不够格跑起这个服务以及你需要提前准备好哪些“零件”。2.1 你的服务器达标了吗ONLYOFFICE 文档服务器本身不算特别重但要想它运行流畅尤其是多人同时编辑的时候硬件不能太寒酸。根据官方建议和我自己的实测经验我梳理了下面这个更贴近实际需求的配置表组件官方最低要求个人推荐小型团队/项目说明与踩坑经验CPU双核2 GHz双核或以上核心数比主频更重要。文档转换、复杂计算如Excel公式吃CPU。虚拟主机务必核对真实分配的核心数。内存2 GB4 GB 或以上这是最容易成为瓶颈的地方。2GB勉强能跑但一旦同时处理几个文档或用户稍多就会卡顿甚至崩溃。4GB是流畅的起点。硬盘40 GB40 GB SSD空间需求不大但强烈建议使用SSD。文档的加载、保存、历史版本生成都是IO密集型操作机械硬盘会明显拖慢速度。交换空间4 GB与内存等大或略大如果物理内存只有4GB务必确保有4GB的swap。这是Linux系统的“安全气囊”能防止内存耗尽时服务直接挂掉。操作系统64位 Ubuntu/DebianUbuntu 20.04 LTS 或 22.04 LTS内核版本需高于3.13。选择LTS版本能获得长期安全更新最稳定省心。我实测在Ubuntu 22.04上最顺畅。除了硬件软件依赖也要提前心里有数。ONLYOFFICE 文档 8.0 依赖几个核心的外部服务PostgreSQL 负责存储文档的元数据、用户信息等。版本需要 12.9 以上。NGINX 作为反向代理服务器处理所有的网络请求。版本需要 1.3.13 以上。RabbitMQ 消息队列服务用于处理文档协作时的实时通信。社区版安装时会一并解决。Redis 用于缓存提升性能。注意只有企业版或开发版才需要社区版安装不需要。好消息是在 Ubuntu 上大部分依赖都可以通过apt包管理器自动安装和配置我们只需要在必要时进行一些微调。2.2 网络与安全考量安装前还需要想好网络访问方式。默认情况下ONLYOFFICE 文档服务会监听服务器的 80 端口HTTP。这意味着如果你在本地虚拟机安装直接用浏览器访问http://localhost即可。如果你在云服务器安装需要确保服务器的安全组或防火墙放行了 80 端口的入站流量。否则你将无法从外部访问。端口冲突怎么办如果你的服务器 80 端口已经被其他Web服务比如另一个网站占用就需要在安装前为 ONLYOFFICE 指定一个新的端口号比如 8080。这个我们后面会详细讲怎么改。最后建议在开始前先更新一下你的 Ubuntu 系统确保所有基础软件包都是最新的这能避免很多因版本过旧导致的依赖问题。打开终端执行sudo apt update sudo apt upgrade -y执行完成后如果提示需要重启就重启一下服务器。好了准备工作就绪我们可以开始安装核心依赖了。3. 一步步安装从依赖到主程序安装过程就像搭积木先把地基依赖打牢再把主体结构ONLYOFFICE放上去。我会把每一步的命令和可能遇到的问题都列出来。3.1 安装并配置 PostgreSQL 数据库ONLYOFFICE 使用 PostgreSQL 作为数据库。虽然安装主程序时会尝试自动安装配置但我强烈建议手动先装好这样更可控出错了也容易排查。首先安装 PostgreSQL。Ubuntu 的默认软件源里通常就有比较新的版本。sudo apt install postgresql postgresql-contrib -y安装完成后PostgreSQL 服务会自动启动。我们需要为 ONLYOFFICE 创建一个专用的数据库和用户。切换到postgres系统用户PostgreSQL 的默认管理用户sudo -i -u postgres这时命令行提示符会变成postgres服务器名:~$。启动 PostgreSQL 命令行工具psqlpsql在psql提示符 (postgres#) 下依次执行以下 SQL 命令。请务必记住你设置的密码后面安装 ONLYOFFICE 时会用到。CREATE DATABASE onlyoffice; CREATE USER onlyoffice WITH PASSWORD your_strong_password_here; GRANT ALL PRIVILEGES ON DATABASE onlyoffice TO onlyoffice;重要提示把your_strong_password_here替换成一个你自己设定的、足够复杂的密码。不要使用简单的onlyoffice或123456。执行\q退出psql再执行exit退出postgres用户身份回到你自己的用户。这样就完成了数据库的准备工作。你可以测试一下连接非必须psql -h localhost -U onlyoffice -d onlyoffice -W输入你刚才设置的密码如果能成功进入psql提示符说明配置正确。3.2 安装其他系统依赖接下来安装一些必要的字体包确保文档能正确显示各种字体尤其是中文和特殊符号。sudo apt install fonts-dejavu fonts-liberation ttf-mscorefonts-installer fonts-crosextra-calibri fonts-takao-gothic fonts-opensymbol -y在安装ttf-mscorefonts-installer时会弹出一个图形化的许可协议窗口你需要用Tab键切换到Ok然后按回车确认。对于 Ubuntu 18.04 及以上的系统还需要安装nginx-extras它包含了一些 ONLYOFFICE 需要的额外 NGINX 模块。sudo apt install nginx-extras -y对于更新的 Ubuntu 版本如 22.04直接安装nginx即可nginx-extras可能已合并或不再需要但安装一下也无妨。3.3 关键步骤添加 ONLYOFFICE 软件源并安装这是核心步骤。我们需要将 ONLYOFFICE 官方的软件仓库添加到系统的源列表中。导入 GPG 密钥用于验证软件包的完整性。mkdir -p -m 700 ~/.gnupg curl -fsSL https://download.onlyoffice.com/GPG-KEY-ONLYOFFICE | gpg --no-default-keyring --keyring gnupg-ring:/tmp/onlyoffice.gpg --import sudo chmod 644 /tmp/onlyoffice.gpg sudo chown root:root /tmp/onlyoffice.gpg sudo mv /tmp/onlyoffice.gpg /usr/share/keyrings/onlyoffice.gpg这一串命令的作用是下载密钥并将其放到系统可信任的位置。添加软件源。ONLYOFFICE 的包是基于 Debian Squeeze 构建的但对所有 Debian/Ubuntu 发行版都兼容。echo deb [signed-by/usr/share/keyrings/onlyoffice.gpg] https://download.onlyoffice.com/repo/debian squeeze main | sudo tee /etc/apt/sources.list.d/onlyoffice.list更新软件包列表让系统识别新加的源。sudo apt update正式安装 ONLYOFFICE 文档社区版。sudo apt install onlyoffice-documentserver在安装过程中安装程序会尝试自动配置 PostgreSQL。它会弹出一个蓝色的对话框询问你之前为onlyoffice数据库用户设置的密码。把你手动创建数据库时设置的那个密码准确输入进去然后确认。安装过程会自动处理 NGINX 和 RabbitMQ 的配置。如果一切顺利安装完成后ONLYOFFICE 文档服务会自动启动。你可以用下面的命令检查服务状态sudo systemctl status onlyoffice-documentserver如果看到active (running)的字样就说明服务已经跑起来了。4. 安装后的配置与调优安装成功只是第一步要让服务更贴合你的使用场景还需要进行一些配置。这里我讲几个最常遇到的配置项。4.1 如何修改默认的访问端口如果你的服务器 80 端口已经被占用比如已经运行了一个网站就需要给 ONLYOFFICE 换一个端口。假设我们想换成8080。必须在安装 ONLYOFFICE 主程序之前设置如果你已经安装完了需要先修改配置然后重新配置软件包。echo “onlyoffice-documentserver onlyoffice/ds-port select 8080” | sudo debconf-set-selections执行完这条命令后如果你还没安装直接进行安装即可。如果你已经安装则需要执行sudo dpkg-reconfigure onlyoffice-documentserver在重新配置的过程中系统就会读取你刚刚设置的端口号 8080。配置完成后记得重启服务sudo systemctl restart onlyoffice-documentserver重要提醒修改端口后一定要确保服务器的防火墙或安全组放行了新端口如 8080的入站流量。访问地址也变成了http://你的服务器IP:8080。4.2 配置 HTTPS 安全访问强烈推荐在生产环境绝对不应该用 HTTP。启用 HTTPS 能加密数据传输防止内容被窃听。ONLYOFFICE 官方推荐使用 NGINX 来配置 SSL。假设你已经有一个域名例如doc.yourcompany.com和对应的 SSL 证书包含.crt和.key文件。停止 ONLYOFFICE 自带的 NGINX 服务因为我们用自己配置的sudo systemctl stop nginx编辑 ONLYOFFICE 的 NGINX 配置文件。默认路径是/etc/onlyoffice/documentserver/nginx/ds.conf。但更规范的做法是在/etc/nginx/sites-available/下创建自己的配置。sudo nano /etc/nginx/sites-available/onlyoffice-ssl将以下配置粘贴进去并根据你的情况修改server_name、ssl_certificate和ssl_certificate_key的路径。upstream documentserver { server 127.0.0.1:8080; # 这里对应 ONLYOFFICE 文档服务实际监听的端口如果你改了端口这里也要改。 } map $http_host $this_host { “” $host; default $http_host; } server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name doc.yourcompany.com; # 改成你的域名 ssl_certificate /path/to/your/certificate.crt; ssl_certificate_key /path/to/your/private.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location / { proxy_pass http://documentserver; proxy_set_header Host $http_host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; } }保存文件后创建一个符号链接到sites-enabled目录并测试配置语法。sudo ln -s /etc/nginx/sites-available/onlyoffice-ssl /etc/nginx/sites-enabled/ sudo nginx -t如果显示syntax is ok就可以重启 NGINX 了。sudo systemctl start nginx sudo systemctl enable nginx现在你应该可以通过https://doc.yourcompany.com安全地访问 ONLYOFFICE 文档了。4.3 启用 JWT 保护你的 APIJWT 是一种令牌用于保护 ONLYOFFICE 文档服务器的 API 接口防止未授权的调用。这对于集成到第三方系统时非常重要。同样在安装前设置最方便。假设我们设置密钥为your_jwt_secret_key_here。echo “onlyoffice-documentserver onlyoffice/jwt-enabled boolean true” | sudo debconf-set-selections echo “onlyoffice-documentserver onlyoffice/jwt-secret password your_jwt_secret_key_here” | sudo debconf-set-selections记住这个密钥以后在你自己的应用如 Nextcloud、WordPress 等中集成 ONLYOFFICE 时需要填写相同的密钥才能正常通信。如果已经安装则需要修改配置文件/etc/onlyoffice/documentserver/local.json。找到services.CoAuthoring.secret部分将其值设置为你的密钥字符串然后重启服务。sudo systemctl restart onlyoffice-documentserver5. 验证安装与基本使用完成所有安装和配置后是时候验收成果了。打开浏览器访问你的 ONLYOFFICE 地址如http://你的服务器IP或https://你的域名。如果一切正常你会看到 ONLYOFFICE 文档服务器的欢迎页面。页面上会显示版本信息应该是 8.0.x并提供一些示例文档和集成指南的链接。你可以点击“示例”链接创建一个测试文档体验一下在线编辑、保存的功能。试着输入一些文字感受一下它的响应速度。你还可以在同一台电脑上打开另一个浏览器或无痕窗口访问同一个文档链接模拟两个用户同时编辑看看协作者的光标和修改是否实时出现。对于管理员来说日常维护可能涉及添加自定义字体。比如你需要让文档支持“思源黑体”或“微软雅黑”。方法很简单将字体文件.ttf 或 .otf复制到服务器目录/usr/share/fonts/下可以新建子目录然后执行 ONLYOFFICE 提供的字体重建脚本sudo documentserver-generate-allfonts.sh执行完成后重启 ONLYOFFICE 服务新的字体就会在编辑器字体列表里出现了。6. 常见问题与故障排查安装过程很少一帆风顺这里我总结几个我遇到过并且社区里问得最多的问题。问题一安装时卡在“Configuring onlyoffice-documentserver”或提示 PostgreSQL 连接失败。原因最常见的原因是前面手动创建 PostgreSQL 数据库和用户时密码没记住或者输入错了。也可能是 PostgreSQL 服务没启动。解决检查 PostgreSQL 服务状态sudo systemctl status postgresql。如果服务没启动启动它sudo systemctl start postgresql。如果密码错误或想重置可以重新配置软件包sudo dpkg-reconfigure onlyoffice-documentserver。在这个过程中会再次询问数据库密码。也可以直接修改配置文件/etc/onlyoffice/documentserver/local.json中的db部分修正主机、用户名、密码等信息然后重启服务。问题二访问欢迎页面时显示“502 Bad Gateway”或“Internal Server Error”。原因通常是后端文档转换服务没有正常启动或者 NGINX 代理配置有问题。解决逐一检查所有相关服务状态sudo systemctl status onlyoffice-documentserver sudo systemctl status nginx sudo systemctl status postgresql sudo systemctl status rabbitmq-server查看 ONLYOFFICE 的日志通常能找到具体错误sudo journalctl -u onlyoffice-documentserver -f检查 NGINX 错误日志sudo tail -f /var/log/nginx/error.log。问题三编辑文档时中文字体显示为方框或乱码。原因系统缺少对应的中文字体包。解决安装中文字体。例如安装“文泉驿”字体和“思源”字体族sudo apt install fonts-wqy-microhei fonts-wqy-zenhei fonts-noto-cjk -y安装后同样需要执行sudo documentserver-generate-allfonts.sh并重启服务。问题四如何升级到新版本ONLYOFFICE 文档社区版可以通过系统的包管理器直接升级。sudo apt update sudo apt upgrade onlyoffice-documentserver升级后通常需要重启服务。升级前强烈建议备份数据库和重要的配置文件虽然出问题的概率不大但以防万一。把 ONLYOFFICE 文档 8.0 成功部署到 Ubuntu 上就像是给你的团队或项目装上了一个动力强劲的协作引擎。整个过程看似步骤不少但每一步都有清晰的逻辑。我最开始部署时也踩过坑比如忘了开防火墙端口或者 JWT 密钥没配置对导致集成失败。但一旦跑通你会发现它的维护成本其实很低稳定性也很好。现在你可以放心地把它集成到你的 Nextcloud、Confluence或者你自己的业务系统里享受安全、可控的在线文档协作体验了。如果在配置过程中遇到其他古怪的问题多看看官方文档和社区论坛大部分都能找到答案。