11. 部署指南

Deployment 描述 FlowNex 的部署组件、外部依赖和推荐部署方式。

11.1 环境依赖

FlowNex 依赖以下基础环境：

  1. Java 21。
  2. Spring Boot 3.3.x。
  3. Python 3.11+。
  4. MySQL。
  5. Redis。
  6. RocketMQ。
  7. OSS / S3 兼容对象存储。
  8. Nacos 或等价注册配置中心。
  9. OpenViking 知识库服务。
  10. 后续 AGFS Server 和 AGFS Metadata Service。

11.2 Java 服务部署

Java 服务包括：

  1. ai-claw-gateway。
  2. ai-app-runtime-gateway。
  3. ai-app-service。
  4. control-center。
  5. user-domain-service。
  6. agent-domain-service。
  7. agent-runtime-gateway。
  8. xingyun-ai-common 公共依赖。

Java 服务推荐按独立应用部署，每个服务拥有独立启动工程和配置。

部署要求：

  1. 所有服务使用统一 trace 头。
  2. 所有服务接入统一日志规范。
  3. Dubbo 服务注册和发现稳定。
  4. 数据库 migration 可重复执行。
  5. 配置按环境隔离。

11.3 share-harness 部署

share-harness 是 Python / FastAPI Agent Runtime。

部署时需要配置：

  1. 模型访问凭证。
  2. Runtime 实例注册信息。
  3. Redis 连接。
  4. OSS 连接。
  5. Tool registry。
  6. Skill root 或 Skill cache。
  7. 回调地址。
  8. AGFS mount 配置。

share-harness 应支持多实例水平扩展。

运行时实例需要通过心跳或注册机制被 agent-runtime-gateway 感知。会话绑定后，同一会话的请求优先路由到已绑定实例。

11.4 agent-runtime-gateway 部署

agent-runtime-gateway 负责 runtime 路由和事件回推。

部署要求：

  1. 可访问 Redis。
  2. 可访问 RocketMQ。
  3. 可访问 share-harness 实例。
  4. 可按来源调用 ai-claw-gateway 或 ai-app-runtime-gateway 的 SSE push 能力。
  5. 支持运行时实例健康检查。
  6. 支持会话绑定恢复。

agent-runtime-gateway 不直接访问 MySQL，避免把运行时路由层变成业务领域服务。

11.5 Redis / MySQL / RocketMQ / OSS 依赖

MySQL

用于保存领域数据：

  1. 用户。
  2. Agent。
  3. Conversation。
  4. Message。
  5. Task。
  6. Task Step。
  7. Skill。
  8. Knowledge Mapping。
  9. AGFS Metadata。

Redis

用于保存运行时状态：

  1. SSE 会话。
  2. Runtime 实例注册。
  3. 会话绑定。
  4. 分布式锁。
  5. 幂等状态。
  6. 临时缓存。

RocketMQ

用于异步事件：

  1. Runtime 回调。
  2. 任务状态事件。
  3. 文件事件。
  4. 知识同步事件。
  5. 经验沉淀任务。

OSS

用于保存大文件正文：

  1. 用户附件。
  2. Agent 输出文件。
  3. AGFS 文件对象。
  4. Runtime backup。

11.6 AGFS 服务部署

AGFS 建议拆分为：

  1. AGFS Server。
  2. AGFS Metadata Service。
  3. AGFS FUSE Client。
  4. AGFS MCP Server。
  5. Object Storage。

AGFS Server 应尽量无状态，支持水平扩展。

Metadata Service 负责：

  1. File Node。
  2. File Version。
  3. Space。
  4. Mount。
  5. Checkpoint。
  6. Version Tree 持久化。

FUSE Client 可部署在 runtime sandbox 或执行节点内，为现成工具提供透明文件系统访问。

11.7 多实例与扩容

FlowNex 的扩容策略：

  1. ai-claw-gateway 按 FlowNex 主站、管理台、飞书渠道连接数和 QPS 扩容。
  2. ai-app-runtime-gateway 按 AI 应用中心 application 路由连接数和 QPS 扩容。
  3. ai-app-service 按 AI 应用交互接口、业务语义接口和业务落库压力扩容。
  4. control-center 按能力中心 QPS、编排请求、回调压力和能力调用治理压力扩容。
  5. agent-domain-service 按领域读写压力扩容。
  6. agent-runtime-gateway 按 runtime 路由和事件压力扩容。
  7. share-harness 按模型并发和工具执行负载扩容。
  8. AGFS Server 按文件 API QPS 扩容。
  9. AGFS Metadata Service 按路径解析和版本写入压力扩容。

11.8 灰度发布与回滚

需要支持灰度的对象：

  1. Java 服务版本。
  2. share-harness runtime 版本。
  3. Skill 版本。
  4. Tool 版本。
  5. 模型配置。
  6. 知识库配置。
  7. AGFS 功能开关。
  8. 多 Agent 策略。

发布前应保证：

  1. migration 已验证。
  2. 新旧协议兼容。
  3. 关键链路有回滚方案。
  4. runtime 事件兼容。
  5. 管理台开关可控。