企业官网建设流程全解析

前后花了两个周末，终于把家里跑了一年多的 Nextcloud 从裸机 LAMP 迁移到了 Docker 全栈方案。之前那套方案虽然也能用，但每次升级 PHP 依赖都能把人整疯，数据库和文件散落在系统各个角落，有次磁盘满了一查，才发现是日志文件把根分区撑爆了。换到 Docker 之后，所有服务——Nextcloud、MariaDB、OnlyOffice、Caddy——各自待在独立容器里，升级隔离、卸载干净、迁移方便，折腾一次以后真的省心很多。

这篇文章就是这套全栈方案从零到一的完整记录。内容包括架构选型思路、Compose 文件编写、MariaDB 初始化与定时备份、OnlyOffice 在线编辑集成、HTTPS 安全接入，以及部署现场遇到的各种报错和排查过程。无论你是想在家庭服务器上搭一个私有网盘，还是小团队需要一套带在线编辑的文件共享平台，这篇文章应该都能帮你少走不少弯路。

1. 整体架构与选型思路：为什么是这套组合

1.1 三个核心需求对应的三个关键组件

先说需求。我要的不只是“把文件放服务器上”，而是三件事：文件要能多端同步、要能直接在网页里编辑 Office 文档、要能通过域名在外网安全访问。这三个需求正好对应三个核心组件。

Nextcloud 本身解决文件同步和共享，自带完善的 WebDAV 接口、客户端 App、相册备份、分享链接等功能。但官方默认用 SQLite 作为数据库，一旦文件数量上到几千、用户并发一多，SQLite 的性能问题就非常明显。所以把数据库换成 MariaDB，这也是官方推荐的生产环境方案。

OnlyOffice Document Server 解决在线编辑。它是一套独立的协同编辑服务，能在浏览器里打开并编辑 docx、xlsx、pptx 这类 Office 格式文件，Nextcloud 有对应的官方连接器应用，安装配置后就能在文件列表里直接点“在线编辑”。

HTTPS 则解决安全访问。Nextcloud 里几乎所有流量都涉及隐私数据——通讯录、日历、照片、文档，如果用明文 HTTP 在公网传输，等于把家门钥匙放在门口脚垫下面。通过 Caddy 反向代理自动申请 Let's Encrypt 证书，配置一次就能长期自动续期。

1.2 容器化部署相对裸机部署的几个明显优势

以前在裸机上部署这套东西，需要手动装 Nginx、PHP-FPM、各种 PHP 扩展、MariaDB、Redis，还要处理版本兼容。Nextcloud 对 PHP 版本、扩展模块要求很苛刻，稍有不慎某个扩展没开，安装向导就卡住。换到 Docker 后，官方镜像已经把 PHP 环境和所有扩展打包好了，我要做的只是选对镜像版本、写好 Compose 编排。

另一个优势是环境隔离。MariaDB 的数据文件、Nextcloud 的配置与数据、OnlyOffice 的缓存与日志，分别落在不同的挂载卷里。某个服务崩了，只需要重建对应容器，不会污染主机系统。升级时也是先拉新镜像、重建容器，不行就回滚到旧镜像，比裸机升级安全太多。

还有一点对家庭服务器用户特别重要：归档和复制。整套编排就一个 docker-compose.yml 文件加一个 .env 文件，放到新机器上，启动容器，数据一卷恢复，服务就能跑起来。这个体验是裸机部署没法比的。

1.3 镜像选择的细节：版本号、发行版与 ARM 注意点

选镜像时要注意几点。首先是版本：Nextcloud 官方镜像我建议避开“latest”，至少用 major 版本号，比如 nextcloud:28-apache，这样既不会意外升级到大版本，又能获得该系列内的小版本更新。MariaDB 用 10.11，这是 Nextcloud 官方验证过的长期支持版本，比 11.x 更稳。

其次是发行版。Nextcloud 官方镜像有 apache 和 fpm 两种。apache 版本自带 Web 服务器，用起来省事，适合大多数场景；fpm 版本不含 Web 服务器，性能边界更清晰，适合配合专用 Nginx 容器做高并发调优。家庭和小团队场景建议直接用 apache 版本，少一层容器依赖就少一个排错点。

最后是 ARM 平台。很多人的 NAS 是 ARM 处理器（群晖、树莓派），选镜像时一定要确认有没有对应平台的 tag。nextcloud 和 mariadb 官方镜像都支持 multi-arch，一般能直接拉取对应平台版本。如果你在 ARM 上遇到“exec format error”，基本可以确定是镜像平台不对，需要在 compose 里显式指定 platform 或者换用支持该 CPU 架构的镜像。

