Skip to content

U
ubains-module-test
提交 39c373d2 authored 作者: 陈泽健's avatar 陈泽健
浏览文件
操作

docs(远程自动化部署): HANDOFF 会话交接（会话2-6）+ PRD 文档更新 

- 自动化部署脚本 HANDOFF：追加会话2（auto_clean V4）/会话4（nginx修复+业务验证）/会话5（业务验证必须执行标注）/会话6（PVE 快照恢复流程落地）
- 远程自动化部署 HANDOFF 新建 + PRD 需求文档/计划执行文档更新（部署授权闭环记录）
- X86架构_部署包目录结构解析_20260907：部署包目录映射表（组件升级依据）
Co-Authored-By: 's avatarClaude <noreply@anthropic.com>
上级 7e0021d6
显示空白字符变更
内嵌 并排
正在显示 包含 744 行增加 和 3 行删除
Docs/PRD/自动化部署脚本/HANDOFF_自动化部署脚本会话交接.md
浏览文件 @ 39c373d2
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
> **生成时间**：2026-09-01 > **生成时间**：2026-09-01
> **会话主题**：新统一平台 ujava2-startup.sh 定时脚本 flock 死锁导致日志停止排查与修复 > **会话主题**：新统一平台 ujava2-startup.sh 定时脚本 flock 死锁导致日志停止排查与修复
> **最近更新**：2026-09-01（首次创建，记录 ujava2 脚本死锁修复闭环：服务器脚本 3 处修复 + 死锁释放 + cron 自动恢复验证 + 问题处理/计划执行双文档） > **最近更新**：2026-09-09（追加会话6：PVE 快照恢复流程落地——恢复自动化部署服务器初始化状态）
--- ---
...@@ -117,3 +117,368 @@ cron 日志 → 无 tee: '' 报错 ...@@ -117,3 +117,368 @@ cron 日志 → 无 tee: '' 报错
> - **待对齐**：服务器与仓库脚本剩余差异（`RETRY_INTERVAL` 20/30、`stop_service` kill 逻辑）为旧版既有配置差异，非本次问题范围，建议后续部署流程统一 > - **待对齐**：服务器与仓库脚本剩余差异（`RETRY_INTERVAL` 20/30、`stop_service` kill 逻辑）为旧版既有配置差异，非本次问题范围，建议后续部署流程统一
> >
> 后续如需继续自动化部署相关工作，先 `Read` 本交接文档与本目录下的 PRD 问题处理文档；排查定时脚本日志停止优先看 cron 日志与锁文件持有者（`fuser -v`），踩坑警示 #1-#4 务必遵守。 > 后续如需继续自动化部署相关工作，先 `Read` 本交接文档与本目录下的 PRD 问题处理文档；排查定时脚本日志停止优先看 cron 日志与锁文件持有者（`fuser -v`），踩坑警示 #1-#4 务必遵守。
---
---
# 会话2（2026-09-08）— auto_clean_deleted_ubains V3→V4 修复落地
> **生成时间**：2026-09-08
> **会话主题**：auto_clean_deleted_ubains 脚本升级 V4.0——仓库 source of truth 同步 + 缺陷修正 + 计划执行文档输出
---
## 任务概述
2026-09-08 凌晨 04:00 发生容器重启风暴：定时脚本 `auto_clean_deleted_ubains_v3.sh` 无差别整体重启 ujava2 容器（meeting2.0、auth、gateway、quartz、mqtt、system、message 共 7 个服务陪葬，meeting2.0 日志中断约 2 分钟），并与 ujava2-startup.sh 相互打架（一个杀、一个拉）。事故当天服务器端已完成 v4 修复部署与验证（PRD 记录）。本会话目标：**将 V3→V4 修复落地到本地仓库 source of truth，并输出计划执行文档**。
---
## 已完成事项
| # | 产出项 | 位置/路径 | 说明 |
|---|--------|-----------|------|
| 1 | v4 脚本入库 | `自动化部署脚本/x86架构/新统一平台/定时脚本/auto_clean_deleted_ubains_v4.sh` | 从 `E:\github\ubains-module-test\Test\` 本地留档同步（服务器已验证版本），`bash -n` 通过（SYNTAX_OK）；v3 原样保留作回滚备份 |
| 2 | **V4 缺陷复核与修正** ⭐ | 同上（修正版已回写 Test 留档） | `get_container_of_pid` 原在**杀进程之后**调用，而 `/proc/<pid>/cgroup` 在进程死后即消失 → 容器归属永远返回空 → 兜底分支（truncate 失败→杀进程）永不重启容器。修正：归属读取上移至循环内 `proc_cwd` 读取之后（杀进程之前），杀进程后直接用已取得的 `container` 变量 |
| 3 | v4 逻辑说明文档 | `自动化部署脚本/x86架构/新统一平台/定时脚本/auto_clean_deleted_ubains_v4_logic.md` | 按仓库惯例新增：整体流程/三级处置策略/V3→V4 变更对照/容器归属判断（含杀前读取警告）/配置参数/注意事项 |
| 4 | README 总览更新 | `自动化部署脚本/x86架构/新统一平台/定时脚本/README_定时脚本总览.md` | 4 处：磁盘清理类表格（v4 当前/v3 停用）、架构图（truncate 零中断）、cron 示例（`0 4 v3` → `20 4 v4`）、风险点汇总（clean 脚本已有 flock） |
| 5 | 计划执行文档 | `Docs/PRD/自动化部署脚本/新统一平台/问题处理/auto_clean_deleted_ubains脚本修复方案与目的_计划执行.md` | 问题分析（V3 五缺陷）/修复方案（三级递进处置 + 变更对照 + 3.4 缺陷修正记录）/实施清单/验证结果/风险评估与回滚/后续工作/优化功能回填（部署入口 auto_crontab_settings.sh 调整为同日后续会话3，见文末） |
---
## 当前阻塞项
| 类型 | 描述 | 原因 |
|------|------|------|
| 待办 | 服务器端 v4 尚未合入 `get_container_of_pid` 调用时机修正（2 行变更） | 服务器 `/opt/scripts/auto_clean_deleted_ubains_v4.sh` 是修正前版本；正常路径（truncate）不受影响，仅兜底分支失效，触发概率极低 |
| 待办 | 本次变更未提交 git | 涉及 6 个文件（见下一步 #3），待用户确认提交；会话3 追加的 auto_crontab_settings.sh 一并提交 |
| 时间 | 首夜定时执行核对需等 2026-09-09 早上 | v4 首次 cron 触发在 04:20 |
仓库侧修复本身已闭环，无技术/信息/决策阻塞。
---
## 下一步计划
| # | 步骤 | 预期结果 |
|---|------|----------|
| 1 | 服务器 nat.ubainsyun.com:18126 同步 3.4 修正：备份 `/opt/scripts/auto_clean_deleted_ubains_v4.sh` → 将 `container=$(get_container_of_pid "$pid")` 上移至循环内 `proc_cwd` 读取之后 → `bash -n` → `DRY_RUN=1` 试跑 | 服务器兜底分支恢复容器归属识别能力，与仓库版本一致 |
| 2 | 2026-09-09 早上首夜人工核对（计划执行文档 5.2） | ① `/var/log/scripts/auto_clean_deleted_ubains.log` 显示 truncate 或"未发现"、无容器重启；② `docker ps` ujava2 Up > 1 天；③ meeting2.0 日志 03:50–04:30 无中断 |
| 3 | 逐文件 `git add` + commit（勿用 `git add .`）：v4.sh、v4_logic.md、README 总览、PRD 修复方案文档、计划执行文档、本 HANDOFF（auto_crontab_settings.sh 由会话3 产出，一并纳入提交） | 修复落地完整入库 develop 分支 |
| 4 | （后续/治本，PRD 第 9 节）排查 deleted 文件删除者、日志清理脚本对占用文件改删为清空、run.sh 统一 `>>` 追加 | deleted 文件不再产生或产生即被清空，v4 杀进程/重启逻辑进入长期休眠 |
---
## ⚠️ 踩坑警示 — 绝对不要再踩
1. ❌ **不要用 `sed -i <(crontab -l) \| crontab -` 管道直灌修改 crontab** — 本次实施事故（PRD 第 6 节如实记录）：sed 对进程替换文件编辑失败后，管道另一端 `crontab -` 读到空输入，**root crontab 被短暂清空约 1 分钟**（幸有 3 分钟前备份完整恢复）。修改 crontab 必须走"**备份 → 临时文件 sed → 装载 → 逐行核对**"流程。
2. ❌ **`/proc/<pid>/` 下的信息（cgroup/cwd/fd）必须在进程存活时读取** — 本次复核发现的 V4 缺陷：杀进程后再读 `/proc/<pid>/cgroup` 必然失败（目录已消失）。凡"杀进程后按归属处置"的逻辑，归属判断一律前移到 kill 之前（与 V3"先读 cwd 再杀防 PID 回收"同一原则）。
3. ❌ **同步留档/已验证脚本入库时必须逐行复核，不能默认无缺陷** — 本次 Test 留档的 v4 已在服务器验证通过，但仍存在兜底分支逻辑缺陷。**正常路径验证通过 ≠ 全部分支正确**；低频兜底分支的缺陷会被高成功率掩盖，恰恰在真正需要它的时候失效。
---
## 附录：关键文件/资源链接（会话2）
| 资源类型 | 位置 | 备注 |
|----------|------|------|
| PRD 修复方案 | `Docs/PRD/自动化部署脚本/新统一平台/问题处理/auto_clean_deleted_ubains脚本修复方案与目的.md` | 事故还原/V3 缺陷/V4 设计/服务器实施记录/验证结果/回滚方案 |
| 计划执行文档 | `Docs/PRD/自动化部署脚本/新统一平台/问题处理/auto_clean_deleted_ubains脚本修复方案与目的_计划执行.md` | 本会话产出，含 3.4 缺陷修正详情与 7.1 服务器同步待办 |
| 仓库脚本（source of truth） | `自动化部署脚本/x86架构/新统一平台/定时脚本/auto_clean_deleted_ubains_v4.sh` | 已含 get_container_of_pid 修正，`bash -n` 通过 |
| 本地留档（已同步修正版） | `E:\github\ubains-module-test\Test\auto_clean_deleted_ubains_v4.sh` | 与仓库保持一致 |
| 服务器部署脚本 | nat.ubainsyun.com:18126 `/opt/scripts/auto_clean_deleted_ubains_v4.sh` | **待同步 3.4 修正**；v3 及 crontab 备份在 `/root/*.bak.20260908` |
| 服务器执行日志 | nat.ubainsyun.com:18126 `/var/log/scripts/auto_clean_deleted_ubains.log` | 首夜核对项（2026-09-09 早上） |
| crontab 现状 | 服务器 `20 4 * * * /opt/scripts/auto_clean_deleted_ubains_v4.sh` | 已于 2026-09-08 切换生效 |
---
## 给接手者的话（会话2）
> **2026-09-08 会话**：auto_clean_deleted_ubains 重启风暴事故已修复落地：
>
> - **根因**：V3.2 脚本"杀进程 + 无差别重启 ujava2"，任何进程（含无关 tail）的 deleted 大文件都触发整容器重启；`NEED_RESTART` 标记粗粒度导致无辜服务陪葬
> - **V4 方案**：truncate 原地清空优先（服务零中断）→ 杀进程仅作 truncate 失败兜底 → 按 cgroup 只重启实际所属容器；flock 互斥 + DRY_RUN 灰度 + cron 错峰 04:20
> - **服务器端**：已于 2026-09-08 14:00–14:15 实施并验证通过（truncate 229MB/3.5MB 实测生效、cron 仅 1 行变更、ujava2 未被重启）
> - **仓库端（本会话）**：v4 入库 + 修正 `get_container_of_pid` 杀后调用缺陷 + logic 文档 + README 同步 + 计划执行文档
> - **同日后续**：部署入口 auto_crontab_settings.sh 同步调整（任务定义 v4 + 升级逻辑增强）见文末 **会话3**
> - **待办**：服务器同步 2 行修正（下一步 #1）→ 09-09 首夜核对（#2）→ 逐文件 git 提交（#3）
>
> 接手后先 `Read` 计划执行文档（含全部上下文与命令）；服务器操作走 paramiko 密码认证；改动 crontab 务必遵守踩坑警示 #1 流程。
---
---
# 会话3（2026-09-08）— auto_clean_deleted_ubains 部署入口 auto_crontab_settings.sh 同步调整
> **生成时间**：2026-09-08
> **会话主题**：部署入口 auto_crontab_settings.sh 的 auto_clean 任务同步到 v4，并增强 crontab 条目升级/清理逻辑
---
## 任务概述
会话2 落地 v4 脚本后复查发现：4 个主部署脚本（new_auto / new_auto_meeting / new_auto_monitor / new_auto_voice）source 的 crontab 注册唯一入口 `auto_crontab_settings.sh` 仍指向 v3 + `0 4 * * *`——新部署服务器会继续装上"重启风暴"脚本，与服务器已切换的 v4 配置脱节。经用户确认采用"**定义调整 + 升级逻辑增强**"方案（而非仅改任务定义），本会话完成 3 处代码变更 + 全量文档同步。
---
## 已完成事项
| # | 产出项 | 位置/路径 | 说明 |
|---|--------|-----------|------|
| 1 | 变更1：auto_clean 任务定义 v3→v4 | `自动化部署脚本/x86架构/新统一平台/auto_crontab_settings.sh` | `TASK_CRON[auto_clean]`：`0 4 * * *` → `20 4 * * *`（错峰 ujava2-startup.sh 整点轮询）；`TASK_SCRIPT[auto_clean]`：v3 → v4 路径；`TASK_LOG[auto_clean]` 保持空（v4 自管日志） |
| 2 | 变更2：`_add_single_cron_job` 条目自动升级 ⭐ | 同上 | 原"marker 存在即跳过"存在升级盲区：存量服务器已有 v3 条目时永不更新。增强为**条目内容比对**——`grep -A1` 取 marker 后任务行，与期望 `script_path` 比对：一致→跳过；不一致（v3→v4 升级、时间变更）→ 用 awk 精准删除该 marker 行+紧跟任务行后重新添加 |
| 3 | 变更3：`cleanup_crontab_jobs` 孤儿条目加固 | 同上 | 原 `grep -vF marker \| grep -vF script` 全量过滤存在缺陷：marker 行与任务行是两行，全量过滤虽两行都删，但若历史上已有孤儿任务行（无 marker）则无法定位；改为 awk 按"marker 行+紧跟任务行"**成对精准删除**，杜绝误删其它任务 |
| 4 | 语法校验 | 本地 | `bash -n auto_crontab_settings.sh` → SYNTAX_OK（与 v4.sh 双脚本复验通过） |
| 5 | 计划执行文档同步 | `Docs/PRD/自动化部署脚本/新统一平台/问题处理/auto_clean_deleted_ubains脚本修复方案与目的_计划执行.md` | 6 处：新增 3.5 节（部署入口 3 处变更表）、实施清单步骤 13、验证结果第 8/9 行（语法/升级逻辑走查）、优化功能回填表新增 1 行、7.1 补充部署包侧说明（重跑主部署脚本即自动升级）、附录一句话版 |
| 6 | HANDOFF 记录 | 本文档会话2 + 会话3 | 会话2 补充指向本节；本节完整记录 |
---
## 当前阻塞项
| 类型 | 描述 | 原因 |
|------|------|------|
| 待办 | 本次变更未提交 git | 与会话2 产出合并为 7 个文件提交清单（见下一步 #3），待用户确认 |
| 待办 | 存量部署包服务器尚未重跑主部署脚本 | 升级逻辑已就绪，但需人工触发 new_auto 等脚本才会将存量 v3 条目升级为 v4 |
无技术/信息/决策阻塞，代码变更已闭环。
---
## 下一步计划
| # | 步骤 | 预期结果 |
|---|------|----------|
| 1 | 逐文件 `git add` + commit（勿用 `git add .`）：v4.sh、v4_logic.md、README 总览、**auto_crontab_settings.sh**、PRD 修复方案文档、计划执行文档、本 HANDOFF | 会话2+3 全部产出入库 develop 分支 |
| 2 | 承接会话2：服务器 nat.ubainsyun.com:18126 同步 `get_container_of_pid` 2 行修正（计划执行文档 7.1） | 服务器兜底分支恢复容器归属识别 |
| 3 | 2026-09-09 早上首夜核对（计划执行文档 5.2）：clean 日志、ujava2 Up>1天、meeting2.0 日志 03:50–04:30 无中断 | 确认 v4 首夜定时执行正常 |
| 4 | 存量部署包服务器择机重跑任一主部署脚本 | `_add_single_cron_job` 自动将 v3 条目（`0 4`）替换为 v4 条目（`20 4`），历史孤儿条目被 `cleanup_crontab_jobs` 顺手清除 |
---
## ⚠️ 踩坑警示 — 绝对不要再踩
1. ❌ **crontab 注册脚本不能只凭"marker 存在"判断任务已是最新** — 原 `_add_single_cron_job` 见 marker 即跳过，脚本升级（v3→v4）或时间变更后存量服务器永远跑旧版。判断逻辑必须是"marker + 任务行内容"双重比对，内容过期则删除重加。任何"存在即跳过"式幂等设计都要问一句：**升级路径通了吗？**
2. ❌ **删除 crontab 条目勿用 grep -v 全量过滤** — marker 行与任务行是相邻两行，过滤方式容易产生"孤儿任务行"（marker 已删、任务行残留继续执行，本例中 v3 会继续在 04:00 触发重启风暴，与 v4 双跑）。用 awk 按"marker 行 + 紧跟任务行"成对删除，模式：`awk -v m="$marker" 'BEGIN{skip=0} {if(skip==1){skip=0;next} if($0==m){skip=1;next} print}'`
3. ❌ **部署入口脚本的变更是全局性的，必须向后兼容** — `auto_crontab_settings.sh` 管 10 个定时任务的注册，改动影响所有新部署与存量重跑服务器。本次方案对全部任务统一生效但行为安全：内容一致→跳过（幂等不变），仅过期→升级替换；不能为单个任务引入破坏其它任务注册路径的逻辑。
---
## 附录：关键文件/资源链接（会话3）
| 资源类型 | 位置 | 备注 |
|----------|------|------|
| 部署入口脚本（本次修改） | `自动化部署脚本/x86架构/新统一平台/auto_crontab_settings.sh` | 3 处变更：任务定义区 / `_add_single_cron_job` 步骤6 / `cleanup_crontab_jobs` |
| source 关系（4 个主部署脚本） | `new_auto.sh:95-96`、`new_auto_meeting.sh:68-69`、`new_auto_monitor.sh:68-69`、`new_auto_voice.sh:68-69` | 均 source auto_crontab_settings.sh |
| 计划执行文档 3.5 节 | `Docs/PRD/自动化部署脚本/新统一平台/问题处理/auto_clean_deleted_ubains脚本修复方案与目的_计划执行.md` | 本次 3 处变更的完整表格与代码片段 |
| 受影响任务清单 | auto_crontab_settings.sh 内 `TASK_*` 数组共 10 个任务 | 本次仅 auto_clean 定义变更；升级/清理逻辑增强对 10 个任务统一生效 |
---
# 会话4（2026-09-08）— X86-统信UOS 5.70 登录修复 + 8步业务功能验证全链路通过
> **生成时间**：2026-09-08
> **会话主题**：修复 superadmin 后台登录失败（nginx 正则 location 遮蔽 `/api/` 前缀路由）+ 用户要求执行的 8 步业务功能验证全部通过
---
## 任务概述
2026-09-07 部署授权完成后（见 2026-09-07 部署分析报告），登录后台 `https://192.168.5.70/#/LoginAdmin` 报 **"令牌不能为空"** 无法进入。本次会话完成：
1. 根因定位：nginx 正则 location `~* ^/api/(.*)$`（→9204/oldmeeting，AuthFilter 拦截）遮蔽前缀 location `location /api/`（→8999 登录处理服务）
2. 修复：`location /api/` 加 `^~` 修饰符 → `/api/*` 恢复转发 8999（unified443.conf:269，备份 `.bak_loginfix_20260908`，nginx -t + reload）
3. 修复验证：Playwright 浏览器流 superadmin 登录成功（返回 JWT，跳转 `/backend/backstage`）+ 4大接口回归复验全部通过
4. **业务功能验证 8 步全链路执行通过**（用户明确指示"业务系统要执行"，原"先不执行"解除）
---
## 已完成事项
| # | 产出项 | 位置/路径 | 说明 |
|---|--------|-----------|------|
| 1 | 根因定位 | 服务器 192.168.5.70 `/data/middleware/nginx/config/unified443.conf` | 证据链：8999 直连 getVerifyCode 返回 PNG+datacode ✅ / 9204 返回 令牌不能为空 ❌ / 8999 带 datacode 登录返回 JWT ✅ → nginx 配置确认正则 location（277行）遮蔽前缀 location（269行） |
| 2 | 修复 | 同上级统一 nginx 配置 line 269 | `location /api/ {` → `location ^~ /api/ {`（^~ 使前缀 location 优先于正则），备份 `unified443.conf.bak_loginfix_20260908`，`docker exec unginx nginx -t` OK + `nginx -s reload` RELOAD_OK |
| 3 | 修复验证 | Playwright 浏览器流 | https 登录 POST → `{"success":true,..."token":"eyJhbGciOiJIUzUxMiJ9..."}`，URL 跳转 `/#/backend/backstage?backstage=%2Fbackstage%2F%23%2FBackend%2FAccount%2FCompany` —— superadmin 后台登录成功 |
| 4 | 回归复验 | 4大接口 | 对外 `无效token` ✅ / 预定 `accessToken为空` ✅ / 运维 `用户不存在` ✅ / 讯飞 `"success":true` ✅ —— nginx 修改无副作用 |
| 5 | 业务验证1 创建公司管理员 admin | `code/verify_business.py --step admin` | ✅ 列表出现精确 admin 记录（18:33-18:34） |
| 6 | 业务验证2 admin 强制改密 | `--step pwd` | ✅ 检测到改密对话框 → 新密码 `Ubains@13579` 登录成功（18:36-18:37） |
| 7 | 业务验证3 创建测试权限组+绑定角色 | `--step permgroup` | ✅ 权限组创建 + 绑定"公司管理员"（全选82个复选框）（18:37-18:39） |
| 8 | 业务验证4 新增用户 admin@test | `--step user` | ✅ 列表出现 admin@test（18:39） |
| 9 | 业务验证5 新增部门 | `--step dept` | ✅ 树形结构出现"默认部门名称"（18:40） |
| 10 | 业务验证6 新增会议室 | `--step room` | ✅ 列表出现"测试会议室"，绑定第1个授权码（18:40-18:41） |
| 11 | 业务验证7 批量启用授权码 | `--step authcode` | ✅ 授权码状态变为"已激活"（18:42） |
| 12 | 业务验证8 前台新建会议 | `--step meeting` | ✅ 前台登录 + 勾选"测试会议室"(JS .el-checkbox+回读) + 弹出"会议创建成功"（18:42-18:43） |
| 13 | 补充部署分析报告 | `AuxiliaryTool/ScriptTool/RemoteDeploy/reports/X86_UOS_5.70_部署分析报告_20260908.md` | 登录修复 + 8步业务验证全链路 + 回归复验完整记录 |
| 14 | 结果存档 | `code/verify_business_result.json` | 8 步全部 `all_ok: true` |
---
## 当前阻塞项
| 类型 | 描述 | 原因 |
|------|------|------|
| 待办 | 本次变更未提交 git（含 HANDOFF 会话4、补充报告、verify_business_result.json、memory 文件） | 等用户确认后逐文件提交 |
| 待办 | `deploy_config.json` SSH 密码过期 | 文件仍为 `Ubains@123`，实际为 `Ubains@2026`，建议更新 |
| 信息 | SSO 配置未深入 | auth 目录仅 bootstrap.yml，凭据在 Nacos（无凭据访问 403），但不阻塞登录 |
无技术/信息/决策阻塞，本次登录修复与业务验证已闭环。
---
## ⚠️ 踩坑警示 — 绝对不要再踩
1. ❌ **nginx 正则 location（`location ~* ^/api/(.*)$`）会遮蔽前缀 location（`location /api/`）** — 本次登录失败直接根因：`/api/system/login` 被正则转发到 9204/oldmeeting（AuthFilter 拦截 → 令牌不能为空），而非本应转发的 8999（登录处理服务）。凡前后缀 location 与正则 location 并存于同一 `location /api/` 路径，前缀必须加 `^~` 修饰符才能优先。排查 `/api/*` 路由类问题：先 `grep -n "location.*api" unified443.conf` 看是否有正则遮蔽，再对端口直连验证（8999 vs 9204 行为差异是决定性证据）。
2. ❌ **修改 nginx 配置执行 `nginx -t` 后必须 `nginx -s reload`** — 本次第一次修复只 sed + `nginx -t`（语法 OK）未 reload，浏览器登录仍报 令牌不能为空；执行 `docker exec unginx nginx -s reload`（RELOAD_OK）后行为立即变化（验证码错误→登录成功）。**语法检查通过 ≠ 配置生效**。
3. ❌ **nginx 容器挂载的是宿主目录，改宿主文件必须 reload 容器内进程** — unginx bind-mount `/data/middleware/nginx/config → /etc/nginx/conf.d`，宿主改文件只是写盘，容器内 nginx 进程持有的是旧配置，必须 `docker exec unginx nginx -s reload`。
4. ❌ **修改 nginx 路由后必须做业务接口回归** — 路由是全局性的，本次修复同时验证 4大接口（对外/预定/运维/讯飞）全部正常才收敛；只验证登录成功不算完。
---
## 给接手者的话（会话4）
> **2026-09-08 会话**：X86-5.70 部署后登录失败已闭环 + 业务验证全通过：
>
> - **根因**：nginx 正则 location 遮蔽前缀 `/api/` 路由，登录被误转发 9204/oldmeeting
> - **修复**：unified443.conf:269 `location /api/` 加 `^~`，reload 生效，备份 `.bak_loginfix_20260908`
> - **验证**：superadmin 登录成功（JWT + 跳转 backstage），4大接口回归全过
> - **业务验证**：用户指示"业务系统要执行"，8 步全链路 ✅（admin创建/改密/权限组/新增用户/部门/会议室/授权码/前台新建会议），`verify_business_result.json` 存档
> - **报告**：`AuxiliaryTool/ScriptTool/RemoteDeploy/reports/X86_UOS_5.70_部署分析报告_20260908.md`
> - **待办**：git 提交（逐文件 add，勿用 `git add .`）；`deploy_config.json` SSH 密码更新为 Ubains@2026
>
> 接手后如需复跑业务验证：`python .claude/skills/X86-TX-XTYBS/code/verify_business.py --step <admin|pwd|permgroup|user|dept|room|authcode|meeting>`；牢记教训 L（Element UI 用 JS 操作样式层+回读）、M（测试会议 15 分钟占用忌来回重跑）、踩坑警示 #1-#4。
---
## 给接手者的话（会话3）
> **2026-09-08 会话**：部署入口 auto_crontab_settings.sh 已与 v4 对齐，仓库侧 auto_clean V3→V4 全链路（脚本 + 注册入口 + 文档）闭环：
>
> - **核心问题**：只改服务器 crontab 不改部署入口，新装服务器仍会装 v3；且原注册逻辑"marker 存在即跳过"+ grep -v 移除，存量服务器既升不了级也清不干净
> - **解法**：任务定义 v4 化 + 条目内容比对自动升级 + awk 成对精准删除，重跑主部署脚本即可完成存量升级，零手工 crontab 操作
> - **待办链**：git 提交（7 文件）→ 服务器同步 2 行修正 → 09-09 首夜核对 → 存量部署包服务器重跑主部署脚本
>
> 接手后先 `Read` 计划执行文档 3.5 节（含本次全部代码片段与 rationale）；改 crontab 相关逻辑前先重读本节踩坑警示 #1/#2（升级盲区与孤儿条目是同一类问题的两个面）。
---
# 会话5（2026-09-09）— SKILL 业务验证标注"先不执行"→"必须执行" + 实时状态复核
> **生成时间**：2026-09-09
> **会话主题**：用户确认业务功能验证为"必须执行"（SKILL.md 标注更新），并对 5.70 当前登录/接口/容器状态做实时复核
---
## 任务概述
会话4（2026-09-08）完成登录修复 + 8 步业务验证后，本会话处理三项收尾：
1. 用户质疑"可以登录啊" → 澄清：登录失败为修复前现象，修复后已恢复（本会话实时复核确认）
2. 用户要求业务验证标注"必须执行"（原 SKILL.md 仍写"先不执行"，与实际执行状态不一致）
3. 实时复核 5.70 登录端点、4 大接口、容器状态，确认系统当前健康
---
## 已完成事项
| # | 产出项 | 位置/路径 | 说明 |
|---|--------|-----------|------|
| 1 | SKILL.md 标注更新：**先不执行 → 必须执行** | `.claude/skills/X86-TX-XTYBS/SKILL.md:252` | 部署注意事项第 5 条"创建用户使用（先不执行）"改为"（必须执行，2026-09-08 已执行 ✅）"，补充指示"后续每次部署完成都必须执行业务功能验证章节" |
| 2 | SKILL.md 业务功能验证章节标题更新 | `.claude/skills/X86-TX-XTYBS/SKILL.md:470` | "## 业务功能验证"改为"## 业务功能验证（必须执行 · 2026-09-08 已执行 8/8 通过 ✅）"，说明段同步标注执行状态与结果存档路径 |
| 3 | HANDOFF 结构修复 | 本文档会话4/会话3 之间 | 修复会话4 插入时吞掉的 `## 给接手者的话（会话3）` 标题（恢复在会话3 blockquote 之前），避免会话3 内容被误归入会话4 |
| 4 | 实时复核：登录端点 | `code/_verify_login.py` | datacode 获取成功 + 带 datacode `/system/login` POST 返回 **JWT**（HTTP 200，token 有效），登录链路正常 |
| 5 | 实时复核：4 大接口回归 | `code/_diag_verify_apis.py` | 对外=`无效token` ✅ / 预定=`accessToken为空` ✅ / 运维=`用户不存在` ✅ / 讯飞=`"success":true` ✅ —— 全部通过 |
| 6 | 实时复核：容器与负载 | SSH docker ps / uptime | 13 容器全部 Up（ujava2/upython 等 3 小时，unginx/unacos 等 3 个月），负载 1.69/1.86/1.78 正常 |
| 7 | 业务验证状态澄清 | — | 8 步业务验证于 2026-09-08 18:33–18:43 已完整执行 8/8 通过（`code/verify_business_result.json` 存档）；本会话仅做实时复验，未重跑 8 步（避免重复数据/时段冲突，教训 M） |
---
## 当前阻塞项
| 类型 | 描述 | 原因 |
|------|------|------|
| 待办 | 本次变更未提交 git | 涉及：SKILL.md（先不执行→必须执行）、HANDOFF（本会话5 + 会话4 + 结构修复）、补充报告 20260908、verify_business_result.json 等，等用户确认后逐文件提交（勿用 `git add .`） |
| 待办 | `deploy_config.json` SSH 密码过期 | 文件仍为 `Ubains@123`，实际为 `Ubains@2026`，建议更新 |
无技术/信息/决策阻塞。
---
## 下一步计划
| # | 步骤 | 预期结果 |
|---|------|----------|
| 1 | 逐文件 `git add` + commit（勿用 `git add .`）：SKILL.md、HANDOFF、补充报告 20260908、verify_business_result.json 等 | 会话4+5 全部产出入库 develop 分支 |
| 2 | 更新 `deploy_config.json` SSH 密码为 Ubains@2026 | 后续部署/验证脚本免密直连不再失败 |
| 3 | 后续每次部署完成后，按 SKILL"必须执行"要求跑 8 步业务验证 | 业务链路每次部署都确认可用 |
---
# 会话6（2026-09-09）— PVE 快照恢复流程落地：恢复自动化部署服务器初始化状态
> **生成时间**：2026-09-09
> **会话主题**：连接 PVE 虚拟化集群定位 5.70 虚拟机（VM 130），实测快照回滚恢复初始化状态，并将该操作沉淀为 SKILL 标准流程与自动化脚本
---
## 任务概述
用户确立部署闭环流程：**自动化部署 → 业务功能验证 → 快照恢复（重置初始化状态）→ 等待虚拟机启动 → 继续下一轮自动化部署**。本会话完成该流程的首次实测与文档落地：
1. 连接 PVE 集群（192.168.5.11 pve11），定位 VM 130（5.70）实际位于节点 pve12（192.168.5.12）
2. 实测快照回滚：停机 → `qm rollback 130 chushihua` → 开机，验证服务器回到部署前初始化状态
3. SKILL.md 新增"快照恢复"章节 + 新增 `code/restore_vm_snapshot.py` 自动化脚本
---
## 关键环境信息（接手必读）
| 项目 | 值 |
|------|-----|
| PVE 集群 | pve11（192.168.5.11）+ pve12（192.168.5.12），`pvecm nodes` 确认 |
| 目标虚拟机 | **VMID 130，名称 `5.70`，位于 pve12**，4核2路/8192MB/110G，running |
| 初始化快照 | `chushihua`（2026-09-08 16:02:22，含内存状态卷 vm-130-state-chushihua） |
| SSH 免密 | `~/.ssh/192.168.5.11/id_rsa` 对 pve11/pve12 均有效（RSAKey 生成部署） |
| 免密兜底密码 | pve11/pve12 root 密码 `ubains@123` |
| VMID 命名规则 | VM 名称 = IP 末段（104=5.44 … 129=5.69、130=5.70），集群内其余 VM 均为其他环境，**严禁触碰** |
---
## 已完成事项
| # | 产出项 | 位置/路径 | 说明 |
|---|--------|-----------|------|
| 1 | PVE 免密打通 | `C:\Users\29194\.ssh\192.168.5.11\id_rsa` | paramiko RSAKey.generate(2048) 生成 + pubkey 部署到 pve11 authorized_keys；同 key 实测可登录 pve12 |
| 2 | VM 130 定位 | pve12 `qm list` | pve11 上无 130；pve12 列表中 `130 5.70 running 8192MB 110G`；`qm config 130` 备注确认 IP 192.168.5.70 |
| 3 | 快照回滚实测 | pve12 | `qm shutdown 130`（ACPI 优雅关机成功）→ `qm rollback 130 chushihua`（薄卷重建成功）→ 回滚后自动恢复运行（快照含内存状态，`qm start` 报 already running 属正常） |
| 4 | 回滚后状态核验 | SSH 192.168.5.70 | **初始化状态确认**：无部署目录 / docker 未运行 / 443、8999、9204 均未监听 / 无 nginx ^~ 修复标记；SSH 密码回到初始 `Ubains@123`；4大接口连接超时属预期 |
| 5 | SKILL.md 新增"快照恢复"章节 | `.claude/skills/X86-TX-XTYBS/SKILL.md`（业务功能验证章节之后、"已知问题"之前） | 流程定位/执行时机（每轮部署+业务验证完成后必须执行）/PVE 环境表/快照内容实测/5 步恢复操作/安全红线（仅限 VMID 130、名称校验防误操作）/自动化脚本用法 |
| 6 | 新增快照恢复脚本 | `.claude/skills/X86-TX-XTYBS/code/restore_vm_snapshot.py` | 默认查看模式（零修改）；`--execute` 执行恢复；强制双重校验（VM 名称=5.70 + 快照存在）不过即中止；优雅关机超时自动降级 qm stop；回滚后轮询 SSH 可达（≤300s） |
| 7 | 脚本查看模式实测 | 本地运行 | 节点定位/身份校验/快照校验全部通过，查看模式未做任何修改 |
---
## 重要澄清（覆盖会话5 的遗留待办）
会话5 遗留待办"更新 deploy_config.json SSH 密码 Ubains@123 → Ubains@2026"**在新流程下不再成立**：
- 快照恢复后服务器密码回到初始 `Ubains@123`（与 deploy_config.json 现值一致）
- `Ubains@2026` 是部署后人工修改的密码，随快照回滚一并消失
- 因此 deploy_config.json **维持 Ubains@123 不改**——每轮部署从初始化快照开始，入口密码即 Ubains@123
---
## 踩坑警示（给接手者）
1. **严禁触碰 VM 130 以外的任何虚拟机**——集群内 100~132/200/558 均为其他环境服务器；任何写操作前必须 `qm config 130 | grep '^name:'` 确认输出 `name: 5.70`
2. **回滚会丢弃快照后全部数据**（部署结果+业务验证数据），这是流程要求而非事故；不要试图"保护"部署后的状态
3. **回滚后无需手动 qm start**——chushihua 含内存状态卷，回滚即自动恢复运行；`qm start` 报 already running 属正常，脚本已处理
4. **4大接口在回滚后必然连接超时**——初始化状态无任何服务，属预期现象，不要误判为故障；判断依据是部署后验证（阶段3），不是回滚后
---
## 下一步计划
| # | 步骤 | 预期结果 |
|---|------|----------|
| 1 | 逐文件 `git add` + commit（勿用 `git add .`）：SKILL.md、HANDOFF、restore_vm_snapshot.py 及会话5 产出 | 快照恢复流程入库 develop |
| 2 | 服务器已处于初始化状态且 SSH 可达，按 SKILL 阶段1 开始新一轮自动化部署 | 部署包上传 → 解压 → new_auto.sh --all |
| 3 | 部署+业务验证完成后执行 `restore_vm_snapshot.py --execute` | 服务器重置，闭环回到步骤2 |
Docs/PRD/远程自动化部署/HANDOFF_X86统信远程自动化部署会话交接.md 0 → 100644
浏览文件 @ 39c373d2
# HANDOFF — X86统信远程自动化部署会话交接文档
> **生成时间**：2026-09-08
> **会话主题**：X86-统信UOS（192.168.5.70）全量部署 + 授权 + 业务功能验证全链路闭环
> **最近更新**：2026-09-08（首次创建：记录 2026-09-07 全链路闭环进度 —— 部署 22分40秒 13容器全 Up / 授权闭环 4大接口 4/4 / 业务验证 8/8 ✅ / 业务验证8排障两处修复 / SKILL.md 教训 A-M 回填；**所有改动均未提交**，见"当前阻塞项"）
---
## 任务概述
围绕 X86-统信UOS 服务器（192.168.5.70）完成以下工作（全链路闭环）：
1. **阶段1-5 全量自动化部署**：跳过网盘上传（使用服务器已有部署包），`new_auto.sh --all` 执行部署
2. **阶段4 系统授权**：下载激活文件 → 上传 license.zip → 重启服务，4大接口复验通过
3. **业务功能验证 8 项**：添加管理员 / 强制改密 / 权限组 / 添加用户 / 新增部门 / 新增会议室 / 批量启用授权码 / 前台新建会议，全部 Playwright UI 自动化（无 API 调用、无手动 shell 干预页面流程）
4. **业务验证8排障**：iframe + Element UI checkbox 假成功修复 + 会议室时间占用自冲突定位
5. **经验回填 SKILL.md**：实战教训新增 L/M + "会议预约 - 新建会议"章节更新（累计教训 A-M 共 13 条）
---
## 已完成事项
### 一、部署与授权（2026-09-07 上午）
| # | 产出项 | 位置/路径 | 说明 |
|---|--------|-----------|------|
| 1 | 阶段1-2 部署执行 | 服务器 `/data/offline_auto_unifiedPlatform` | 跳过网盘上传，使用服务器已有部署包；`new_auto.sh --all` 净用时 **22分40秒**（11:25:44→11:48:24，DEPLOY_EXIT=0），13 个容器全部 Up |
| 2 | 阶段3 接口验证 | `phase4_verify.py` | 4大接口复验 4/4 一次命中并二次确认通过：对外=`无效token`、运维=`用户不存在`、讯飞=`"success":true`、预定=`accessToken为空` |
| 3 | 阶段4 授权闭环脚本 | `.claude/skills/X86-TX-XTYBS/code/phase4_run.py` + `phase4_verify.py` | 下载激活文件（绑定硬件指纹）→ 上传 license.zip → 重启服务（meeting2.0 进程 12:23:17 重启）；激活文件 484B→19992B 闭环信号（教训K） |
| 4 | 部署分析报告 | `AuxiliaryTool/ScriptTool/RemoteDeploy/reports/X86_UOS_5.70_部署分析报告_20260907.md` | 阶段5 产出 |
| 5 | 部署包目录结构解析 | `Docs/PRD/远程自动化部署/X86架构_部署包目录结构解析_20260907.md` | 为容器组件升级制作新部署包做准备（**未提交**） |
| 6 | 已知误报记录 | deploy.log | nginx 部署成功后仍打印"部分中间件部署失败"ERROR（脚本判断瑕疵，实际全部成功） |
### 二、业务功能验证 8/8（2026-09-07 下午，Playwright UI 自动化）
| # | 模块 | 完成时间 | 关键结果 |
|---|------|----------|----------|
| 7 | 1.添加管理员 | 16:40 | 列表出现精确 admin 记录 |
| 8 | 2.强制改密 | 17:08 | 首登强制改密对话框 → 新密码 Ubains@13579 登录成功 |
| 9 | 3.创建权限组+绑定角色 | 17:39 | 测试权限组已存在跳过重复创建，绑定公司管理员 |
| 10 | 4.添加用户 | 17:40 | 列表出现 admin@test |
| 11 | 5.新增部门 | 17:44 | 树形结构出现 默认部门名称 |
| 12 | 6.新增会议室 | 17:46 | 测试会议室 + 授权码 CCA-0K7-0001 |
| 13 | 7.批量启用授权码 | 17:46 | 10 个授权码 未激活→已激活 |
| 14 | 8.前台新建会议 | 18:41 | 会议创建成功对话框（**本会话重点排障，见下**） |
**权威结果文件**：`.claude/skills/X86-TX-XTYBS/code/verify_business_result.json`（8 模块全 `all_ok: true`）；截图在 `~/deploy_logs/screenshots/`（关键截图 `biz_meeting_created_1788777670.png`）。
### 三、业务验证8排障（本会话核心工作）
| # | 产出项 | 位置/路径 | 说明 |
|---|--------|-----------|------|
| 15 | 问题1定位：iframe + Element UI checkbox 假成功 | `code/verify_business.py` `step_create_meeting` | 勾选"测试会议室"标记 ✅ 但实际未选中，点【确定创建】报"请选择会议室"（toast 3秒消失抓不到）。根因三个：①`:has-text` locator 在 iframe 嵌入页匹配不到表格行（Element UI 固定列 duplicate DOM）②`check(force=True)` 点隐藏 input 不触发 Element UI change ③只"点了"不回读状态造成假成功 |
| 16 | 问题1修复 | `code/verify_business.py` | JS `querySelectorAll('.el-table__row')` 按 `innerText.includes('测试会议室')` 过滤 → 点击 `.el-checkbox` 容器（label 事件代理）→ 回读 `input.checked` 为 true 才标记成功；点【确定创建】后立即轮询 `.el-message` 抓错误提示 |
| 17 | 诊断脚本1 | `code/diag_meeting_room.py` | 确定创建后错误抓取轮询 6→8 次（`grab_errors()`） |
| 18 | 诊断脚本2 | `code/diag_meeting_room2.py` | 4种点击方式（label点击/原生input/原生click+change/点inner span）逐一尝试并回读状态；实证 `.el-checkbox.click` 唯一有效 |
| 19 | 问题2定位："该时间段已有会议"自冲突 | 18:28 首跑失败 | 18:22 诊断脚本 diag_meeting_room2.py 已创建"立即开始"会议（默认时长15分钟），会议室被占用至约18:37；**不是 bug，是测试数据自冲突**。对策：等时段结束/换会议室/改预定未来时段；诊断脚本成功创建后立即收手 |
| 20 | 重跑通过 | 18:40-18:41 | 等待约11分钟释放后重跑，8.前台登录/选择开会区域/勾选会议室/新建会议 4 步全 ✅ |
### 四、经验回填 SKILL.md（`.claude/skills/X86-TX-XTYBS/SKILL.md`）
| # | 产出项 | 位置 | 说明 |
|---|--------|------|------|
| 21 | 教训 L | SKILL.md 实战教训 | 前台新建会议 iframe 内 Element UI 表格 checkbox：`check(force=True)` 和 `:has-text` 都不可用；唯一可靠组合 = JS `.el-table__row` innerText 过滤 → 点 `.el-checkbox` → 回读 `input.checked`；点【确定创建】后立即轮询 `.el-message`；含通用规律"JS 操作样式层容器 + 回读真实状态验证" |
| 22 | 教训 M | SKILL.md 实战教训 | "该时间段已有会议"= 测试数据自冲突非 bug；重跑前确认会议室空闲；看到该报错先查时间轴，不要往服务/授权方向排障 |
| 23 | 会议预约章节更新 | SKILL.md「会议预约 - 新建会议」 | 操作步骤4.4 改为 ✅/❌ 对照写法（正确 JS 方式 + 两种错误方式）；关键要点补 3 条（勾选必须回读验证 / 错误提示易丢失需立即抓取 / 该报错属数据自冲突） |
| 24 | 教训 I/J/K（前序会话回填） | SKILL.md 实战教训 | I=维护平台左侧菜单扁平结构（无"系统管理"子菜单，与 LoginAdmin 两套菜单勿混淆）；J=上传授权弹拖拽上传对话框不自动弹文件选择器（对 `.el-dialog:visible input[type="file"]` 直接 `set_input_files`）；K=激活文件大小可作授权状态信号（484B=仅注册指纹，19992B=完整授权） |
| 25 | 记录完整性确认 | SKILL.md | grep 确认实战教训 A-M 共 13 条齐全（A-H 前序 + I-M 本次），用户已确认"记录清楚" |
---
## 验证结果
```
# 部署（2026-09-07 上午）
new_auto.sh --all → 11:25:44→11:48:24，DEPLOY_EXIT=0，净用时 22分40秒
docker ps → 13 个容器全部 Up
# 授权闭环（12:23:17 meeting2.0 重启后）
4大接口复验 → 4/4 一次命中并二次确认通过
对外 = 无效token
运维 = 用户不存在
讯飞 = "success":true
预定 = accessToken为空
激活文件大小 → 484B（上传前）→ 19992B（上传后）
# 业务功能验证（verify_business_result.json）
admin=✅ pwd=✅ permgroup=✅ user=✅ dept=✅ room=✅ authcode=✅ meeting=✅
meeting 明细（18:41）：
8.前台登录 ✅ 前台已登录
8.选择开会区域 ✅ 已点击 选择开会区域
8.勾选会议室 ✅ 已勾选 测试会议室 (JS .el-checkbox.click)
8.新建会议 ✅ 弹出 会议创建成功 提示
关键截图 → biz_meeting_created_1788777670.png（"会议创建成功，是否继续创建会议"对话框）
# SKILL.md 记录完整性
grep '^### ' 实战教训条目 → A/B/C/D/E/F/G/H/I/J/K/L/M 共 13 条齐全
```
---
## 当前阻塞项
| 类型 | 描述 | 原因 |
|------|------|------|
| **阻塞** | X86-TX 全部改动**未提交未推送** | 见下方清单，待用户确认后分组提交 |
| 信息 | `AuxiliaryTool/FunctionalTestReportGeneration/temp/` | 运行产物，按此前约定不提交不删除，留工作区 |
**未提交清单**（`git status` 实测）：
| 状态 | 文件 | 内容 |
|------|------|------|
| M | `.claude/skills/X86-TX-XTYBS/SKILL.md` | 教训 I-M + 会议预约章节更新 |
| M | `.claude/skills/X86-TX-XTYBS/code/phase4_authorize.py` | 授权脚本更新 |
| M | `Docs/PRD/远程自动化部署/_PRD_X86_统信远程自动化部署_需求文档.md` | 需求文档更新 |
| M | `Docs/PRD/远程自动化部署/_PRD_X86_统信远程自动化部署_需求文档_计划执行.md` | 计划执行更新（跳过网盘上传等） |
| ?? | `code/` 下 15 个脚本 | phase2_launch/retry/watch、phase4_run/verify、verify_business、create_permgroup、diag_pwd/perm/bind/meeting_room/meeting_room2、_diag_login、_deploy_only.sh、_phase2_chain.sh |
| ?? | `code/` 下 2 个结果 json | phase4_verify_result.json、verify_business_result.json |
| ?? | `Docs/PRD/远程自动化部署/X86架构_部署包目录结构解析_20260907.md` | 部署包目录解析文档 |
---
## 下一步计划
| # | 步骤 | 预期结果 |
|---|------|----------|
| 1 | X86-TX 改动分组提交推送（逐文件 add，遵守"不用 git add ."规范） | 建议分组：①SKILL.md + code 脚本（部署授权+业务验证）②PRD 双文档 + 部署包目录解析 ③结果 json |
| 2 | 【待办①】按《X86架构_部署包目录结构解析_20260907.md》进行容器组件升级并制作新全量自动化部署包 | 新部署包可用于下次全量部署 |
| 3 | （可选）修复 deploy.log"部分中间件部署失败"误报的脚本判断瑕疵 | 部署日志判断准确 |
| 4 | （可选）清理 `code/` 下一次性诊断脚本（`_diag_login.py`、`diag_*.py`、`_phase2_chain.sh` 等） | 保留 verify_business.py / phase4_run.py / phase4_verify.py 等主干脚本 |
---
## ⚠️ 踩坑警示 — 绝对不要再踩
1. ❌ **Element UI 组件不要用 Playwright 原生 `check()/click()` 操作隐藏 input** — 原生 input 隐藏、事件代理挂在 `.el-checkbox` 样式层容器上；`check(force=True)` 不触发 change，Vue 状态不变。一律 **JS 操作样式层容器（`.el-checkbox`/`.el-switch`）+ 回读真实状态验证**，不回读就标记成功 = 假成功（教训L）。
2. ❌ **`:has-text` locator 在 iframe 嵌入页的 Element UI 表格中匹配不到行** — 固定列 duplicate DOM 导致；用 JS `querySelectorAll('.el-table__row')` + `innerText.includes()` 过滤（教训L）。
3. ❌ **Element UI toast（`.el-message`）约3秒自动消失** — 点【确定创建】等提交按钮后必须立即轮询抓取，否则"请选择会议室"等真实错误被静默吞掉，失败原因无从查起（教训L）。
4. ❌ **"该时间段已有会议"先查时间轴再排障** — 是之前运行创建的"立即开始"会议（默认15分钟）占用了会议室，属测试数据自冲突；等待释放/换会议室/改预定未来时段，不要往服务/授权方向排查（教训M）。
5. ❌ **诊断脚本成功创建会议后立即收手** — 每次成功创建都占用会议室15分钟，主脚本与诊断脚本来回跑会互相撞车（教训M）。
6. ❌ **授权必须先"下载激活文件"再上传 license.zip** — 服务器重部署后硬件指纹变化，跳过下载激活文件会导致 meeting2.0 报"CPU/MAC不匹配"、预定500（教训A）。
7. ❌ **维护平台（LoginConfig）与后台（LoginAdmin）是两套菜单结构** — 维护平台左侧是扁平结构（服务授权/服务升级/服务信息），无"系统管理"子菜单可展开（教训I vs 教训E）。
8. ❌ **授权后预定系统接口恢复需10-15分钟** — ujava2 内 meeting2.0 Spring Boot 启动慢，重启后耐心等待，不要反复重启重置启动周期；验证时预定接口放最后测（教训G）。
---
## 附录：关键文件/资源链接
| 资源类型 | 位置 | 备注 |
|----------|------|------|
| 业务验证主脚本 | `.claude/skills/X86-TX-XTYBS/code/verify_business.py` | 8 模块分步验证，含修复后的 `step_create_meeting` |
| 业务验证结果 | `.claude/skills/X86-TX-XTYBS/code/verify_business_result.json` | 8/8 全部 `all_ok: true` |
| 授权脚本 | `.claude/skills/X86-TX-XTYBS/code/phase4_run.py` + `phase4_verify.py` | 授权闭环 + 4大接口复验 |
| 诊断脚本 | `code/diag_meeting_room.py` / `diag_meeting_room2.py` | checkbox 4种点击方式对照实证 |
| 部署主脚本 | `code/full_deploy.py`（`--arch x86_uos --deploy` / `--verify`） | 阶段1-3 |
| SKILL 文档 | `.claude/skills/X86-TX-XTYBS/SKILL.md` | 实战教训 A-M 共13条 + 业务验证全流程记录 |
| 部署分析报告 | `AuxiliaryTool/ScriptTool/RemoteDeploy/reports/X86_UOS_5.70_部署分析报告_20260907.md` | 阶段5 产出 |
| 部署包目录解析 | `Docs/PRD/远程自动化部署/X86架构_部署包目录结构解析_20260907.md` | 容器组件升级准备 |
| 截图目录 | `~/deploy_logs/screenshots/` | 业务验证全程截图 |
| 服务器 | root@192.168.5.70（Ubains@123） | 部署目录 `/data/offline_auto_unifiedPlatform` |
| 平台入口 | 维护平台 `/#/LoginConfig` / 后台 `/#/LoginAdmin` / 前台 `/` | superadmin/Ubains@1357、admin/Ubains@13579、验证码 csba |
---
## 给接手者的话
> 2026-09-07 全链路已闭环：**部署（22分40秒，13容器全 Up）→ 授权（4大接口 4/4）→ 业务功能验证（8/8 ✅）**，全程 Playwright UI 自动化，符合 skill"禁止 API 调用、禁止手动 shell 干预页面流程"约束。
>
> **本次会话（业务验证8排障）核心产出**：
>
> - 根因1：iframe 嵌入页 Element UI 表格 checkbox，`:has-text` 匹配不到行 + `check(force=True)` 不触发 change → 改 JS `.el-checkbox` 点击 + 回读 `input.checked` 验证
> - 根因2："该时间段已有会议"= 诊断脚本创建的立即开始会议占用会议室15分钟 → 等待释放后重跑通过
> - 经验已回填 SKILL.md（教训 L/M + 会议预约章节 ✅/❌ 对照写法），用户确认记录完整
>
> **接手第一件事**：处理"当前阻塞项"的未提交清单（分组提交推送）。之后如做容器组件升级/新部署包，先读《X86架构_部署包目录结构解析_20260907.md》。所有坑已沉淀在 SKILL.md 实战教训 A-M，动手前先读一遍。
Docs/PRD/远程自动化部署/X86架构_部署包目录结构解析_20260907.md 0 → 100644
浏览文件 @ 39c373d2
# X86架构_新统一平台部署包目录结构解析
> **架构标识**: X86 - 统信UOS (Server 20)
> **目标服务器**: 192.168.5.70 (root@Ubains@123)
> **部署目录**: `/data/offline_auto_unifiedPlatform`
> **解析日期**: 2026-09-07
> **部署包**: `offline_auto_unifiedPlatform.tar.gz`（8.9GB，解压后约 13GB）
> **说明**: 本文档为 X86 统信架构独有，ARM 架构部署包结构可能不同（镜像基于 arm64、中间件版本可能差异）
---
## 一、部署包全景架构
```
/data/offline_auto_unifiedPlatform/
├── 📄 入口与调度脚本体系（根目录）
│ ├── new_auto.sh # 主入口调度脚本（whiptail交互/管道自动应答，协调以下模块）
│ ├── auto_check_space.sh # 部署前置硬件资源/挂载点/磁盘空间校验
│ ├── auto_file_upload_check.sh # 部署包文件完整性与各微服务目录存在性校验
│ ├── auto_firewall_settings.sh # firewalld 防火墙端口批量检查与放行
│ ├── auto_middleware_install.sh # 核心中间件（Docker/MySQL/Redis/EMQX/Nacos/FDFS/Nginx）安装部署
│ ├── auto_deploy_services.sh # 业务微服务容器加载与部署（ujava2/upython/uvoice3等）
│ ├── auto_crontab_settings.sh # 系统自愈监控与定时任务注册（如 ujava2-startup.sh、日志轮转）
│ └── replace_ip_interactive.sh # 数据库、Nacos 及服务配置 IP 批量替换脚本
│
└── 📁 data/ # 核心资源载荷目录（实际直接同步/软链接到宿主机 /data）
├── 📦 temp/ # 离线介质与镜像包总库（约 6.3GB，容器升级核心替换区）
│ ├── docker-29.1.3.tgz # Docker 引擎离线安装包及 systemd 单元
│ ├── mysql-8.0.46.tar.gz # MySQL 8.0 镜像离线包
│ ├── redis-8.8.0.tar.gz # Redis 镜像离线包
│ ├── uemqx-6.0.0.tar.gz # EMQX 消息中间件镜像
│ ├── nacos-server-v2.5.2.tar.gz # Nacos 注册中心/配置中心服务
│ ├── nginx-1.30.2.tar.gz # Nginx 镜像离线包
│ ├── ufastdfs-v2.tar.gz # FastDFS 分布式文件系统镜像（tracker+storage）
│ ├── ungrok2.tar.gz # 内网穿透/代理组件镜像
│ ├── java1.8.0_492.tar.gz # 核心 Java 微服务底座镜像（139.9.60.86:5000/ujava:v7）
│ ├── python_v16.tar.gz # 核心 Python 运维管理后台镜像（upython）
│ ├── uvoice3.tar.gz # 讯飞转录与语音微服务镜像（upython_voice）
│ ├── paperless.tar # 无纸化会议组件镜像
│ └── uos-cardtable.tar # 桌牌与智能硬件终端交互镜像
│
├── 📁 middleware/ # 中间件持久化配置与数据挂载点
│ ├── mysql/ # conf（my.cnf）、conf.d、data、log
│ ├── redis/ # config（redis.conf）、data、log
│ ├── emqx/ # config、data、log
│ ├── nacos/ # bin（startup.sh）、conf（application.properties）、data、logs
│ ├── nginx/ # config（nginx.conf 路由映射）、data、log
│ └── ngrok/ # config、data、log
│
├── 📁 services/ # 业务应用层（宿主机目录直接挂载进容器内部运行）
│ ├── api/ # 微服务代码及运行时 Jar / Python
│ │ ├── java-meeting/ # 预定核心：java-meeting2.0、3.0、extapi、scheduling、mqtt、quartz
│ │ ├── dubbo/ # 10大集控对接模块（teams、tencent-meeting、smc-two/three、dingding等）
│ │ ├── auth/ # SSO单点认证微服务群（sso-auth、sso-gateway、sso-system）
│ │ ├── python-cmdb/ # 运维集控后台 API
│ │ └── python-voice/ # 语音处理 API
│ ├── web/ # 前端静态 Web 资源（由 Nginx 承载）
│ │ ├── pc/ # PC 管理后台与大屏页面
│ │ └── h5/ # 移动端 / 企业微信 / 钉钉 H5 界面
│ └── scripts/ # 运维与守护脚本（自愈监控、日志备份、定时备份）
│
├── 📁 storage/ # 分布式存储与静态媒体资源（FastDFS 数据卷、会议室图标、固件包）
├── 📁 security/ # 安全证书目录（nginx_cert/cert.pem, private.key 自签名证书）
└── 📁 third_party/ # 讯飞转录、无纸化等第三方集成套件
```
---
## 二、各子目录详细内容
### 2.1 根目录部署脚本清单（全部已赋权 755）
| 脚本文件 | 大小 | 职责 |
| :--- | ---: | :--- |
| `new_auto.sh` | 52KB | 主入口调度脚本，source 串联各模块，处理 whiptail 交互 |
| `auto_middleware_install.sh` | 38KB | 中间件安装（Docker/MySQL/Redis/EMQX/Nacos/FDFS/Nginx） |
| `auto_deploy_services.sh` | 44KB | 业务微服务容器加载与部署 |
| `auto_crontab_settings.sh` | 18KB | 定时任务与自愈监控脚本注册 |
| `auto_file_upload_check.sh` | 16KB | 部署文件完整性校验 |
| `auto_firewall_settings.sh` | 5.1KB | firewalld 端口放行 |
| `auto_check_space.sh` | 4.3KB | 空间/挂载点校验（阈值 100G，现场已降为 75G） |
| `replace_ip_interactive.sh` | 5.2KB | 数据库/Nacos/服务配置 IP 替换 |
### 2.2 微服务清单
**java-meeting（预定核心）**：`java-meeting2.0`、`java-meeting3.0`、`java-meeting-extapi`、`java-message-scheduling`、`java-mqtt`、`java-quartz`
**dubbo（10大集控对接）**：`dubbo-cloudLink`、`dubbo-dingding`、`dubbo-meeting-control`、`dubbo-polycom`、`dubbo-serviceCall`、`dubbo-smc-three`、`dubbo-smc-two`、`dubbo-teams`、`dubbo-tencent-meeting`、`dubbo-xylink`
**auth（SSO单点认证）**：`auth-sso-auth`、`auth-sso-gatway`、`auth-sso-system`
**其他**：`python-cmdb`（运维集控后台）、`python-voice`（语音处理）
### 2.3 中间件数据挂载目录（middleware/）
| 组件 | 目录结构 |
| :--- | :--- |
| mysql | conf / conf.d / data / log |
| redis | config / data / log |
| emqx | config / data / log |
| nacos | bin / conf / data / derby.log / logs / plugins |
| nginx | config / data / log |
| ngrok | config / data / log / ngrok.sh |
---
## 三、容器组件版本现状与升级映射表
| 组件名称 | 对应容器名 | 当前离线镜像包（`/data/temp/`） | 当前镜像Tag/版本 | 升级改造涉及文件与关注点 |
| :--- | :--- | :--- | :--- | :--- |
| **Docker** | *(宿主机服务)* | `docker-29.1.3.tgz` | 29.1.3 | `auto_middleware_install.sh` 中的二进制释放与服务配置 |
| **MySQL** | `umysql` | `mysql-8.0.46.tar.gz` | `mysql:8.0` | `auto_middleware_install.sh`、数据目录版本兼容性与初始 SQL |
| **Redis** | `uredis` | `redis-8.8.0.tar.gz` | `redis:latest` / `8.x` | `auto_middleware_install.sh`、`redis.conf` 配置项兼容性 |
| **EMQX** | `uemqx` | `uemqx-6.0.0.tar.gz` | `emqx:v4.x/5.x` | 端口 1883/8883/18083，MQTT 认证与集群配置规则 |
| **Nacos** | *(裸机/容器)* | `nacos-server-v2.5.2.tar.gz` | 2.5.2 | JDK 兼容性、MySQL 数据源连接配置（`application.properties`） |
| **Nginx** | `unginx` / 宿主机 | `nginx-1.30.2.tar.gz` | `nginx:1.30` | `nginx.conf` 路由指令语法兼容、SSL 证书配置 |
| **FastDFS** | `utracker`, `ustorage` | `ufastdfs-v2.tar.gz` | v2 | 存储卷 `/data/storage/storage/data` 挂载路径保持一致 |
| **Java底座** | `ujava2` | `java1.8.0_492.tar.gz` | `139.9.60.86:5000/ujava:v7` | JDK 版本（当前 1.8.0_492）、容器内启动脚本 `ujava2-startup.sh` |
| **Python集控** | `upython` | `python_v16.tar.gz` | `python:v16` | Python 运行时依赖库（Django/Tornado/Paramiko 等） |
| **语音转录** | `upython_voice` | `uvoice3.tar.gz` | `uvoice3` | 讯飞 SDK 与声学模型依赖 |
### 容器关键启动配置
- `ujava2` 容器：`--privileged --entrypoint /bin/bash --restart=always --mac-address="02:42:ac:11:00:02"`，挂载 `/data/services/api`、`/data/services/web`、`/data/middleware/nginx/nginx_log`、`/etc/localtime`、`/data/storage/storage/data`
- 镜像来源：`docker load -i /data/temp/java1.8.0_492.tar.gz` → `139.9.60.86:5000/ujava:v7`
---
## 四、升级后重新打包输出自动化部署包标准流程
1. **镜像包构建与导出**：
```bash
# 更新升级镜像后重新导出为 tar.gz
docker save <新镜像名称:Tag> | gzip > /data/offline_auto_unifiedPlatform/data/temp/<新组件.tar.gz>
```
2. **版本号与脚本联动修改**：
- 同步更新 `auto_middleware_install.sh` 或 `auto_deploy_services.sh` 中的 `image_tar` 与 `image_name` 变量
- 检查 `auto_file_upload_check.sh`，确保校验逻辑覆盖新版本文件名
3. **清洗临时与敏感数据**：
- 清除 `data/middleware/mysql/data/*`（保留初始化结构，避免将现场历史脏数据打包）
- 清除业务运行时日志：`data/logs/*`、`data/services/api/**/logs/*`
- 移除历史临时文件：`*.bak`、`nohup.out`、`DEPLOY_*` 标志
4. **统一归档与 MD5 校验生成**：
```bash
cd /data
# 规范打包（保留所有执行权限）
tar -zcvf offline_auto_unifiedPlatform.tar.gz offline_auto_unifiedPlatform/
# 生成校验指纹
md5sum offline_auto_unifiedPlatform.tar.gz > offline_auto_unifiedPlatform.tar.gz.md5
```
---
## 五、部署注意事项（X86统信特有）
1. **磁盘空间阈值**：`auto_check_space.sh` 中 `new_type_mount` 要求 ≥100G，现场 `/data` 为 81G，需降阈值至 75G（备份为 `.bak`）
2. **系统时间同步**：虚拟机系统时间可能滞后于 RTC，需 `hwclock --hctosys` 校准（否则解压报未来时间戳警告）
3. **root 密码过期策略**：UOS 默认 root 密码 90 天过期，需 `chage -M 99999 root` 解除
4. **whiptail 交互**：`new_auto.sh` 依赖 whiptail，非交互 SSH 执行需 `export TERM=dumb` + `printf 'y\ny\ny\ny\ny\ny\ny\nn\n' |` 管道自动应答
5. **SSH 免密配置**：每次连接服务器后需配置 SSH 免密，免密文件夹以服务器 IP 命名（`~/.ssh/192.168.5.70/`）
---
## 优化功能回填
| 日期 | 内容 | 状态 |
| :--- | :--- | :--- |
| 2026-09-07 | 首次输出 X86 统信部署包完整目录结构解析文档 | [x] 已完成 |
\ No newline at end of file
Docs/PRD/远程自动化部署/_PRD_X86_统信远程自动化部署_需求文档.md
浏览文件 @ 39c373d2
...@@ -156,7 +156,7 @@ ...@@ -156,7 +156,7 @@
``` ```
- 重试机制：根据文档的接口调用要求，执行重试机制。 - 重试机制：根据文档的接口调用要求，执行重试机制。
5. 新统一平台访问使用 5. 新统一平台访问使用
- 根据部署文档第四章节创建公司管理员，按照描述步骤进行操作。---这个先不执行。 - 根据部署文档第四章节创建公司管理员，按照描述步骤进行操作。（2026-09-07 指示：业务功能验证需要执行）
6. 输出分析结果 6. 输出分析结果
- 按照分析要求输出分析结果，文档以md格式。 - 按照分析要求输出分析结果，文档以md格式。
......
Docs/PRD/远程自动化部署/_PRD_X86_统信远程自动化部署_需求文档_计划执行.md
浏览文件 @ 39c373d2
# 计划执行_X86_统信远程自动化部署 # 计划执行_X86_统信远程自动化部署
> 版本：V1.0 > 版本：V1.1
> 创建日期：2026-06-04 > 创建日期：2026-06-04
> 本次更新：2026-09-07（跳过网盘上传，使用服务器已有部署包）
> 基于文档：`_PRD_X86_统信远程自动化部署_需求文档.md` > 基于文档：`_PRD_X86_统信远程自动化部署_需求文档.md`
> 部署文档：`X86架构_新统一平台自动化部署操作指导.md` > 部署文档：`X86架构_新统一平台自动化部署操作指导.md`
> 交付物： > 交付物：
...@@ -175,3 +176,32 @@ python full_deploy.py --arch x86_uos --verify # 验证阶段 ...@@ -175,3 +176,32 @@ python full_deploy.py --arch x86_uos --verify # 验证阶段
| API接口超时 | 验证失败 | 等待更长时间，手动验证 | | API接口超时 | 验证失败 | 等待更长时间，手动验证 |
| 授权文件不匹配 | 服务异常 | 确认授权文件与服务器IP对应 | | 授权文件不匹配 | 服务异常 | 确认授权文件与服务器IP对应 |
| 统信UOS兼容性 | 部署脚本异常 | 参考X86架构部署文档，统信基于CentOS兼容 | | 统信UOS兼容性 | 部署脚本异常 | 参考X86架构部署文档，统信基于CentOS兼容 |
---
## 七、2026-09-07 本次执行调整
### 前置检查结果（已实测确认）
| 检查项 | 结果 |
|--------|------|
| Z:网盘部署包路径 | ❌ 不可访问（未映射）→ **用户指示跳过上传** |
| 服务器已有部署包 | ✅ `/data/offline_auto_unifiedPlatform.tar.gz`（8.9G，6月8日）+ md5 文件 |
| MD5 完整性校验 | ✅ 通过（`md5sum -c` 退出码 0） |
| /data 分区空间 | ✅ 81G 总量，已用 9.5G，可用 72G（12%） |
| 解压目录 | 不存在（干净状态，全新部署） |
| Docker | 未运行（服务器未部署过，符合全新部署预期） |
| 授权文件 | ✅ `E:\自动化部署\X86-5.70\license.zip`（66KB）存在 |
| SSH 免密 | ❌ 未配置（`~/.ssh/192.168.5.70/id_rsa` 不存在），本次连接后配置 |
### 本次执行流程
1. **阶段1（已完成）**：SSH 连接 + 硬盘检查 + 部署包确认 + MD5 校验 —— 全部通过；跳过网盘上传
2. **阶段2**：配置 SSH 免密 → 后台解压（禁止中断，日志监控）→ `chmod 755 *.sh` → `TERM=dumb` + 管道应答执行 `new_auto.sh --all`（后台，监控 `DEPLOY_SCRIPT_FINISHED`，超时 60 分钟）→ `source /etc/profile` → `docker ps`
3. **阶段3**：等待 10 分钟 → 容器状态 → 4 个接口验证（5 次重试/30 秒间隔，成功后二次确认）→ 4 个服务日志检查
4. **阶段4**：Playwright（自签名证书需 `--ignore-certificate-errors`）登录维护平台 → **先"下载激活文件"**（绑定当前硬件指纹，不可省略，见教训A）→ 上传 license.zip → 服务升级页勾选"运维系统+预定系统2.0"重启 → 等待 10 分钟 → 重新接口验证
5. **阶段5**：生成部署分析报告至 `AuxiliaryTool/ScriptTool/RemoteDeploy/reports/X86_UOS_5.70_部署分析报告_20260907.md`
### 接口成功标志修正（教训F）
- 讯飞转录接口成功标志为 `"success":true`（X86 已适配），非文档描述的"缺少关键参数"
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑！
请 注册 或者 后发表评论