Supervisor 系统管理组件设计

对应路线图阶段：系统部署测试期 → OS 镜像期
状态：设计稿
相关模块：Genapsed、操作系统层（systemd）、首次启动配置向导

1. 组件定位

Supervisor 是 Everpast 系统管理层面的守护进程，仅在 Everpast OS 集成部署中存在。它负责填补 Genapsed（应用层守护进程）和操作系统之间的管理空白。

发音建议：/ˈsuːpərvaɪzər/
命名来源：沿用 Unix/Linux 系统中"supervisor"作为安全管理守护进程的经典命名法。
同时对标 Home Assistant Supervisor 的职责层次——"系统"在前，"应用"在后。

1.1 一句话定义

Supervisor 是 Everpast 的操作系统管理层守护进程：管服务、管网络、管存储、管更新，但不参与任何应用层业务逻辑。

1.2 什么时候需要 Supervisor？

部署方式	是否需要 Supervisor	说明
`pip install` 或 `docker run`	不需要	用户自行管理系统和网络，Genapsed 直接运行
Everpast OS（虚拟机镜像）	需要	Supervis or 随系统启动，负责首次配置和系统管理
树莓派 / 单机部署包	需要	用户不需要 Linux 运维经验，Supervisor 代管一切

2. 设计目标与非目标

2.1 设计目标

系统层与应用层职责分离
Genapsed 管理应用组件和插件，Supervisor 管理系统服务和硬件资源。二者职责不重叠，不互相依赖核心逻辑。
无运维经验的用户也可用
首次启动时 Supervisor 提供 Web 配置向导，引导用户完成网络设置、摄像头添加、插件选择等初始化流程。
安全可靠的系统管理
系统更新支持版本化回滚；服务崩溃时自动自愈；磁盘不足时提前预警。
可选可卸载
Supervisor 是可选组件，不强制任何部署场景使用。docker-compose up 部署的用户完全感受不到 Supervisor 的存在。
与 Genapsed 数据互通但不耦合
Supervisor 通过 MQTT 发布系统状态（磁盘、温度、服务健康），Genapsed 可以读取和展示，但 Genapsed 不依赖 Supervisor 运行。

2.2 非目标

不参与应用层消息路由
MQTT 消息的发布、订阅和转发由 Genapsed 全权管理，Supervisor 只作为一个普通组件发布自己的状态消息。
不管理插件生命周期
插件的安装、卸载、更新、权限由 Genapsed 的插件管理器负责。Supervisor 只保证 Genapsed 进程本身正常运行。
不负责摄像头接入和视频处理
摄像头配置可以经由 Supervisor 的向导完成，但实际视频流接入和处理完全由 Frigate 和 Genapsed 管理。
不替代用户手动管理系统的能力
Supervisor 不锁定系统，用户仍可通过 SSH 或终端直接管理 Linux 系统。

3. 职责边界

3.1 职责总览

职责	说明	对应功能模块
系统服务管理	管理 Genapsed 等核心组件的 systemd 启停、状态监控和自愈	`service_manager`
网络配置	WiFi 扫描与连接、静态 IP、网桥配置	`network_manager`
存储管理	磁盘分区、存储池初始化、录像目录挂载与健康监控	`storage_manager`
系统更新	检查 OS 镜像更新、下载、安装、回滚	`update_manager`
首次配置向导	全新安装时引导用户完成初始化	`setup_wizard`
系统监控	CPU 温度／磁盘／内存／服务状态上报	`monitor`
系统恢复	配置重置、升级失败回退、恢复出厂设置	`recovery`

3.2 系统服务管理（service_manager）

Service Manager 负责管理 Genapsed 及其他核心组件的 systemd 服务。

主要能力：

在首次启动时注册 Genapsed 的 systemd unit 文件；
监控各核心服务运行状态（active / failed / stopped）；
服务崩溃时自动重启（Restart=always），连续崩溃3次以上则停止重试并告警；
对外提供 API：start / stop / restart / status / logs；
配置开机自启选项。

3.3 网络配置（network_manager）

Network Manager 负责系统网络的配置与管理。

主要能力：

扫描并列出可用 WiFi 网络；
连接/断开 WiFi，支持 WPA2/WPA3；
配置静态 IP 或 DHCP；
配置 DNS；
配置网桥（用于摄像头隔离网络）；
对外提供 API：scan / connect / disconnect / status。

实现建议：底层通过 nmcli 或 iwctl 调用系统网络管理器，不直接操作 netlink。

