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

# 从开发目录部署
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：日常升级（代码更新后）

触发：开发目录有代码变更，需要更新生产环境

# 标准升级（自动构建前端 + 重启）
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 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 scripts/build-frontend.sh
# 产物在 src/frontend/dist/
# 然后用 deploy.sh --skip-build 同步

场景 5：数据备份

# 在线备份（不停服务，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：数据重置

触发：测试数据污染、需要干净环境

# 预览（不加 --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 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

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