docs(deploy): 同步 1Panel 运维 SSOT（round4–8 能力）

README 与知识文档补全 nx cron/备份/验收；卸载脚本提示改为 1Panel 容器名。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-06 23:23:27 +08:00
parent 72e46cef32
commit fb9dbcb11a
5 changed files with 135 additions and 28 deletions
@@ -13,6 +13,10 @@
 | `nexus-1panel.sh` | 底层 install / upgrade | `bash deploy/nexus-1panel.sh upgrade` |
 | `fix-1panel-mysql-grant.sh` | 修复 1045 nexus@Docker | `bash deploy/fix-1panel-mysql-grant.sh` |
 | `test-1panel-redis.sh` | Redis 认证诊断 | `REDIS_PASS='...' bash deploy/test-1panel-redis.sh` |
+| `verify-1panel-install-wizard.sh` | 一键验收（网络/cron/镜像） | `bash deploy/verify-1panel-install-wizard.sh` |
+| `install_ops_cron.sh` | 宿主机 cron（巡检+备份） | `sudo bash deploy/install_ops_cron.sh` |
+| `mysql_dump_to_file.sh` | MySQL 备份（Docker exec） | 见 `db_backup.sh` / `nx` 菜单 `[9]` |
+| `upgrade.sh` | 自动识别 Docker/Supervisor | `bash deploy/upgrade.sh` |
 | **`nx`** | **统一运维菜单** | `nx` |

 档位：`--profile 1c4g` · `2c8g`（默认）· `4c16g`
@@ -87,13 +91,47 @@ nexus-fresh     # 等同 install-nexus-fresh.sh
 nexus-install   # 等同 quick-install.sh
 ```

-| 菜单 | 功能 |
-|------|------|
+| 菜单 / 子命令 | 功能 |
+|---------------|------|
 | `[1]` | 安装向导（档位 / 迁机 / skip-clone） |
 | `[2]` | 全新安装 → `/app/install.html` |
-| `[4]` | **一键更新** |
-| `[5]` | 重启 Nexus |
+| `[3]` | 状态 + `/health` + install.html 归档检查 |
+| `[4]` / `nx update` | **一键更新**（备份 + 重建镜像 + 升级后验收） |
+| `[5]` | 重启 Nexus 容器 |
 | `[6]` | 日志 |
+| `[7]` | 启动 / 停止 Compose 栈 |
+| `[8]` | 无缓存重建镜像 |
+| `[9]` | 立即备份 MySQL |
+| `[e]` / `nx cron` | 安装 health_monitor + db_backup crontab |
+| `[v]` / `nx verify` | 运行 `verify-1panel-install-wizard.sh` |
+
+---
+
+## 三层守护（1Panel Docker）
+
+| 层 | 机制 | 说明 |
+|----|------|------|
+| Layer 1 | Compose `restart` + 容器 `healthcheck` | 容器崩溃自动拉起 |
+| Layer 2 | Python `self_monitor`（30s） | Redis/MySQL/WebSocket 自检 |
+| Layer 3 | 宿主机 `health_monitor.sh`（cron） | `/health` 连续失败 → `docker restart` + 可选 Telegram |
+
+Layer 3 需**在宿主机**安装（容器内无法写 crontab）：
+
+```bash
+sudo nx cron
+# 或
+sudo bash /opt/nexus/deploy/install_ops_cron.sh
+```
+
+MySQL 定时备份：每日 03:00 → `/var/backups/nexus/`（`docker exec` 进 1Panel MySQL 容器 dump，**无需**宿主机 `mysqldump`）。
+
+---
+
+## 安装完成后
+
+- 向导锁定后 `install.html` → **`install.html.bak`**，外网 `/app/install.html` 返回 **404**（正常）
+- 登录：`https://你的域名/app/`
+- 验收：`sudo nx verify`

 ---

@@ -190,13 +228,16 @@ MySQL 密码在 1Panel 自建库时设定，向导步骤 3 填写。

 ## 安装向导验收（服务器执行）

