Genapsed
AIGC by Qwen and loong，待审 @hexianglong
简介
发音：/dʒɛˈnæps-d/
—— “创世之初第一道苏醒的 脉冲 ，编织依赖的经纬、点燃组件的星火、汇聚日志的川流、守望异常的暗礁；它是贯穿万物的神经突触，亦是黄昏降临时最后熄灭的灯塔。”
系统主程序被加载后启动的第一个组件，用来检查环境是否满足其他组件依赖、检查更新、启动其他组件、管理插件、收集日志、异常退出、插件安装、系统和插件的更新等，同时负责系统各组件的通讯、权限管理。是系统的底层和核心组件之一。
命名来源
- Gen- → Genesis (γένεσις)：创世、起源——系统加载后第一个被唤醒的组件
- -aps- → Synapse (σύναψις)：突触——神经元间传递信号的最底层微观结构；隐喻本组件作为所有其他组件之间通讯、调度、依赖传递的基础通道
- -d → Daemon (Unix/Linux)：守护进程后缀——表明其以后台常驻服务形态运行，承担系统级监护与生命周期管理
对外接口
- 检查更新
- 安装更新
- 组件（插件）健康检查
- 系统、组件、插件历史日志
- 系统、组件、插件实时日志
- 重启插件
- 系统、组件、插件版本号
- 安装插件
- 更新插件源
- 获取插件信息
消息网关
系统各组件使用 MQTT 通讯，由 Genapsed 统一管理。对于大文件，存储在文件系统中并合理设置权限，在 MQTT 上传输路径由接收方读取。
MQTT Topic 设计规范
Topic 层级结构
everpast/<component>/<message_type>/[target]
| 层级 | 说明 | 示例 |
|---|---|---|
everpast | 固定根前缀，避免冲突 | everpast |
<component> | 源组件/插件标识 | genapsed, frigate, minilm, plugin.xxx |
<message_type> | 消息类型 | event, cmd, status, log, file |
[target] | 目标组件（可选，用于点对点通讯） | plugin.xxx |
Topic 定义
# 系统级
everpast/genapsed/status/normal/ # 系统状态广播
everpast/genapsed/cmd/critical/ # 系统控制指令
everpast/genapsed/log/low/ # 系统日志
# 组件级
everpast/frigate/event/high/ # Frigate 检测事件
everpast/frigate/status/normal/ # Frigate 运行状态
everpast/frigate/cmd/normal/ # 发往 Frigate 的指令
everpast/minilm/event/normal/ # LVM 事件生成
everpast/minilm/result/normal/ # LVM 识别结果
# 插件级
everpast/plugin.<id>/event/normal/ # 插件事件
everpast/plugin.<id>/status/normal/ # 插件状态
everpast/plugin.<id>/cmd/normal/ # 插件指令
消息格式规范
{
"msg_id": "[uuid-v4生成]",
"source": "frigate.cam01",
"target": "minilm",
"type": "motion_detected",
"priority": "high",
"timestamp": 1741000000,
"payload": {
"camera_id": "cam01",
"confidence": 0.95,
"file_ref": "/data/recordings/20260401_1200.mp4",
"thumbnail": "data:image/jpeg;base64,/9j/..."
},
"metadata": {
"requires_ack": true,
"ttl": 300,
"trace_id": "trace-uuid"
}
}
QoS 策略分级
| 消息类型 | QoS | 说明 |
|---|---|---|
| 控制指令 (cmd) | QoS 2 | 必须确保送达且仅一次 |
| 事件通知 (event) | QoS 1 | 允许重复但不可丢失 |
| 状态心跳 (status) | QoS 0 | 可丢失，最新状态优先 |
| 日志 (log) | QoS 0 | 可丢失 |
组件间通讯流程
- 组件 A 检测到事件，发布消息到
everpast/A/event/high - Genapsed 收到消息，根据路由规则转发到组件 B 的订阅 topic
- 组件 B 处理完成后发送 ACK 确认
- Genapsed 将 ACK 转发给组件 A
文件传输机制
对于需要传输大文件的场景：
- 写入：发送方将文件写入本地存储（如
/data/recordings/20260401_1200.mp4） - 发送引用：通过 MQTT 发送轻量级消息，包含文件路径引用
- 读取：接收方解析消息后，自行读取文件或通过 HTTP 下载
{
"event": "motion_detected",
"file_ref": "/data/recordings/20260401_1200.mp4",
"timestamp": 1741000000
}
插件安全
对于系统插件或经过认证的社区插件，可以直接在宿主机上运行（使用自己的虚拟环境）。 对于未经认证的插件，统一在一个 docker 容器中运行；用户可以强制插件在宿主机运行但需自行承担安全隐患。
对于需要传输大文件的场景，Genapsed 将文件拷贝到文件传输临时目录并设置权限，插件需在接收后复制文件到自己的数据目录并返回接收成功结果到 Genapsed，Genapsed 收到后从临时目录删除文件完成本次文件传输。
对于容器，每个容器有自己的临时目录；默认情况下，容器只挂载和使用属于自己的临时目录。
宿主机的传输临时目录对所有宿主机插件可读。对于可能传输敏感信息的插件可添加到额外用户（组）中使用安全临时目录，安全临时目录有更严格的权限管控，同时插件也需要被严格审核。
权限管理
Topic 权限隔离
# 每个插件只能：
# - 发布到自己的 topic: everpast/plugin.<id>/+/+
# - 订阅 genapsed 广播：everpast/genapsed/+/+
# - 订阅特定目标 topic: everpast/+/cmd/+/plugin.<id>
# Genapsed 可以：
# - 订阅所有：everpast/+/+/+/+
# - 发布到所有
消息确认与重试机制
- 重要消息设置
requires_ack: true - 发送方启动定时器，超时未收到 ACK 则重试（最多 3 次）
- Genapsed 负责跟踪未确认消息并告警
消息追踪
每个请求生成唯一 trace_id，贯穿所有组件，便于调试和故障定位。