auto-sync: 2026-05-22 18:37:17

2026-05-22 18:37:17 +08:00
parent 2c5f886998
commit c4824da298
1 changed files with 292 additions and 0 deletions
@@ -0,0 +1,292 @@
+# moziplus v2 运维脚本设计
+
+**版本**: 3.0.0
+**作者**: 庞统（副军师）🐦
+**日期**: 2026-05-22
+**基于**: deployment-v2.6.md + deployment-v2.6-guide.md（更新版）
+
+---
+
+## 1. 概述
+
+moziplus v2 提供一套运维脚本，覆盖部署、状态查看、数据管理、备份和卸载的全生命周期。
+
+### 脚本清单
+
+| 脚本 | 用途 | 风险等级 |
+|------|------|---------|
+| `deploy.sh` | 部署/升级 | 低（不覆盖 data/config） |
+| `status.sh` | 运行状态查看 | 无（只读） |
+| `build-frontend.sh` | 构建前端 | 无 |
+| `backup.sh` | 备份数据到 NAS | 无 |
+| `reset-data.sh` | 清空运行数据 | 高（删数据） |
+| `uninstall.sh` | 完全卸载 | 高（删目录） |
+
+### 目录约定
+
+```
+开发目录:  ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/   ← Git 仓库
+安装目录:  ~/.sanguo_projects/sanguo_moziplus_v2/             ← PM2 运行
+脚本位置:  开发目录/scripts/
+```
+
+---
+
+## 2. 环境要求
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| Python | ≥ 3.9 | 后端运行 |
+| Node.js | ≥ 20 | 前端构建 |
+| PM2 | ≥ 5.0 | 进程管理 |
+| rsync | 任意 | 代码同步 |
+| curl | 任意 | 健康检查 |
+| sqlite3 | 任意 | 数据查询（status -v） |
+| NAS SMB | — | 备份目标（backup.sh） |
+
+---
+
+## 3. 场景手册
+
+### 场景 1：首次部署
+
+**触发**：新机器上第一次安装 moziplus v2
+
+```bash
+# 从开发目录部署
+cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v2
+bash scripts/deploy.sh
+
+# 自定义安装目录
+bash scripts/deploy.sh --target=/path/to/install
+
+# 跳过前端构建（已有 dist/）
+bash scripts/deploy.sh --skip-build
+```
+
+**deploy.sh 执行流程**：
+1. 前置检查（Python/PM2/源码目录）
+2. 前端构建（npm install → npm run build）
+3. 创建安装目录
+4. rsync 同步代码（排除 data/logs/inbox/config/docs/tests）
+5. 确保目录结构（data/logs/inbox/config）
+6. 首次创建默认配置（不覆盖已有）
+7. PM2 start（首次）
+8. 前端 + 后端健康检查
+9. 输出结果
+
+**排除项**（不部署到生产）：
+- `docs/` — 设计文档只存开发目录
+- `tests/` — 测试代码不需要在生产环境
+- `scripts/` — 脚本从开发目录执行
+- `config/` — 不覆盖用户配置
+- `data/` `logs/` `inbox/` — 运行时数据
+- `frontend/src/` `node_modules/` — 只需要 dist/
+
+### 场景 2：日常升级（代码更新后）
+
+**触发**：开发目录有代码变更，需要更新生产环境
+
+```bash
+# 标准升级（自动构建前端 + 重启）
+cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v2
+bash scripts/deploy.sh
+
+# 仅后端改动，跳过前端构建
+bash scripts/deploy.sh --skip-build
+```
+
+**deploy.sh 自动检测**：
+- 安装目录已存在 → PM2 restart（而非 start）
+- 不覆盖 `config/` 和 `data/`
+- 健康检查确认服务正常
+
+### 场景 3：查看运行状态
+
+```bash
+# 简要状态
+bash scripts/status.sh
+
+# 详细状态（项目列表、任务数、磁盘占用）
+bash scripts/status.sh -v
+```
+
+**输出示例**：
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  moziplus v2 — Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Version:   v3.0.0
+  Install:   ~/.sanguo_projects/sanguo_moziplus_v2 ✅
+  PM2:       online ✅
+  PID:       19591
+  Restarts:  18
+  Memory:    49.6MB
+  Health:    running ✅
+  Ticks:     106
+  Projects:  26
+  Data size: 23M
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 场景 4：前端独立构建
+
+**触发**：只改了前端代码，不需要完整部署
+
+```bash
+bash scripts/build-frontend.sh
+# 产物在 src/frontend/dist/
+# 然后用 deploy.sh --skip-build 同步
+```
+
+### 场景 5：数据备份
+
+```bash
+# 在线备份（不停服务，SQLite 可能有不一致快照，日常可接受）
+bash scripts/backup.sh
+
+# 一致性备份（停服务）
+bash scripts/backup.sh --stop
+
+# 指定 NAS 路径
+bash scripts/backup.sh --nas=/Volumes/stock
+```
+
+**备份策略**：
+- 目标：NAS `/Volumes/stock/moziplus-v2-backups/backup-<timestamp>/`
+- 内容：data/ + config/ + metadata.json
+- 自动保留最近 10 个备份
+- metadata.json 记录时间、版本、是否停服务
+
+### 场景 6：数据重置
+
+**触发**：测试数据污染、需要干净环境
+
+```bash
+# 预览（不加 --confirm 只显示会做什么）
+bash scripts/reset-data.sh
+
+# 清空所有数据
+bash scripts/reset-data.sh --confirm
+
+# 只清指定项目
+bash scripts/reset-data.sh --project=demo --confirm
+bash scripts/reset-data.sh --project=demo,e2e-test --confirm
+```
+
+**安全保护**：
+- 必须传 `--confirm`，否则只预览不执行
+- 停服务 → 清数据 → 重启
+- trap EXIT 确保异常时也恢复服务
+- 保留 config/ 配置
+
+### 场景 7：完全卸载
+
+**触发**：不再使用 moziplus v2
+
+```bash
+# 预览
+bash scripts/uninstall.sh
+
+# 完全删除（含数据）
+bash scripts/uninstall.sh --confirm
+
+# 保留数据
+bash scripts/uninstall.sh --confirm --keep-data
+```
+
+**安全保护**：
+- 必须传 `--confirm`
+- `--keep-data` 将 data/ 移动到 `~/moziplus-v2-data-backup-<timestamp>/`
+- PM2 delete + save
+
+---
+
+## 4. 典型工作流
+
+### 日常开发 → 部署循环
+
+```
+开发目录修改代码
+    ↓
+git commit（sanguo-git-sync 自动推送到 gitee）
+    ↓
+bash scripts/deploy.sh
+    ↓
+bash scripts/status.sh（确认正常）
+    ↓
+继续开发 或 测试验证
+```
+
+### 版本发布
+
+```
+1. 开发目录完成功能 + 测试
+2. 司马评审通过
+3. 更新 pyproject.toml 版本号
+4. git tag + git push
+5. bash scripts/deploy.sh
+6. bash scripts/backup.sh --stop（发布前备份）
+7. bash scripts/status.sh -v（确认）
+```
+
+### 故障恢复
+
+```
+1. bash scripts/status.sh（确认问题）
+2. pm2 logs sanguo-moziplus-v2（查看日志）
+3. 如需回滚数据：从 NAS 恢复备份
+4. 如需回滚代码：git revert → bash scripts/deploy.sh
+5. 如 v2 不可用：pm2 stop sanguo-moziplus-v2，切回 v1(8082)
+```
+
+---
+
+## 5. 脚本参数速查
+
+### deploy.sh
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--source=DIR` | 开发目录 | 源码目录 |
+| `--target=DIR` | `~/.sanguo_projects/sanguo_moziplus_v2` | 安装目标 |
+| `--skip-build` | false | 跳过前端构建 |
+
+### status.sh
+| 参数 | 说明 |
+|------|------|
+| `-v, --verbose` | 显示项目详情、配置信息 |
+
+### build-frontend.sh
+无参数。自动检测 package-lock 变化并安装依赖。
+
+### backup.sh
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--target=DIR` | 安装目录 | 数据源 |
+| `--nas=DIR` | `/Volumes/stock` | NAS 挂载点 |
+| `--stop` | false | 备份前停服务 |
+
+### reset-data.sh
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--target=DIR` | 安装目录 | 目标 |
+| `--project=NAME` | 全部 | 指定项目（逗号分隔） |
+| `--confirm` | false | **必须传** |
+
+### uninstall.sh
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--target=DIR` | 安装目录 | 目标 |
+| `--keep-data` | false | 保留数据到备份目录 |
+| `--confirm` | false | **必须传** |
+
+---
+
+## 6. 与旧部署文档的关系
+
+本文档替代以下旧文档：
+- `deployment-v2.6.md` §6 部署流程 → 改用 `deploy.sh`
+- `deployment-v2.6-guide.md` 全文 → 改用脚本 + 本文档场景说明
+- `deployment-v2.6.md` §13 运维场景手册 → 改用 `status.sh` + `backup.sh` + `reset-data.sh`
+
+旧文档保留作为架构参考，不删除。