5143 字
26 分钟
Nextcloud + OnlyOffice:私有云盘与在线文档协作
2026-11-15

先说定位:这次要的不是「能存文件」,是「能干活」#

自建文件服务有很多种活法。本系列前面写过 Cloudreve,它的定位是轻量网盘:部署简单、分享链接好用、给博客和团队当文件中转站非常称职。但如果你想要的不只是存取文件,还包括这些事:

  • 桌面文件夹和服务器实时双向同步,换台电脑打开就是同一份工作区;
  • Word、Excel、PPT 直接在浏览器里打开编辑,还能多人同时改一份文档;
  • 日历、通讯录、任务、笔记都收进自己的服务器,不再散落各家云服务;

那要的就是 Nextcloud 这一档了。它是一个完整的私有云协作平台,网盘只是其中一块。而在线编辑 Office 文档这块拼图,靠它自带的简易编辑器远远不够,必须外挂一套真正的文档引擎——这就是 OnlyOffice Document Server 的位置。

本篇主线:四件套架构总览 → Docker Compose 一次编排到位 → 初始化与可信域名 → 性能调优把卡顿消掉 → OnlyOffice 集成与内网回连大坑 → 客户端同步 → 外部存储概念 → 备份要点。全篇用 Docker Compose 部署,数据库选 PostgreSQL(选型理由和参数细节可参考 PostgreSQL 安装与配置)。

架构总览:四个容器,各管一段#

先把四件套的分工说清楚,后面所有配置都是在给这张图填细节:

组件角色说明
Nextcloud(app)平台本体Web 界面、文件管理、用户与权限、应用生态,对外提供服务
PostgreSQL数据库存用户、文件索引、分享记录等全部元数据,不存文件本体
Redis缓存与文件锁内存缓存 + 事务文件锁,缺了它 Nextcloud 又慢又容易出冲突
OnlyOffice Document Server文档引擎负责 docx/xlsx/pptx 的渲染与协同编辑,通过连接器与 Nextcloud 对接
cron(app 镜像复用)后台任务定时跑预览生成、垃圾回收、索引维护等计划任务

文件本体躺在宿主机目录(或数据卷)里,数据库只记元数据,这是理解后面备份章节的关键:备份 = 数据库 + data 目录 + config 配置,三样缺一不可。

四件套的核心关系一句话:Nextcloud 管人和文件,PostgreSQL 管账本,Redis 管速度,OnlyOffice 管文档编辑。

资源预估先交代:Nextcloud 本体加 PostgreSQL、Redis 大约 1.5 GB 内存能跑,OnlyOffice Document Server 自己就要吃 2 GB 左右(它内置了转换服务和消息队列,是个重量级选手)。整机建议 4 GB 内存起步,磁盘按你打算存多少文件另算。内存不够时 OnlyOffice 打开文档会明显迟钝,这不是调优能救的。

完整编排:docker-compose.yml#

部署目录约定为 /opt/nextcloud,先把骨架搭起来:

Terminal window
mkdir -p /opt/nextcloud/{data,db}
cd /opt/nextcloud

.env 文件放所有密码和域名,Compose 自动读取:

Terminal window
cat > .env << 'EOF'
DOMAIN=cloud.example.com
POSTGRES_PASSWORD=换成你的强密码
REDIS_PASSWORD=换成你的强密码
OO_JWT_SECRET=换成一串足够长的随机字符串
EOF

docker-compose.yml 全文如下,这是本篇的核心资产,后面几节都是在解释和调优它:

services:
db:
image: postgres:16-alpine
container_name: nc-db
restart: unless-stopped
environment:
POSTGRES_DB: nextcloud
POSTGRES_USER: nextcloud
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- ./db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U nextcloud"]
interval: 10s
timeout: 5s
retries: 5
redis:
image: redis:7-alpine
container_name: nc-redis
restart: unless-stopped
command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy allkeys-lru
volumes:
- redis_data:/data
app:
image: nextcloud:30-apache
container_name: nc-app
restart: unless-stopped
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
environment:
POSTGRES_HOST: db
POSTGRES_DB: nextcloud
POSTGRES_USER: nextcloud
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
REDIS_HOST: redis
REDIS_HOST_PASSWORD: ${REDIS_PASSWORD}
NEXTCLOUD_TRUSTED_DOMAINS: ${DOMAIN}
OVERWRITEPROTOCOL: https
TZ: Asia/Shanghai
volumes:
- ./data:/var/www/html/data
- app_html:/var/www/html
ports:
- "127.0.0.1:8080:80"
cron:
image: nextcloud:30-apache
container_name: nc-cron
restart: unless-stopped
depends_on:
- app
entrypoint: /cron.sh
volumes:
- ./data:/var/www/html/data
- app_html:/var/www/html
onlyoffice:
image: onlyoffice/documentserver:latest
container_name: nc-onlyoffice
restart: unless-stopped
environment:
JWT_SECRET: ${OO_JWT_SECRET}
JWT_ENABLED: "true"
volumes:
- oo_data:/var/www/onlyoffice/Data
ports:
- "127.0.0.1:8081:80"
volumes:
app_html:
redis_data:
oo_data:

几个关键点逐个说:

  • 端口只绑 127.0.0.1。两个 Web 服务都只监听本机回环,对外统一走反向代理(自建服务系列的标准入口做法见 Nginx Proxy Manager 统一入口),由它负责域名和 HTTPS 证书。
  • 数据库和 Redis 完全不映射端口。绝对不要图省事把 PostgreSQL 的 5432 端口映射到公网,数据库裸奔在公网上被扫描爆破是迟早的事,它们只需要被 app 容器按服务名访问。
  • app 和 cron 共用同一套卷。cron 容器跑的是官方镜像自带的 /cron.sh,每 5 分钟触发一次后台任务,和 app 共享代码卷与 data 目录,这是官方推荐的独立 cron 方案,比在 Web 进程里顺带跑 AJAX 后台任务可靠得多。
  • data 目录用宿主机目录挂载而不是命名卷,纯粹为了备份和迁移时看得见摸得着,后面备份一节会用到。

启动:

Terminal window
docker compose pull
docker compose up -d
docker compose ps

等 nc-db 变为 healthy、其余容器都 running 后,在反向代理里加两条:cloud.example.com 指向 127.0.0.1:8080,再给 OnlyOffice 单独一个子域名 office.example.com 指向 127.0.0.1:8081,两条都申请好 HTTPS 证书。为什么 OnlyOffice 必须独立域名,后面集成一节细说。

初始化与可信域名#

浏览器打开 https://cloud.example.com,首次访问是创建管理员账号的页面。注意:因为 Compose 里已经通过环境变量把数据库连接参数喂给了安装向导,这里不要在页面上再选 SQLite,老老实实确认 PostgreSQL 参数无误,设好管理员用户名和密码,点安装。

装完先做三件事,都在服务器上用 occ 命令完成(occ 是 Nextcloud 的官方命令行管理工具,容器里执行要带上 Web 用户身份):

Terminal window
# 1. 确认可信域名(环境变量已注入,再核对一遍)
docker exec -u www-data nc-app php occ config:system:get trusted_domains
# 2. 补一条本机回环,方便服务器内部自检
docker exec -u www-data nc-app php occ config:system:set trusted_domains 2 --value=127.0.0.1
# 3. 设置默认语言与时区等区域项
docker exec -u www-data nc-app php occ config:system:set default_language --value=zh_CN
docker exec -u www-data nc-app php occ config:system:set default_locale --value=zh_Hans_CN

