跳转至

集群部署与排障

本文是实际实现的操作入口。集群系统调用契约参见 01-abi.md,用户态服务架构参见 05-userspace.md。

可选的远程页服务独立配置、默认关闭;只读/可写模式、容量与流量限制、初始文件和客户端 API 参见 runtime-ssi.md。它提供显式页快照和原子提交,不会自动给普通进程建立跨机共享地址空间。

普通 Linux pthread 的自动跨机执行与透明缺页参见 runtime-ssi.md。该功能有独立的默认关闭开关与资源限制,当前为 x86_64/UP 的串行交接实验模式,尚不提供同进程多机并行加速;worker 需要 a20.tcpmode=lwip。

1. 部署前提

每台机器有唯一持久 128 位 node_id,每次启动有非重复 boot epoch。完整主机从显式持久配置恢复身份与种子,STM32 从 UID 和两页 Flash journal 生成身份/epoch。IP、UART 短地址、服务槽位都不代替持久身份。

角色 配置 role 能力与职责
Native 执行节点 worker RELIABLE;运行 agent、clusterd,可选 jobd
UDP/UART 网关 relay RELAY+RELIABLE;转发原来源事务,可同时执行任务
静态 MCU 板级 leaf LEAF+RELIABLE;预置算子、单缓存、专用 UART 周期泵

MCU 不加载 ELF、不运行文件配置监管者;它与完整主机使用相同 CL/CW 协议和能力查询。不同资源档改变容量,不改变算子结果或事务语义。

2. 构建与启动

make ARCH=riscv64 native-cluster-agent
make ARCH=x86_64 CLUSTER_UART_COM2=1 dev-build
PATH=/path/to/arm-toolchain/bin:$PATH make ARCH=armv7m BOARD=stm32f103 \
  STM32_FLASH_KB=64 STM32_RAM_KB=20 STM32_CLUSTER_PORT=2 kernel-only

按实际机器替换配置中的 ID、种子地址和架构二进制后,持久保存配置。示例见docs/assets/cluster/configs/worker-rv.conf 与 relay-x86_64.conf。在目标 Native 环境:

/bin/cluster-supervisor-rv /bin/cluster.conf
/bin/cluster-wordcount-rv /tmp/input.txt

监管者预先验证配置与全部服务镜像,再设置不可变身份、安装种子、启动服务。同一系统只能有一个 cluster.supervisor。每个子服务独立退避重启;监管者本身由 init/外层管理器或操作者启动和恢复,仓库没有自动替换所有架构的 init 策略。进程任务的可执行路径来自本地清单,不能通过网络传入任意路径或本机句柄。

STM32 控制台为 USART1,集群为 USART2(PA2/PA3)或 USART3(PB10/PB11);头节点 COM2 为 115200、8N1。双方使用原始二进制字节,不能启用终端换行转换。具体固件参数与节点身份生成参见 mcu-shared-kernel.md 及 04-transports.md。升级固件不能擦除持久 epoch 区后继续使用原 node_id;维护时需重新生成节点会话与身份配置。

业务单向接收需要在相关端点和中继升级后显式启用 feature oneway,服务以 A20_EXPORT_ONEWAY 导出;MCU 则在首次握手前注册静态 sink。默认配置不激活新增能力位。成功发送只保证本地入队,应用须观察自己的业务完成条件后再关闭连接。完整契约参见 02-wire-protocol.md。

3. 拓扑与发现

只把实际邻居配置为 metric=0 种子。完整互联适合少量主机;树形拓扑适合串口 leaf 和网关。间接目的的路由由已确认邻居传播,不把所有节点伪装成同一个直连链路地址。网关必须有 RELAY,双方都要有到原来源/目的的返回路径。

clusterd 先确认邻居,再传播有界成员页和租约路由;目录与能力仍通过真实端点查询验证。显式路由优先于动态路由,租约清理只条件删除自己拥有的 tuple。服务 any 只选择 ALIVE、租约有效且输入/算子能力匹配的实例;轮询不保证单个作业均匀覆盖所有节点。来源表、服务表和路由表满时拒绝新增,不逐出仍在保护的去重记录。MCU 最多 8 个间接来源、一个在途回复缓存。