2. 目录规划与 Compose 文件编写

2.1 先想清楚宿主机目录结构

开始写 Compose 之前，我会先把宿主机上的目录规划好。这套方案涉及 4 个服务、3 组持久化数据，目录结构混乱是后期运维灾难的根源。我习惯把所有数据放在同一个根目录下，用服务名区分：

~/nextcloud/ ├── .env ├── docker-compose.yml ├── caddy/ │ └── Caddyfile ├── db/ │ └── data/ # MariaDB 数据文件 ├── nextcloud/ │ ├── config/ # Nextcloud 配置 │ ├── data/ # 用户文件数据 │ └── apps/ # 自定义应用与连接器 ├── onlyoffice/ │ ├── data/ # 证书缓存、字体缓存 │ ├── logs/ # 日志 │ └── lib/ # 联邦缓存 └── backup/ # 定时备份输出目录

这个布局有几个好处：备份时只需要打包 backup 目录或者把各卷打包；重装系统后目录结构可以原样恢复；每个目录独立挂载，排错时能直接看到是哪个服务的持久化数据在膨胀。

注意一个容易踩的坑：Nextcloud 数据目录（nextcloud/data）不要和 MySQL 数据目录（db/data）混在一个父目录下，否则备份时容易漏掉或者重复打包，而且文件权限互相干扰。容器内运行的用户不同，混在一起后可能出现某一边无法写入的情况。

2.2 docker-compose.yml 完整解读

先放上这套方案的核心文件，后面再逐步拆解每个服务的关键配置。以下配置基于 Docker Compose v2。

version: "3.8" services: db: image: mariadb:10.11 container_name: nextcloud-db restart: unless-stopped env_file: .env environment: - MARIADB_ROOT_PASSWORD=${MARIADB_ROOT_PASSWORD} - MARIADB_DATABASE=nextcloud - MARIADB_USER=nextcloud - MARIADB_PASSWORD=${MARIADB_PASSWORD} - TZ=Asia/Shanghai command: - --character-set-server=utf8mb4 - --collation-server=utf8mb4_unicode_ci - --lower_case_table_names=1 volumes: - ./db/data:/var/lib/mysql healthcheck: test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"] interval: 10s timeout: 5s retries: 5 start_period: 30s networks: - nextcloud-net app: image: nextcloud:28-apache container_name: nextcloud-app restart: unless-stopped depends_on: db: condition: service_healthy environment: - MYSQL_HOST=db - MYSQL_DATABASE=nextcloud - MYSQL_USER=nextcloud - MYSQL_PASSWORD=${MARIADB_PASSWORD} - TRUSTED_PROXIES=${TRUSTED_PROXIES} - NEXTCLOUD_TRUSTED_DOMAINS=${NEXTCLOUD_TRUSTED_DOMAINS} - OVERWRITEPROTOCOL=https - PHP_UPLOAD_LIMIT=10G - PHP_MEMORY_LIMIT=2G volumes: - ./nextcloud/config:/var/www/html/config - ./nextcloud/data:/var/www/html/data - ./nextcloud/apps:/var/www/html/custom_apps networks: - nextcloud-net onlyoffice: image: onlyoffice/documentserver:latest container_name: nextcloud-onlyoffice restart: unless-stopped environment: - JWT_ENABLED=true - JWT_SECRET=${JWT_SECRET} - JWT_HEADER=Authorization - TZ=Asia/Shanghai volumes: - ./onlyoffice/data:/var/log/onlyoffice - ./onlyoffice/lib:/var/lib/onlyoffice - ./onlyoffice/data:/var/www/onlyoffice/Data depends_on: - app networks: - nextcloud-net caddy: image: caddy:2-alpine container_name: nextcloud-caddy restart: unless-stopped ports: - "80:80" - "443:443" environment: - DOMAIN=${DOMAIN} - ADMIN_EMAIL=${ADMIN_EMAIL} - NEXTCLOUD_HOST=app volumes: - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro - caddy_data:/data - caddy_config:/config depends_on: - app - onlyoffice networks: - nextcloud-net volumes: caddy_data: caddy_config: networks: nextcloud-net: driver: bridge

这条编排里最核心的设计是：所有服务处于同一个自定义网络 nextcloud-net 中，服务之间通过容器名互相访问，Caddy 是唯一对公网暴露端口的入口。这样最小化了暴露面，也为后面域名解析和证书申请打下基础。

2.3 .env 文件与敏感信息管理

我习惯把密码、域名这类经常变的配置放在 .env 文件里，compose 文件本身保持相对稳定。这样做的好处是：docker-compose.yml 可以放进 Git 管理而不泄露凭据，换机器部署时只需要复制 .env 并修改几行。