可信域名(trusted_domains)是 Nextcloud 的一道门禁:不在名单里的 Host 头访问会被直接拒绝并提示「通过不受信任的域名访问」。反代场景下如果忘了把正式域名写进去,就会出现网站明明能打开却被拦在门外的情况,排查方向就是这条配置。

WARNING

关于覆盖协议与代理的提醒:Nextcloud 在反向代理后面时,必须知道自己对外的真实协议是 HTTPS,否则生成的分享链接、客户端发现地址会全部带着 http 和内网端口。Compose 里已经设了 OVERWRITEPROTOCOL: https;如果你改用手工配置,等价命令是 occ config:system:set overwriteprotocol --value=https,改完记得验证分享链接是否正确。

性能调优:把「能用」调成「不卡」#

Nextcloud 原生状态有几个广为人知的卡点:打开文件夹要等、缩略图现生成现等、后台任务靠访问触发。这节逐个消掉。

Redis 缓存与文件锁#

Compose 的环境变量已经让安装向导自动写入了 Redis 配置,验证一下:

Terminal window
docker exec -u www-data nc-app php occ config:system:get memcache.local
docker exec -u www-data nc-app php occ config:system:get memcache.locking

两个值都应该是 \OC\Memcache\Redis。前者是本地内存缓存,后者是事务文件锁——多人或多客户端同时操作同一批文件时,没有文件锁很容易出现冲突副本和莫名报错。如果输出为空,说明 Redis 没接上,手工补齐:

Terminal window
docker exec -u www-data nc-app php occ config:system:set memcache.local --value='\OC\Memcache\Redis'
docker exec -u www-data nc-app php occ config:system:set memcache.distributed --value='\OC\Memcache\Redis'
docker exec -u www-data nc-app php occ config:system:set memcache.locking --value='\OC\Memcache\Redis'
docker exec -u www-data nc-app php occ config:system:set redis host --value=redis
docker exec -u www-data nc-app php occ config:system:set redis port --value=6379
docker exec -u www-data nc-app php occ config:system:set redis password --value='你的Redis密码'

PHP 与 OPcache#

Apache 版镜像的 PHP 配置基本够用,重点确认 OPcache 已启用并给足内存。在 app 容器里挂一个自定义 ini 即可,新建 opcache.ini 通过卷挂进 /usr/local/etc/php/conf.d/:

opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.revalidate_freq=60
apc.enable_cli=1
memory_limit=1024M
upload_max_filesize=16G
post_max_size=16G
max_execution_time=3600

最后三行是给大文件上传留的余量,下一节排障里的 413 问题有一半要在这里解决(另一半在反代那边)。

后台任务切到 Cron 模式#

进入管理设置 → 基本设置 → 后台任务,选 Cron。我们已经有独立 cron 容器每 5 分钟调用一次,这里选错成 AJAX 的话,等于白养了一个容器还继续卡。选好后页面会显示上次执行时间,应该是 5 分钟以内的新鲜时间。

预览图预生成#

文件夹里照片和视频的缩略图默认是首次打开时现算的,慢且占 CPU。装 Preview Generator 应用后让 cron 在后台提前算好:

Terminal window
# 在应用商店装 Preview Generator,或命令行直接装
docker exec -u www-data nc-app php occ app:install previewgenerator
# 先全量生成一次(文件多时耗时较久,挑空闲时段跑)
docker exec -u www-data nc-app php occ preview:generate-all
# 限制预览图尺寸,别让它生成原图级预览吃爆磁盘
docker exec -u www-data nc-app php occ config:app:set previewgenerator squareSizes --value="32 256"
docker exec -u www-data nc-app php occ config:app:set previewgenerator widthSizes --value="256 384"
docker exec -u www-data nc-app php occ config:app:set previewgenerator heightSizes --value="256"
docker exec -u www-data nc-app php occ config:system:set preview_max_x --value=2048
docker exec -u www-data nc-app php occ config:system:set preview_max_y --value=2048