3.4 存储管理（storage_manager）

Storage Manager 负责磁盘和存储的管理。

主要能力：

列出可用磁盘和分区；
格式化和挂载存储分区；
初始化录像存储目录并设置权限；
监控磁盘使用率，超过阈值时预警；
支持存储迁移（从一块磁盘迁移到另一块）。

3.5 系统更新（update_manager）

Update Manager 负责 OS 级更新的检查和应用。

主要能力：

检查 Everpast OS 镜像更新（连接更新服务器）；
下载更新包并校验完整性；
安装更新（支持 A/B 分区无中断升级或停机升级）；
更新失败时回滚到上一个版本；
对外提供 API：check / install / rollback / status。

3.6 首次配置向导（setup_wizard）

Setup Wizard 在全新启动的 Everpast OS 上自动运行，引导用户完成初始化。

流程：

系统启动 → Supervisor 启动 → 检测到首次启动
                              ↓
                    启动 Web 配置向导（临时 HTTP 服务）
                              ↓
                    用户通过浏览器访问 http://everpast.local:8080
                              ↓
                    步骤 1：网络配置（WiFi 连接）
                    步骤 2：摄像头添加（扫描/手动添加）
                    步骤 3：存储配置（选择录像存储位置）
                    步骤 4：插件选择（推荐插件包选择）
                    步骤 5：创建管理员账户
                              ↓
                    配置完成 → 启动 Genapsed 进入正常模式
                              ↓
                    配置向导 Web 服务关闭

3.7 系统监控（monitor）

Monitor 负责收集系统级指标并通过 MQTT 发布。

发布 topic：everpast/supervisor/status/normal

{
  "source": "supervisor",
  "type": "system_health",
  "timestamp": 1741000000,
  "payload": {
    "cpu": {
      "temperature_celsius": 52.3,
      "load_percent": 23
    },
    "memory": {
      "total_gb": 8,
      "used_gb": 3.2,
      "available_gb": 4.8
    },
    "disk": {
      "total_gb": 256,
      "used_gb": 89,
      "available_gb": 167,
      "usage_percent": 35
    },
    "services": {
      "genapsed": "running",
      "frigate": "running",
      "mqtt": "running",
      "minivlm": "running"
    },
    "uptime_seconds": 24601
  }
}

3.8 系统恢复（recovery）

Recovery 模块为系统提供安全兜底能力。

场景	恢复方式
配置错误导致无法启动	通过恢复模式重置配置
系统更新失败	自动回滚到上一个版本
用户忘记管理员密码	恢复模式提供密码重置入口
磁盘损坏	提示用户更换存储介质，引导迁移

4. 与 Genapsed 的关系

4.1 职责二维矩阵

              系统层 (root)                    应用层 (user)
              ┌────────────────────┐           ┌────────────────────┐
              │   Supervisor        │           │   Genapsed          │
              │                     │           │                     │
              │  • systemd 管理     │           │  • MQTT 路由        │
              │  • 网络配置          │   通过    │  • 组件生命周期     │
              │  • 磁盘存储          │   MQTT    │  • 插件管理         │
              │  • 系统更新          │  互通     │  • 权限控制         │
              │  • 首次配置向导      │     │     │  • 配置管理(模块)   │
              │  • 系统监控          │           │  • 日志查询与管理   │
              └────────────────────┘           └────────────────────┘
                        │                               │
                        │       MQTT topic 通信         │
                        └───────────────────────────────┘

4.2 通信方式

Supervisor 与 Genapsed 的通信遵循系统统一的 MQTT 规范。

方向	Topic	内容	频率
Supervisor → Genapsed	`everpast/supervisor/status/normal`	系统健康状态	每 60 秒
Supervisor → Genapsed	`everpast/supervisor/event/high`	系统告警（磁盘满/温度高/服务崩溃）	触发时
Genapsed → Supervisor	`everpast/genapsed/cmd/normal/supervisor`	管理命令（如请求重启服务/触发更新检查）	按需
Supervisor → Genapsed	`everpast/supervisor/log/low`	系统日志	持续

关键原则：Supervisor 不订阅也不处理任何应用层 topic（不监听 everpast/frigate/+/+、everpast/minivlm/+/+、everpast/plugin.+/+/+ 等）。

4.3 启动时序

