Nextcloud + Collabora CODE 离线部署安装
环境概述
两台服务器在同一 LAN（192.168.1.0/24），内网环境无公网域名，使用自签名 SSL 证书。
|---------------|--------------|---------------------|-----------------------------------------------|
| 组件 | IP 地址 | 系统 | 用途 |
| Nextcloud 服务器 | 192.168.1.80 | Ubuntu 24.04 LTS | | Nextcloud 33.0.4 + Apache + MariaDB + PHP 8.3 |
| Collabora 服务器 | 192.168.1.81 | Ubuntu 24.04 LTS | Ubuntu 24.04 LTS |
1. 前置准备
1.1 下载离线安装包
由于服务器访问外网速度慢且不稳定，所有安装包在本地 Windows上下载后上传到服务器。
**所需文件：**
|----------------------------------|--------------------------------------------------------------|-------------------------|
| 文件 | 来源 | 备注 |
| `latest.zip` | https://nextcloud.com/install/ | Nextcloud 33.0.4 Server |
| Collabora .deb 包 | https://www.collaboraoffice.com/code/linux-packages/ | 见下方列表 |
| `richdocuments-v10.1.3.tar.gz` | https://github.com/nextcloud-releases/richdocuments/releases | Nextcloud Office 连接器 |
**Collabora CODE 所需 .deb 包：**
coolwsd_25.04.10.3-1_amd64.deb
code-brand_25.04.9-3_all.deb
collaboraoffice_25.04.10-3_amd64.deb
collaboraoffice-ure_25.04.10-3_amd64.deb
collaboraofficebasis-core_25.04.10-3_amd64.deb
collaboraofficebasis-calc_25.04.10-3_amd64.deb
collaboraofficebasis-draw_25.04.10-3_amd64.deb
collaboraofficebasis-impress_25.04.10-3_amd64.deb
collaboraofficebasis-math_25.04.10-3_amd64.deb
collaboraofficebasis-writer_25.04.10-3_amd64.deb
collaboraofficebasis-graphicfilter_25.04.10-3_amd64.deb
collaboraofficebasis-images_25.04.10-3_amd64.deb
collaboraofficebasis-en-us_25.04.10-3_amd64.deb
collaboraofficebasis-ooofonts_25.04.10-3_amd64.deb
collaboraofficebasis-ooolinguistic_25.04.10-3_amd64.deb
collaboraofficebasis-extension-pdf-import_25.04.10-3_amd64.deb
2. 安装 Nextcloud 服务器
（以下操作在Nextcloud 服务器192.168.1.80执行）
2.1 基础环境
系统预装：Apache2, MariaDB 10.11.14, PHP 8.3.6
前置准备：更新系统
#sudo apt update
#sudo apt upgrade -y
安装 Apache 2
#sudo apt install -y apache2
启用 Nextcloud 所需的 Apache 模块
#sudo a2enmod rewrite headers env dir mime setenvif ssl
#sudo systemctl restart apache2
安装 MariaDB
Ubuntu 24.04 的默认仓库自带的是 MariaDB 10.11 系列，该版本已在 Nextcloud 的推荐列表中，且经过大量测试，兼容性良好。直接执行以下命令即可：
#sudo apt install -y mariadb-server mariadb-client
启动并设置开机自启：
#sudo systemctl start mariadb
#sudo systemctl enable mariadb
运行安全设置，按提示设置 root 密码、移除匿名用户、禁止远程 root 登录等：
#sudo mysql_secure_installation
Root 密码 Nextcloud@123456
PHP 扩展：
apcu, bcmath, ctype, curl, dom, exif, gd, gmp, imagick,
intl, mbstring, mysqli, openssl, pcntl, PDO, pdo_mysql,
redis, SimpleXML, sockets, xml, zip, zlib
Ubuntu 24.04 原生支持 PHP 8.3。一次性安装全部所需扩展和工具
sudo apt install -y php8.3 libapache2-mod-php8.3 \
php8.3-gd php8.3-mysql php8.3-curl php8.3-mbstring php8.3-intl \
php8.3-gmp php8.3-bcmath php8.3-xml php8.3-imagick php8.3-zip \
php8.3-bz2 php8.3-apcu php8.3-redis php8.3-common \
php8.3-opcache php8.3-readline imagemagick unzip curl
2.2 安装 Nextcloud
上传并解压
把本地windows下载好的Nextcloud安装包latest.zip通过psftp上传到服务器192.168.1.80 /tmp目录下
#cd /var/www
#sudo unzip /tmp/latest.zip
#sudo chown -R www-data:www-data /var/www/nextcloud
#sudo chmod -R 755 /var/www/nextcloud
创建数据目录： 在实际生产环境中，通常建议将数据目录（data）放在一个独立的存储空间或系统盘之外，以便于备份和扩展。此处，我们将数据目录与 Nextcloud 代码目录分离，提升数据安全性。
#sudo mkdir -p /var/www/nextcloud_data
#sudo chown -R www-data:www-data /var/www/nextcloud_data
#sudo chmod -R 750 /var/www/nextcloud_data
在后续的网页安装流程中，需要将数据目录指定为 /var/www/nextcloud_data。这样做的好处是：
安全性更高：用户上传的文件与程序代码完全分离。
备份更灵活：可以只备份 nextcloud_data 目录，无需包含程序文件。
便于迁移：未来如果需要更换服务器，只需迁移 nextcloud_data 目录和数据库即可。
2.3 配置 MariaDB 数据库
#sudo mysql -e "CREATE DATABASE IF NOT EXISTS nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"
#sudo mysql -e "CREATE USER IF NOT EXISTS nextcloud@localhost IDENTIFIED BY 'NextcloudUser@123456';"
#sudo mysql -e "GRANT ALL PRIVILEGES ON nextcloud.* TO nextcloud@localhost;"
#sudo mysql -e "FLUSH PRIVILEGES;"
2.4 配置 Apache 虚拟主机
创建 `/etc/apache2/sites-available/nextcloud.conf`：
#vi /etc/apache2/sites-available/nextcloud.conf
输入以下内容：
<VirtualHost *:80>
ServerName 192.168.1.80
Redirect permanent / https://192.168.1.80/
</VirtualHost>
<VirtualHost default:443>
ServerName 192.168.1.80
DocumentRoot /var/www/nextcloud
<Directory /var/www/nextcloud>
Require all granted
AllowOverride All
Options FollowSymlinks MultiViews
</Directory>
SSLEngine on
SSLCertificateFile /etc/apache2/ssl/nextcloud.crt
SSLCertificateKeyFile /etc/apache2/ssl/nextcloud.key
<IfModule mod_headers.c>
Header always set Strict-Transport-Security "max-age=15552000; includeSubDomains"
</IfModule>
</VirtualHost>
```
生成自签名证书：
#sudo mkdir -p /etc/apache2/ssl
#sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
-keyout /etc/apache2/ssl/nextcloud.key \
-out /etc/apache2/ssl/nextcloud.crt \
-subj "/C=CN/ST=Shanghai/L=Shanghai/O=IT/CN=192.168.1.80"
#sudo chmod 600 /etc/apache2/ssl/nextcloud.key
启用站点和模块：
#sudo a2enmod rewrite headers ssl
#sudo a2ensite nextcloud.conf
#sudo a2dissite 000-default.conf
#sudo systemctl restart apache2
2.5 Web 界面安装
访问 `https://192.168.1.80/\`，在安装页面填写：
-
管理员账号：`admin` / `Admin@Nextcloud123456!`
-
将数据目录指定为 /var/www/nextcloud_data
-
数据库：`MySQL/MariaDB`
-
数据库用户：`nextcloud`
-
数据库密码：`NextcloudUser@123456`
-
数据库名：`nextcloud`
-
数据库主机：`localhost`
2.6 配置 Redis 缓存
#sudo apt-get install -y redis-server php-redis
#sudo systemctl start redis-server
#sudo systemctl enable redis-server
编辑 `/etc/redis/redis.conf`，确认 `bind 127.0.0.1` 和 `port 6379`已启用配置。
将以下内容追加到 `/var/www/nextcloud/config/config.php` 中 `);` 之前：
'redis' => [
'host' => '127.0.0.1',
'port' => 6379,
'timeout' => 0.0,
],
'memcache.local' => '\OC\Memcache\Redis',
'memcache.locking' => '\OC\Memcache\Redis',
2.7 配置 Cron
#crontab -u www-data -e
添加以下行：
*/5 * * * * php /var/www/nextcloud/cron.php
2.8 最终 `config.php`
<?php
$CONFIG = array (
'passwordsalt' => '<自动生成>',
'secret' => '<自动生成>',
'trusted_domains' =>
array (
0 => '192.168.1.80',
1 => 'localhost',
),
'datadirectory' => '/var/www/nextcloud/data',
'dbtype' => 'mysql',
'version' => '33.0.4.1',
'overwrite.cli.url' => 'https://192.168.1.80',
'instanceid' => '<自动生成>',
'dbname' => 'nextcloud',
'dbhost' => 'localhost',
'dbtableprefix' => 'oc_',
'mysql.utf8mb4' => true,
'dbuser' => 'nextcloud',
'dbpassword' => 'NextcloudUser@1213456',
'installed' => true,
'overwriteprotocol' => 'https',
'redis' =>
array (
'host' => '127.0.0.1',
'port' => 6379,
'timeout' => 0.0,
),
'memcache.local' => '\\OC\\Memcache\\Redis',
'memcache.locking' => '\\OC\\Memcache\\Redis',
);
3. 安装 Collabora CODE 服务器
（以下操作在Collabora CODE 服务器192.168.1.81执行）
3.1 安装依赖和仓库
添加 Collabora 仓库密钥和源
#wget -qO- https://www.collaboraoffice.com/repos/CollaboraOnline/CODE-deb/ubuntu/code2025.04.gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/collabora.gpg
#echo 'deb https://www.collaboraoffice.com/repos/CollaboraOnline/CODE-2025.04/ubuntu ./' | sudo tee /etc/apt/sources.list.d/collabora.list
#sudo apt-get update
此处遇到执行报错
root@collabora:/home# wget -qO- https://www.collaboraoffice.com/repos/CollaboraOnline/CODE-2025.04/ubuntu/code2025.04.gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/collabora.gpg
gpg: no valid OpenPGP data found.
转离线安装
3.2 离线安装（
将 .deb 包上传到 /tmp/collabora/
#sudo dpkg -i /tmp/collabora/*.deb
修复可能的依赖问题
#sudo apt-get install -f -y
3.3 生成自签名 SSL 证书
#sudo mkdir -p /etc/coolwsd
#sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
-keyout /etc/coolwsd/key.pem \
-out /etc/coolwsd/cert.pem \
-subj "/C=CN/ST=Shanghai/L=Shanghai/O=IT/CN=192.168.1.81"
#sudo chown cool:cool /etc/coolwsd/key.pem /etc/coolwsd/cert.pem
#sudo chmod 600 /etc/coolwsd/key.pem /etc/coolwsd/cert.pem
3.4 配置 coolwsd.xml
配置文件位于 `/etc/coolwsd/coolwsd.xml`。
**关键配置项：**
|--------------------------|------------------------------------|-----------------------|
| 配置项 | 值 | 说明 |
| `server_name` | `192.168.1.81:9980` | 服务器名称和端口 |
| `ssl.enable` | `true` | 启用 SSL |
| `ssl.cert_file_path` | `/etc/coolwsd/cert.pem` | SSL 证书 |
| `ssl.key_file_path` | `/etc/coolwsd/key.pem` | SSL 私钥 |
| `ssl.ca_file_path` | `/etc/coolwsd/ca-chain.cert.pem` | CA 链（自签名则复制 cert.pem） |
| `ssl.ssl_verification` | `false` | 禁用远程 SSL 验证（自签名环境） |
| `net.listen` | `any` | 监听所有接口 |
| `net.proto` | `all` | IPv4 + IPv6 |
> **关键注意事项**：`ca_file_path` 指向的 `/etc/coolwsd/ca-chain.cert.pem` **必须存在**，否则 coolwsd 启动时崩溃并报错 `Failed to initialize COOLWSD: File not found`。自签名环境下复制 cert.pem：
> #sudo cp /etc/coolwsd/cert.pem /etc/coolwsd/ca-chain.cert.pem
> #sudo chown cool:cool /etc/coolwsd/ca-chain.cert.pem
> #sudo chmod 600 /etc/coolwsd/ca-chain.cert.pem
使用 `coolconfig` 工具设置：
设置服务器名称
#sudo coolconfig set server_name 192.168.1.81:9980
设置管理员密码
#sudo coolconfig set-admin-password
或使用预设密码：
sudo coolconfig set-admin-password --password CollaboraAdmin@123456
3.5 启动服务
#sudo systemctl enable coolwsd
#sudo systemctl start coolwsd
#sudo systemctl status coolwsd
确认监听端口：
#sudo ss -tlnp | grep cool
应输出：LISTEN 0 64 *:9980 *:* users:(("coolwsd",...))
3.6 验证 Discovery 端点
#curl -k https://192.168.1.81:9980/hosting/discovery
应返回包含 <wopi-discovery> 的 XML
4. 集成 Nextcloud + Collabora
4.1 安装 richdocuments 应用
**不要使用 `occ app:install richdocuments`（网络慢时会失败）。**
1. 下载安装包richdocuments-v10.1.3.tar.gz
下载地址：https://github.com/nextcloud-releases/richdocuments/releases
2. 上传安装包
文件名：richdocuments-v10.1.3.tar.gz
3. 解压并安装
#cd /var/www/nextcloud/apps
#sudo tar xzf /tmp/richdocuments-v10.1.3.tar.gz
4. 设置权限
#sudo chown -R www-data:www-data richdocuments
5. 安装 composer 依赖（release 版本已包含 vendor，此步可选）
#cd /var/www/nextcloud/apps/richdocuments
#sudo -u www-data /usr/bin/composer install --no-dev
6. 启用应用
#sudo -u www-data php /var/www/nextcloud/occ app:enable richdocuments
4.2 配置 WOPI 连接
设置 Collabora 服务器地址
#sudo -u www-data php /var/www/nextcloud/occ config:app:set richdocuments wopi_url --value 'https://192.168.1.81:9980'
#sudo -u www-data php /var/www/nextcloud/occ config:app:set richdocuments public_wopi_url --value 'https://192.168.1.81:9980'
设置回调 URL（Collabora 回调 Nextcloud 的地址）
#sudo -u www-data php /var/www/nextcloud/occ config:app:set richdocuments wopi_callback_url --value 'https://192.168.1.80'
禁用 SSL 验证（自签名证书）
#sudo -u www-data php /var/www/nextcloud/occ config:app:set richdocuments disable_certificate_verification --value 'yes'
激活配置
#sudo -u www-data php /var/www/nextcloud/occ richdocuments:activate-config
4.3 验证集成
#sudo -u www-data php /var/www/nextcloud/occ richdocuments:setup
预期输出：
✓ Reset callback url autodetect
✓ Fetched /hosting/discovery endpoint
✓ Valid mimetype response
✓ Valid capabilities entry
✓ Fetched /hosting/capabilities endpoint
✓ Detected WOPI server: Collabora Online Development Edition 25.04.XX.X
5. 排错指南
5.1 coolwsd 启动后没有监听端口
**现象**：`systemctl status coolwsd` 显示 `active (running)`，但 `ss -tlnp | grep cool` 无输出。
**原因**：`/etc/coolwsd/ca-chain.cert.pem` 文件不存在。
**日志**：`journalctl -u coolwsd` 显示 `Failed to initialize COOLWSD: File not found: /etc/coolwsd/ca-chain.cert.pem`
**解决方法**：
#sudo cp /etc/coolwsd/cert.pem /etc/coolwsd/ca-chain.cert.pem
#sudo chown cool:cool /etc/coolwsd/ca-chain.cert.pem
#sudo chmod 600 /etc/coolwsd/ca-chain.cert.pem
#sudo systemctl restart coolwsd
5.2 点击文档后直接下载而不是在线打开
**现象**：在 Nextcloud 中点击 .docx/.odt 文件，浏览器直接下载文件。
**可能原因和解决**：
-
**浏览器缓存** --- 清除浏览器缓存或按 Ctrl+F5 强制刷新。
-
**JS 资源未编译** --- 确认使用了 release 版本的 tarball（14 MB，包含预编译 JS），而非 GitHub 自动生成的源码包（3.8 MB）。
-
**JS 资源 404** --- 检查 Nextcloud 日志是否有 `Could not find resource richdocuments/js/richdocuments-fileActions.js`。
-
**查看日志**：
```bash
sudo tail -f /var/www/nextcloud/data/nextcloud.log | grep -i 'richdoc\|wopi\|jsresource'
5.3 登录后第一次在线打开doc、xls文档时会报"文档加载失败"
**可能原因和解决**：
1： 先在浏览器中访问 https://192.168.1.81:9980/，点击"高级"→"继续前往"接受自签名证书（只需做一次）。
2： 回到 Nextcloud https://192.168.1.80/，刷新页面（Ctrl+F5），再尝试打开 xlsx/doc 文件。
说明：
根本原因是 Nextcloud 默认禁止向内网 IP发起请求（安全策略）。已设置 allow_local_remote_servers=true 放行 Collabora 的 WOPI 回调。
Collabora 使用自签名证书，浏览器首次访问时需要手动确认信任。