做完这四步,再把管理设置页的「安全及设置警告」逐条清掉(排障一节有清单),Nextcloud 的体感会从「自建的凑合用」变成「这不就是个正经云盘」。

OnlyOffice 集成:成败全在「回连地址」#

装连接器、填三要素#

  1. 以管理员登录 Nextcloud,右上角头像 → 应用,搜索 ONLYOFFICE,下载并启用官方连接器应用。
  2. 进入管理设置 → ONLYOFFICE,填三样东西:
    • Document Server 地址:https://office.example.com/(用户浏览器要访问的地址,必须是公网可达的 HTTPS 地址);
    • 密钥(JWT Secret):就是 .env 里给 OnlyOffice 容器设置的 OO_JWT_SECRET,两边必须一字不差;
    • 勾选「在新标签页打开编辑器」与否按个人喜好,下面的高级设置先展开,有大坑等着。
  3. 点保存。顺利的话会提示连接成功,打开任意 docx 文件就直接进编辑器了。

为什么 Document Server 要独立子域名而不是挂在子路径下:它的编辑器页面、转换服务、静态资源都按根路径设计,塞进子路径会引出一串资源加载和 WebSocket 的问题,独立子域名是官方和社区的共识做法,别在这上面省一个域名。

大坑:内网回连地址#

这是整个集成里最容易翻车、也最少有人一次讲透的一环。先理解编辑一份文档时发生了什么:

  1. 你的浏览器从 office.example.com 加载编辑器界面;
  2. OnlyOffice 服务器需要回头到 Nextcloud 把文档文件下载下来;
  3. 你编辑完,OnlyOffice 服务器再把新文件回传给 Nextcloud 保存。

第 2、3 步是服务器对服务器的访问。问题来了:OnlyOffice 容器要访问的 Nextcloud 地址,就是连接器里填的那个公网地址吗?不是——连接器会把 Nextcloud 的地址按请求来源拼出来发给 OnlyOffice。在纯公网部署里这能工作,但在我们这种「容器内网 + 反代对外」的结构里,OnlyOffice 容器拿着 https://cloud.example.com 去回连,要先绕出公网、过 DNS、再被反代送回来一圈,经常卡在 DNS 解析不到、回环被拒或者证书校验失败上,表现就是编辑器一直转圈,或者文档能打开但保存时报错。

解法是连接器高级设置里的两个「内部地址」,让两台服务器在内网直连,把浏览器那条公网链路和服务器间链路分开:

设置项填什么谁用
Document Server 地址https://office.example.com/浏览器加载编辑器
Document Server 内部请求地址http://nc-onlyoffice/Nextcloud 向 OnlyOffice 发起请求时走内网
Nextcloud 内部请求地址http://nc-app/OnlyOffice 回连 Nextcloud 下载/回传文件时走内网

填容器名能通的前提是两个容器在同一个 Docker 网络里——用同一份 Compose 编排天然满足(默认网络互通,按服务名和容器名都能解析)。注意内部地址用 http 即可,内网链路不经过公网,没必要再套一层证书。

OnlyOffice 集成的核心结论:浏览器走公网域名,服务器互访走容器内网地址,两条路分开,九成的转圈和保存失败都会消失。

验证内网连通性不用靠猜,进容器实测:

Terminal window
# OnlyOffice 容器能否摸到 Nextcloud
docker exec nc-onlyoffice curl -sI http://nc-app/status.php | head -3
# Nextcloud 容器能否摸到 OnlyOffice 的健康检查
docker exec nc-app curl -s http://nc-onlyoffice/healthcheck

第二条返回 true 才算通。另外要注意,JWT 密钥两边不一致时编辑器会直接报权限错误且日志里不会明说,改过 .env 后记得 OnlyOffice 容器要重建、连接器设置页要重新保存一次密钥。

客户端同步:让文件自己流动#

