Huly on Network基于 Huly 虚拟网络构建 session、query、transactor 容器架构的实践指南【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform导读本文以 foundations/net/Huly.md 为核心讲解如何在 Huly 虚拟网络Huly Virtual Network即foundations/net下的 network 子仓库之上构建 Huly 平台的分布式运行骨架由session、query、transactor三类容器协同完成客户端查询、事务写入与事件推送。通过本文你将掌握 Huly Network 的容器类型体系、三类容器的职责划分、完整的数据流与消息流拓扑以及其在真实平台中的落地方式DatalakeDB、QueryDB、Kafka、索引器、异步触发器与外部服务集成。一、为什么 Huly 平台需要一张虚拟网络Huly 是一个 All-in-One 项目管理平台需要同时服务 Web/桌面客户端、移动端、以及 GitHub/Telegram/Translate 等外部集成服务。传统单体部署在扩展性和多租户隔离上捉襟见肘。Huly 的解法是在foundations/net中实现一套分布式、可水平扩展、支持自动服务发现与故障转移的虚拟网络让平台逻辑以容器为单位分布在任意数量的 agent 节点上。从 foundations/net/README.md 可以看到这套网络的核心抽象只有三个Network中心协调器Hub维护 agent 与容器注册表负责路由与生命周期管理Agent承载并管理容器的 worker 节点向网络声明自己能创建的容器类型kindContainer真正执行业务逻辑的服务实例例如会话、查询引擎、事务处理器。而 Huly 平台正是把自身拆解为三类容器session、query、transactor运行在这张网络上从而获得多租户隔离、跨区域数据查询、串行化写入与实时事件推送能力。二、三类容器session、query、transactor 的职责划分根据 foundations/net/Huly.mdHuly 平台由如下容器种类container kinds管理容器种类英文职责说明职责翻译sessiona map/reduce/find executor for queries and transactions from client面向客户端查询与事务的 map/reduce/find 执行器是客户端进入网络的入口querya DB query engine, executefindrequests from session and pass them to DB, allow to search for all data per region. Should have access to tables of account - workspace mapping for security数据库查询引擎执行 session 转交的find请求并将其下推给数据库支持按区域region检索全部数据出于安全需要必须能访问 account → workspace 映射表transactormodification orchestrator for all edit operations, do them one by one所有编辑操作修改的编排器事务被逐个串行执行从源码看容器种类在 foundations/net/packages/core/src/api/types.ts 中定义为type ContainerKind string { _containerKind: true }即一种带类型标记的字符串而 foundations/net/packages/core/src/containers.ts 定义了每个容器都必须实现的Container接口export interface Container { request: (operation: string, data?: any, clientId?: ClientUuid) Promiseany onTerminated?: () void terminate: () Promisevoid ping: () Promisevoid connect: (clientId: ClientUuid, broadcast: (data: any) Promisevoid) void disconnect: (clientId: ClientUuid) void }可以看到request处理操作请求、ping承担健康检查、connect/disconnect支撑事件广播——这恰好支撑了 Huly 平台中 session 的查询/事务入口、query 的检索执行、transactor 的写入编排三种角色。三、容器之间的拓扑与完整数据流foundations/net/Huly.md 用一张 mermaid 流程图完整描述了 Huly 平台的网络拓扑这里将其转化为文字说明原图结构完整保留Endpoint客户端接入点 │ 连接 session/user1 ▼ Huly Network虚拟网络中心 │ ├─ 个人工作区容器 parsonal-ws:user1 │ ├─ 获取工作区信息 → DatalakeDB数据湖存储 │ ├─ find 查询 → query:europe区域查询引擎 │ ├─ 事件 → Endpoint回推给客户端 │ └─ 事务 → transactor:ws1 │ ├─ query:europe │ ├─ 响应 → parsonal-ws:user1 │ └─ 更新 → QueryDB查询数据库/索引存储 │ └─ transactor:ws1 ├─ 事件 → HulyPulse实时推送网关再转发 Client ├─ 事件 → parsonal-ws:user1 ├─ 更新 → DatalakeDB └─ 事务 → Kafka输出队列 ├─ Indexer结构索引 全文索引→ QueryDB │ ├─ 已索引事务 → HulyPulse │ └─ 已索引事务 → parsonal-ws:user1 └─ AsyncTriggers异步触发器 ├─ find → query:europe └─ 派生事务 → transactor:ws1 输入队列 InputQueue → transactor:ws1 外部服务Github/Telegram/Translate→ InputQueue Kafka → 外部服务订阅变更 外部服务 → query:europe Client ⇄ Endpoint双向通信从拓扑中可以提炼出四条核心链路查询链路findClient → Endpoint → session → query:europe → QueryDB查询结果沿原路返回。query 容器按 region区域划分每个区域只查自己辖区内的数据实现数据本地化。事务写入链路txClient → session → transactor → DatalakeDB / Kafka。所有编辑操作进入 transactor 后被逐个串行执行do them one by one保证修改顺序一致。实时推送链路transactor/Indexer → HulyPulse → Client。事务提交与索引完成后产生的事件通过 HulyPulse 实时推送给客户端客户端可立即感知数据变更。异步派生链路Kafka → AsyncTriggers → query → transactor。异步触发器查询数据后生成派生事务derived tx再次写回配合Kafka → 外部服务、外部服务 → InputQueue形成与 GitHub/Telegram/Translate 等外部系统的双向闭环。四、链路背后的源码实现原理Huly.md 描述的是网络之上如何编排平台而网络本身的机制可以在foundations/net源码中找到对应实现。4.1 网络中心注册、轮询路由与事件广播网络服务端实现在 foundations/net/packages/core/src/network.ts 的NetworkImpl中。与拓扑图对应它维护_agentsagent 注册表、_containers容器注册表与_clients客户端注册表。关键的getContainer方法演示了拓扑图中Endpoint → session的请求如何被路由若请求指定了uuid且容器已存在则直接复用否则在支持该 kind 的 agents 中做轮询round-robin选择源码中的this.idx % suitableAgents.length返回[uuid, endpoint]给客户端建立连接。这正是 Huly.md 中parsonal-ws:user1这类个人工作区容器被创建并复用的底层机制。同时sendEvents方法会把容器/agent 的 added/updated/removed 事件合并后广播给所有订阅客户端支撑拓扑图中事件 → Endpoint与 HulyPulse 的实时推送。4.2 引用计数与自动回收Huly.md 中transactor 串行处理与容器按需创建背后是网络的引用计数生命周期管理客户端get()容器时引用数 1close()时 -1引用归零的容器进入_orphanedContainers超过unusedContainerTimeout默认 5 秒见 foundations/net/packages/core/src/api/timeouts.ts后被自动terminateagent 必须在pingInterval默认 1 秒内心跳超过aliveTimeout默认 3 秒即被判死其名下容器全部移除并广播 removed 事件。4.3 客户端接入session 的角色载体客户端侧实现位于 foundations/net/packages/client/src/client.ts 的NetworkClientImpl。它既可作为纯客户端请求容器也可通过serveAgent()同时托管容器——这正好对应拓扑图中 Endpoint/Client 与 session 容器的关系。其中establishConnection会根据 endpoint 的 kind 选择直连direct或经 agent 路由routed建立与容器的双向连接支持request同步请求与事件广播on回调两种通信模式。4.4 端点引用容器如何被寻址容器地址在 foundations/net/packages/core/src/endpoints.ts 中定义为 JSON 形式的EndpointRefData含kindrouted/direct/noconnect、host、port、agentId、uuid等字段。拓扑图中parsonal-ws:user1、query:europe、transactor:ws1之所以能被客户端与网络精准寻址正是依赖这种统一端点引用containerOnAgentEndpointRef负责把容器端点挂在对应 agent 上形成路由地址。五、完整拓扑中的基础设施组件Huly.md 流程图中的数据库与消息组件对应 Huly 平台的实际基础设施组件角色交互方DatalakeDB数据湖存储保存工作区全量数据与最终事务结果session读、transactor写QueryDB查询数据库/索引存储供 query 容器按区域检索query、Indexer写入Kafka输出队列解耦写入与索引、异步处理transactor发布、Indexer/AsyncTriggers/Services订阅InputQueue输入队列接收外部服务发来的事务Services投递、transactor消费HulyPulse实时推送网关向客户端下发事件transactor/Indexer事件源、Client订阅这些组件与foundations/net网络层共同构成 Huly 平台的可扩展运行基座网络负责容器的发现、路由与生命周期基础设施负责数据与消息的持久化流转二者通过session、query、transactor三类容器对接。六、安全约束query 容器的 account → workspace 映射Huly.md 特别强调query容器Should have access to tables of account - workspace mapping for security。这意味着跨区域查询search for all data per region必须校验账号与工作区的隶属关系防止越权读取其他工作区数据query是唯一被授予该映射表读取权限的容器种类其他容器不得直接访问形成权限最小化设计这种按容器种类授予数据访问边界的方式与网络层 foundations/net/README.md 中通过容器 kind 与标签实现多租户天然隔离的理念一脉相承labels可用于表达租户 ID、区域region、环境dev/staging/production等选择条件容器工厂据此为不同租户/区域创建隔离实例。七、部署与运行注意事项结合 foundations/net/README.md 与本文拓扑落地 Huly on Network 时需注意网络服务本身是单实例Network Server 不支持 HA需要借助 systemd/PM2/Kubernetes 重启策略保障可用性agent 与容器则具备自动重连与故障转移能力stateless 容器场景下同一 UUID 的容器仅首个 agent 注册成功其余作为备用。安全模型网络当前面向可信内网private cloud部署无内置认证与加密生产环境需配合防火墙、VPN/VPC 进行网络隔离并仅开放默认端口 3737。端口约定网络服务默认监听 3737agent 通常在 3738 上提供容器连接端点示例代码中多 agent 场景使用 3738 i 递增端口。运行环境网络层要求 Node.js 22、TypeScript 5.8、ZeroMQ 6.5构建与测试使用 Rushnode common/scripts/install-run-rush.js install、node common/scripts/install-run-rush.js build、node common/scripts/install-run-rush.js test。八、参考与延伸阅读网络层入口与架构总览foundations/net/README.md本文主题文档foundations/net/Huly.md核心概念Network/Agent/Container/Clientfoundations/net/docs/CORE_CONCEPTS.md网络服务端实现注册/路由/生命周期/健康检查foundations/net/packages/core/src/network.ts客户端实现连接/请求/事件/serveAgentfoundations/net/packages/client/src/client.ts容器接口与工厂定义foundations/net/packages/core/src/containers.ts端点引用与解析foundations/net/packages/core/src/endpoints.ts超时与健康参数foundations/net/packages/core/src/api/timeouts.ts类型定义ContainerKind/GetOptions/NetworkEvent 等foundations/net/packages/core/src/api/types.ts【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Huly on Network：基于 Huly 虚拟网络构建 session、query、transactor 容器架构的实践指南
Huly on Network基于 Huly 虚拟网络构建 session、query、transactor 容器架构的实践指南【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform导读本文以 foundations/net/Huly.md 为核心讲解如何在 Huly 虚拟网络Huly Virtual Network即foundations/net下的 network 子仓库之上构建 Huly 平台的分布式运行骨架由session、query、transactor三类容器协同完成客户端查询、事务写入与事件推送。通过本文你将掌握 Huly Network 的容器类型体系、三类容器的职责划分、完整的数据流与消息流拓扑以及其在真实平台中的落地方式DatalakeDB、QueryDB、Kafka、索引器、异步触发器与外部服务集成。一、为什么 Huly 平台需要一张虚拟网络Huly 是一个 All-in-One 项目管理平台需要同时服务 Web/桌面客户端、移动端、以及 GitHub/Telegram/Translate 等外部集成服务。传统单体部署在扩展性和多租户隔离上捉襟见肘。Huly 的解法是在foundations/net中实现一套分布式、可水平扩展、支持自动服务发现与故障转移的虚拟网络让平台逻辑以容器为单位分布在任意数量的 agent 节点上。从 foundations/net/README.md 可以看到这套网络的核心抽象只有三个Network中心协调器Hub维护 agent 与容器注册表负责路由与生命周期管理Agent承载并管理容器的 worker 节点向网络声明自己能创建的容器类型kindContainer真正执行业务逻辑的服务实例例如会话、查询引擎、事务处理器。而 Huly 平台正是把自身拆解为三类容器session、query、transactor运行在这张网络上从而获得多租户隔离、跨区域数据查询、串行化写入与实时事件推送能力。二、三类容器session、query、transactor 的职责划分根据 foundations/net/Huly.mdHuly 平台由如下容器种类container kinds管理容器种类英文职责说明职责翻译sessiona map/reduce/find executor for queries and transactions from client面向客户端查询与事务的 map/reduce/find 执行器是客户端进入网络的入口querya DB query engine, executefindrequests from session and pass them to DB, allow to search for all data per region. Should have access to tables of account - workspace mapping for security数据库查询引擎执行 session 转交的find请求并将其下推给数据库支持按区域region检索全部数据出于安全需要必须能访问 account → workspace 映射表transactormodification orchestrator for all edit operations, do them one by one所有编辑操作修改的编排器事务被逐个串行执行从源码看容器种类在 foundations/net/packages/core/src/api/types.ts 中定义为type ContainerKind string { _containerKind: true }即一种带类型标记的字符串而 foundations/net/packages/core/src/containers.ts 定义了每个容器都必须实现的Container接口export interface Container { request: (operation: string, data?: any, clientId?: ClientUuid) Promiseany onTerminated?: () void terminate: () Promisevoid ping: () Promisevoid connect: (clientId: ClientUuid, broadcast: (data: any) Promisevoid) void disconnect: (clientId: ClientUuid) void }可以看到request处理操作请求、ping承担健康检查、connect/disconnect支撑事件广播——这恰好支撑了 Huly 平台中 session 的查询/事务入口、query 的检索执行、transactor 的写入编排三种角色。三、容器之间的拓扑与完整数据流foundations/net/Huly.md 用一张 mermaid 流程图完整描述了 Huly 平台的网络拓扑这里将其转化为文字说明原图结构完整保留Endpoint客户端接入点 │ 连接 session/user1 ▼ Huly Network虚拟网络中心 │ ├─ 个人工作区容器 parsonal-ws:user1 │ ├─ 获取工作区信息 → DatalakeDB数据湖存储 │ ├─ find 查询 → query:europe区域查询引擎 │ ├─ 事件 → Endpoint回推给客户端 │ └─ 事务 → transactor:ws1 │ ├─ query:europe │ ├─ 响应 → parsonal-ws:user1 │ └─ 更新 → QueryDB查询数据库/索引存储 │ └─ transactor:ws1 ├─ 事件 → HulyPulse实时推送网关再转发 Client ├─ 事件 → parsonal-ws:user1 ├─ 更新 → DatalakeDB └─ 事务 → Kafka输出队列 ├─ Indexer结构索引 全文索引→ QueryDB │ ├─ 已索引事务 → HulyPulse │ └─ 已索引事务 → parsonal-ws:user1 └─ AsyncTriggers异步触发器 ├─ find → query:europe └─ 派生事务 → transactor:ws1 输入队列 InputQueue → transactor:ws1 外部服务Github/Telegram/Translate→ InputQueue Kafka → 外部服务订阅变更 外部服务 → query:europe Client ⇄ Endpoint双向通信从拓扑中可以提炼出四条核心链路查询链路findClient → Endpoint → session → query:europe → QueryDB查询结果沿原路返回。query 容器按 region区域划分每个区域只查自己辖区内的数据实现数据本地化。事务写入链路txClient → session → transactor → DatalakeDB / Kafka。所有编辑操作进入 transactor 后被逐个串行执行do them one by one保证修改顺序一致。实时推送链路transactor/Indexer → HulyPulse → Client。事务提交与索引完成后产生的事件通过 HulyPulse 实时推送给客户端客户端可立即感知数据变更。异步派生链路Kafka → AsyncTriggers → query → transactor。异步触发器查询数据后生成派生事务derived tx再次写回配合Kafka → 外部服务、外部服务 → InputQueue形成与 GitHub/Telegram/Translate 等外部系统的双向闭环。四、链路背后的源码实现原理Huly.md 描述的是网络之上如何编排平台而网络本身的机制可以在foundations/net源码中找到对应实现。4.1 网络中心注册、轮询路由与事件广播网络服务端实现在 foundations/net/packages/core/src/network.ts 的NetworkImpl中。与拓扑图对应它维护_agentsagent 注册表、_containers容器注册表与_clients客户端注册表。关键的getContainer方法演示了拓扑图中Endpoint → session的请求如何被路由若请求指定了uuid且容器已存在则直接复用否则在支持该 kind 的 agents 中做轮询round-robin选择源码中的this.idx % suitableAgents.length返回[uuid, endpoint]给客户端建立连接。这正是 Huly.md 中parsonal-ws:user1这类个人工作区容器被创建并复用的底层机制。同时sendEvents方法会把容器/agent 的 added/updated/removed 事件合并后广播给所有订阅客户端支撑拓扑图中事件 → Endpoint与 HulyPulse 的实时推送。4.2 引用计数与自动回收Huly.md 中transactor 串行处理与容器按需创建背后是网络的引用计数生命周期管理客户端get()容器时引用数 1close()时 -1引用归零的容器进入_orphanedContainers超过unusedContainerTimeout默认 5 秒见 foundations/net/packages/core/src/api/timeouts.ts后被自动terminateagent 必须在pingInterval默认 1 秒内心跳超过aliveTimeout默认 3 秒即被判死其名下容器全部移除并广播 removed 事件。4.3 客户端接入session 的角色载体客户端侧实现位于 foundations/net/packages/client/src/client.ts 的NetworkClientImpl。它既可作为纯客户端请求容器也可通过serveAgent()同时托管容器——这正好对应拓扑图中 Endpoint/Client 与 session 容器的关系。其中establishConnection会根据 endpoint 的 kind 选择直连direct或经 agent 路由routed建立与容器的双向连接支持request同步请求与事件广播on回调两种通信模式。4.4 端点引用容器如何被寻址容器地址在 foundations/net/packages/core/src/endpoints.ts 中定义为 JSON 形式的EndpointRefData含kindrouted/direct/noconnect、host、port、agentId、uuid等字段。拓扑图中parsonal-ws:user1、query:europe、transactor:ws1之所以能被客户端与网络精准寻址正是依赖这种统一端点引用containerOnAgentEndpointRef负责把容器端点挂在对应 agent 上形成路由地址。五、完整拓扑中的基础设施组件Huly.md 流程图中的数据库与消息组件对应 Huly 平台的实际基础设施组件角色交互方DatalakeDB数据湖存储保存工作区全量数据与最终事务结果session读、transactor写QueryDB查询数据库/索引存储供 query 容器按区域检索query、Indexer写入Kafka输出队列解耦写入与索引、异步处理transactor发布、Indexer/AsyncTriggers/Services订阅InputQueue输入队列接收外部服务发来的事务Services投递、transactor消费HulyPulse实时推送网关向客户端下发事件transactor/Indexer事件源、Client订阅这些组件与foundations/net网络层共同构成 Huly 平台的可扩展运行基座网络负责容器的发现、路由与生命周期基础设施负责数据与消息的持久化流转二者通过session、query、transactor三类容器对接。六、安全约束query 容器的 account → workspace 映射Huly.md 特别强调query容器Should have access to tables of account - workspace mapping for security。这意味着跨区域查询search for all data per region必须校验账号与工作区的隶属关系防止越权读取其他工作区数据query是唯一被授予该映射表读取权限的容器种类其他容器不得直接访问形成权限最小化设计这种按容器种类授予数据访问边界的方式与网络层 foundations/net/README.md 中通过容器 kind 与标签实现多租户天然隔离的理念一脉相承labels可用于表达租户 ID、区域region、环境dev/staging/production等选择条件容器工厂据此为不同租户/区域创建隔离实例。七、部署与运行注意事项结合 foundations/net/README.md 与本文拓扑落地 Huly on Network 时需注意网络服务本身是单实例Network Server 不支持 HA需要借助 systemd/PM2/Kubernetes 重启策略保障可用性agent 与容器则具备自动重连与故障转移能力stateless 容器场景下同一 UUID 的容器仅首个 agent 注册成功其余作为备用。安全模型网络当前面向可信内网private cloud部署无内置认证与加密生产环境需配合防火墙、VPN/VPC 进行网络隔离并仅开放默认端口 3737。端口约定网络服务默认监听 3737agent 通常在 3738 上提供容器连接端点示例代码中多 agent 场景使用 3738 i 递增端口。运行环境网络层要求 Node.js 22、TypeScript 5.8、ZeroMQ 6.5构建与测试使用 Rushnode common/scripts/install-run-rush.js install、node common/scripts/install-run-rush.js build、node common/scripts/install-run-rush.js test。八、参考与延伸阅读网络层入口与架构总览foundations/net/README.md本文主题文档foundations/net/Huly.md核心概念Network/Agent/Container/Clientfoundations/net/docs/CORE_CONCEPTS.md网络服务端实现注册/路由/生命周期/健康检查foundations/net/packages/core/src/network.ts客户端实现连接/请求/事件/serveAgentfoundations/net/packages/client/src/client.ts容器接口与工厂定义foundations/net/packages/core/src/containers.ts端点引用与解析foundations/net/packages/core/src/endpoints.ts超时与健康参数foundations/net/packages/core/src/api/timeouts.ts类型定义ContainerKind/GetOptions/NetworkEvent 等foundations/net/packages/core/src/api/types.ts【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考