MediaStack Node Agent

MediaStack Node Agent 完整规划方案，包含架构设计、模块划分、任务执行机制、容错与安全策略，确保系统具备 高可靠性、可扩展性、可维护性。

---

🧱 MediaStack Node Agent 完整规划方案

---

✅ 一、设计目标

目标	描述
模块化架构	各功能为独立模块，支持后期插拔扩展
节点无用户系统	使用安装生成的 API KEY 接收主控指令，节点不自持用户
API 控制式执行	所有操作由主控系统 API 请求触发，节点为被动执行器
幂等性保障	避免任务重复执行的副作用
虚拟环境部署	使用 Python venv，避免污染系统环境
稳定性高	抵抗网络抖动、节点故障、任务重发等异常情况
易于监控与告警	节点支持健康上报、容量预警、服务进程检测等

---

✅ 二、整体架构概览

            ┌────────────────────┐
            │     主控系统       │
            └────────┬───────────┘
                     │ 通过 API 请求任务
                     ▼
           ┌──────────────────────┐
           │  MediaStack 节点Agent │
           └──────────────────────┘
                     │
     ┌────────┬──────┼───────┬────────┐
     ▼        ▼      ▼       ▼        ▼
  Auth     FTP    NGINX     FS     Monitor
           模块    模块     模块     模块（告警、进程）

---

✅ 三、模块划分

🧩 基础模块

模块	功能
auth	API Key 校验、签名校验（可选）
ftp	管理 Pure-FTPD 用户、目录、权限等
nginx	创建虚拟主机、绑定目录、配置 SSL
fs	目录管理、权限设置
stats	实时查询节点资源状态：CPU / 内存 / 磁盘等

🔌 可选扩展模块

模块	功能
monitor	检测磁盘使用率、nginx/pure-ftpd 存活
alert	容量/服务异常时主动上报主控系统
queue	异步慢任务处理（如全量统计）
log	本地记录任务执行历史、状态、失败原因
backup	文件备份或快照（未来可扩展）

---

✅ 四、任务处理流程

主控系统 → 节点API（带 API_KEY + REQUEST_ID）
                   ↓
           节点校验签名和任务ID
                   ↓
           判断是否已执行 → 是：直接返回状态
                   ↓ 否
           执行模块任务（幂等）
                   ↓
           成功：返回结果并记录
           失败：返回错误 + 本地记录 + 可选上报主控

---

✅ 五、幂等性机制

场景	处理方式
创建 FTP 用户	若存在则跳过/更新
建立目录	os.makedirs(path, exist_ok=True)
配置 NGINX	比较配置文件 hash，仅在变更时 reload
重复任务	使用 request_id 检查执行记录避免重复执行

---

✅ 六、故障与容错机制

问题	解决方案
网络抖动	主控请求重试（3次 + 超时限制）
节点离线	主控心跳失联判断为“不可用”
执行失败	节点上报失败状态 + 主控决定是否重试
服务异常	monitor 检查 NGINX / Pure-FTPD，自动上报主控

---

✅ 七、健康检查与上报机制

主动健康上报（建议）

节点每 60 秒向主控发送如下信息：

{
  "node_id": "node-xxx",
  "time": 1728069999,
  "status": {
    "cpu_load": 0.3,
    "disk_usage_percent": 82.4,
    "nginx_status": "running",
    "pureftpd_status": "stopped"
  }
}

主控可据此做：

• 节点状态打标
• 自动告警或切换节点

---

✅ 八、安全设计

机制	说明
API Key 验证	所有请求需携带节点的 X-API-KEY
时间戳签名（可选）	限制请求有效期，防止重放攻击
IP 白名单（可选）	限制只允许主控 IP 访问
本地日志脱敏	日志中不得记录密码/证书内容

---

✅ 九、部署规范

要点	推荐做法
Python 虚拟环境	python3 -m venv /opt/mediastack-node/venv
模块安装	使用 pip install -r requirements.txt
启动方式	推荐 systemd 服务，或 docker 启动
配置文件	config.yaml 控制端口、API_KEY、启用模块等

示例 systemd：

[Unit]
Description=MediaStack Node Agent
After=network.target

[Service]
ExecStart=/opt/mediastack-node/venv/bin/python /opt/mediastack-node/main.py
WorkingDirectory=/opt/mediastack-node
Restart=always

[Install]
WantedBy=multi-user.target

---

✅ 十、后续扩展能力建议

方向	建议
模块热加载	主进程不重启即可启用新模块（可监测 config 变动）
插件机制	使用统一入口接口，动态发现 modules/*.py
控制端 SDK	提供主控系统调用节点的 Python SDK
节点分组调度	为主控支持“只调度某组节点”做准备
多级任务确认	关键任务增加“执行成功回调确认”机制

---

如你需要，我可以进一步输出：

• 完整的项目目录结构模板（FastAPI + 模块）
• 示例任务执行模块（如 FTP / NGINX / monitor）
• 一键安装部署脚本模板

是否现在需要我开始生成这些内容？或者先从哪一块开始写？