服务端跑通后,把日常设备接进来才算落地:

  • 桌面端:官网下载 Nextcloud Desktop(Windows/macOS/Linux 都有),登录时填服务器地址 https://cloud.example.com,走浏览器授权流程。可以选「虚拟文件」模式(文件按需下载,本地只占索引)或整文件夹实同步,工作区建议实同步,归档区用虚拟文件省磁盘。
  • 手机端:Nextcloud 官方 App(Android/iOS),登录后打开「自动上传」,把相册目录映射到服务器的 Photos 文件夹,拍照即备份。注意在系统里给它放行后台运行和流量权限,否则自动上传会断断续续。
  • WebDAV:任何支持 WebDAV 的工具(文档扫描、笔记软件等)都能直连,地址是 https://cloud.example.com/remote.php/dav/files/你的用户名/,密码建议在个人设置 → 安全里生成应用专用密码,不要用主密码到处填。

外部存储:把别的盘也挂进来#

Nextcloud 支持把外部存储当作一个文件夹挂进网盘视图:本地其他目录、S3 兼容对象存储、另一台机器的 SMB/NFS 共享等。启用方式:应用里启用 External storage support,管理设置 → 外部存储里添加。

概念上要分清两种用法:

  • 主存储:整个实例的 data 目录直接放对象存储(objectstore 配置),适合文件量巨大、要横向扩容的场景,但元数据与小文件性能要实测,个人部署一般没必要;
  • 挂载式外部存储:主 data 还是本地盘,只把某个大目录(比如 NAS 上的影音库)挂进来浏览下载,编辑和协同仍走本地文件,这是个人场景最实用的形态。

挂载进来的目录权限、分享规则跟随 Nextcloud 的用户体系,但要注意:外部目录里被别的程序直接改动的文件,Nextcloud 的索引不会实时感知,需要手动触发扫描:

Terminal window
docker exec -u www-data nc-app php occ files:scan --all

备份要点#

Nextcloud 的备份对象在架构一节已经点明:数据库 + data 目录 + app 的 config。其中 config.php 里存着实例的密钥盐(passwordsalt)和实例 ID,丢了它,数据库和文件都在也拼不回原样。完整的方法论(一致性快照、异地留存、恢复演练)在 自建服务备份与迁移 里有系统展开,这里只列 Nextcloud 特有的动作顺序:

Terminal window
cd /opt/nextcloud
# 1. 进维护模式,冻结写入,保证数据库与文件的一致性
docker exec -u www-data nc-app php occ maintenance:mode --on
# 2. 导出数据库
docker exec nc-db pg_dump -U nextcloud nextcloud > backup-$(date +%F).sql
# 3. 打包 data 目录与配置(app_html 卷里的 config 也要带走)
tar czf nc-files-$(date +%F).tar.gz data
docker run --rm -v nextcloud_app_html:/html -v $PWD:/backup alpine \
tar czf /backup/nc-config-$(date +%F).tar.gz -C /html config
# 4. 退出维护模式
docker exec -u www-data nc-app php occ maintenance:mode --off

维护模式这步最容易图省事跳过,但不进维护模式直接拷 data,拷到一半正好有人上传文件,备份里的数据库记录和文件就会对不上,恢复时轻则丢文件,重则索引错乱。备份做完把三件套同步一份到另一台机器或对象存储,本机留一份不算备份。

常见问题与排障#

上传大文件报 413#

413(Request Entity Too Large)是请求体超过了某一层的上限,链路上有三层都可能拦,按顺序查:

  1. 反向代理层:最常见。Nginx 系反代默认 client_max_body_size 只有 1 MB,在站点配置里调大,例如 client_max_body_size 16G;,改完重载。用 NPM 的话在站点的 Advanced 里加这一行。
  2. PHP 层:前面 opcache.ini 里已经把 upload_max_filesize 和 post_max_size 设为 16G,没设的话在这一层被拦。
  3. Nextcloud 本身:Web 端上传走分片机制,一般不是瓶颈;桌面客户端同步大文件失败先看前两层。