-在 **1Panel 终端**（root）一键检查网络、容器名预填、本地 `/health` 与 `/api/install/env-check`：
+在 **1Panel 终端**（root）一键检查网络、容器名预填、cron、镜像版本、本地 `/health`：

 ```bash
-cd /opt/nexus && bash deploy/verify-1panel-install-wizard.sh
+cd /opt/nexus && sudo nx verify
 ```

-通过后再浏览器打开 `https://你的域名/app/install.html`。常见修复：
+**未安装**：通过后再打开 `https://你的域名/app/install.html`。  
+**已安装**：`install.html` 应 HTTP 404；验收检查 crontab、`mysql_dump_to_file.sh`、容器内 round6/7 代码特性。
+
+常见修复：

 ```bash
 cd /opt/nexus && bash deploy/detect-1panel-services.sh
@@ -118,4 +118,4 @@ echo ""
 info "当前 Nexus 栈:"
 docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}' | grep -i nexus || docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
 echo ""
-info "下一步：自建 MySQL 数据库与用户，安装向导步骤 3 使用 host.docker.internal:3306"
+info "下一步：1Panel 应用商店安装 MySQL → nx update 探测容器名 → 向导步骤 3 使用 1Panel-mysql-xxxx"
@@ -109,8 +109,6 @@ else
 fi

 echo ""
-info "下一步：在宿主机或 1Panel 安装 Redis，确认监听 6379："
-echo "  apt install -y redis-server && systemctl enable --now redis-server"
-echo "  redis-cli ping   # 期望 PONG"
-echo ""
-info "Docker 内 Nexus 连接宿主机 Redis：安装向导 / .env 使用 host.docker.internal:6379"
+info "下一步：1Panel 应用商店安装 Redis → nx update 写入 NEXUS_1PANEL_REDIS_HOST"
+echo "  向导 Redis URL：redis://:密码@1Panel-redis-xxxx:6379/0（无 root 用户）"
+echo "  诊断：bash deploy/test-1panel-redis.sh"
@@ -0,0 +1,26 @@
+# nx 上帝菜单巡检第九轮 — 1Panel 运维文档同步
+
+| 项 | 内容 |
+|----|------|
+| 日期 | 2026-06-06 |
+| 动机 | round4–8 新增备份/cron/验收/镜像检查等内容未写入 SSOT；卸载脚本仍提示 host.docker.internal |
+
+## 变更摘要
+
+1. **deploy/README-1panel.md**：补全 nx 菜单 `[e][v][9]`、三层守护、install.html 归档、新脚本速查。
+2. **nexus-1panel-operations-knowledge.md**：升级流程、§5.2 守护与备份、§7.6–7.7、验收清单、提交索引 round4–8。
+3. **uninstall-mysql/redis-compose.sh**：收尾提示改为 1Panel 容器名路径。
+
+## 涉及文件
+
+- `deploy/README-1panel.md`
+- `docs/project/nexus-1panel-operations-knowledge.md`
+- `deploy/uninstall-mysql-compose.sh`
+- `deploy/uninstall-redis-compose.sh`
+
+## 验证
+
+```bash
+bash -n deploy/uninstall-mysql-compose.sh deploy/uninstall-redis-compose.sh
+grep -E 'nx cron|mysql_dump|install.html.bak' deploy/README-1panel.md
+```
@@ -2,7 +2,7 @@

 | 项 | 内容 |
 |----|------|
-| 版本 | 2026-06-06 |
+| 版本 | 2026-06-06（round9 同步 god-menu 巡检 round4–8） |
 | 读者 | 运维、接续开发、AI Agent |
 | 定位 | **1Panel 生产部署 SSOT**（安装向导、网络、MySQL/Redis、日常 nx update） |
 | 关联 | [deploy/README-1panel.md](../../deploy/README-1panel.md) · [nexus-functional-development-guide.md](nexus-functional-development-guide.md) · [2026-06-04-1panel-docker-production.md](../design/plans/2026-06-04-1panel-docker-production.md) |
@@ -89,6 +89,10 @@ install --fresh
 步骤 4 create-admin
  → 写 admins，自动 lock（.install_locked）

+步骤 5 lock / entrypoint
+  → install.html 重命名为 install.html.bak（外网 /app/install.html → 404）
+  → 安装锁双写：/app/.install_locked + /var/lib/nexus/.install_locked
+
 entrypoint EXIT trap
  → /app/.env 复制到 nexus-state
 ```