# 数据库配置 MARIADB_ROOT_PASSWORD=your_strong_root_password MARIADB_PASSWORD=your_strong_user_password # OnlyOffice JWT 密钥 JWT_SECRET=your_random_jwt_secret # 域名与代理 DOMAIN=cloud.example.com ADMIN_EMAIL=admin@example.com TRUSTED_PROXIES=172.16.0.0/12 NEXTCLOUD_TRUSTED_DOMAINS=cloud.example.com

关于 .env 有两点经验。一是密码生成用专门工具，不要自己手打一段“看起来随机”的字符串，实际强度可能很低。Linux 下可以用 openssl rand -base64 32 这类命令生成。二是 TRUSTED_PROXIES 这个参数很多人会忽略，但 Nextcloud 在反代后面时，如果不声明可信代理网段，获取客户端真实 IP 会失效，日志里全是 172.x.x.x，甚至某些安全校验会异常。这里填的是 Docker 默认网段，如果你自定义过网络，需要按实际情况调整。

2.4 为什么我用 Caddy 而不用 Nginx

HTTPS 反代有两个常见选择：Nginx 加 certbot，或者 Caddy 自动 HTTPS。我最终选 Caddy，核心原因是“自动化程度差了一个量级”。

如果用 Nginx + certbot，需要手动写反代配置、写证书路径、配置续期 hook、处理 WebSocket 代理头，前后至少十几个配置片段。而 Caddy 只需要在 Caddyfile 里写几行，它会自动申请证书、自动续期、自动处理 HTTP/2 和 WebSocket 升级头。对于 Nextcloud 这种对反向代理头要求苛刻的应用，Caddy 个中细节处理得非常干净。

有人担心 Caddy 性能不如 Nginx，但如果是家庭服务器、小团队文件共享，Caddy 的并发能力足够用了。真正卡性能瓶颈的通常在 MariaDB 和 PHP 进程，而不是反代层。

3. MariaDB 初始化：从建库到定时备份

3.1 字符集、排序规则和表名大小写

很多人在安装 Nextcloud 时经历过“数据库连接错误”或“表已存在”之类的诡异问题，多半是数据库字符集或大小写敏感配置没对齐。

我在 MariaDB 配置里强制指定了三项：

command: - --character-set-server=utf8mb4 - --collation-server=utf8mb4_unicode_ci - --lower_case_table_names=1

utf8mb4 是互联网标准字符集，能完整支持中文、生僻字、emoji。Nextcloud 在安装检测里也会检查数据库默认字符集，如果数据库是拉丁字符集，安装时会直接给出警告。utf8mb4_unicode_ci 是排序规则，对应多数场景下的合理默认值。

lower_case_table_names 是另一个容易被忽略的点。Linux 上 MySQL/MariaDB 默认区分表名大小写，而 Windows 上不区分。如果你在同一套 Nextcloud 数据目录上切换过操作系统，或者数据库导入导出跨平台，大小写策略不一致会导致“表不存在”的怪异报错。统一设为 1 可以避免这类问题。

3.2 启动顺序与健康检查

Compose 里 depends_on 默认只能控制“启动顺序”，不能保证数据库已经“准备好接受连接”。Nextcloud 容器如果比 MariaDB 先完成初始化，应用尝试连接数据库时会报错退出，可能导致反复崩溃循环。

解决办法是给 db 服务加健康检查。我用的是官方镜像自带的 healthcheck.sh 脚本，它会检测 MariaDB 是否真正可连接且 InnoDB 初始化完成。app 服务的 depends_on 使用 condition: service_healthy，这样 Nextcloud 只有在数据库真正就绪后才会启动。

healthcheck: test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"] interval: 10s timeout: 5s retries: 5 start_period: 30s

start_period 的作用很重要。MariaDB 首次初始化数据目录时可能需要几十秒甚至更久，这段时间内的健康检查失败不计入 retries，避免容器被错误标记为 unhealthy。

3.3 首次启动与安装向导要点

配置都写好之后，首次启动流程很简单，却有几个细节必须说清楚。

执行 docker compose up -d 会按依赖顺序拉镜像、启动容器。首次启动后，用 docker compose ps 查看容器状态，确认 4 个容器都是 running 或 healthy。接着浏览器访问 https://你的域名 ，进入安装向导。

向导里三个关键字段这样填：

• 数据库选“MySQL/MariaDB”
• 数据库地址填 db，也就是 compose 里的服务名
• 账号密码用 .env 里设置的 MARIADB_USER 和 MARIADB_PASSWORD

