企业官网建设流程全解析

自建网盘这件事，我折腾过很多轮。最早是把一台闲置小主机扔在角落，装个现成的网盘面板，结果一次意外断电之后，三块盘里的索引全乱了，恢复花了两天。后来换成 Linux 上用 Docker 跑 Nextcloud，再配上域名和证书，把入口统一收拢，才算真正稳定下来。这套组合的核心价值在于：数据在自己手里，客户端体验又接近商业网盘，手机、平板、公司电脑同时挂上去，出差在外打开浏览器就能取文件。适合的人群很明确——手上有云服务器或者愿意买一台的、有一点 Linux 命令行基础、对资料私密性和长期可维护性有要求的人。下面我按自己实际落地的顺序，把每一步的选择理由、配置细节和踩过的坑完整写一遍，配置可以直接抄，但理由最好也看一眼，因为环境一换，参数就得跟着调。

1. 先把账算清楚：为什么这套组合是"云盘自建"里最省心的

动手之前我习惯先把需求和代价算明白，不然装到一半发现方案不对，返工的成本比重新规划高得多。很多人一上来就问"哪个网盘程序最好"，其实这个问题问错了方向，真正决定成败的是运行环境、数据落盘方式和访问入口这三件事，程序本身反而排在后面。

1.1 需求拆解：我要的其实不是"网盘"，是"可随时拿回的数据"

把需求摊开看，其实就四条：文件要能多端同步、要能生成分享链接给外部的人看、要能在线预览常见的图片文档、要能在任何有网络的地方打开。前三条属于应用层能力，Nextcloud 基本都覆盖了，包括日历、通讯录、在线协作文档这些附加模块。第四条才是真正的分水岭——它决定了你必须有公网可达的入口，而不是一个只能在家里局域网访问的玩具。

我见过太多人把服务装好、局域网内测通了，就以为完事了，结果出门用 4G 打开链接一片空白。原因很简单：家庭宽带的地址通常是运营商动态分配的，而且很多地区根本不给固定公网地址，你在外面根本找不到家里那台机器。所以从第一天起，我就把"公网入口"当成一个必须先解决的前置条件，而不是装完再想的补丁。

这里我的选择是直接用一台带固定公网地址的云服务器来承载服务。代价是每月一笔固定开销和有限的磁盘容量，收益是省掉了所有网络层的折腾——域名解析过去就能通，安全组放行端口就行，不用去研究任何复杂的中转方案。如果你的资料量很大，可以用云服务器跑应用、把大容量存储挂在独立的数据盘或者对象存储上，这个后面会讲。

至于"要不要在家里放一台机器"，我的建议是：除非你确认自己的宽带能拿到固定公网地址并且愿意做端口映射，否则别折腾。稳定性、功耗、断电保护、硬盘故障率，每一项都是隐性成本。

1.2 Docker 与 Nextcloud 各自的边界在哪里

Nextcloud 本质是一个 PHP 应用，依赖 Web 服务器（Apache 或 Nginx）、PHP 运行时、数据库、缓存服务。传统装法是手动装 LAMP 再解压源码，这条路我走过，问题在于版本耦合极强——PHP 从 8.1 升到 8.2，某个扩展没跟上，整个站点就 500。而且升级 Nextcloud 主版本时，还要处理文件权限、数据目录迁移、数据库 schema 变更，手工操作出错概率很高。

Docker 在这里解决的是"环境一致性"问题。官方镜像把 Apache、PHP 扩展、必要的依赖全部打包好，你只需要关心三件事：数据往哪儿挂、数据库连哪个、对外暴露什么端口。升级的时候换一个镜像标签，跑一次内置的升级命令，剩下的它自己处理。

但 Docker 不是银弹，它带来的新问题是：数据持久化必须显式声明，否则容器一删数据全没；容器之间的网络要显式打通；日志默认在容器里，不做配置会无限增长把磁盘撑爆。这几点在后面配置章节里我都会具体处理。