@@ -224,19 +228,22 @@ cd /opt/nexus && bash deploy/install-nexus-fresh.sh --skip-clone
 | `nx update` | `deploy/update.sh` → `nexus-1panel.sh upgrade` |
 | `nexus-update` | 同上 |

-**upgrade 顺序**（2026-06-06+）：
+**upgrade 顺序**（2026-06-06 god-menu round4–8+）：

 ```
-git fetch → MySQL 备份（失败默认 WARN）→ git reset --hard
-→ sync_1panel_service_hosts → sync_env_prod_to_volume
+git fetch → MySQL 备份（mysql_dump_to_file.sh：docker exec 1Panel MySQL）→ git reset --hard
+→ sync_1panel_service_hosts → sync_env_prod_to_volume → NEXUS_HOST_ROOT 写入 .env.prod
 → tag 当前镜像为 nexus-prod-nexus:rollback
 → compose build → 镜像门控 (import server.main)
-→ compose up -d --no-build
-→（仅 install.html 非 200 时）sync-install-wizard-to-container.sh
-→ set_install_complete → verify_health（端口 NEXUS_PUBLISH_PORT）
+→ compose up -d --no-build → verify_nexus_1panel_network
+→ 已锁定：跳过 install.html 热同步；未锁定且非 200 才 sync-install-wizard
+→ set_install_complete → verify_health
+→ TTY：prompt_ops_cron_if_missing；已锁定：verify-1panel-install-wizard.sh
 → 健康失败：自动 tag rollback + up -d 回滚
 ```

+`deploy/upgrade.sh`、`deploy-production.sh` 等会自动识别 **Docker vs Supervisor**，Docker 路径委托 `nexus-1panel.sh upgrade`。
+
 | 参数 | 含义 |
 |------|------|
 | `--check` | 仅查 Git |
@@ -257,6 +264,25 @@ git fetch → MySQL 备份（失败默认 WARN）→ git reset --hard

 Redis 容器改名时，`resolve_nexus_redis_url` 会尝试将旧 URL 中的密码迁移到新 host。

+### 5.2 三层守护与宿主机 cron
+
+| 层 | Docker 1Panel | 裸机 Supervisor |
+|----|---------------|-----------------|
+| L1 | Compose `restart` + healthcheck | Supervisor `autorestart` |
+| L2 | `self_monitor`（30s） | 同左 |
+| L3 | **宿主机** `health_monitor.sh`（cron） | 同左 |
+
+安装向导步骤 5（Docker）会提示在宿主机执行 `sudo nx cron`；`nx update` 结束时 TTY 下可交互安装。
+
+| 脚本 | 用途 |
+|------|------|
+| `install_ops_cron.sh` | 幂等写入 health_monitor（每分钟）+ db_backup（03:00） |
+| `health_monitor.sh` | Layer 3：3 次 `/health` 失败 → `docker restart` + Telegram |
+| `db_backup.sh` | 调用 `mysql_dump_to_file.sh`，保留 30 天 |
+| `mysql_dump_to_file.sh` | `docker exec` MySQL 容器 → 宿主机 mysqldump → 临时 mysql:8 客户端 |
+
+备份目录默认 `/var/backups/nexus/`。菜单 `nx` → `[9]` 手动备份；`[e]` / `nx cron` 安装定时任务。
+
 ---

 ## 6. 脚本速查
@@ -264,13 +290,16 @@ Redis 容器改名时，`resolve_nexus_redis_url` 会尝试将旧 URL 中的密
 | 脚本 | 用途 |
 |------|------|
 | [deploy/README-1panel.md](../../deploy/README-1panel.md) | 速查表 |
