客户端节点

客户端节点（Client Node）是 Snail AI 分布式架构中的实际执行单元。每个节点是一个独立运行的 Agent Client 进程，通过 gRPC 双向流与 Server 保持连接，负责执行 LLM 调用、本地工具运行、拦截器链处理等推理逻辑。

节点注册

注册流程

Agent Client 启动后，会自动向 Snail AI Server 发起注册。注册流程如下：

Agent Client 启动
       │
       ▼
连接 gRPC Server（默认端口 18888）
       │
       ▼
携带 appId + token 发起注册请求
       │
       ▼
Server 验证 token 合法性
       │
       ├── 验证通过 → 注册成功，建立 gRPC 双向流
       │
       └── 验证失败 → 拒绝注册
       │
       ▼
  开始心跳维持

注册成功后，节点进入在线状态，开始接受 Server 分发的推理请求。

心跳机制

节点注册成功后，需要持续向 Server 发送心跳以维持在线状态：

参数	值	说明
心跳间隔	每 10 秒	客户端每 10 秒向 Server 发送一次心跳
超时判定	心跳过期	如果 Server 在超时时间内未收到心跳，将节点标记为离线
自动重连	是	客户端在连接断开后会自动尝试重新注册

心跳除了维持连接，还会携带节点的最新状态信息（如当前活跃对话数），帮助 Server 进行实时的负载评估。

节点属性

每个客户端节点包含以下属性：

属性	类型	说明
id	number	节点记录主键
appId	string	所属应用 ID
appName	string	所属应用名称
hostId	string	主机唯一标识，用于在同一应用内区分不同的客户端实例
hostIp	string	客户端的 IP 地址
grpcPort	number	客户端暴露的 gRPC 端口
maxConcurrent	number	节点的最大并发处理能力（可同时处理的对话数量）
activeChats	number	当前正在处理的活跃对话数
labels	object	自定义标签键值对，用于标记节点属性（如环境、区域、GPU 类型等）
expireDt	string	心跳过期时间
online	boolean	节点是否在线

负载率

节点的负载率通过以下公式计算：

负载率 = activeChats / maxConcurrent * 100%

在节点管理界面中，负载率以进度条形式可视化展示：

• 进度条显示当前负载百分比。
• 进度条右侧显示 activeChats/maxConcurrent 的具体数值。

标签（Labels）

标签是一个 Key-Value 键值对集合，用于对节点进行分类和标记。常见的标签使用场景：

标签键	示例值	用途
env	production、staging	标记运行环境
region	cn-east、cn-south	标记地理区域
gpu	A100、V100	标记 GPU 型号
team	order、customer	标记所属团队

标签在节点卡片上以小标签形式展示（如 env=production）。

TIP

标签目前用于管理员的可视化识别，后续版本可能支持基于标签的高级路由策略（如按标签匹配分发请求）。

节点管理

查看节点列表

有两种方式查看客户端节点：

1. 按应用查看：在应用管理页面，点击某个应用的 ID 或「实例」按钮，查看该应用下的所有节点。
2. 全局查看：通过全局节点接口（GET /app/all-nodes），查看所有应用下的所有节点。

节点以卡片列表形式展示，每张卡片包含：

• 在线状态指示灯：绿色圆点表示在线，灰色表示离线。
• 地址信息：hostIp:grpcPort 格式。
• 状态标签：在线 / 离线。
• 负载进度条：显示当前负载率。
• 标签列表：以小标签形式展示所有 labels。
• Host ID：节点的唯一标识。
• 踢出按钮：强制将节点从应用中移除。

踢出节点（Kick）

踢出操作用于将某个客户端节点从应用中强制移除。

操作步骤

1. 在节点列表中找到目标节点。
2. 点击「踢出」按钮。
3. 在确认对话框中确认操作。

踢出后的行为

• 节点将从 Server 的注册列表中移除。
• Server 不再向该节点分发新的推理请求。
• 如果被踢出的客户端仍在运行，它会在下一次心跳时发现连接已断开，并尝试重新注册。

使用场景

踢出操作通常用于以下场景：

• 节点运行异常，需要将其从服务池中临时移除。
• 准备对节点进行维护或升级，先将其摘除以避免新请求路由到该节点。
• 节点已经停止运行但仍显示为在线（心跳超时前），需要手动清理。

节点容量规划

并发能力评估

每个节点的 maxConcurrent 决定了它能同时处理多少对话。该值通常由客户端在启动时根据以下因素设定：

• 硬件资源：CPU、内存、GPU 等资源配置。
• 模型大小：使用的 LLM 模型的资源消耗。
• 业务复杂度：对话中工具调用的频率和复杂度。

扩缩容

Snail AI 支持通过增减客户端实例来实现水平扩缩容：

• 扩容：启动更多的 Agent Client 实例并注册到同一应用，新实例会自动参与负载分发。
• 缩容：停止部分 Agent Client 实例，或通过踢出操作将其从服务池移除。Server 会自动将流量重新分配到剩余节点。

平滑发布

在进行节点升级或发布时，建议采用滚动更新策略：

1. 先启动新版本的 Client 实例并注册。
2. 确认新节点正常后，逐步踢出或停止旧版本实例。
3. 这样可以确保服务不中断。

监控建议

1. 关注在线节点数：确保每个应用至少有 1 个在线节点，否则该应用下的智能体将无法执行推理。
2. 监控负载率：如果多个节点的负载率持续接近 100%，说明需要扩容。
3. 检查心跳状态：频繁的离线/在线状态切换可能表明网络不稳定。
4. 利用标签分类：为不同环境和区域的节点打上标签，便于快速定位和管理。

下一步

• 路由策略 -- 了解 Server 如何将请求分发到不同节点