Huly Virtual Network 深入解析基于 ZeroMQ 的分布式容器网络架构与高可用实践【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform导读Huly Virtual Networkhcengineering/network-*系列包仓库位于 foundations/net是一套面向企业级分布式系统的虚拟网络架构它以 Network / Agent / Container 三层模型为基础配合 ZeroMQ 高速消息层、引用计数生命周期管理、标签化服务发现、多租户隔离与无状态容器高可用机制让开发者可以像调用本地对象一样跨机器调度和通信。本文以该仓库 CHANGELOG.md 中 0.7.9 首次公开版本发布的功能清单为主线结合 docs 系列指南与packages/下四个包的源码实现系统讲解其核心概念、通信模式、生命周期管理、高可用与多租户方案并给出可复制运行的部署与编码示例帮助你掌握这套网络框架的完整实战能力。一、版本脉络CHANGELOG 视角下的能力全景仓库 CHANGELOG.md 记录了 huly.net 的版本演进Unreleased待发布补充了全面的文档与示例、GitHub 社区健康文件CONTRIBUTING.md、SECURITY.md以及 Issue / PR 模板——对应 CONTRIBUTING.md 与仓库根部的 SECURITY.md。0.7.92025-10-01Initial public release首次公开版本集中交付了以下能力它们是本文展开的核心骨架类别能力架构分布式架构、多租户容器管理、支持多客户端的 Server 实现通信ZeroMQ 基 RPC 通信层、请求/响应模式、事件广播、自动重连与重试可靠性高可用无状态容器、自动故障转移、健康监控、孤儿容器检测与清理调度跨 Agent 的分布式负载均衡、基于标签的容器发现、容器生命周期引用计数管理交付客户端库、可配置超时、Docker 部署支持、完整测试套件下文将逐项深入这些能力对应的文档与源码。二、核心架构Network / Agent / Container 三层模型在动手写代码前必须先理解 Huly Network 的三个核心概念详见 CORE_CONCEPTS.mdNetwork网络中央协调者维护 Agent 注册表与容器注册表、路由客户端请求、执行引用计数与清理、广播系统事件。Agent代理工作节点向网络注册并声明自己支持的容器种类kind负责容器的创建、健康检查与本地路由每个 Agent 可托管多个容器。Container容器承载业务逻辑的服务实例实现统一的Container接口客户端通过{kind uuid}或标签定位它。⚠️ 关键边界文档多处强调Network Server 只能以单实例运行自身不支持 HA/集群是系统的单点而Agent 与 Container 支持完整的高可用无状态容器注册 自动故障转移。生产环境请用 systemd、PM2、Kubernetes 重启策略守护网络服务Agent 会在网络服务重启后自动重连。从源码结构看这一模型被拆为四个包见 README.mdhcengineering/network-core网络核心实现、Agent 管理与容器编排index.ts 统一导出 API 类型、Agent、容器、网络与代理实现hcengineering/network-backrpc基于 ZeroMQ 的双向 RPC 通信层hcengineering/network-client客户端库负责连接网络与管理容器hcengineering/network-server多客户端支持的网络服务端。网络服务端启动示例import { NetworkImpl, TickManagerImpl } from hcengineering/network-core import { NetworkServer } from hcengineering/network-server const tickManager new TickManagerImpl(1000) // 心跳 tick 频率 tickManager.start() const network new NetworkImpl(tickManager) const server new NetworkServer( network, tickManager, *, // 绑定所有网卡 3737 // 默认端口 ) console.log(Network server running on port 3737)三、通信底座ZeroMQ 双向 RPC 层network-backrpcCHANGELOG 中ZeroMQ-based RPC communication layer对应 network-backrpc 包。从其源码 server.ts 可以看到服务端基于zeromq的Router 套接字构建new zmq.Router({ linger: 0, tcpKeepalive: 1, ... })用于高性能消息路由通过RPCClientInfo维护每个客户端的上次活跃时间lastSeen、在途请求集合、请求计数与耗时统计配合perClientAliveTimeoutSeconds做连接健康管理提供requestHandler/helloHandler/closeHandler/onPing等回调接口形成请求-响应协议骨架并配套 types.ts 中定义的backrpcOperations与 json-utils.ts 的 JSON 序列化工具。这意味着客户端与 Agent、Agent 与网络之间的每一次调用底层都经由 ZeroMQ 消息帧交换而非传统的 HTTP 长连接从而获得更低的延迟与更强的并发能力。相关单测见 backrpc.spec.ts 与 zmq.spec.ts。四、四种通信模式与客户端用法客户端通过createNetworkClient()连接网络地址host:port可传超时秒数其核心 APIget/list/register/onUpdate/close定义在 CORE_CONCEPTS.md 中。CHANGELOG 强调的请求/响应与事件广播对应以下模式1. 请求/响应同步const ref await client.get(user-session as ContainerKind, {}) const result await ref.request(processData, { value: 42 }) console.log(result) await ref.close()2. Fire-and-Forget异步await containerRef.request(logEvent, { event: user_login, timestamp: Date.now() })3. 事件广播发布/订阅容器通过connect(clientId, broadcast)保存客户端的广播函数需要推送时逐一向所有已连接客户端调用const connection await containerRef.connect() connection.on async (event) console.log(Received:, event)容器侧实现connect(clientId: ClientUuid, broadcast: (data: any) Promisevoid): void { this.clients.set(clientId, broadcast) } // 广播给所有客户端 for (const broadcast of this.clients.values()) { await broadcast({ type: update, data: changes }) }4. 双向流式连接const connection await containerRef.connect() connection.on async (chunk) console.log(Chunk:, chunk) await connection.request(subscribe, { topic: updates })资源自动释放await usingCHANGELOG 与 AUTO_DISPOSAL_GUIDE.md 提到客户端库对显式资源管理的支持NetworkClientWithAgents实现了Symbol.dispose/Symbol.asyncDispose。短生命周期脚本/测试/纯客户端应用应使用await using自动清理async function fetchData() { await using client createNetworkClient(localhost:3737) await client.waitConnection(5000) const container await client.get(my-service as ContainerKind, {}) return await container.request(getData) // 离开作用域时自动 close() }长驻服务 / 托管 Agent 的服务绝不可用await using否则函数返回即断开连接应持有强引用并手动await client.close()。五、容器生命周期引用计数、超时与孤儿清理CHANGELOG 中的Container lifecycle management with reference counting与Orphaned container detection and cleanup是系统自动运维的核心每次client.get()对目标容器引用计数 1每次containerRef.close()-1引用归零后容器不会立即销毁而是保留一段可配置的闲置超时时间超时后自动调用terminate()并移出注册表网络持续追踪容器与 Agent 健康状态失败 Agent 的容器会被移除——这就是孤儿容器检测与清理。时间参数集中在 timeouts.tsexport const timeouts { aliveTimeout: 3, // 秒判定 Agent/Client 失活的超时 unusedContainerTimeout: 5, // 秒未被引用容器的终止等待时间 pingInterval: 1 // 秒Agent 心跳间隔 }与之配套客户端工厂在创建容器时可用GetOptions指定uuid、labels、extra工厂附加参数从而精确控制容器的创建策略。六、高可用无状态容器、选主与自动故障转移CHANGELOG 的High availability support with stateless containers与Automatic failover and health monitoring由 HA_STATELESS_CONTAINERS.md 与 QUICKSTART_HA.md 完整描述。机制概括为多个 Agent 用同一个 UUID预注册无状态容器网络对同一 UUID 采用first-wins策略第一个注册者被接受其余被拒绝活跃容器终止或所属 Agent 失活时网络广播移除事件备机收到事件后延迟约 100ms 重新注册避免惊群效应先到先得完成接管——无需外部协调服务即可实现选主。推荐的生产写法是使用serveAgent()的第三个参数无状态容器工厂await client.serveAgent( localhost:3801, {}, // 动态容器工厂 (agentEndpoint) [{ uuid: sharedUUID, kind: my-service as ContainerKind, endpoint: containerOnAgentEndpointRef(agentEndpoint, sharedUUID), container: new MyService(sharedUUID) }] )典型应用场景集群选主、单例服务如数据库迁移、主备数据库。需要记住的边界文档明确列出无脑裂保护、故障转移期间存在短暂无实例窗口、无状态容器不自动迁移状态。配套测试见 ha-stateless.spec.ts完整可运行示例见 ha-stateless-container-example.ts。七、多租户与标签发现Multi-tenant container management与Label-based container discovery共同支撑多租户场景详见 MULTI_TENANT.md容器种类kind语义化字符串如user-session、workspace、query-engine、transactorAgent 声明自己支持哪些 kind标签labels精细选择条件天然适合表达租户 ID、地域、套餐等级、环境dev/staging/prod。// 按租户标签获取独立工作区租户即容器 const workspace await client.get(tenant-workspace as ContainerKind, { labels: [tenant:acme-corp] }) // 或用 extra 传递租户上下文 const workspace2 await client.get(workspace as ContainerKind, { extra: { tenantId: acme-corp, tier: enterprise, region: us-west } })文档还给出三种隔离深度容器级隔离一租户一容器、共享容器 行级安全过滤、数据库级隔离每租户独立库/模式以及配额、限流、审计日志与计量计费等 SaaS 化最佳实践。可运行示例见 03-multi-tenant.ts。八、分布式负载均衡与多 Agent 扩展Distributed load balancing across multiple agents的实现路径是多个 Agent 注册同一种 kind 的容器工厂网络在客户端get()时按round-robin在候选 Agent 间分配新增 Agent 无需中断服务即可动态扩容。客户端可通过list()查看容器注册表、通过onUpdate()订阅 Agent/Container 的 added / updated / removed 事件实现运维可视化与故障感知示例见 README.md 中的 Example 7。配合Automatic reconnection and retry logic当请求失败或容器不可用时客户端可结合指数退避重试生产代码模式可参考 05-error-handling-retry.tsfor (let attempt 1; attempt maxRetries; attempt) { try { const containerRef await client.get(kind, options) const result await containerRef.request(process, { attempt }) return result } catch (err) { await containerRef.close().catch(() {}) const delay Math.min(1000 * Math.pow(2, attempt - 1), 10000) // 指数退避 await new Promise((resolve) setTimeout(resolve, delay)) } }九、可配置超时适配不同环境CHANGELOG 的Configurable timeouts for different environments在 custom-timeout-example.ts 中给出了环境差异化配置的范式// 开发环境1 小时便于断点调试 const devClient createNetworkClient(localhost:3737, 3600) // 生产环境3 秒默认值快速释放资源 const prodClient createNetworkClient(production-network:3737) function createClientForEnvironment(networkHost: string) { const isDevelopment process.env.NODE_ENV development return createNetworkClient(networkHost, isDevelopment ? 3600 : 3) }超时语义分为两类客户端连接存活超时影响 Agent 失活判定与容器闲置终止超时影响未引用容器的保留时长前者通过createNetworkClient第二参数设置后者与aliveTimeout/unusedContainerTimeout全局默认值相关见 timeouts.ts。十、测试套件与 Docker 部署测试CHANGELOG 声明了Comprehensive test suite。仓库中的测试覆盖三个层次核心层packages/core/src/test含网络行为、HA 无状态、Agent 扩展、alive checkin、代理与工具函数测试RPC 层backrpc.spec.ts、zmq.spec.ts客户端层packages/client/src/tests覆盖连接建立、容器连接、释放与扩展行为。另外 tests 目录提供 docker-compose 与 prepare 脚本支撑端到端集成测试test-examples.sh 用于批量验证示例脚本。在packages/core下运行rushx test即可执行单元测试。Docker 部署Docker deployment support由 network-pod含 Dockerfile与 network-tool 提供。完整的生产部署Docker Compose / Kubernetes、环境变量与配置文件、Prometheus 指标、结构化日志、健康检查、备份恢复与滚动更新详见 PRODUCTION_DEPLOYMENT.md。快速上手本地开发安装、三终端跑通 Hello World见 QUICKSTART.md。十一、能力边界与运维提醒综合 CHANGELOG 与各文档以下边界必须写进你的架构评估Network Server 单实例不支持集群与双活是系统单点建议以进程守护 快速重启 健康监控缓解Agent 会自动重连README.md。故障转移有短暂窗口无状态容器接管存在约 100ms 延迟系统是最终一致的。无脑裂保护、无状态迁移跨分区部署时需自行设计冗余与状态同步策略HA_STATELESS_CONTAINERS.md。多租户隔离靠约定网络层提供 kind / labels / 引用管理数据级隔离行级、库级、内存级需在容器内实现MULTI_TENANT.md。结语从 CHANGELOG.md 的功能清单出发本文沿分布式架构 → ZeroMQ 通信 → 通信模式 → 生命周期 → 高可用 → 多租户 → 负载均衡 → 超时 → 测试与部署的脉络把 Huly Virtual Network 的核心设计逐一落地到文档与源码证据上。若要进一步动手建议按以下顺序深入仓库先跑通 examples/01-basic-container-request-response.ts再依次实验 02-event-broadcasting.ts事件广播、03-multi-tenant.ts多租户、04-complete-production-setup.ts生产级组合与 ha-stateless-container-example.ts高可用最后参照 PRODUCTION_DEPLOYMENT.md 完成容器化上线。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