-| `verify-1panel-install-wizard.sh` | 服务器一键验收 |
+| `verify-1panel-install-wizard.sh` | 服务器一键验收（含 cron、镜像特性） |
 | `detect-1panel-services.sh` | 输出 `NEXUS_1PANEL_*_HOST` |
+| `detect_deploy_runtime.sh` | Docker / Supervisor 运行时检测 |
 | `fix-1panel-mysql-grant.sh` | 修复 MySQL 1045（`nexus@'%'`） |
 | `test-1panel-redis.sh` | **Redis 多格式认证诊断** |
-| `sync-install-wizard-to-container.sh` | 热同步 `install.html` + `install.py` |
+| `sync-install-wizard-to-container.sh` | 热同步（**已归档时早退**） |
 | `uninstall-mysql-compose.sh` | 清理旧内置 MySQL 栈 |

+`nx` 子命令：`update` · `verify` · `cron` · `health` · `install-fresh`
+
 ---

 ## 7. 故障排查决策树
@@ -351,19 +380,27 @@ nx update --no-cache
 - `curl -s http://127.0.0.1:8600/health` → `ok`  
 - `curl -sk https://域名/health` → 应 `ok`

-### 7.6 install.html 非 200
+### 7.6 install.html 非 200 / 已归档 404
+
+| 状态 | 期望 | 处理 |
+|------|------|------|
+| 安装中 | HTTP 200 | `sync-install-wizard-to-container.sh` 或 `nx update` |
+| **已锁定** | HTTP **404** | 正常；容器内仅 `install.html.bak` |

 ```bash
-bash deploy/sync-install-wizard-to-container.sh
-# 或 nx update --no-cache
+sudo nx verify   # 已安装时应 PASS「install.html 已归档 → HTTP 404」
 ```

+### 7.7 升级前 MySQL 备份被跳过
+
+旧版因宿主机无 `mysqldump` 且 URL host 为容器名而跳过。现用 `mysql_dump_to_file.sh`（`docker exec` 1Panel MySQL）。手动：`sudo bash /opt/nexus/deploy/db_backup.sh`。
+
 ---

 ## 8. 验收清单

 ```bash
-cd /opt/nexus && bash deploy/verify-1panel-install-wizard.sh
+cd /opt/nexus && sudo nx verify
 ```

 关键 `[PASS]`：
@@ -371,8 +408,9 @@ cd /opt/nexus && bash deploy/verify-1panel-install-wizard.sh
 - Git ≥ `b25d079`（1Panel sync）  
 - `NEXUS_1PANEL_DB_HOST` / `NEXUS_1PANEL_REDIS_HOST`  
 - Nexus 在 `1panel-network`  
- `/app/.env` 不存在（安装模式）或连接检测全绿  
- `env-check` 的 `docker_defaults.db_host` 为 `1Panel-mysql-*`
+- **已安装**：`install.html` → 404；Crontab 含 health_monitor + db_backup  
+- **已安装**：容器 `install.py` 含 `host_deploy_root`；`NEXUS_HOST_ROOT=/opt/nexus`  
+- **安装中**：`/app/.env` 不存在；`env-check` 的 `docker_defaults.db_host` 为 `1Panel-mysql-*`

 浏览器：步骤 3 **先检测** → 初始化 → 步骤 4 创建 admin → `/app/` 登录。

@@ -387,6 +425,10 @@ cd /opt/nexus && bash deploy/verify-1panel-install-wizard.sh
 | `da061d3` | 步骤 3 `test-credentials` 门禁 |
 | `807f4c2` | Redis URL `redis://:pass@` 修复（曾误加 root，已废弃） |
 | `3b2856f+` | 自动解析 `:pass@` / `default`；步骤 4 connection-check 可自愈 `.env` |
+| `4e1347b`–`ba69bc3` | Docker MySQL 备份、`install_ops_cron.sh`、`nx cron` |
+| `89865ec` | `upgrade.sh` / `deploy-production.sh` Docker·Supervisor 分流 |
+| `c9e0879`–`e5d4822` | 守护配置 `host_deploy_root`、向导 Layer 3 cron UI |
+| `72e46ce` | 升级后自动验收、`nx verify`、镜像特性检查 |

 ---