sanguo_moziplus_v2/docs/design/deployment-scripts.md

# 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`

旧文档保留作为架构参考，不删除。