数据库地址这一项是新手最容易错的地方。这里填的不是宿主机 IP，也不是 localhost，而是容器网络内的服务名。因为在 Compose 网络里，服务名就是 DNS 名称，app 容器可以通过 db 这个主机名访问数据库容器。填 localhost 的话，容器的 localhost 指向自己，一定连接失败。

安装向导完成后，建议立刻去“应用”页安装 Office 连接器（即 Nextcloud 里的 OnlyOffice 插件）。这个应用不在内置列表里，需要在应用商店搜索“OnlyOffice”，找到后安装并启用。

3.4 MariaDB 定时备份：给数据上保险

私有云最怕的不是服务崩溃，而是数据丢失。我强烈建议在部署当天就把数据库备份脚本安排上，不要等出了问题再后悔。

下面这个脚本我一直在用，功能是每日凌晨 3 点执行 mysqldump，按日期保留最近 14 天备份，超过 14 天的自动删除。

#!/bin/bash BACKUP_DIR=/opt/nextcloud/backup/db DB_HOST=localhost DB_USER=backup DB_PASSWORD='your_backup_password' DB_NAME=nextcloud RETENTION_DAYS=14 mkdir -p "$BACKUP_DIR" BACKUP_FILE="$BACKUP_DIR/nextcloud-$(date +\%Y\%m\%d-\%H\%M\%S).sql.gz" docker exec nextcloud-db sh -c \ 'exec mysqldump --single-transaction --quick --routines \ -h"$DB_HOST" -u"$DB_USER" -p"$DB_PASSWORD" "$DB_NAME"' \ | gzip > "$BACKUP_FILE" find "$BACKUP_DIR" -name "nextcloud-*.sql.gz" -mtime +$RETENTION_DAYS -delete

几个参数我要解释一下。--single-transaction 用于 InnoDB 表，能在不锁表的情况下做一致性备份，这样备份期间用户仍然可以正常读写文件，不会产生“备份时业务中断”的问题。--quick 逐行流式导出，避免一次性把大数据表读进内存。

备份账号我建议单独建一个，只授予 SELECT、LOCK TABLES、SHOW VIEW 权限，不要直接用 root 做备份。即使脚本文件泄露，影响面也受控。

这个脚本配合宿主机的 crontab 使用：

0 3 * * * /opt/nextcloud/backup/db_backup.sh >> /opt/nextcloud/backup/backup.log 2>&1

另外提醒一句：数据库备份只保护结构化数据，用户上传的文件还需要单独做文件级备份。我的做法是把 nextcloud/data 目录同步到另一块硬盘或者对象存储。文件备份和数据库备份尽量分开执行，避免同一台磁盘故障时两个备份一起丢失。

4. OnlyOffice 集成：在线编辑的完整链路

4.1 OnlyOffice Document Server 到底做了什么

OnlyOffice Document Server 是一套独立的协同编辑服务。当你在 Nextcloud 里点击一个 docx 文件并选择“在 OnlyOffice 中打开”时，Nextcloud 会把文件内容传递给 OnlyOffice，由 OnlyOffice 在浏览器里渲染出类 Office 的编辑界面，所有编辑器功能——格式、批注、协同编辑——都由它负责。

这里有一个很容易误会的点：Nextcloud 和 OnlyOffice 是两套完全独立的系统，只通过接口通信。Nextcloud 负责文件存储和权限控制，OnlyOffice 负责编辑渲染和保存回写。两者通过一个加密签名机制（默认是 JWT）互相鉴别身份，确保文件不会落到未经授权的第三方手里。

理解了这一点，很多配置问题就好排查了。在线编辑打不开、保存失败，大半是这两者之间的通信出了故障，要么是地址不通，要么是 JWT 密钥不一致，要么是网络策略挡住了请求。

4.2 container 部署与密钥配置

OnlyOffice 容器在 Compose 里我已经写过了，关键配置是 JWT 相关环境变量：

environment: - JWT_ENABLED=true - JWT_SECRET=${JWT_SECRET} - JWT_HEADER=Authorization

JWT 是一把双刃剑。开启后，Nextcloud 和 OnlyOffice 之间所有请求都会带上签名，能有效防止未授权用户拿 OnlyOffice 接口做文件解析。但同时，Nextcloud 端必须配置完全一致的密钥，否则就会出现经典的“文档安全令牌的格式不正确”。

JWT_SECRET建议用至少 32 字节的随机字符串。生成方法：

openssl rand -base64 32

这串密钥要同时配置在两个地方：OnlyOffice 容器的 JWT_SECRET 环境变量，以及 Nextcloud 后台 OnlyOffice 设置里的“Secret key”输入框。两边完全一致，缺一不可。

