第 8 篇：部署清单驱动架构——用“期望状态“统一管理边缘节点上的一切

边缘节点上有几十个模块。它们该创建、该删除、该升级------由云端统一决策。但边缘网络不稳定，云端命令随时可能丢失。本文设计一套"主动拉取 + 全量 Diff + 事件分发"的架构，让边缘节点在任何网络条件下都能准确执行云端的意图。

一、开篇场景：云端说"停"，边缘还在跑

云端管理员在管理平台上点击了"停止模块 A"。

方案一：云端直接推送命令 ------POST /edge-node/command { action: "stop", module: "A" }。问题：边缘节点此时恰好 4G 信号弱，这个 HTTP 请求丢了。云端不知道丢没丢，边缘不知道自己该停。两边状态彻底不一致。

方案二：云端不推送命令，改为维护一份"期望状态清单"。清单上说"所有模块的期望状态如下"。边缘节点每隔 5 分钟来拉一次清单，对比自己当前的实际情况，自动把不一致的纠正过来。

方案二看起来比方案一"重"------每次拉的是全量清单，不是增量命令。但这正是它在弱网下可靠的原因：

对比维度	推送增量命令	拉取全量清单
命令丢失风险	高（网络不可靠）	低（周期拉取，总有一次能成功）
状态一致性	差（部分命令丢失后系统状态不明）	好（每次拉取都是完整期望状态）
幂等性	需要单独设计	天然幂等（全量 Diff 重复执行结果一样）
云端压力	低	中（需缓存全量清单）

这一篇，我们就来设计这套"部署清单驱动"的完整架构。

二、概念铺垫：声明式管理 vs 命令式管理

这是整个控制面设计的哲学根基。

命令式："停掉模块 A，然后删除模块 B，最后创建模块 C 的 v2.0。"------如果执行到一半断电了，你无法知道"到底停了 A 没有、删了 B 没有"。

声明式："最终状态应该是：A 停止、B 不存在、C 运行 v2.0。"------系统自己决定怎么达到这个状态，你只需要告诉它"终点在哪"。

Kubernetes 的 Controller 模式就是声明式管理的典范。你写一个 Deployment YAML 描述期望状态（3 个 Pod、用 v2 镜像），Controller 不断对比当前状态和期望状态，不一致就纠正。我们的部署清单驱动的思路与之完全一致，只是把"集群调度"换成了"边缘模块编排"。

通用原理 ：声明式 vs 命令式是编程语言理论的基础概念。你在学校里写 SQL（SELECT name FROM users WHERE age > 18------声明"要什么"）和 HTML（声明页面结构）时就在用声明式。它的核心优势是幂等性 ------声明式描述反复执行结果不变（全量 Diff 天然幂等），命令式序列反复执行可能有副作用（"先删再建"不能安全地重复执行）。分布式系统选择声明式的根本原因：在不可靠网络上，幂等操作比非幂等操作可靠一万倍。

核心数据结构------部署清单（Deploy Manifest）

go 复制代码

// 部署清单 = 云端对这个边缘节点的完整期望
type DeployManifest struct {
    DeployID      string          // 清单版本号，变了说明有新版本
    NodeID        string          // 目标节点
    UpdateTime    int64           // 云端最后修改时间（Unix 毫秒）
    SystemModules []ModuleConfig  // 系统模块（如 DeployMaster、MessageHub）
    Modules       []ModuleConfig  // 业务模块
}

// 一个模块的完整定义
type ModuleConfig struct {
    ModuleID   string            // 模块唯一标识
    Version    string            // 期望版本
    Image      string            // 镜像/包地址
    Type       string            // "docker" / "process"
    Status     ModuleStatus      // 期望状态：Running / NotRunning
    UpdateTime int64             // 模块配置最后修改时间
    Envs       map[string]string // 环境变量
    Resources  ResourceConfig    // CPU/内存限制
    Volumes    []VolumeConfig    // 挂载卷
    Ports      []PortConfig      // 端口映射
}

三、方案设计：从拉取到执行的全链路