完整 UDP 路径可按双方资源档分片;经过 UART 的路径退回 256 B 单帧,可靠请求/回复业务上限分别为 206/202 B。切片还要减去 CW 头,并检查算子能力。不要依据服务器的本地 RAM 向 MCU 发送超限消息。相关协商参见 02-wire-protocol.md 及 04-transports.md。

4. 排障顺序

现象/步骤 检查入口 判定与处理
本机服务未出现 cluster_snapshot(EXPORT)、监管者本地状态 检查路径、启用项、退出原因与退避时间
远端连接失败 cluster_link_status DOWN 检查种子地址、串口引脚、握手双方 ID;SUSPECT 检查心跳进展
链路正常仍不可达 cluster_snapshot(ROUTE) 检查目标完整 ID、下一跳、RELAY、返回路由、动态租约
目录解析超时 CD/1、CM MEMBER、CS 会话 检查最终 epoch、CS cookie 挑战、服务目录刷新;不能复用旧 boot 绑定
服务名找到但调用失败 CW QUERY 和 Native 资源快照 比较输入/输出、算子 ID、budget、max_inflight 与路径 MTU
大消息不进展 cluster_snapshot(kind=4) 检查分片资格、重组拒绝/超时、槽位和字节峰值
偶发缓存忙 kind=3、重试/收据统计 查看未接纳重试与放弃收据;MCU 单缓存不得被强制逐出后重复执行
链路存在但丢帧增长 cluster_snapshot(kind=5) 分开查看 malformed、策略 drops 与重传;核对 CRC、身份/地址绑定和 TTL
停止后资源仍增长 kind=3 与 /proc/a20/task_lifetime 分别检查代理/重试字节归零、任务和僵尸恢复;回复保留内存不等同泄漏

Native SDK 包装为 a20_cluster_resources、a20_cluster_reassembly_resources和 a20_cluster_link_resources,计数口径与故障复现参见 01-abi.md 及验收测试。

性能入口会占用正在测量的镜像,运行期间不要重打包同一构建变体。监管状态服务 LOCAL_ONLY;它返回统计,不能用于远程执行管理命令。当前没有完整交互式 clusterctl,以上检查应通过 SDK 或已提供的验收程序执行。

5. 恢复与升级

agent 重启后服务 slot 更新,同一内核 epoch 不变;客户端重新解析服务。 clusterd 重启从内核快照恢复,已有业务连接继续工作。节点重启 epoch 改变,旧绑定取消,必须重新确认和连接。jobd 根故障终止作业,没有持久作业日志;重复 CJ 提交会创建新作业。对不确定失败,只有明确 REPLAY_SAFE 的算子可以重派,进程任务不能自动重派。关闭调用只是放弃结果,不承诺终止远端回调。

升级保留 wire v0 金样与 v1 协商兼容;新旧 CS 混合路径降级单帧。先验证独立 leaf/网关小拓扑,再逐批升级完整主机。不能用升级操作重置身份或清除持久 epoch 来绕过旧会话检查。无硬件实测时,固件成功链接不能代替 Flash、电气和持续运行验收。

6. 验证与部署边界

make check-cluster-unit check-cluster-fuzz
make smoke-native-cluster smoke-native-cluster-supervisor
make check-cluster-reliable check-cluster-mesh
make check-cluster-hardening
python3 tools/cluster/check-cluster-gateway.py --gossip --abandon
make demo-wordcount

同一镜像变体的构建、打包和 QEMU 检查应顺序执行;运行中不能改写其基础镜像。每个检查器自己的产物目录保留配置、日志及源文件哈希。

CRC 检测损坏,邻接地址绑定与 CS 挑战抵抗旧会话重放;它们不提供密码学身份、机密性或敌对网络完整性。当前信任边界为受控 LAN/专用串口。开放网络需要已认证的外层通道或后续认证协议,不能把现有部署描述为自带加密的安全集群。生产环境长期运行吞吐与物理板验收需配合实际基准单独记录。