4.3 Nextcloud 里的 OnlyOffice 应用设置

安装并启用 ONLYOFFICE 连接器后，进入 Nextcloud 管理设置，找到 ONLYOFFICE 板块，需要填几项内容：

• 文档编辑服务地址：填http://onlyoffice:8080（容器网络内地址）或https://cloud.example.com/onlyoffice（如果走反代）
• Secret key：填和容器环境变量相同的 JWT_SECRET
• 编辑格式：默认包含 docx、xlsx、pptx 等，按需调整

这里有个关键选择：OnlyOffice 容器对内还是对外。我的方案是只走内网地址（http://onlyoffice:8080），由 Nextcloud 服务端代为转发。这样可以避免把 OnlyOffice 直接暴露到公网，减少攻击面。缺点是浏览器打开编辑页面时会通过 Nextcloud 中转，增加一点延迟。家庭场景下感知不到差异，安全性却高不少。

如果你需要 OnlyOffice 走外网地址（比如 Nextcloud 和 OnlyOffice 不在同一台服务器），就把地址填成 https 的完整 URL，并确保 Caddy 的 Caddyfile 里配置了对应的 onlyoffice 路由。这种情况下，一定要让浏览器能直接访问该地址，否则 API.js 加载不出来，编辑器就是一片空白。

4.4 OnlyOffice api.js 无法访问的排查

这个报错非常典型，尤其出现在跨域、反代配置不全、或者直接 IP 访问的场景。表现是打开编辑页面后，浏览器控制台提示无法加载 API.js，界面停留在转圈或白屏。

排查顺序我建议按下面几步来：

1. 先确认 OnlyOffice 容器本身正常：docker exec nextcloud-onlyoffice curl -I http://localhost:8080/healthcheck，如果返回 200，说明核心服务没问题。
2. 在宿主机上测试网络链路：curl -I http://127.0.0.1:8080/healthcheck，如果宿主机能通，但浏览器不通，多半是端口映射或防火墙策略问题。
3. 检查 Caddy 日志：如果 OnlyOffice 走了外网地址，看docker logs nextcloud-caddy里有没有 404 或 5xx，反代路径写错是常见原因。
4. 检查浏览器控制台具体报错：如果提示跨域（CORS），需要在 OnlyOffice 容器环境变量里配置额外的允许来源。

一个容易踩的坑：OnlyOffice 容器首次启动时会在 /var/www/onlyoffice/Data 目录下生成一些配置和密钥文件。如果你在容器启动之后才调整 JWT 配置，务必重新创建容器，而不是 restart。因为容器重启只能读取环境变量，不能重新生成内部已写入的配置。我见过不少人改了 env 后 restart 容器，结果 JWT 密钥实际没变，排查半天才发现是这个原因。

5. HTTPS 接入：从裸奔到自动续期

5.1 为什么必须上 HTTPS，HTTP 明文风险在哪

可能有人觉得“我的服务器就自己用，HTTP 也没关系吧”。HTTP 明文传输意味着什么？你在咖啡店连公共 WiFi，登录 Nextcloud 输入密码，密码以明文方式在网络里流传。任何能捕捉网络流量的人，都能直接看到你的账号密码。

更隐蔽的问题是页面上被注入内容。运营商、路由器、恶意脚本都可能往 HTTP 响应里塞广告、挖矿脚本甚至恶意跳转代码。Nextcloud 这种自建系统，一旦页面被篡改，用户数据的安全边界就完全破了。HTTPS 通过 TLS 加密传输内容，同时通过证书验证服务器身份，两者共同保证你访问到的内容和输入的数据都只属于你。

从我自己的经历看，上了 HTTPS 之后，最明显的区别是移动端 App 不再需要额外允许“不安全连接”的开关。iOS 和 Android 的 Nextcloud 客户端对 http 地址支持越来越严格，很多版本已经强制要求 https。这一步不上，移动端体验基本是断的。

5.2 Caddy 自动申请和续期证书的原理

Caddy 把 HTTPS 做成了默认行为：只要 Caddyfile 里写了域名，它就会自动从 Let's Encrypt（或 ZeroSSL）申请证书，并且到期前自动续期。整个流程对用户透明，不需要安装 certbot、不需要写 cron 续期任务、不需要手动指定证书路径。

原理上，Caddy 通过 ACME 协议向证书颁发机构验证你确实拥有这个域名。验证方式最常见的是 HTTP-01 挑战：Caddy 会在一段很短时间内响应一个特定路径的请求，证书机构访问这个路径确认通过后，就会签发证书。这也是为什么 80 端口必须对外开放。如果 80 端口被占用或封锁，证书申请大概率失败。

