From fb9dbcb11a730a7a937928f63c5d2a53d3363787 Mon Sep 17 00:00:00 2001 From: Nexus Agent Date: Sat, 6 Jun 2026 23:23:27 +0800 Subject: [PATCH] =?UTF-8?q?docs(deploy):=20=E5=90=8C=E6=AD=A5=201Panel=20?= =?UTF-8?q?=E8=BF=90=E7=BB=B4=20SSOT=EF=BC=88round4=E2=80=938=20=E8=83=BD?= =?UTF-8?q?=E5=8A=9B=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README 与知识文档补全 nx cron/备份/验收；卸载脚本提示改为 1Panel 容器名。 Co-authored-by: Cursor --- deploy/README-1panel.md | 55 ++++++++++++-- deploy/uninstall-mysql-compose.sh | 2 +- deploy/uninstall-redis-compose.sh | 8 +-- ...06-06-nx-god-menu-audit-round9-ops-docs.md | 26 +++++++ .../nexus-1panel-operations-knowledge.md | 72 +++++++++++++++---- 5 files changed, 135 insertions(+), 28 deletions(-) create mode 100644 docs/changelog/2026-06-06-nx-god-menu-audit-round9-ops-docs.md diff --git a/deploy/README-1panel.md b/deploy/README-1panel.md index 2bd8c3ab..98642763 100644 --- a/deploy/README-1panel.md +++ b/deploy/README-1panel.md @@ -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 diff --git a/deploy/uninstall-mysql-compose.sh b/deploy/uninstall-mysql-compose.sh index a80da45f..1d05d88f 100755 --- a/deploy/uninstall-mysql-compose.sh +++ b/deploy/uninstall-mysql-compose.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" diff --git a/deploy/uninstall-redis-compose.sh b/deploy/uninstall-redis-compose.sh index 44eda6f4..e39957f4 100755 --- a/deploy/uninstall-redis-compose.sh +++ b/deploy/uninstall-redis-compose.sh @@ -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" diff --git a/docs/changelog/2026-06-06-nx-god-menu-audit-round9-ops-docs.md b/docs/changelog/2026-06-06-nx-god-menu-audit-round9-ops-docs.md new file mode 100644 index 00000000..1af02b96 --- /dev/null +++ b/docs/changelog/2026-06-06-nx-god-menu-audit-round9-ops-docs.md @@ -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 +``` diff --git a/docs/project/nexus-1panel-operations-knowledge.md b/docs/project/nexus-1panel-operations-knowledge.md index b9a37d6f..7b53cc07 100644 --- a/docs/project/nexus-1panel-operations-knowledge.md +++ b/docs/project/nexus-1panel-operations-knowledge.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`、镜像特性检查 | ---