系统上电
  │
  ├── 1. 引导加载程序（Grub/U-Boot）
  ├── 2. Linux 内核启动
  ├── 3. initramfs → 根文件系统挂载
  ├── 4. systemd 初始化
  │
  ├── 5. Supervisor 启动 (root)
  │     ├── 首次启动？→ 运行配置向导
  │     └── 正常启动 → 监控系统服务
  │
  ├── 6. Supervisor 启动 MQTT Broker → 检查网络连通性
  ├── 7. Supervisor 启动 Genapsed
  │
  └── 8. Genapsed 接管应用层
        ├── 启动 Frigate
        ├── 启动 MiniVLM
        ├── 加载插件
        └── 打开 Web UI

5. 接口设计

5.1 MQTT Topic

Topic	方向	QoS	说明
`everpast/supervisor/status/normal`	→ Genapsed	0	系统健康状态心跳
`everpast/supervisor/event/high`	→ Genapsed	1	系统告警事件
`everpast/supervisor/log/low`	→ Genapsed	0	系统日志
`everpast/supervisor/log/normal`	→ Genapsed	1	系统错误/预警日志
`everpast/genapsed/cmd/normal/supervisor`	← Genapsed	2	管理命令

5.2 管理命令格式

{
  "msg_id": "uuid-v4",
  "source": "genapsed",
  "target": "supervisor",
  "type": "restart_service",
  "payload": {
    "service": "frigate"
  },
  "metadata": {
    "requires_ack": true,
    "trace_id": "trace-uuid"
  }
}

支持的命令类型：

命令	payload	说明
`restart_service`	`{ "service": "genapsed" }`	重启指定服务
`update_check`	`{}`	触发更新检查
`update_install`	`{ "version": "v1.2.0" }`	安装指定版本更新
`update_rollback`	`{}`	回滚到上一个版本
`disk_info`	`{}`	返回完整磁盘信息
`network_scan`	`{}`	扫描 WiFi 网络
`network_connect`	`{ "ssid": "...", "password": "..." }`	连接 WiFi
`network_status`	`{}`	返回网络状态
`reboot`	`{}`	重启系统
`shutdown`	`{}`	关闭系统
`factory_reset`	`{}`	恢复出厂设置

5.3 Web API（配置向导期间）

首次配置向导在 http://everpast.local:8080 提供临时 Web API：

端点	方法	说明
`/api/setup/status`	GET	获取配置向导进度
`/api/setup/network/scan`	GET	扫描 WiFi
`/api/setup/network/connect`	POST	连接 WiFi
`/api/setup/storage/disks`	GET	列出磁盘信息
`/api/setup/storage/init`	POST	初始化存储
`/api/setup/camera/scan`	GET	扫描局域网摄像头
`/api/setup/camera/add`	POST	添加摄像头
`/api/setup/plugins/available`	GET	查询可用插件包
`/api/setup/plugins/install`	POST	安装插件包
`/api/setup/admin/create`	POST	创建管理员账号
`/api/setup/complete`	POST	完成配置，启动系统

6. 配置项设计

Supervisor 的配置文件默认位于 /etc/everpast/supervisor.yaml。

supervisor:
  enabled: true

  mqtt:
    broker_host: "127.0.0.1"
    broker_port: 1883
    client_id: "supervisor"
    status_topic: "everpast/supervisor/status/normal"
    event_topic: "everpast/supervisor/event/high"
    cmd_topic: "everpast/genapsed/cmd/normal/supervisor"

  services:
    - genapsed
    - frigate
    - mosquitto
    - minivlm

  monitor:
    interval_seconds: 60
    cpu_temperature_threshold_celsius: 85
    disk_usage_warning_percent: 80
    disk_usage_critical_percent: 95
    memory_warning_percent: 85

  network:
    default_interface: "wlan0"
    fallback_to_dhcp: true

  updates:
    server_url: "https://update.everpast.cn"
    check_on_boot: true
    auto_update: false          # 默认关闭自动更新，用户可开启
    backup_before_update: true

  setup_wizard:
    enabled: true
    port: 8080
    auto_close_after_complete: true

7. 安全设计

最小权限原则
Supervisor 以 root 运行，但 Genapsed 以普通用户运行。Supervisor 通过 MQTT 接收 Genapsed 的管理命令，Genapsed 不能直接执行系统级操作。
命令认证
Supervisor 对 MQTT 命令消息进行来源校验，只处理来自 Genapsed 的已知 topic 的命令。
配置向导安全
首次配置向导的 Web 服务只监听 127.0.0.1:8080 和 everpast.local:8080（仅局域网可达），不暴露到公网。配置完成后自动关闭。
更新安全
更新包需经过 GPG 签名校验；下载通过 HTTPS；A/B 分区更新确保中断后仍可回滚。
恢复模式保护
恢复模式需要物理按键或串口触发，防止远程攻击者触发恢复操作。