Caddy 容器把证书数据存放在 caddy_data 卷里，这个卷不要随意删除。一旦删除，Caddy 会重新走一遍证书申请流程，而 Let's Encrypt 有频率限制，短期内频繁申请会触发限流，导致一段时间内无法发证。

5.3 Caddyfile 关键配置

我的 Caddyfile 长这样：

{$DOMAIN} { encode zstd gzip header { Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" X-Content-Type-Options "nosniff" X-Frame-Options "SAMEORIGIN" Referrer-Policy "no-referrer" } reverse_proxy nextcloud-app:80 handle_path /onlyoffice/* { reverse_proxy nextcloud-onlyoffice:8080 } }

解释几个关键点。encode 开启响应压缩，zstd 和 gzip 是主流浏览器的通用压缩算法，对 Nextcloud 这种有大量 JSON 和文本响应的应用效果明显。

header 里的三个配置是安全基线。Strict-Transport-Security 告诉浏览器强制走 HTTPS，不给明文连接任何机会。X-Frame-Options 防止页面被嵌入到恶意 iframe 中，Nextcloud 的管理界面本身也会校验这个头。Referrer-Policy 减少 URL 泄露。

reverse_proxy nextcloud-app:80 把主域名流量转发到 Nextcloud 容器。注意这里的目标地址是 docker compose 里 app 服务的 80 端口，因为 nextcloud:28-apache 镜像内部跑的就是 Apache 加上 PHP。

handle_path /onlyoffice/* 是给 OnlyOffice 留的转发路径。如果你决定让 OnlyOffice 走外网地址，浏览器加载 OnlyOffice 前端资源时就会请求这个路径，Caddy 需要把它转发给 OnlyOffice 容器。

5.4 HTTP/2、大文件上传和代理超时

Nextcloud 部署完成后，默认配置还有个隐藏限制：上传文件大小。镜像里 PHP 默认 upload_max_filesize 通常是 2M 或 10M，对网盘场景远远不够。我在 app 服务的 environment 里设置了：

- PHP_UPLOAD_LIMIT=10G - PHP_MEMORY_LIMIT=2G

PHP_UPLOAD_LIMIT 会同时修改 upload_max_filesize 和 post_max_size，设置成 10G 后，单文件最大 10G 以内都能上传。PHP_MEMORY_LIMIT 影响 PHP 进程可用内存，Nextcloud 在处理大文件索引、图片预览时会比较吃内存，建议至少 512M，文件多的话 1G 到 2G 更保险。

Caddy 作为反代，默认对传输大小没有硬性限制，但它对请求体有默认的缓冲配置。实际使用中，如果遇到上传大文件总在中途断掉，超出 Nextcloud 自身的限制还没用到，多半是 PHP-FPM 的超时或者客户端与服务器之间的连接被中断。可以在 app 服务的 PHP 配置里增加 max_execution_time 等参数，但不要盲目调太大，以免脚本僵死拖垮容器。

5.5 只打算内网访问时，证书怎么办

不是所有人都需要把 Nextcloud 暴露到公网。如果只在家里局域网用，可以不用 Let's Encrypt，而是让 Caddy 使用内部 CA 签发自签名证书。此时浏览器会提示证书不受信任，需要在客户端手动信任这台服务器的 CA。

更省事的方案是用 mkcert 生成加进本机信任的证书，但这种方案每台客户端都要装一次根证书，维护成本不低。如果你只有一两台设备，可以接受；如果家里有五六台设备，我建议还是老老实实买个域名、用 Caddy 自动申请证书，哪怕通过 DDNS 解析到家庭宽带，体验也顺畅得多。

6. 部署现场：常见报错与排查实录

6.1 Windows Docker Desktop 无法启动：虚拟化未开启

很多人在 Windows 上用 Docker Desktop，安装后启动直接报错：Docker Desktop failed to start because virtualization support is not detected。这个报错的意思是宿主机没有开启硬件虚拟化功能。

排查办法很简单：打开任务管理器，切到“性能”标签，看底部“虚拟化”这一项。如果显示“已启用”，说明虚拟化已开，问题可能出在 Windows 的 Hyper-V 或 WSL2 功能没有启用；如果显示“已禁用”，需要进 BIOS/UEFI 开启 Intel VT-x（不同主板叫法不同，常见的是 Intel Virtualization Technology）或 AMD-V。

开启后保存重启，再在 Windows 功能里确认“适用于 Linux 的 Windows 子系统”和“虚拟机平台”已勾选。Docker Desktop 现在是基于 WSL2 后端，这两个功能缺一不可。很多人装好了 Docker Desktop 后才发现 WSL2 没更新，需要把内核补丁装上。这些都处理好，Docker Desktop 就能正常启动了。

6.2 OnlyOffice 提示“文档安全令牌的格式不正确”

这个报错出现的位置就是 OnlyOffice 编辑器加载的时候，页面弹出红色提示条，文档无法打开。绝大多数情况下原因是 JWT 密钥不一致。

需要检查三个地方：

1. OnlyOffice 容器环境变量 JWT_SECRET 的实际值，用 docker inspect nextcloud-onlyoffice 查看环境变量。
2. Nextcloud 后台 ONLYOFFICE 设置里的 Secret key。
3. 两边是否都是非空、完全一致的字符串。

如果之前用“Secret key 留空”试过，再开启 JWT 时，需要重新创建 OnlyOffice 容器才能让 JWT 配置生效。不要用 restart，必须用 up -d --force-recreate 让容器按新环境变量重新初始化。

另外，OnlyOffice 新版本调整了 JWT 头部名称和历史默认值。如果你升级过 OnlyOffice 或者 Nextcloud 的 ONLYOFFICE 插件版本，前后版本对 JWT 的处理可能不同。最简单的方法是两边都设置显式的 JWT_SECRET，不要依赖默认值。

6.3 在线编辑保存时提示“文件版本已更改，该页面将被重新加载”

这个问题出在多人同时编辑，或者同一个文件被两边同时修改时。OnlyOffice 检测到服务端文件已经被别人更新，因此停止当前编辑会话，并提示页面即将重新加载。

单用户场景下如果也频繁出现这个提示，多数是“保存回写”链路不稳定。文件在 Nextcloud 端被修改后，OnlyOffice 还在沿用旧版本缓存，导致每次打开都触发冲突检测。常见原因有两个：

• 客户端和服务器系统时间相差过大。JWT 签名依赖时间戳，时间偏差会导致签名有效期判断异常。
• 浏览器缓存了旧的 API.js 和前端资源。可以强制刷新（Ctrl+Shift+R），或者在 OnlyOffice 容器中清理 iframe 缓存。

如果是在局域网内频繁出问题，我建议先检查各设备的时间同步，再确认 OnlyOffice 与 Nextcloud 之间的网络延迟是否过高。编辑保存需要一次完整的请求往返，超过某一阈值后前端会误判超时，进而产生版本冲突。

6.4 MariaDB 连接失败：从“Access denied”到“Table doesn't exist”

连接失败可以分两类看。一类是凭据问题：报 Access denied for user，说明账号密码不对，或者账号只允许特定主机访问。检查 MariaDB 容器内的用户授权：

SELECT User, Host FROM mysql.user;

如果 nextcloud 用户对应的 Host 不是 %，那就要么改授权，要么确保应用从正确的容器网络访问。在 Compose 网络内，应用从 db:3306 连接，目标主机一般是 db 服务的容器名，使用 % 通配最省事。

另一类是跨平台恢复备份后出现的 Table doesn't exist，通常就是我在 3.1 节提到的 lower_case_table_names 配置不一致。数据库备份文件里表名是区分大小写的，从 Windows 恢复回 Linux 时，如果两边大小写策略不同，就会出这种诡异问题。统一设置为 1 后重建数据目录，基本能解决。

6.5 磁盘爆满才发现日志在狂涨

前面提到的日志问题再展开说。Nextcloud 应用自身的日志默认写在 nextcloud/config 目录下，文件数量多了日志会很大。OnlyOffice 容器的日志写在挂载的 onlyoffice/data 目录下，也会持续增长。MariaDB 的日志则通过容器内的轮转机制处理。

我的做法是在宿主机上加日志轮转。用 Docker 原生的 log rotation 可以限制每个容器日志文件的大小和数量，在 /etc/docker/daemon.json 里改：

{ "log-driver": "json-file", "log-opts": { "max-size": "50m", "max-file": "5" } }

改完重启 Docker 服务后，新日志会按此策略轮转。如果磁盘已经满了，先把旧容器日志清理掉、释放空间，再启动容器做后续修复。不要在生产环境直接删容器日志文件指向的 inode，正确做法是 truncate 或关闭容器后清理。

7. 几个容易被忽略但值得留意的配置细节

7.1 反向代理后的客户端 IP 显示异常

如果你不设置 TRUSTED_PROXIES，Nextcloud 后台看到的客户端 IP 会全是 Caddy 容器的 IP（比如 172.18.0.x），日志里的审计信息基本报废。在 app 服务的环境变量里我已经加了 TRUSTED_PROXIES，填写的是 Docker 内部网络网段。注意一点：这个值必须覆盖 Caddy 容器所在的子网，否则无法生效。

如果用的是默认 bridge 网络，子网一般就是 172.16.0.0/12 或者 172.17.0.0/16，视 Docker 版本而定。最稳妥的办法是执行 docker network inspect 查看你自定义网络的子网，然后把对应网段填进 TRUSTED_PROXIES。

还有一个常见关联问题：Nextcloud 检测到“您正在通过反向代理访问，但代理头配置不当”，安装向导会警告,有时甚至间歇性提示“不受信任的域名”。这时需要同步检查 OVERWRITEPROTOCOL 是否设置为 https，以及 nextcloud 配置里的 trusted_domains 是否包含你的域名。这两处设置不完整，即使 HTTPS 证书是有效的，浏览器也可能出现重定向循环。

7.2 Redis 内存缓存：数据量上来后的必备项

Nextcloud 官方推荐在用户量和文件量大时配置 Redis 作为分布式缓存。如果文件操作经常报锁等待超时、或者后台任务（如预览生成、文件扫描）频繁卡住，给 Nextcloud 加 Redis 缓存能明显改善。

这里没有把 Redis 加进主 Compose，因为小规模使用（两三用户、几万文件以内）不配置也能跑。一旦文件数量超过十万，建议在 Compose 里新增 redis 服务，并在 nextcloud 配置里添加：

'memcache.local' => '\OC\Memcache\Redis', 'memcache.distributed' => '\OC\Memcache\Redis', 'memcache.locking' => '\OC\Memcache\Redis', 'redis' => [ 'host' => 'redis', 'port' => 6379, ],

注意这个配置要写在 nextcloud/config/config.php 里，而且要写在安装生成的配置数组里。改了之后重启 app 容器。Redis 容器本身几乎不需要特殊配置，默认监听 6379，只对 compose 网络内的服务开放即可。

7.3 移动端客户端始终连不上：别忘了“覆盖协议”

在浏览器里一切正常，但手机 App 一连接就提示网络错误，很多人会以为是 App 的问题，其实是 App 默认用 https 协议请求，而服务器端认为自己跑在 http 上，于是返回了错误的重定向。

这个问题靠 OVERWRITEPROTOCOL=https 解决。这个环境变量的含义是：告诉 Nextcloud，所有外部分流在到达它之前已经被反代转换成 https，所以它生成链接时要按 https 规则来。不设置这个变量，Nextcloud 生成的下载链接、WebDAV 地址、分享链接都会是 http 开头，移动端会被拒之门外。

7.4 文件权限与挂载目录的属主

挂载目录如果在容器外部创建，宿主机用户与容器内用户（通常 www-data，uid 是 33）会发生权限冲突。表现是容器里报“Permission denied”，或者 Nextcloud 提示数据目录不可写。

我习惯先创建好所有目录，然后统一把属主改成 33：

mkdir -p ~/nextcloud/{db/data,nextcloud/{config,data,apps},caddy,onlyoffice/{data,lib}} chown -R 33:33 ~/nextcloud/nextcloud chown -R 999:999 ~/nextcloud/db

79 是 MySQL/MariaDB 容器内 mysql 用户的 uid（不同镜像可能不同），33 是 www-data 的 uid。设置好属主后再启动容器，可以避免掉很多奇怪的权限报错。

写在最后的一点实操体会

这套方案跑起来之后，我最大的感受是从“天天救火”变成了“几乎忘掉它的存在”。文件同步、在线编辑、HTTPS 证书续期，全部自动运行。唯一需要主动去做的，就是每周瞥一眼备份目录里是不是有新的备份文件产生。

如果你准备照着这套方案动手，我给你的忠告是：不要一上来就追求把所有组件一次配到最完美，先把 Nextcloud + MariaDB 跑通，再逐步加 OnlyOffice、加 HTTPS、加备份策略。每加一层，就验证一层。这个顺序能让你在某一步出问题时，清楚地知道问题出在哪一层，而不是面对四个容器集体报错无从下手。

还有就是别忘了把 .env 文件备份好。容器和数据都可以重建，但数据库密码、JWT 密钥、域名信息一旦丢失，恢复过程会非常痛苦。把 .env 放在一个安全的地方，比如密码管理器或者离线存储里，花不了几分钟，却能省下将来很大一笔时间。

最后再分享一个小技巧：所有关键配置改完之后，执行 docker compose config 检查一下最终渲染出的配置是否符合预期。这个命令不会启动任何容器，却能把环境变量、卷映射、端口冲突这类问题提前暴露出来。我每次改动 Compose 文件后都会习惯性地跑一遍，省掉了不少因为手误导致的启动失败。