1.3 公网可达这件事，只有两条合规路径

说清楚这点很重要，因为它直接决定了后面的架构。想让外面的设备访问到你的网盘，本质上只有两种方式。

第一种是有公网地址的入口：你的服务所在主机本身就有一个外部可以直接访问的地址，配合域名解析和端口放行，直接就能通。这是最干净的做法，配置量最小，延迟最低，出问题也最好排查——网络不通就是安全组没放行或者防火墙拦了，一查一个准。我推荐的云服务器方案就属于这一类。

第二种是借道中转：服务在私有网络里，通过某个中间的转发节点把外部请求送进来。这种方式在家庭宽带场景下很常见，但会引入额外的故障点——中间节点挂了、转发通道断了、延迟抖动了，你根本没法从服务端看到问题，排查成本陡增。

我的实际选择是第一种，并且只做第一种。理由很朴素：自建网盘的核心诉求是"长期可维护"，我不想在半夜发现同步失败时，还要去猜是应用挂了还是中转通道挂了。所以后文所有配置都建立在"服务器有固定公网地址"这个前提上。

2. 落地前的底座准备：磁盘、系统与 Docker 运行时

服务器买回来第一件事不是装 Docker，而是把底座规划好。这一步偷懒，后面数据量上来会非常难受。

2.1 服务器规格与磁盘布局的取舍

配置上，2 核 4G 是 Nextcloud 单用户到小团队的舒适起点。低于 2G 内存会很难受，因为 PHP-FPM 加上数据库和缓存，峰值很容易把内存吃满，然后触发系统的内存回收机制，表现为网页偶尔卡住几秒。磁盘方面，系统盘 40G 足够跑应用，数据一定要单独挂一块数据盘——这不是洁癖，是运维现实：系统重装、镜像升级、误操作，都不会波及数据盘，你只要重新挂载就能原地复活。

数据盘的挂载我一般这么处理：

# 确认新盘设备名，通常是 vdb 或 nvme1n1 lsblk # 格式化（仅在盘是全新时执行一次，已有数据千万不要跑） mkfs.ext4 /dev/vdb # 建挂载点并挂载 mkdir -p /data mount /dev/vdb /data # 写入开机自动挂载，防止重启后失效 echo "UUID=$(blkid -s UUID -o value /dev/vdb) /data ext4 defaults,noatime 0 2" >> /etc/fstab # 验证 fstab 写得对不对，这一步绝不能省 mount -a && df -h | grep /data

noatime这个选项值得加上，它让系统不去记录文件的最后访问时间。网盘场景下文件读取非常频繁，关掉这个记录能减少不少无谓的磁盘写入，对寿命和性能都有好处。

提示：写fstab之后务必执行mount -a验证。我见过写完直接重启、结果因为一个空格错误导致系统进不了紧急模式的案例，那台机器在机房，处理起来相当麻烦。

2.2 系统层最小化配置（时区、swap、防火墙）

时区不对会导致日志时间错乱，排查问题时对不上是件很折磨的事。顺手把时间同步也确认一遍：

timedatectl set-timezone Asia/Shanghai timedatectl set-ntp true timedatectl status

swap 的取舍有点争议。小内存机器上开 2G 的 swap 能防住 OOM Killer 突然把数据库杀掉，代价是极端情况下的卡顿。我的做法是开 2G 并调低使用倾向：

fallocate -l 2G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile echo '/swapfile none swap sw 0 0' >> /etc/fstab sysctl -w vm.swappiness=10 echo 'vm.swappiness=10' >> /etc/sysctl.conf

防火墙这块，我倾向于分两层理解：云服务商侧的安全组负责"谁能从外面进来"，系统侧的防火墙负责"进来之后能碰哪些端口"。两层都配，只放行 SSH 的 22 和 Web 的 80、443。数据库端口、Redis 端口、应用容器的 8080 端口，一律不对公网暴露，全部只在容器内部或者本机回环地址上监听。这个原则后面在 compose 里会具体体现——端口映射写成127.0.0.1:8080:80而不是8080:80，一字之差，安全性差一个量级。