3.1 整体数据流

复制代码

云端 EdgeManager
  │
  │  维护部署清单，用户修改后更新 UpdateTime
  │
  ▼
┌──────────────────────────────┐
│  影子拉取器 (ShadowPuller)    │  300s 周期 + 首次随机延迟 10~60s
│  从云端 GET /deployment       │  拿到最新 DeployManifest
└──────────┬───────────────────┘
           ▼
┌──────────────────────────────┐
│  清单处理器 (ManifestHandler) │
│                               │
│  1. 校验清单有效性             │
│  2. 幂等检查（deployID 没变？）│
│  3. 新旧全量 Diff             │
│  4. 生成 ModuleEvent          │
│     · CreateModules [C, D]    │
│     · UpdateModules [A]       │
│     · DeleteModules [B]       │
└──────┬───────────┬───────────┘
       │           │
       ▼           ▼
┌──────────┐ ┌──────────────┐
│ 模块监控器│ │ 升级编排器    │
│ (负责生命 │ │ (负责升级的  │
│  周期管理)│ │  探针和卡点) │
└──────────┘ └──────────────┘

3.2 影子拉取器------主动拉取 + 防惊群

为什么是 300 秒间隔？这是"云端部署指令的最长生效延迟"和"云端 API 负载"之间的平衡。300 秒意味着用户修改部署配置后，最长等 5 分钟才能生效------对于边缘场景（非实时交易），这是可接受的。

首次启动时延迟 10~60 秒随机值------防止大规模断电恢复后，数万个节点同时向云端发起请求。

go 复制代码

type ShadowPuller struct {
    interval    time.Duration // 300s
    initialJitter time.Duration // 10~60s 随机
    cloudClient *CloudClient
    handler     *ManifestHandler
}

func (s *ShadowPuller) Start() {
    // 首次拉取加随机延迟，防止多节点同时请求
    initialDelay := time.Duration(rand.Intn(50)+10) * time.Second

    time.AfterFunc(initialDelay, func() {
        s.pull() // 首次拉取
        ticker := time.NewTicker(s.interval)
        for range ticker.C {
            s.pull() // 周期拉取
        }
    })
}

func (s *ShadowPuller) pull() {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    manifest, err := s.cloudClient.GetDeployManifest(ctx)
    if err != nil {
        // 拉取失败，记录日志，等待下次周期重试
        log.Errorf("拉取部署清单失败: %v", err)
        return
    }

    // 交给处理器对比和分发
    s.handler.Handle(manifest)
}

3.3 清单处理器------全量 Diff 的核心

这是整个部署驱动架构最关键的算法。

go 复制代码

type ManifestHandler struct {
    db          *DeployRepo     // 本地持久化旧清单的数据库
    moduleMgr   *ModuleMonitor   // 下游 1：生命周期管理
    upgradeMgr  *UpgradeOrchestrator // 下游 2：升级编排
    mu          sync.Mutex
}

func (h *ManifestHandler) Handle(newManifest *DeployManifest) {
    h.mu.Lock()
    defer h.mu.Unlock()

    // === 步骤 1：幂等检查 ===
    // deployID 没变 → 清单没有更新，跳过
    currentDeployID := h.db.GetCurrentDeployID()
    if currentDeployID == newManifest.DeployID {
        return
    }

    // === 步骤 2：从本地加载旧清单 ===
    oldManifest, err := h.db.GetLocalManifest()
    if err != nil {
        // 没有旧清单（首次启动）→ 全部视为创建
        h.notify(&ModuleEvent{
            CreateModules: merge(newManifest.SystemModules, newManifest.Modules),
        })
        h.db.SaveManifest(newManifest)
        return
    }

    // === 步骤 3：全量 Diff ===
    creates, updates, deletes := h.diffModules(
        oldManifest.AllModules(),
        newManifest.AllModules(),
    )

    // === 步骤 4：生成事件并分发 ===
    event := &ModuleEvent{
        CreateModules: creates,
        UpdateModules: updates,
        DeleteModules: deletes,
    }

    if event.IsEmpty() {
        // 没有变更，只更新 deployID
        h.db.UpdateDeployID(newManifest.DeployID)
        return
    }

    // 先通知下游执行变更，再持久化
    // 这个顺序的设计原因见下方的"边界与反模式"
    h.notify(event)
    h.db.SaveManifest(newManifest)
}

