MediaCrawler/mac-agent-os-main/05_tools/10_dashboard/PLANS/DEPLOYMENT.md

多机部署与同步更新指南

版本: 1.1.0 | 最后更新: 2026-05-16 适用: AgentOS 联邦架构下所有主机

---

更新流程概览

本机 (Redmi-12C)                其他主机 (Mac mini / …)
┌──────────────────┐           ┌──────────────────┐
│ git add + commit  │           │                    │
│ git push          │──Gitee──▶│ git pull           │
│ (本机已就绪)       │           │ 停止旧服务          │
│                   │           │ 启动新服务          │
└──────────────────┘           │ (完成更新)          │
                                └──────────────────┘

---

一、本机提交（已完成）

变更清单：

文件	类型	说明
05_tools/09_ave/scripts/main.py	修改	dashboard 命令重定向到 10_dashboard/
05_tools/09_ave/scripts/lib/dashboard.py	修改	Python 3.9 兼容修复 (from __future__ import annotations)
05_tools/09_ave/scripts/dashboard/app.py	删除	迁出到 10_dashboard/
05_tools/09_ave/scripts/dashboard/static/index.html	删除	迁出到 10_dashboard/
05_tools/10_dashboard/	新增	系统级监控面板（完整模块）
03_knowledge/versions.json	新增	guardd 版本跟踪清单
10_dashboard/app.py	修改	v1.1.0 新增 /api/machines 联邦机器状态接口
10_dashboard/static/index.html	修改	新增「机器状态」面板（含在线/离线/磁盘/CPU）
requirements.txt	修改	新增 fastapi / uvicorn 依赖
05_tools/09_ave/scripts/composer/hybrid.py	新增	Sprint 2 口播+卡点融合
05_tools/09_ave/scripts/composer/speed_ramp.py	新增	Sprint 2 变速卡点引擎
05_tools/09_ave/scripts/asset_manager/	新增	素材资产管理
05_tools/09_ave/scripts/story_director/	新增	故事导演模块

---

二、其他主机同步步骤

在 每台 需要更新的主机上按顺序执行：

步骤 1：同步代码

cd ~/workbuddy-agent-os/agent-sync
git pull

预期结果：

• 05_tools/10_dashboard/ 目录出现（含 app.py / run.py / plugins/ 等）
• 05_tools/09_ave/scripts/dashboard/ 目录消失（已被删除）
• 05_tools/09_ave/scripts/main.py 更新（dashboard 命令）
• 05_tools/09_ave/scripts/lib/dashboard.py 更新（Python 3.9 修复）
• 03_knowledge/versions.json 出现（版本跟踪）
• 05_tools/10_dashboard/static/index.html 新增「机器状态」导航项
• requirements.txt 新增 fastapi / uvicorn（需重新安装依赖）

步骤 2：检查旧 Dashboard 进程（如已启动过）

ps aux | grep uvicorn | grep -v grep

如果有输出，说明旧 Dashboard 仍在运行，需要停止并重启。

步骤 3：停止旧服务

# 找到旧进程 PID（第二列数字）
ps aux | grep uvicorn | grep -v grep | awk '{print $2}' | xargs kill

⚠️ 旧 Dashboard 的路径 09_ave/scripts/dashboard/ 已被删除， 如果不停止，进程会报 FileNotFoundError。

步骤 4：启动新 Dashboard（使用 managed Python 3.13）

# 推荐使用 managed Python venv（避免 Python 3.9 兼容问题）
~/.workbuddy/binaries/python/envs/agent-os/bin/python \
  ~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard/run.py

或者简写为：

cd ~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard
~/.workbuddy/binaries/python/envs/agent-os/bin/python run.py

验证启动：

curl http://localhost:9988/api/health
# 预期: {"status":"ok","version":"1.0.0","plugins":{"ave":"available"}}

curl http://localhost:9988/api/machines
# 预期: {"machhes":[ ... ],"total":N} 显示联邦内所有主机状态

步骤 5：验证 guardd 正常运行（无需重启）

cat ~/workbuddy-agent-os/agent-local/runtime/guardd/last_run.json
# 确认所有 7 模块状态为 "ok"

guardd 本身未变化，无需重启。它会自动发现 versions.json，检测到 version 变更后写入事件。

---

三、启动方式参考（Dashboard）

新 Dashboard 支持三种启动方式：

# 方式 1: 通过 AVE 入口（推荐，自动处理路径）
cd ~/workbuddy-agent-os/agent-sync/05_tools/09_ave/scripts
~/.workbuddy/binaries/python/envs/agent-os/bin/python main.py dashboard

# 方式 2: 独立启动
cd ~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard
~/.workbuddy/binaries/python/envs/agent-os/bin/python run.py

# 方式 3: uvicorn 开发模式
cd ~/workbuddy-agent-os/agent-sync/05_tools/10_dashboard
~/.workbuddy/binaries/python/envs/agent-os/bin/uvicorn app:app --reload --port 9988

⚠️ 注意 Python 版本：系统默认 python3 为 3.9.6，不支持 X | Y 类型注解语法。 必须使用 managed Python 3.13.12 venv 路径，否则会报 TypeError。

---

四、故障排查

症状	原因	解决
`TypeError: unsupported operand type(s) for	`	使用系统 Python 3.9 运行
ModuleNotFoundError: No module named 'app'	uvicorn 找不到 10_dashboard/app.py	确保 CWD 在 10_dashboard/ 目录下
curl: (7) Connection refused	Dashboard 未启动	先执行启动命令
FileNotFoundError: dashboard/app.py	旧进程仍在运行	kill 旧 uvicorn 进程
guardd 未检测到版本更新	versions.json 不存在或格式错误	检查 03_knowledge/versions.json 是否存在且 JSON 有效

---

五、后续模块接入

当前仪表盘仅含 AVE 插件。后续模块（Matrix / guardd）接入方法：

# 1. 创建 10_dashboard/plugins/matrix.py
# 2. 实现 DashboardPlugin 基类
# 3. 在 app.py 的 _register_plugins() 中添加一行

详见 10_dashboard/PLANS/ARCHITECTURE.md。