# 以 Ubuntu 的 ufw 为例 ufw default deny incoming ufw default allow outgoing ufw allow 22/tcp ufw allow 80/tcp ufw allow 443/tcp ufw enable ufw status verbose

2.3 Docker 与 Compose 的安装与国内环境注意点

Docker 我用官方脚本装，比追发行版仓库的版本更可控：

curl -fsSL https://get.docker.com | sh systemctl enable --now docker docker version docker compose version

现在 compose 已经作为 docker 的插件存在，命令是docker compose（中间有空格），不是老的docker-compose。网上很多老教程还在用带横杠的写法，照抄会报命令找不到。

如果你的服务器拉镜像速度很慢，需要配置镜像加速地址，具体地址请以你所使用的云服务商文档为准。配置后重启服务：

mkdir -p /etc/docker cat > /etc/docker/daemon.json <<'EOF' { "log-driver": "json-file", "log-opts": { "max-size": "20m", "max-file": "3" }, "data-root": "/data/docker" } EOF systemctl restart docker

># /opt/nextcloud/.env MYSQL_ROOT_PASSWORD=换成你自己的强密码 MYSQL_PASSWORD=换成你自己的强密码 REDIS_PASSWORD=换成你自己的强密码 DOMAIN=cloud.example.com

3.2 卷挂载策略：为什么我只挂一个目录

这是我在踩过坑之后做的决定。很多教程会分别挂载config、apps、data三个子目录，看起来更"模块化"，但实际操作中很容易出问题：官方镜像在首次启动时会做一次初始化，把版本文件铺到/var/www/html，如果这个目录被一个空的具名卷或者空目录覆盖，初始化逻辑就可能被跳过或者执行不完整，表现是访问首页出现 404 或者 Apache 的默认页。

我的做法是整体挂载/var/www/html到宿主机的./nextcloud，初始化、升级、文件同步全部由镜像自己处理，只在备份的时候按需取config和data两个子目录。简单，可控，升级不出幺蛾子。

完整的 compose 文件：

services: db: image: mariadb:10.11 restart: unless-stopped command: --transaction-isolation=READ-COMMITTED --binlog-format=ROW volumes: - ./db:/var/lib/mysql environment: - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD} - MYSQL_PASSWORD=${MYSQL_PASSWORD} - MYSQL_DATABASE=nextcloud - MYSQL_USER=nextcloud healthcheck: test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"] interval: 10s timeout: 5s retries: 12 redis: image: redis:7-alpine restart: unless-stopped command: redis-server --requirepass ${REDIS_PASSWORD} --maxmemory 256mb --maxmemory-policy allkeys-lru volumes: - ./redis:/data app: image: nextcloud:29.0.4-apache restart: unless-stopped depends_on: db: condition: service_healthy ports: - "127.0.0.1:8080:80" volumes: - ./nextcloud:/var/www/html environment: - MYSQL_HOST=db - MYSQL_DATABASE=nextcloud - MYSQL_USER=nextcloud - MYSQL_PASSWORD=${MYSQL_PASSWORD} - REDIS_HOST=redis - REDIS_HOST_PASSWORD=${REDIS_PASSWORD} - NEXTCLOUD_TRUSTED_DOMAINS=${DOMAIN} 127.0.0.1 - PHP_MEMORY_LIMIT=512M - PHP_UPLOAD_LIMIT=10G - APACHE_DISABLE_REWRITE_IP=1 - TRUSTED_PROXIES=172.16.0.0/12

逐条说几个容易被抄错的地方：

command里的READ-COMMITTED和ROW不是可选项。Nextcloud 官方明确要求这个隔离级别，用默认的可重复读在某些并发场景下会产生死锁，表现是页面偶发 500，日志里是数据库死锁相关的内容。