3.4 Diff 算法------不是简单的集合运算

go 复制代码

func (h *ManifestHandler) diffModules(
    oldModules, newModules []ModuleConfig,
) (creates, updates, deletes []ModuleConfig) {

    // 构建旧模块的索引：ModuleID → ModuleConfig
    oldMap := make(map[string]ModuleConfig)
    for _, m := range oldModules {
        oldMap[m.ModuleID] = m
    }

    // 构建新模块的索引
    newMap := make(map[string]ModuleConfig)
    for _, m := range newModules {
        newMap[m.ModuleID] = m
    }

    // 一、新有旧无 → 创建
    for id, newMod := range newMap {
        if _, exists := oldMap[id]; !exists {
            creates = append(creates, newMod)
        }
    }

    // 二、旧有新无 → 删除
    for id, oldMod := range oldMap {
        if _, exists := newMap[id]; !exists {
            deletes = append(deletes, oldMod)
        }
    }

    // 三、新旧都有 → 检查是否变更
    for id, newMod := range newMap {
        oldMod, exists := oldMap[id]
        if !exists {
            continue
        }
        // 关键判断：不是比较整个 ModuleConfig 是否相等
        // 而是比较 UpdateTime------只有云端明确修改了才更新
        if newMod.UpdateTime != oldMod.UpdateTime {
            updates = append(updates, newMod)
        }
    }

    return
}

为什么用 UpdateTime 而不是全字段对比？

因为部署清单是全量下发的。即使模块配置没变，每次全量下发的 JSON 里也会有字段出现（比如 Envs 的 key 排序可能不同）。用全字段对比会产生大量"假更新"。而 UpdateTime 是云端在用户真正修改配置时才更新的时间戳，用它来判断更准确、更高效。

3.5 事件分发------一人一个 Event

go 复制代码

type ModuleEvent struct {
    CreateModules []ModuleConfig
    UpdateModules []ModuleConfig
    DeleteModules []ModuleConfig
}

func (h *ManifestHandler) notify(event *ModuleEvent) {
    // 下游 1：ModuleMonitor ------ 负责模块生命周期的创建/启停/删除
    h.moduleMgr.OnModuleEvent(event)

    // 下游 2：UpgradeOrchestrator ------ 负责升级的探针和卡点
    // 只关心 UpdateModules（只有更新可能涉及版本变化）
    if len(event.UpdateModules) > 0 {
        h.upgradeMgr.OnModuleUpdate(event.UpdateModules)
    }
}

四、Go 核心骨架：全链路走一遍

go 复制代码

// ===== 云端（EdgeManager）=====

// 用户在管理平台上新增了一个模块
func HandleUserAddModule(nodeID string, newModule ModuleConfig) {
    // 1. 从数据库加载该节点当前的部署清单
    manifest := db.LoadManifest(nodeID)

    // 2. 将新模块添加到清单中，更新 UpdateTime
    newModule.UpdateTime = time.Now().UnixMilli()
    manifest.Modules = append(manifest.Modules, newModule)

    // 3. 更新清单的 deployID（自增或 UUID）
    manifest.DeployID = generateNewDeployID()

    // 4. 保存
    db.SaveManifest(manifest)

    // 不需要主动推送------边缘节点下次拉取时会自动拿到最新清单
}


// ===== 边缘节点（DeployMaster）=====

