前段时间给团队搭了一套私有云办公环境核心就是标题这套组合Docker 部署 NextCloud 做文件管理OnlyOffice 提供在线文档编辑外面再用 Nginx 把 HTTPS 配好。整套东西现在跑在公司一台服务器上同事打开浏览器就能直接编辑 Word、Excel、PPT再也不用微信传文件传来传去客户资料和人事表格也终于不放在别人的云端里了。这篇文章我把完整的部署思路、docker-compose 配置、HTTPS 证书申请和 Nginx 反代配置都写出来包括实际踩过的几个大坑——比如 OnlyOffice 的“文档安全令牌格式不正确”、api.js 无法访问、保存后提示“文件版本已更改”之类。如果你手里有台云主机或者公司内网服务器想搭一套能多人协作的私有云办公环境这份配置可以直接抄。1. 为什么把 NextCloud 和 OnlyOffice 放在一起聊1.1 这套组合解决的痛点先说一下实际场景。我这边是小团队文档管理以前基本靠微信和邮件问题是多人的同一份方案有“最终版”“最终版2”“最终版真的不改了”版本完全失控。有人改了表格里某个字段其他人拿到的还是旧文件。想给外部客户发个大文件邮件附件传不动就得临时找传输工具。更关键的是有些资料涉及客户信息和内部薪酬放在公共网盘上过不了自己心里那关。NextCloud 解决的是“文件怎么管”它本质上是一个私有化的网盘系统有目录权限、分享链接、版本历史、回收站、WebDAV移动端 App 也能连。OnlyOffice 解决的是“文件怎么改”它是一套开源办公套件包括文档、表格、演示可以嵌入 NextCloud 里两个项目通过官方连接器打通用户点一下文件就进入在线编辑界面多人同时协作、评论、修订记录都支持。这两个东西组合起来效果就很像企业版 Office 365 的私有化替代方案。文件存储在自己服务器上编辑在浏览器里完成用户不需要安装任何桌面软件。1.2 和商用方案的对比为什么这样选我在选型时也对比过其他路线。用一张表说明对比维度商用网盘 / 在线 OfficeNextCloud OnlyOffice数据归属存在服务商服务器合规风险看运气全部在自己服务器数据自己掌控授权成本按人头订阅长期费用高开源免费只出服务器成本文件格式兼容一般是自家格式Office 兼容看心情原生兼容 docx、xlsx、pptx格式还原度不错二次开发基本不开放API 有限开源可以改有完整 API部署门槛零门槛注册即用需要自己搭服务器有技术门槛维护成本服务商兜底需要自己处理备份、升级、故障表格里最后一行是最真实的差别。商用方案省心但长期用下来费用不低而且数据出境的合规问题会越来越难解释。自己搭这套环境一次性投入就是一台服务器和一个运维兼职长期看是非常划算的。另外我也对比过 NextCloud 自带的 Collabora Online。Collabora 也很成熟但部署重量级更高资源占用比 OnlyOffice 更大中文界面和 Office 文件兼容性上OnlyOffice 在我的实际测试里表现更稳。OnlyOffice 官方还提供了完善的 Docker 镜像和 NextCloud 的连接器插件更新频率也高这是最终选它的原因。1.3 整体架构和每个容器负责什么部署架构如下所有的服务都跑在 Docker 里Nginx 做统一入口Nginx宿主机或独立容器监听 80/443负责 HTTPS 证书和反向代理。外部请求先进到这一层再分发到后面的 NextCloud 和 OnlyOffice。nextcloud 容器跑 NextCloud 主程序用官方nextcloud:stable-apache镜像内含 PHP 和 Apache负责用户登录、文件管理、分享、权限控制。onlyoffice 容器跑 OnlyOffice DocumentServer也就是文档编辑的核心服务它内部自带 PostgreSQL 数据库负责文档在线编辑、保存、多人协作。db 容器MariaDB存 NextCloud 的元数据用户账号、文件关系、设置项等。redis 容器缓存和文件锁。NextCloud 官方推荐必须配 Redis尤其是在线编辑场景文件锁机制能避免多人同时写同一份文件导致的数据异常。这几个容器之间的通信都放在同一个 Docker 网络里NextCloud 能直接通过服务名访问 db 和 redisOnlyOffice 也能访问到 NextCloud。外部流量只通过宿主机 Nginx 进来所以容器不需要直接暴露公网端口比裸奔开端口安全不少。2. 部署前的准备硬件、域名、端口规划2.1 硬件和系统要求先把资源预估说清楚。OnlyOffice DocumentServer 是这套环境里的资源大户我从实际监控看它空闲时约占 2GB 左右内存打开文档时 CPU 会短时间飙升。NextCloud 加 PHP 再加缓存大概占 1GB。MariaDB 和 Redis 加起来约 1GB。所以最低配置4核 CPU、8GB 内存、50GB SSD 磁盘。只有 4GB 内存的 VPS 别想了OnlyOffice 启动阶段就可能被杀进程。推荐配置4核 8GB 起步能上 16GB 更稳。磁盘建议 SSDNextCloud 文件锁和 OnlyOffice 临时目录对 IO 比较敏感。操作系统我用的是 Ubuntu 22.04 LTSDebian 12 也完全没问题。CentOS 用户注意 SELinux 需要适当调整。Docker 环境Docker Engine 20.10 以上Docker Compose v2 插件。这里默认读者已经装好 Docker还没装的先把 Docker 装好再说。2.2 域名规划和证书思路这一步非常重要我建议直接决定后面会不会踩坑。用谁访问 NextCloud定义一个主域名cloud.example.com。用谁访问 OnlyOffice 文档服务定义另一个域名office.example.com。两个域名都解析到同一台服务器的公网 IP 即可。为什么不只用 IP 加端口因为 HTTPS 证书是绑定域名的现代浏览器对 IP 证书支持差OnlyOffice 的 WebSocket 和 api.js 加载对 HTTPS 的域名要求很严格。也不要图省事把 OnlyOffice 变成cloud.example.com/onlyoffice这种子路径操作可行性有但后面踩坑概率大大增加。只在公司内网测试的话可以先把域名写进内网 DNS 或本地 hosts等环境通了再切公网。2.3 目录结构和端口约定我在服务器上规划了这样一套结构/opt/office/ docker-compose.yml /var/www/certbot/ # 证书校验临时目录 /etc/letsencrypt/ # 证书最终保存目录端口分配上宿主机的 80 和 443 由 Nginx 使用Docker 容器中 NextCloud 的内部端口是 80但只映射到宿主机的 127.0.0.1:8080OnlyOffice 内部端口是 80只映射到宿主机的 127.0.0.1:8090。这样外部流量根本接触不到容器只有本机 Nginx 可以把请求转给它们。3. docker-compose 一键编排核心应用栈3.1 完整 compose 文件我最终使用的docker-compose.yml文件如下密码部分请替换成你自己的强密码version: 3.8 networks: office-net: driver: bridge volumes: db-data: redis-data: nc-data: ods-data: ods-log: services: db: image: mariadb:10.11 container_name: office-db restart: always command: --transaction-isolationREAD-COMMITTED --binlog-formatROW networks: - office-net volumes: - db-data:/var/lib/mysql environment: MYSQL_ROOT_PASSWORD: ChangeMe_root_password MYSQL_DATABASE: nextcloud MYSQL_USER: nextcloud MYSQL_PASSWORD: ChangeMe_db_password redis: image: redis:7.2-alpine container_name: office-redis restart: always networks: - office-net volumes: - redis-data:/data command: redis-server --appendonly yes onlyoffice: image: onlyoffice/documentserver:7.3 container_name: office-ds restart: always networks: - office-net environment: JWT_ENABLED: true JWT_SECRET: ChangeMe_JWT_Secret_long_and_random JWT_HEADER: Authorization volumes: - ods-data:/var/www/onlyoffice/Data - ods-log:/var/log/onlyoffice nextcloud: image: nextcloud:stable-apache container_name: office-nc restart: always networks: - office-net depends_on: - db - redis - onlyoffice ports: - 127.0.0.1:8080:80 environment: MYSQL_HOST: db MYSQL_DATABASE: nextcloud MYSQL_USER: nextcloud MYSQL_PASSWORD: ChangeMe_db_password REDIS_HOST: redis NEXTCLOUD_ADMIN_USER: admin NEXTCLOUD_ADMIN_PASSWORD: ChangeMe_admin_password NEXTCLOUD_TRUSTED_DOMAINS: cloud.example.com OVERWRITEPROTOCOL: https OVERWRITEHOST: cloud.example.com PHP_UPLOAD_LIMIT: 10G PHP_MEMORY_LIMIT: 1G volumes: - nc-data:/var/www/html这个文件保存到/opt/office/docker-compose.yml后面所有操作都基于这个目录。3.2 关键配置逐项拆解为什么 MariaDB 而不是 MySQL 8NextCloud 官方文档明确支持 MariaDB而且 MySQL 8 的默认认证插件和 PHP 之间偶尔会出连接问题MariaDB 兼容性更省心。--transaction-isolationREAD-COMMITTED --binlog-formatROW是 NextCloud 安装向导对数据库服务器的硬性要求不加这个参数后续可能出现数据不一致。为什么加 RedisNextCloud 官方文档已经写明推荐用 Redis 做文件锁和分布式缓存。文件锁在多人协作编辑场景尤其重要。有读者可能问开着 Redis 会不会增加复杂度我实际体会是加 Redis 只多了两行配置但它能避免很多“文件正在被使用”的诡异报错。OnlyOffice 环境的JWT_ENABLEDtrue、JWT_SECRET...、JWT_HEADERAuthorization这三个参数是配套出现的。JWT 是文档服务的安全令牌机制NextCloud 和 OnlyOffice 通信时必须双方持有同一个密钥。这个密钥在 compose 里设置了多长的字符串后面在 NextCloud 后台也要填一模一样的。NextCloud 的环境变量里OVERWRITEPROTOCOLhttps和OVERWRITEHOSTcloud.example.com是配合 Nginx 反向代理必须设置的。没有它们NextCloud 会认为自己跑在 http 和 127.0.0.1 上用户访问时可能出现重定向循环或链接拼错。PHP_UPLOAD_LIMIT10G把上传大小限制放开默认值只有 513M传大视频和项目压缩包时会直接失败。3.3 启动并首次初始化写好 compose 文件后执行cd /opt/office docker compose up -d docker compose ps第一次启动会拉取四个镜像时间看网络情况。拉完镜像后OnlyOffice 容器第一次初始化比较耗时内部要安装和配置自己的 PostgreSQL一般需要 2 到 5 分钟。可以通过下面的命令观察日志docker logs -f office-ds看到类似Server started的日志就说明文档服务准备好了。NextCloud 容器首次启动因为有管理员账号环境变量会自动初始化数据库并创建管理员。等到docker compose ps里所有容器都显示 healthy 或 Up 状态后打开浏览器访问http://服务器IP:8080注意此时还是 http因为还没配 HTTPS应该能看到 NextCloud 的欢迎页并且已经自动登录了 admin 账号。3.4 安装 OnlyOffice 连接器并完成配置NextCloud 本身不会自动“认识”OnlyOffice需要装一个官方连接器插件。步骤如下进入 NextCloud 后台右上角头像点“应用 Application”。在搜索框里输入 “ONLYOFFICE”找到官方连接器点“安装并启用”。进入“管理设置 → ONLYOFFICE”。在“文档编辑服务地址”里填写https://office.example.com在“文档编辑服务的密钥”里填写 compose 文件中设置的JWT_SECRET值。保存后进入文件列表新建一个 Word 文档或用鼠标悬停已有的 docx 文件选择“在 ONLYOFFICE 中打开”。如果之前所有配置正确这里会直接打开在线编辑器。第一次打开时浏览器会向office.example.com请求 api.js 和文档内容需要保证那个子域名的 HTTPS 是通的。3.5 补几个必要的 NextCloud 系统配置容器部署后NextCloud 一直在反向代理后面它会认为所有客户端 IP 都是 127.0.0.1日志里的来源 IP 全是乱的。同时命令行工具也需要知道对外地址。执行两条命令修正docker exec -u www-data office-nc php occ config:system:set trusted_proxies 0 --value127.0.0.1 docker exec -u www-data office-nc php occ config:system:set overwrite.cli.url --valuehttps://cloud.example.com这两条命令本质是在改 NextCloud 的config/config.php。不设置的话后续用 OnlyOffice 时部分回调地址可能不对这也是后面要讲到的“文件版本已更改”报错的诱因之一。4. HTTPS 配置让整条链路加密4.1 申请 Lets Encrypt 证书我用的是 Lets Encrypt 免费证书配合 Nginx 做签发和管理。在宿主机上操作先安装必要工具apt update apt install -y nginx certbot python3-certbot-nginx mkdir -p /var/www/certbot先用一个最简单的 Nginx 配置把 80 端口服务起来主要目的是让域名校验请求能够到达证书签发目录。创建/etc/nginx/sites-available/office-initserver { listen 80; server_name cloud.example.com office.example.com; location /.well-known/acme-challenge/ { root /var/www/certbot; } location / { return 301 https://$host$request_uri; } }启用配置并启动 Nginxln -s /etc/nginx/sites-available/office-init /etc/nginx/sites-enabled/ systemctl enable --now nginx然后申请证书一条命令同时签两个域名certbot certonly --webroot -w /var/www/certbot \ -d cloud.example.com -d office.example.com \ --email youexample.com --agree-tos --no-eff-email签下来的证书位置在/etc/letsencrypt/live/cloud.example.com/里面包含两个域名的 SAN 证书所以后面两个 server 块共用这份证书文件。4.2 Nginx 反向代理配置示例拿到证书后写正式的 Nginx 配置。这份配置我在生产环境验证过重点在两处To NextCloud 要设置 Host、X-Forwarded-* 头并加大上传体积To OnlyOffice 必须支持 WebSocket 升级并且不能开缓冲对在线编辑的实时同步很关键。创建/etc/nginx/sites-available/officeupstream nextcloud_backend { server 127.0.0.1:8080; } upstream onlyoffice_backend { server 127.0.0.1:8090; } server { listen 80; server_name cloud.example.com office.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name cloud.example.com; ssl_certificate /etc/letsencrypt/live/cloud.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/cloud.example.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; client_max_body_size 10G; location / { proxy_pass http://nextcloud_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 60s; proxy_read_timeout 300s; proxy_send_timeout 300s; } } server { listen 443 ssl http2; server_name office.example.com; ssl_certificate /etc/letsencrypt/live/cloud.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/cloud.example.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; client_max_body_size 0; location / { proxy_pass http://onlyoffice_backend; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_redirect off; proxy_buffering off; proxy_request_buffering off; proxy_read_timeout 300s; } }启用这份配置ln -s /etc/nginx/sites-available/office /etc/nginx/sites-enabled/ rm /etc/nginx/sites-enabled/default nginx -t systemctl reload nginxclient_max_body_size 10G很关键NextCloud 默认允许上传较大文件但 Nginx 的默认值只有 1M不调大上传稍大一点的压缩包就会报 413。OnlyOffice 那块我把请求体限制设为 0因为文档服务要处理二进制流不能让它被 Nginx 限制住。4.3 验证 HTTPS 是否都通了配置完成后按顺序验证curl -I https://cloud.example.com curl -I https://office.example.com第一个应该返回 302 或 200第二个应该返回 302OnlyOffice 根路径会跳转到欢迎页。再验证关键的 api.jscurl -I https://office.example.com/web-apps/apps/api/documents/api.js返回 200 就表示 OnlyOffice 的文档服务对外完全可用。如果返回 404 或 502先别急着往下排查问题基本出在这一层的反代配置或容器状态上。4.4 证书续期Lets Encrypt 证书有效期 90 天需要自动续期。我加了两个 cron 任务一个负责续期一个负责重载 Nginxcrontab -e添加17 3 * * * certbot renew --webroot -w /var/www/certbot --quiet systemctl reload nginxcertbot 到时间会自动判断哪些证书快到期并续签成功后重载 Nginx 让新证书生效。5. 常见问题排查与避坑实录5.1 OnlyOffice 提示“文档安全令牌的格式不正确”这个问题几乎每个部署 OnlyOffice 的人都会遇到。我来梳理一下最常见的两种原因。第一种JWT 密钥不一致。NextCloud 后台 ONLYOFFICE 设置里填的密钥和 OnlyOffice 容器里环境变量的JWT_SECRET对不上。这个好解决把两边改成同一串随机字符串然后重启 OnlyOffice 容器docker restart office-ds第二种OnlyOffice 容器已经启动了但修改环境变量后没有重建。只执行docker restart不会让新环境变量生效必须重建容器docker compose up -d --force-recreate onlyoffice排错时先检查两边配置docker exec office-ds env | grep JWT输出里的JWT_SECRET要和 NextCloud 后台填的一模一样包括末尾不能有空格。提示改完 JWT 之后浏览器里按 CtrlF5 强制刷新一下页面旧版 JS 缓存也会导致类似报错。5.2 api.js 无法访问这个报错通常表现为在 NextCloud 里打开文档编辑器一直白屏控制台报 api.js 404 或 502。先说结论90% 的可能是你在 NextCloud 后台填的“文档编辑服务地址”填错了。我见过有人图省事填了http://127.0.0.1:8090。如果在服务器本机测试这个地址能通但用户的浏览器拿到这个地址后会尝试在用户自己的电脑上访问 127.0.0.1那当然访问不到。所以这个地址必须填浏览器能访问的公网 HTTPS 地址也就是https://office.example.com。还有一种情况是 Nginx 反代配置不对。OnlyOffice 的 API 路径比较固定验证方法很简单curl -I https://office.example.com/web-apps/apps/api/documents/api.js返回 200 就说明配置没问题。如果返回 404检查 Nginx 里location /的proxy_pass是否指向了正确的 8090 端口如果返回 502多半是 OnlyOffice 容器没起来或容器内部服务还没初始化完成。5.3 编辑完再打开提示“文件版本已更改该页面将被重新加载”这个提示我一开始也困扰了很久。现象是在 OnlyOffice 里编辑文档保存后页面弹出“文件版本已更改该页面将被重新加载”页面刷新后你的修改可能就丢了。定位思路是这样的OnlyOffice 保存文件时会向一个回调地址发起请求告知 NextCloud“文件被更新了”。如果这个回调地址拼错NextCloud 没有收到更新但文档服务已经认为文件改了两边就会对不上于是弹出这个提示。根本原因大多是 NextCloud 的OVERWRITEHOST和OVERWRITEPROTOCOL没设置或者设置的值和你实际访问地址不一致。比如你设置的是http://内网IP:8080但用户通过https://cloud.example.com访问回调地址就错了。解决方法就是确保 compose 里这两个环境变量正确并执行前面 3.5 节的两条 occ 命令。另外修改完 JWT 后我也碰到过一次类似问题重启 OnlyOffice 容器并强制刷新浏览器后就好了。所以排查顺序是先检查回调地址配置再检查 JWT 配置最后清浏览器缓存。5.4 Docker 环境类问题速查表我整理了一张表对应常见的 Docker 环境报错报错或现象可能原因解决办法Docker Desktop 提示 virtualization support not detectedBIOS 里没有开启虚拟化或 Windows 功能没启用进入 BIOS 开启 Intel VT-x/AMD-V在 Windows 功能里勾选 Hyper-V 和虚拟机平台Failed to connect to the docker api at npipe:////./pipe/dockerDesktopLinuxEngineDocker Desktop 服务没起来重启 Docker Desktop或检查 WSL2 内核是否更新docker: permission denied while trying to connect当前用户不在 docker 用户组执行sudo usermod -aG docker $USER重新登录拉取镜像非常慢镜像源网络不佳在 Docker 配置里设置镜像加速源容器一直 Restarting启动参数或镜像初始化失败docker logs 容器名查看具体报错这些问题如果是在云主机上直接部署 Docker Engine基本不会遇到主要困扰的是 Windows 上用 Docker Desktop 做实验的读者。我的建议是生产环境老老实实用 Linux 服务器Windows 的 Docker 环境用于测试和练手就够了。5.5 上传大文件被限制有段时间同事说上传 2GB 的邮件备份文件总是失败排查后发现是三层限制叠加Nginx 的client_max_body_size默认 1M我改成了 10G。PHP 的upload_max_filesize默认只有 513M我在 NextCloud 环境变量里设置了PHP_UPLOAD_LIMIT10G。浏览器和前端的超时时间如果网络慢大文件没传完连接断了需要调整proxy_read_timeout。如果改完 compose 里的PHP_UPLOAD_LIMIT记得重建容器docker compose up -d --force-recreate nextcloud改完之后在 NextCloud 管理设置里能看到当前上传限制变为 10G这时再传大文件就不会被 PHP 拦截了。5.6 其他几个值得留意的细节OnlyOffice 容器内存占用高是正常现象。如果服务器只有 4GB 内存我建议先别开 OnlyOffice 的缓存和转换服务或者干脆内存升到 8GB。我用docker stats观察过OnlyOffice 在后台文档转换时会瞬间吃到 2.5GB 内存虽然结束后会释放但这期间如果和其他服务抢内存可能导致容器被杀。备份策略别落下。NextCloud 数据库和文件存储在前后端都改动后要定期备份docker exec office-db mysqldump -u root -pYourRootPassword nextcloud /backup/nextcloud_$(date %F).sql同时备份nc-data卷的数据。恢复的时候只要把 sql 导入 MariaDB把 nc-data 目录放回原位再重启容器即可。OnlyOffice 的配置不算复杂但ods-data卷里也有文档缓存和密钥信息有条件的话也一起备份。写在最后整套环境我在不同机器上部署过三四次最大的感悟是这一个组合的坑绝大多数不在 Docker 也不在 NextCloud而集中在 OnlyOffice 的地址配置、JWT 密钥一致性和反向代理的回调链路。只要把“文档服务地址、JWT 密钥、回调地址”这三个点对齐了后面就是很稳定的运行状态。最后给还没上手的读者一个建议如果你也是第一次搭先用内网域名跑通整个流程甚至可以先用 HTTP 试一遍记得把 NextCloud 的 OVERWRITEPROTOCOL 临时改成 http验证文件上传、在线编辑、多人协作都正常了再换上 HTTPS 正式使用。这样排错范围会小很多等到线上操作时也会更有底气。