healthcheck配合depends_on的condition: service_healthy，解决的是"数据库还没起来应用就急着连"的经典竞态。没有这个配置，首次启动大概率失败一次，需要手动重启容器。

镜像标签不要写latest。我固定到具体的小版本号，升级时手动改标签，这样每次升级都是可控动作，而不是某天重启之后突然发现界面变样、插件不兼容。

TRUSTED_PROXIES只在容器前面还有一层入口转发时才需要，用来告诉 Nextcloud 信任哪个网段传来的来源信息。Docker 默认网段在172.16.0.0/12里面，所以填这个。如果你直接用 8080 端口对外，就不需要它。

3.3 首次启动与 Web 安装向导里的三个关键选择

cd /opt/nextcloud docker compose up -d docker compose logs -f app

看到 Apache 的启动日志稳定下来，浏览器访问http://服务器地址:8080（暂时用端口直连做初始化，等证书配好再切域名）。

第一次进安装向导要填数据库信息，注意数据库主机填db（服务名），不是localhost，也不是127.0.0.1。这是新手最容易填错的一项，填错会报"无法连接数据库"。

数据目录保持默认/var/www/html/data，因为我们整体挂载了/var/www/html，它已经在持久化目录里了。如果你把数据目录指到别处，一定要确保那个路径也被挂载且权限正确，否则容器重建时数据就丢了。

管理员账号建议单独建一个，不要用admin这种常见名字。这一步做完，Nextcloud 的核心就跑起来了，剩下的都是优化和加固。

4. 让域名真正公网可达：Nginx 入口层与证书签发

到这一步服务已经能用，但只能通过 IP 加端口访问，而且没有 HTTPS。浏览器会提示不安全，很多客户端同步功能在非加密连接下会被限制。所以入口层必须补齐。

4.1 域名解析与安全组的最小放行原则

去域名服务商那里加一条 A 记录，把cloud.example.com指向服务器公网地址。解析生效一般几分钟，用dig验证：

dig +short cloud.example.com

输出的地址和你的服务器一致，就可以继续了。云服务商的安全组里，确认 80 和 443 对0.0.0.0/0放行，22 端口最好限制为你自己的常用出口地址段，不要对全网开放。8080 端口绝对不能出现在安全组里——我们希望它只在服务器本机回环上监听，由 Nginx 在中间做转发。

这里解释一下为什么不直接让容器的 80 端口对外。容器里的 Apache 处理静态文件和 PHP 够用，但它在 TLS 配置、大文件传输缓冲、限流、访问日志分析这些方面的能力远不如 Nginx。而且把证书放在宿主机上统一管理，比塞进容器里、每次升级镜像都要重新处理要干净得多。

4.2 Nginx 配置逐段拆解

先装 Nginx：

apt install -y nginx systemctl enable --now nginx

新建站点配置/etc/nginx/sites-available/nextcloud.conf：