8. 部署方案

8.1 Everpast OS（完整镜像）

分区布局：
┌───────────────────────┐
│ /boot                 │  ← 引导分区 (512MB)
├───────────────────────┤
│ / (root) - 分区 A     │  ← 主系统分区 (4GB ext4)
├───────────────────────┤
│ / (root) - 分区 B     │  ← 备用系统分区 (4GB ext4)
├───────────────────────┤
│ /data                 │  ← 录像与持久化数据 (剩余空间)
└───────────────────────┘

A/B 分区策略允许无中断升级：

当前运行在 A 分区
更新下载并安装到 B 分区
下次启动自动切换到 B 分区
如果 B 分区启动失败，自动回退到 A 分区

8.2 Docker 部署（无 Supervisor）

Genapsed 管理的基础设施 Compose:
  mysql:

应用服务 Compose（部署层编排）:
  genapsed:
  frigate:
  mosquitto:
  minivlm:
  timeline:
  query-engine:
  web-ui:

Docker 部署不需要 Supervisor。MySQL 等基础设施可由 Genapsed 生成项目内 Compose 文件管理，默认写入 data/genapsed/docker/compose.yaml，数据放在 data/db/mysql；应用服务的生命周期仍由部署层 Docker Compose 或系统服务管理。系统级管理（网络、存储、更新）由主机操作系统负责。

9. 路线图

阶段	内容	预计时间
原型期（当前）	Genapsed 直接用 systemd unit 管理自身服务；不开发 Supervisor	—
系统部署测试期	Supervisor 原型开发：service_manager + monitor + 基础 MQTT 通信	原型完成后
OS 镜像期	Setup Wizard + Network Manager + Storage Manager + Update Manager	部署测试完成后
成熟期	恢复模式、A/B 分区更新、多设备管理	长期迭代

10. 待确认问题

Supervisor 使用哪种编程语言实现？建议 Python（与 Genapsed 保持一致）还是 Go（更低的系统资源占用和更好的独立二进制分发）？
首次配置向导使用 Web 界面还是终端 TUI？Web 界面需要内嵌 HTTP 服务，初装时用户可能还没有安装浏览器（需通过手机访问）。
A/B 分区更新方案是否适用于树莓派 SD 卡场景？SD 卡空间和写入寿命限制可能影响方案选择。
Supervisor 和 Genapsed 之间的 MQTT 通信是否需要独立的内部 broker 连接？还是共用系统 MQTT Broker？

1. 组件定位​

1.1 一句话定义​

1.2 什么时候需要 Supervisor？​

2. 设计目标与非目标​

2.1 设计目标​

2.2 非目标​

3. 职责边界​

3.1 职责总览​

3.2 系统服务管理（service_manager）​

3.3 网络配置（network_manager）​

3.4 存储管理（storage_manager）​

3.5 系统更新（update_manager）​

3.6 首次配置向导（setup_wizard）​

3.7 系统监控（monitor）​

3.8 系统恢复（recovery）​

4. 与 Genapsed 的关系​

4.1 职责二维矩阵​

4.2 通信方式​

4.3 启动时序​

5. 接口设计​

5.1 MQTT Topic​

5.2 管理命令格式​

5.3 Web API（配置向导期间）​

6. 配置项设计​

7. 安全设计​

8. 部署方案​

8.1 Everpast OS（完整镜像）​

8.2 Docker 部署（无 Supervisor）​

9. 路线图​

10. 待确认问题​

1. 组件定位

1.1 一句话定义

1.2 什么时候需要 Supervisor？

2. 设计目标与非目标

2.1 设计目标

2.2 非目标

3. 职责边界

3.1 职责总览

3.2 系统服务管理（service_manager）

3.3 网络配置（network_manager）

3.4 存储管理（storage_manager）

3.5 系统更新（update_manager）

3.6 首次配置向导（setup_wizard）

3.7 系统监控（monitor）

3.8 系统恢复（recovery）

4. 与 Genapsed 的关系

4.1 职责二维矩阵

4.2 通信方式

4.3 启动时序

5. 接口设计

5.1 MQTT Topic

5.2 管理命令格式

5.3 Web API（配置向导期间）

6. 配置项设计

7. 安全设计

8. 部署方案

8.1 Everpast OS（完整镜像）

8.2 Docker 部署（无 Supervisor）

9. 路线图

10. 待确认问题