「安全及设置警告」逐条消#

管理设置页顶部的警告清单是 Nextcloud 的体检报告,新装完通常有四五条,逐条对应处理:

  • 「未配置内存缓存」/「没有默认的电话区域」等:前者说明 Redis 没接上,按调优一节补 memcache.local 配置;电话区域顺手补上 occ config:system:set default_phone_region --value=CN。
  • 「数据库缺少一些索引」:一条命令补齐:docker exec -u www-data nc-app php occ db:add-missing-indices,大表会跑一会儿,低峰期执行。
  • 「数据库缺少一些可选列 / 主键」:依次跑 occ db:add-missing-columns、occ db:add-missing-primary-keys。
  • 「未设置或无法检查 HSTS 等 HTTP 响应头」:这是反代的活,在反代站点上补齐 Strict-Transport-Security 等安全响应头,Nextcloud 自己不发这些头。
  • 「后台任务上次执行在很久以前」:cron 容器没跑起来或模式选错,回调优一节检查 cron 容器日志与后台任务模式。
  • 「PHP 的 OPcache 未正确配置」:按调优一节的 ini 挂载后重启 app 容器。

目标是让这个页面显示「一切正常」。这不是强迫症:长期挂着警告的实例,往往在某次大版本升级时因为缺失索引或缓存未配置而直接翻车。

OnlyOffice 打开文档一直转圈#

按这个顺序排查,命中率从高到低:

  1. 内网回连不通:回集成一节,用两条 curl 实测容器互访,这是第一嫌疑。
  2. JWT 密钥不一致:连接器设置页与 OnlyOffice 容器环境变量逐字对比,改过要重建容器并重新保存设置。
  3. Document Server 地址协议不对:页面是 HTTPS、编辑器填了 http 地址会被浏览器拦截混合内容,公网地址必须是 HTTPS。
  4. OnlyOffice 容器资源不足:它启动要预热转换服务,内存紧张时 healthcheck 长时间不返回 true,先 docker logs nc-onlyoffice 看有没有反复重启。

文档能打开但保存失败 / 改动丢失#

编辑器有强制保存机制,关页面太快时最后几秒的改动靠回调落盘。先查 OnlyOffice 回连 Nextcloud 的那条内网链路(同上),再在连接器高级设置里确认没有把回调地址改错;也可以在管理设置里开启「保存后强制组装」相关的连接器选项做对照测试。多人协同同时先确认 Redis 文件锁已生效(memcache.locking 为 Redis),没有文件锁的协同编辑出问题只是时间问题。

客户端登录时报「不受信任的域名」#

手机/桌面客户端填的地址 Host 不在 trusted_domains 名单里。用命令查看现有名单并补上正式域名,注意名单是带下标的数组,新增要顺延下标:

Terminal window
docker exec -u www-data nc-app php occ config:system:get trusted_domains
docker exec -u www-data nc-app php occ config:system:set trusted_domains 3 --value=cloud.example.com

小结#

  • Nextcloud + PostgreSQL + Redis + OnlyOffice 四件套,是自建文件服务里「能干活」的那一档:同步、分享、在线协同编辑一条龙;
  • 部署本身不难,难的是三处细节:Redis 缓存与文件锁要接实、后台任务要交给独立 cron、OnlyOffice 的服务器间回连要走内网地址;
  • 安全及设置警告清零、备份三件套(数据库+data+config)定期留异地副本,这套私有云就能长期稳住。

和 Cloudreve 的分工可以这样记:轻量分享用 Cloudreve,正经当工作云盘用 Nextcloud,两者并不冲突,完全可以一台机器上各跑一套,按场景分流。

Nextcloud + OnlyOffice:私有云盘与在线文档协作
https://www.anexns.cloudns.org/posts/selfhost-nextcloud-onlyoffice/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0