server { listen 80; listen [::]:80; server_name cloud.example.com; location /.well-known/acme-challenge/ { root /var/www/certbot; } location / { return 301 https://$host$request_uri; } } server { listen 443 ssl; listen [::]:443 ssl; http2 on; 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_prefer_server_ciphers off; add_header Strict-Transport-Security "max-age=15552000" always; add_header X-Content-Type-Options nosniff always; add_header X-Frame-Options SAMEORIGIN always; client_max_body_size 10G; client_body_timeout 600s; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; 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_request_buffering off; proxy_max_temp_file_size 0; proxy_read_timeout 600s; proxy_send_timeout 600s; proxy_connect_timeout 60s; } location /.well-known/carddav { return 301 /remote.php/dav; } location /.well-known/caldav { return 301 /remote.php/dav; } }

几个参数的作用值得展开。client_max_body_size 10G决定了单次请求能被接收的最大体积，默认只有 1M，不改成 10G 的话，上传稍大的文件会直接返回 413，而这个错误在 Nextcloud 界面上表现为"上传失败"，不提示原因，很容易误判成应用问题。

proxy_request_buffering off是做流式上传用的。默认情况下 Nginx 会把整个请求体先收完再转发给后端，传一个 5G 的文件意味着要先占 5G 的临时空间。关掉之后请求边收边转，磁盘压力小很多，断点续传体验也更好。

X-Forwarded-Proto $scheme这一行是让后端知道"用户实际是用 HTTPS 访问的"。少了它，Nextcloud 会认为自己在 HTTP 下运行，生成的内部链接全是 http 开头，页面就会出现混合内容告警，甚至导致重定向循环。

别忘了把配置链接到启用目录并做语法检查：

ln -s /etc/nginx/sites-available/nextcloud.conf /etc/nginx/sites-enabled/ nginx -t && systemctl reload nginx

4.3 证书签发与自动续期

第一次签证书时 Nginx 还没有证书文件，443 配置会报错，所以先只启用 80 的健壮配置，或者用 certbot 的独立模式。我习惯用 webroot 方式，因为它不影响已经跑着的服务：

apt install -y certbot mkdir -p /var/www/certbot certbot certonly --webroot -w /var/www/certbot -d cloud.example.com --email you@example.com --agree-tos --no-eff-email

签发成功后证书在/etc/letsencrypt/live/cloud.example.com/，这时候再把 443 段启用，nginx -t检查后 reload。

自动续期用系统自带的定时任务最省事：

systemctl list-timers | grep certbot # 确认有 certbot.timer 在跑

大多数发行版安装 certbot 时会自动生成续期任务。再补一个续期后重载 Nginx 的钩子，避免新证书生效了但 Nginx 还在用旧的：

echo 'deploy-hook = systemctl reload nginx' >> /etc/letsencrypt/cli.ini

验证一下续期逻辑能跑通（只做演练，不会真的消耗配额）：

certbot renew --dry-run

4.4 混合内容与重定向循环的根因

配置完之后最常见的两个症状，我把根因列一下。

症状一：页面能打开，但样式加载失败，控制台一片混合内容告警。根因是 Nextcloud 不知道自己跑在 HTTPS 后面。解决方式是显式告诉它：在config/config.php里加overwriteprotocol => 'https'，或者去管理后台的"概览"页看有没有相关提示，通常那里会直接给出需要补的配置项。改完docker compose restart app生效。

症状二：浏览器报重定向次数过多。一般是 80 和 443 两段配置互相跳，或者X-Forwarded-Proto没传对导致后端不停地把请求踢回 HTTPS。排查方法是看 Nginx 的访问日志：

tail -f /var/log/nginx/access.log

如果看到同一个请求在短时间内在 301 和 200 之间反复，基本就能定位到是哪一段配置在作怪。

另外，务必确认域名已经写进NEXTCLOUD_TRUSTED_DOMAINS。如果访问时提示"通过未受信任的域名访问"，就是这一项漏了，改环境变量后重建容器即可。

5. 打开之后才发现慢：性能调优与大文件上传

服务能访问之后，接下来就是让它好用。默认配置跑起来不报错，但会一直在后台管理界面挂着几条黄色警告，而且体验上确实能感觉到迟滞。

5.1 内存缓存与文件锁：APCu 与 Redis 的配合

Nextcloud 有两类缓存，用途不同。本地缓存用在单机进程内，把一些热点数据放在共享内存里；分布式缓存和文件锁用在多进程、多容器场景，必须放到 Redis 上。两者都要配，缺一个就会出现性能问题或者锁冲突。

编辑config/config.php，在数组里加：

'memcache.local' => '\OC\Memcache\APCu', 'memcache.distributed' => '\OC\Memcache\Redis', 'memcache.locking' => '\OC\Memcache\Redis', 'redis' => [ 'host' => 'redis', 'port' => 6379, 'password' => '你的Redis密码', 'timeout' => 0.0, ],

APCu 在命令行下默认是关闭的，这会导致occ命令运行时告警，或者修饰符缓存失效。容器里可以通过增加一个 PHP 配置来开启：

cat > /opt/nextcloud/nextcloud/config/apcu.ini <<'EOF' apc.enable_cli=1 apc.shm_size=128M EOF

改完之后docker compose restart app。回头去看后台的"概览"页面，关于内存缓存的警告应该消失了。这一步的收益不是玄学——页面首屏的响应时间在低配机器上通常能降一到两成。

5.2 后台任务从 AJAX 切到 Cron

默认的后台任务是 AJAX 模式，靠用户访问页面时顺带触发。问题很明显：没人访问的时候任务就不跑，文件扫描、预览生成、垃圾回收全部滞后，时间长了会拖慢整个系统。

Cron 模式需要容器内有定时任务在跑。官方镜像已经内置了调度支持，通过环境变量或者单独的服务来驱动。我的做法是在宿主机上配一个系统级的定时任务，每 5 分钟调一次容器内的命令：

cat > /etc/cron.d/nextcloud <<'EOF' */5 * * * * root docker exec -u www-data nextcloud-app php -f /var/www/html/cron.php EOF chmod 644 /etc/cron.d/nextcloud

之前用docker compose起服务，容器名默认是目录名-app-1这种格式，容易和这行命令对不上。稳妥的做法是在 compose 里给容器加个固定的container_name: nextcloud-app，这样定时任务永远不会因为目录改名而失效。

配完去后台"基本设置"里把后台任务方式切到"定时任务（Cron）"，那个警告才会消失。

5.3 大文件上传的三处限制

传大文件失败是我被问得最多的一个问题。它涉及三个不同的限制点，逐个排查才不会漏。

注意PHP_UPLOAD_LIMIT是官方镜像提供的便捷变量，它会同时设置upload_max_filesize和post_max_size，比自己进去改 php.ini 干净得多。如果你用的是第三方镜像或者自定义 Dockerfile，就得手动处理这两个值，而且必须保证post_max_size不小于upload_max_filesize，否则上传会静默失败。

还有一点常被忽略：前端的分片上传依赖服务器的超时设置。10G 的文件即使带宽理想也要传很久，client_body_timeout和proxy_read_timeout都要相应放大，否则传到一半连接被掐，界面上显示的是"上传失败"，实际是超时断开。

6. 长期运行的底气：备份、升级与故障定位链路

装好只是开始，能不能安心用三年，取决于备份是否可恢复、升级是否可控、出问题能不能快速定位。

6.1 一份能真正恢复的备份长什么样

很多人备份只拷数据目录，这是不够的。真正的完整备份包含三份东西：数据库导出、应用的config目录、data目录。少了数据库，文件虽然在，但用户、分享链接、版本历史全丢了，等于要从零重建索引。

为了保证备份的一致性，导数据前先进入维护模式，让所有写入停止：

docker exec -u www-data nextcloud-app php occ maintenance:mode --on TS=$(date +%F-%H%M) mkdir -p /data/backup/$TS docker exec db sh -c 'exec mysqldump --single-transaction -u root -p"$MYSQL_ROOT_PASSWORD" nextcloud' > /data/backup/$TS/nextcloud.sql tar -czf /data/backup/$TS/config.tar.gz -C /opt/nextcloud/nextcloud config rsync -a --delete /opt/nextcloud/nextcloud/data/ /data/backup/$TS/data/ docker exec -u www-data nextcloud-app php occ maintenance:mode --off

--single-transaction让导出在一个事务里完成，不会因为并发写入产生不一致的快照。数据目录用rsync而不是打包，是因为数据量上去之后，每天打一个完整 tar 包的速度和磁盘占用都不可接受，rsync只传差异部分，几分钟就能跑完。

提示：备份文件存在同一台服务器上等于没备份。务必定期同步到另一台机器或者独立的存储空间。我一般是本地留 7 天，远端留 30 天。

恢复的时候流程反过来：先停容器，把data和config放回原位，导入数据库，再启动。有条件的话，每季度真正演练一次恢复，比什么备份策略都让人安心。

6.2 小版本与大版本升级的两种节奏

升级我分两种情况处理。小版本更新（比如 29.0.3 到 29.0.4）风险很低，直接改 compose 里的标签，然后：

cd /opt/nextcloud docker compose pull app docker compose up -d app

容器起来之后跑一次数据库结构检查，把新增的索引补齐：

docker exec -u www-data nextcloud-app php occ upgrade docker exec -u www-data nextcloud-app php occ db:add-missing-indices docker exec -u www-data nextcloud-app php occ maintenance:repair

大版本跨越（比如 28 到 29）就必须按流程走：先做完整备份，再进入维护模式，再换镜像，再跑升级，最后关维护模式。Nextcloud 的大版本升级只允许逐级进行，不能跳版本，这个限制在官方文档里写得很清楚。跳了会出现数据库 schema 无法匹配的情况，恢复起来很痛苦。

升级过程中如果卡住，看日志：

docker compose logs -f --tail=100 app

大部分升级失败的原因集中在文件权限或者应用兼容性上。权限问题可以通过chown -R www-data:www-data解决；应用兼容性问题则需要禁用那个应用再重试升级。

6.3 故障复现：一次 502 与一次登录后白屏的完整排查

502 Bad Gateway。那天早上打开页面直接报 502。排查顺序是：先看 Nginx 的错误日志tail -50 /var/log/nginx/error.log，内容是连接 127.0.0.1:8080 被拒绝。这说明容器没在监听。接着docker compose ps一看，app容器状态是Restarting，说明它在反复崩溃重启。

再docker compose logs --tail=200 app，日志末尾是 PHP 内存耗尽。原因是前一晚有人批量上传了几千张照片，缩略图生成把内存打满了。临时抬高内存上限先恢复服务，把PHP_MEMORY_LIMIT从 512M 调到 1G，重启后恢复正常。长期方案是限制预览图生成的并发数，或者把预览生成挪到夜间执行。这类问题的关键经验是：看到 502 不要先去改 Nginx 配置，先确认后端进程是不是活着。

登录后白屏。输完账号密码之后页面一片空白，浏览器控制台没有明显报错，Network 里那个请求返回 200 但内容为空。这种最难受，因为什么都没告诉你。

我的排查路径是先确认日志位置：

docker exec -u www-data nextcloud-app tail -50 /var/www/html/data/nextcloud.log

nextcloud.log是应用自己的日志，比容器的标准输出详细得多。那次里头是一行关于某个第三方应用的类找不到的错误。原因是我在升级主版本时，那个应用没有同步更新，和新内核不兼容。

处理方法是在命令行禁用这个应用：

docker exec -u www-data nextcloud-app php occ app:list docker exec -u www-data nextcloud-app php occ app:disable 应用名

禁用之后页面立刻恢复。之后再去找该应用的新版本重新启用。这件事给我的教训是：大版本升级前，一定要先确认所有已安装的第三方应用都支持新版本，否则升级完就是一地鸡毛。

排查这类问题，我总结出一条固定顺序：先看容器状态，再看应用日志，最后才怀疑配置。顺序反了，会在配置文件里绕很久却找不到真正的原因。

还有一个容易被忽略的小细节：服务器的系统时间一定要准确同步。证书校验、客户端同步的时间戳判断、日志的时间线对照，全都依赖系统时间。我遇到过一次时间漂移了十几分钟的情况，表现是部分客户端同步时报"服务器时间不正确"，查了半天应用配置，最后timedatectl一看就明白了。

整套配置跑下来，从裸机到域名能访问，熟练的话两三个小时。真正花时间的是后面这几个月的观察和微调——什么时候该清预览图、备份任务要不要错峰、磁盘用到多少该扩容。这些没有标准答案，得看自己的使用节奏。我从一开始每天盯着看，到现在一个月不看也不慌，中间靠的就是这套配置加上几次真实的故障排查积累下来的判断力。