From 54783f40687278294474234c62dca7af52f8b5c2 Mon Sep 17 00:00:00 2001 From: zhangxiang Date: Sun, 1 Nov 2026 16:58:33 +0800 Subject: [PATCH] =?UTF-8?q?fix(ops):=20=E7=A3=81=E7=9B=98=E5=86=99?= =?UTF-8?q?=E6=BB=A1=E4=BA=8B=E6=95=85=E6=94=B6=E5=8F=A3=E2=80=94=E2=80=94?= =?UTF-8?q?=E5=A4=87=E4=BB=BD=E9=A2=84=E6=A3=80=E6=8C=89=E6=A8=A1=E5=BC=8F?= =?UTF-8?q?=E5=8F=96=E9=98=88=E5=80=BC=E3=80=81=E6=AE=8B=E6=A1=A3=E5=8D=B3?= =?UTF-8?q?=E5=88=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 生产全站 502 约 5.5 小时、Gitea 500 约 13 小时,根因是 / 写到 100%(20G/20G)。 仓库侧落这四处;另三处守卫在服务器侧脚本(未入仓,已在 runbook §7.3 登记)。 - backup-cicd.sh:预检阈值必须与本轮实际开销绑定。原 .env 把 MIN_FREE_GB 从 3 降到 1, 于是 2GB 可用时放行了一次要写 2.6GB 的全量导出,tar 写到 2.0GB 撞盘。改为含仓库导出时 上调至 BACKUP_FULL_MIN_FREE_GB(默认 4GB),thin 仍按 1GB —— 一并抬高等于又关掉 「唯一副本、不可重建」的那份 DB 备份,是同一个错法的两个方向。 - backup-cicd.sh:归档失败即删残档。半截归档把一次备份失败升级成了全站故障, 且 set -e 让末尾的保留清理从未执行,形成「失败越多越容易满盘」的正反馈。 - backup-cicd.sh:Jenkins 容器缺失时只在预检记录并跳过第 [3/3] 步。原先的 require_container 会让整轮备份(含 Gitea DB dump)在预检阶段就中止。 - nginx-static-production.conf:upstream jenkins_app 后端置 127.0.0.1:1 down。 Jenkins 下线后 `server jenkins:8080` 让 nginx -t 报 host not found, 而修 502 正需要 reload,形成死锁。保留结构以便一行还原。 - runbook §7:复发时的四步判据(盘满时 docker ps 读数不可信)、已落地守卫表、9 项未闭环。 - lessons §5.53:诊断仪器在故障态下自身会失真这一族。§5.52 空号是他人未落库的在途段。 --- docs/development/deploy-runbook.md | 54 ++++++++++++++++++++++++++++++ docs/lessons-learned.md | 50 ++++++++++++++++++++++++++- infra/cicd/backup/backup-cicd.sh | 37 ++++++++++++++++++-- nginx-static-production.conf | 2 +- 4 files changed, 138 insertions(+), 5 deletions(-) diff --git a/docs/development/deploy-runbook.md b/docs/development/deploy-runbook.md index 08a0d2c..d7a0890 100644 --- a/docs/development/deploy-runbook.md +++ b/docs/development/deploy-runbook.md @@ -176,3 +176,57 @@ docker logs --since 10m novalon-website 2>&1 | grep -c '退回代码真源' # 2. 本地 `core.hooksPath` 指向主检出的 `.husky`,那份仍是 644 ⇒ 本机提交不跑 lint-staged (索引里已 100755,克隆/检出即生效)。 3. 视觉基线虽已逐名清单化,但**逐张人工读图追认**仍需决策人分批完成。 + +## 7. 2026-11-01 磁盘写满事故(记录 + 已落地守卫) + +现象:`www.novalon.cn` 全站 502(含 `/api/health`)持续约 5.5 小时;`git.f.novalon.cn` 500、 +开发者 `git fetch` 报 500 持续约 13 小时。根因 `/dev/vda1` 写到 100%(20G/20G,可用 0)。 +机理、证据与教训见 `docs/lessons-learned.md` §5.53,本节只留**操作面**要记得的东西。 + +### 7.1 复发时先跑这四条判据(顺序即诊断顺序) + +```bash +ssh root@139.155.109.62 'df -h / | tail -1' # 1) 盘满? +ssh root@… 'docker ps -a --format "{{.Names}}|{{.Status}}"' # 2) 盘满时此项不可信 +ssh root@… 'docker inspect -f "{{.State.Status}} {{.NetworkSettings.IPAddress}}" novalon-website' # 3) 真实状态与当前 IP +ssh root@… 'docker exec novalon-nginx-secure sh -c "tail -5 /var/log/nginx/error.log"' # 4) 日志里的 upstream IP +``` + +**盘满时 `docker ps` 会报错误状态**(本轮同一容器同时出现 `Exited (0) 6 hours ago` 与 +`Status=running`)。先腾空间,再相信任何 docker 读数。 +若 `nginx error.log` 里的 upstream IP ≠ 第 3 步的当前 IP,则是 nginx 缓存旧地址, +`docker exec novalon-nginx-secure nginx -s reload` 即恢复(应用侧无需重启)。 + +### 7.2 已落地守卫 + +| 位置 | 守卫 | 验证读数 | +|---|---|---| +| `scripts/docker-cleanup.sh`(服务器侧,**未入仓**) | 容器/镜像/网络清理改为逐个判定 + 保护名单(`postgresql gitea novalon-website novalon-nginx-secure novavis-authority`);删掉 blanket `image prune -a` | 实跑后容器/镜像/网络三项 diff 全空;`alpine:latest` 在「引用容器 0 个」下仍保留 | +| `/usr/local/bin/container-monitor.sh`(每 5 分钟) | 新增 `check_nginx_upstream_drift`:容器 IP 变化时先 `nginx -t` 再 reload | 伪造 `172.20.0.99 → 172.20.0.3` 触发,日志 `WARN…准备 reload` + `OK nginx 已 reload`,站点仍 200 | +| `infra/cicd/backup/backup-cicd.sh` | ① Jenkins 容器缺失时**只在预检记一条并跳过第 [3/3] 步**,不再 `require_container` 拦掉整轮;② 归档失败即删残档;③ 预检阈值按 thin/full 分别取(含仓库导出时上调至 `BACKUP_FULL_MIN_FREE_GB`,默认 4GB) | `--skip-repos` 真实跑 EXIT=0、`gzip -t` 独立通过、保留清理正常执行;`--dry-run` 两模式分别显示阈值 1GB / 4GB | +| `nginx-static-production.conf` + 仓库同名文件 | `upstream jenkins_app` 后端置 `127.0.0.1:1 down`(保留结构,Jenkins 回归时一行还原) | 仓库与生产 md5 一致 `1bf99ea4…`;`ci.f.novalon.cn` 按预期不再可用 | + +服务器侧改动均留了带时间戳的备份:`nginx-static-production.conf.bak.20261101_1635`、 +`backup-cicd.sh.bak.20261101_1650`、`container-monitor.sh.bak.20261101_1650`。 + +### 7.3 未闭环(需决策人输入,不是工程侧能自决的) + +1. **`ALERT_WEBHOOK_URL` 三处全空**(`infra/cicd/.env`、`container-monitor.sh` 的 `ALERT_WEBHOOK=""`)。 + 告警函数都在,但空值使其成为 no-op ⇒ 磁盘阈值告警连续 13 小时无人收到。 + **需要一个企业微信/钉钉 webhook 地址**才能闭环,代理侧不能编造。 +2. **备份仍是同盘**:`.env` 里 `RCLONE_REMOTE=` 空,脚本自己每次都在打 + 「未配置 RCLONE_REMOTE —— 同盘备份不抗主机故障」。周日全量单份 ~2.0–2.6GB,而整机盘只有 20GB, + 这是本次事故的算术来源。需要决策:裸库全量 offload 到对象存储,或接受「周日不做含仓库全量」并另设异地副本。 +3. **`docker-cleanup.sh` / `disk-monitor.sh` / `container-monitor.sh` 三个运维脚本未入仓** + (只在服务器上),本轮改动无法评审、也无法回滚到仓库版本。建议纳入 `infra/cicd/` 或 `scripts/ops/`。 +4. **保留清理在 `backup-cicd.sh` 末尾** ⇒ 峰值占用 = 旧全量 + 新全量。本轮用阈值兜住,未重构脚本分段。 +5. **`container-monitor.sh` 的容器清单基本是虚构的**:`woodpecker-server`、`woodpecker-agent`、 + `novalon-nginx`、`forgejo`、`registry` 均不存在(真实名 `novalon-nginx-secure`、`gitea`、 + `novavis-authority`)。本轮**未改清单**——它会对清单内容器执行 `docker restart`,而 + `novavis-authority` 属另一项目,不应由本仓擅自纳管。需领域主确认后再补。 +6. **nginx upstream 仍是加载期一次性解析**(本轮靠 5 分钟巡检兜)。根治是 `resolver 127.0.0.11 valid=10s` + + 变量形式 `proxy_pass`,但变量形式会改变 URI 传递语义,需逐个 `location` 复核后单独一轮做。 +7. `docs/PRODUCTION_DEPLOYMENT_LIGHTWEIGHT.md:141` 记载的健康检查 `/api/health` **在当前代码里不存在** + (`src/app/api/` 只有 `admin auth cms contact`)。本轮实测该路径 404 是既有状态、非事故造成;文档需修正口径。 +8. §6.1 说「CI 在 Jenkinsfile 单独阶段跑」在 Jenkins 下线后已不成立(且 2026-10-20 实测该任务从未被触发)。 +9. `novavis-authority` 处于 `unhealthy`(Java/reactor-netty 连接报错),属另一项目,本仓未代改。 diff --git a/docs/lessons-learned.md b/docs/lessons-learned.md index 8c28f1a..0d86f1e 100644 --- a/docs/lessons-learned.md +++ b/docs/lessons-learned.md @@ -969,4 +969,52 @@ expected 是已显影正文 ⇒ 内容停在 `opacity:0` 初始态,而不是 同高空白带 = 装配竞态,用状态判据修;不等高且内容换了一套 = 先证伪自己的机理解释, 再决定是数据侧还是环境侧。判据实验是「隔离复跑 N 次是否稳定 + 页高是否一致 + 解释能否被代码读回」,而不是「换一种并发就绿了」。动基线之前这几步都要跑完, -否则会把竞态或一次偶发固化成参照。 \ No newline at end of file +否则会把竞态或一次偶发固化成参照。 +### 5.53 磁盘写满时 dockerd 自己的读数会撒谎;nginx 缓存的 upstream IP 是第二个故障点(2026-11-01) + +生产全站 502 的一轮排查,根因是 `/` 写到 100%(20G/20G),但真正拖长时间的是**诊断仪器在故障态下不可信**: + +1. **ENOSPC 会让 `docker ps` 给出错误状态。** 同一容器同时出现 `docker ps -a` 报 `Exited (0) 6 hours ago` + 与 `docker inspect` 报 `Status=running`;腾出 791MB 后读数才收敛为 `Up 6 hours (healthy)`。 + 更硬的证据是 `docker exec` 自己失败:`write /tmp/runc-process…: no space left on device`—— + **这条信息本身就是磁盘读数**,不必另跑 `df` 才知道盘满了。 + ⇒ 判「容器挂了」之前先 `df`,并用容器内部探针(`docker exec … wget -qO- 127.0.0.1:3000/`)交叉验证。 + 我第一版汇报据此写下「容器退出导致 502」,是错的,见本节第 2 条。 + +2. **nginx 在加载配置时把 upstream 主机名解析一次并缓存。** 应用 10:50 重启后 IP 从 `172.20.0.7` 变 + `172.20.0.3`,nginx 仍连旧地址 ⇒ 症状是「容器 healthy、内部 200、外部 502」, + 错误日志形如 `connect() failed (113: Host is unreachable) … upstream: "http://172.20.0.7:3000/"`。 + ⇒ 诊断钥匙是**把日志里的 upstream IP 与 `docker inspect` 当前 IP 并排比**;`nginx -s reload` 即可刷新。 + 本轮补了巡检里的 IP 漂移守卫(≤5min 自愈,实测能识别伪造漂移并先 `nginx -t` 再 reload), + 根治方案 `resolver 127.0.0.11` + 变量 `proxy_pass` **未做**(变量形式会改变 URI 传递语义,不在热修里动),登记在 runbook §6。 + +3. **无白名单的 `docker container prune -f` 删掉的是编排对象,不是状态。** 周日 03:00 的清理把「已停止」的 + `postgresql`(Gitea 唯一数据源的宿主容器)删除,而没有任何东西会重建它 ⇒ Gitea 全站 500、 + `git fetch` 报 500,持续 13 小时。同族第二处:`image prune -a --filter until=168h` 删掉 `alpine`, + 而备份脚本归档仓库时要 `docker run alpine tar`,于是每晚重新 pull。 + ⇒ **清理类 cron 的危险在于它在磁盘压力下最容易被触发,而那时恰恰是最不该删的时候。** + +4. **告警代码存在 ≠ 告警在响,要读变量值而不是函数体。** `backup-cicd.sh` 与 `healthcheck-cicd.sh` 都写了 + `alert()`,但 `.env` 里 `ALERT_WEBHOOK_URL=` 为空,`[[ -z "$URL" ]] && return 0` 于是把两套告警同时静默关闭; + `disk-monitor.sh` 每小时都在报警,通知那行仍是注释。磁盘阈值告警连续 13 小时无人收到。 + 同一处还有第二个脱钩:`BACKUP_MIN_FREE_GB=1` 把脚本默认的 3GB 预检降到 1GB, + 于是 2GB 可用时放行了一次要写 2.6GB 的全量导出。 + ⇒ 门禁的阈值必须与**本轮实际开销**绑定(已改为按 thin/full 分别取门槛), + 常数调大也不行——把 thin 一起拦掉等于又关掉「唯一副本、不可重建」的那份 DB 备份。 + +5. **半截归档是「失败」里最贵的一种,且失败会自我放大。** 归档失败只 `fail` 不删残档, + 2.0GB 的半截 `gitea-repos-*.tar.gz` 留在盘上把盘写死;`set -e` 又让末尾的保留清理从未执行, + 于是「失败越多 → 清理越不跑 → 越容易满盘」是正反馈。 + ⇒ 失败路径要**回滚自己产生的副作用**(残档即删)。另注:保留清理放在脚本末尾使峰值 = 旧全量 + 新全量, + 本轮没重构(改生产备份脚本的分段结构风险大于收益),改用按模式上调预检阈值兜住,登记在 runbook §6。 + +6. **批准一个「移除」动作时,要一起盘出依赖它的门禁与编排。** 批准移除 Jenkins 后,三个下游同时坏: + 备份预检 `require_container "$JENKINS_CONTAINER"` 让整轮备份(含 Gitea DB)在预检阶段中止; + nginx `upstream jenkins_app { server jenkins:8080; }` 让 `nginx -t` 报 `host not found in upstream` + 从而**无法 reload**(而当时正需要 reload 来修 502);第 [3/3] 步 `--volumes-from jenkins` 每晚必失败。 + ⇒ 删除类决定落地前,先 `grep` 出引用该对象的所有门禁、健康检查与配置解析点。 + +7. **「文档说保留 N 份」不等于盘上只有 N 份,也不等于那文件能用。** 10-20 同一天留下 4 份 + `dist_backup_*`(runbook 只要求 3 份);而今天的「全量备份」经 `gzip -t` 实测 + `unexpected end of file`,是坏档——它却被保留策略判定为一份合法全量, + 制造「仓库已受保护」的假象。⇒ 判断备份可用性只能靠**校验命令的退出码**,不能靠文件存在与目录命名。 diff --git a/infra/cicd/backup/backup-cicd.sh b/infra/cicd/backup/backup-cicd.sh index 7031958..34444ab 100755 --- a/infra/cicd/backup/backup-cicd.sh +++ b/infra/cicd/backup/backup-cicd.sh @@ -126,6 +126,17 @@ command -v docker >/dev/null || fail "docker 不可用" FREE_GB=$(df -P "$BACKUP_ROOT" 2>/dev/null | awk 'NR==2{print int($4/1048576)}' \ || df -P / | awk 'NR==2{print int($4/1048576)}') + +# 预检阈值必须按「本轮要写多大」取,而不是一个常数: +# 2026-11-01 事故 —— .env 把 MIN_FREE_GB 降为 1,周日全量在 2GB 可用时通过预检, +# 然后 tar 写到 2.0GB 撞盘并留下半截归档,nginx 与站点连带挂掉。 +# 反之若把常数一律抬到 4GB,周中只写 ~8MB 的薄备份会被拦掉 —— 那等于又关掉一次 +# 「唯一副本、不可重建」的 DB 备份。两种错法是同一个:门槛与开销脱钩。 +if (( JENKINS_ONLY == 0 && SKIP_REPOS == 0 )); then + FULL_MIN="${BACKUP_FULL_MIN_FREE_GB:-4}" + if (( MIN_FREE_GB < FULL_MIN )); then MIN_FREE_GB=$FULL_MIN; fi + log "本轮含仓库导出(实测裸库约 2.6G),预检阈值上调至 ${MIN_FREE_GB}GB" +fi log "备份卷可用空间: ${FREE_GB}GB(阈值 ${MIN_FREE_GB}GB)" if (( FREE_GB < MIN_FREE_GB )); then fail "可用空间 ${FREE_GB}GB < 阈值 ${MIN_FREE_GB}GB,中止备份以免写满磁盘。请清理或扩容。" @@ -135,7 +146,16 @@ if (( JENKINS_ONLY == 0 )); then require_container "$PG_CONTAINER" require_container "$GITEA_CONTAINER" fi -require_container "$JENKINS_CONTAINER" +# Jenkins 容器缺失时只跳过第 [3/3] 步,不得拦掉整轮备份。 +# 2026-11-01 事故:Jenkins 下线后,这里的硬预检会让 Gitea DB(唯一副本、不可重建) +# 每晚在预检阶段就中止 —— 被关掉的是最不能丢的那份备份。 +JENKINS_PRESENT=0 +if docker inspect "$JENKINS_CONTAINER" >/dev/null 2>&1; then + require_container "$JENKINS_CONTAINER" + JENKINS_PRESENT=1 +else + log "⏭ Jenkins 容器不存在(2026-11-01 起下线),跳过其配置备份;Gitea DB 与仓库导出不受影响" +fi if (( DRY_RUN == 1 )); then log "dry-run:预检全部通过,未产出备份。" @@ -169,12 +189,18 @@ if (( JENKINS_ONLY == 0 )); then # 全量:仓库 + LFS + 附件 + 头像 docker run --rm --volumes-from "$GITEA_CONTAINER" -v "$STAMP_DIR:/out" alpine \ tar czf "/out/$(basename "$REPO_TAR")" -C /data git 2>/dev/null \ - || fail "Gitea 全量归档失败" + || { rm -f "$REPO_TAR"; fail "Gitea 全量归档失败(残档已删除,避免半截归档继续占盘)"; } else # 标准:仅裸库(LFS/附件可从对象存储或后续补,磁盘优先) docker run --rm --volumes-from "$GITEA_CONTAINER" -v "$STAMP_DIR:/out" alpine \ sh -c 'tar czf /out/'"$(basename "$REPO_TAR")"' -C /data git/repositories' \ - || fail "Gitea 仓库归档失败" + || { rm -f "$REPO_TAR"; fail "Gitea 仓库归档失败(残档已删除,避免半截归档继续占盘)"; } + # 校验必须在删除之前显式做:fail() 内部是 `exit 1` 而非 return, + # 写成 `verify_archive ... || rm -f ...` 会因 exit 直接离开脚本而成死代码。 + if ! tar -tzf "$REPO_TAR" >/dev/null 2>&1; then + rm -f "$REPO_TAR" + fail "Gitea 仓库归档损坏(tar 校验失败,残档已删除)" + fi verify_archive "$REPO_TAR" tar fi fi @@ -184,6 +210,8 @@ fi # !关键:排除 builds/ workspace/ caches/ logs —— 这些占空间且可从作业定义重建 # !但必须包含 credentials.xml 与 secrets/(否则恢复后凭据全丢) # ============================================================ +# 守卫:Jenkins 下线后容器不存在,整段跳过(不重新缩进这段以保持 diff 面) +if (( JENKINS_PRESENT == 1 )); then log "----- [3/3] Jenkins 配置薄备份 -----" JENKINS_TAR="$STAMP_DIR/jenkins-config-$TS.tar.gz" # 归档整个 JENKINS_HOME 并排除可重建项,不再写死具体路径 @@ -248,6 +276,9 @@ if grep -qE '(^|/)(secrets/master\.key|secret\.key)$' <<< "$J_LIST"; then else fail "归档缺少 master key(secrets/master.key 或 secret.key)—— 恢复后所有 Jenkins 凭据将不可解密" fi +else + log "⏭ 已跳过 [3/3] Jenkins 配置备份:容器不存在(2026-11-01 下线)" +fi # 生成清单 cat > "$STAMP_DIR/MANIFEST.txt" <