func (dm *DeployMaster) Start() {
    // 第一步：从本地数据库恢复上次的部署清单
    // （这是第 5 篇讲的 NodeCore 恢复保证的------SQLite 里存了上次的清单）
    lastManifest, err := dm.db.GetLocalManifest()
    if err == nil {
        // 恢复到内存缓存，ModuleMonitor 可以用它
        dm.cache.SetCurrentManifest(lastManifest)
    }

    // 第二步：启动影子拉取器，开始周期拉取云端最新清单
    dm.shadowPuller.Start()

    // 第三步：启动 ModuleMonitor，开始 5s 周期状态协调
    dm.moduleMonitor.Start()
}

// 清单处理器收到新清单后的完整调用链
//   shadowPuller.pull()
//     → manifestHandler.Handle(newManifest)
//       → diffModules(old, new) → ModuleEvent{Creates:[C,D], Updates:[A], Deletes:[B]}
//         → moduleMonitor.OnModuleEvent(event)
//           → handleCreateList([C,D]) → 为 C 创建 Runner + 拉镜像 + 启动 FSM
//           → handleUpdateList([A])   → 推送更新事件到 A 的 Runner
//           → handleDeleteList([B])   → 推送删除事件到 B 的 Runner, delete B
//
//         → upgradeOrchestrator.OnModuleUpdate([A])
//           → 检查 A 是否有升级探针 → 有则启动三阶段升级流程

五、边界与反模式

反模式一：用单独的命令接口代替部署清单

错误做法 ：云端暴露 /node/{id}/module/start、/node/{id}/module/stop、/node/{id}/module/delete 等独立接口，用户触发一个操作云端就推送一个命令。

为什么错：5 个独立操作会乱序到达、部分丢失。用户在云端点了"更新 A 的版本"，又立刻点了"删除 B"------两条命令是独立推送的，如果 A 的更新命令丢了、B 的删除命令到了，边缘上 B 被删但 A 还在旧版本。云端以为两件事都生效了，实际上 A 没有更新。

正确做法：云端只维护一份部署清单。用户的所有操作（创建/更新/删除/启停）最终都落到这份清单上。边缘拉取的是清单的快照，不会丢失、不乱序。

反模式二：先持久化再通知下游

错误做法：

go 复制代码

h.db.SaveManifest(newManifest)  // 先存数据库
h.notify(event)                  // 再通知下游执行

为什么这看起来对，但我们偏偏反着做？

因为边缘场景下，DB 写入可能因为磁盘 IO 慢而延迟（比如 SD 卡写入 200ms），而模块部署的时效性更强（用户期望点了"启动"后尽快看到效果）。更关键的是------即使部署成功但 DB 写入失败，下一次拉取清单时 diff 会重新检测到差异并重试（幂等）。但如果 DB 写入成功、部署失败（因为网络或资源问题），下次 diff 发现新旧清单一致就不再重试------变化被"吞"了。

所以我们的顺序是：先通知下游执行变更 → 再持久化。如果持久化失败，下次 diff 会发现不一致，重新重试部署（幂等安全）。

反模式三：一个节点多个 deployID

错误做法：允许多个管理员同时编辑同一个节点的部署清单，各自生成不同的 deployID。

为什么错：后编辑者的清单可能覆盖先编辑者的修改。管理员 A 加了模块 X、管理员 B 删了模块 Y------两份清单各自生成 deployID，哪个先被边缘拉到就"胜出"，另一个的修改被覆盖。

正确做法：部署清单在云端用乐观锁（version 字段）保护。每次修改时检查 version，冲突时提示用户刷新后重试。

六、小结

部署清单驱动架构的核心设计思想：

声明式优于命令式------告诉系统"终点在哪"，别事无巨细地指挥每一步
主动拉取优于被动推送------在弱网下，周期拉取的可靠性远超一次性的命令推送
全量 Diff 优于增量事件------全量对比天然幂等，不怕消息丢失、乱序
UpdateTime 是变更的唯一信号------别试图比较全字段，用时间戳做判断

下一篇，我们深入部署清单的下游------模块被标记为"需要变更"之后，怎样从当前状态安全地走到目标状态？这就引出了控制面最精彩的设计：有限状态机------状态环 + 步进表。

本文是《边缘平台架构沉思录：Go 架构推演与工程决策》系列的第 8 篇。