架构说明

  FinClaw 后端服务采用 100% 云原生的微服务架构，每个服务编译后被打包成容器镜像，通过 Docker Compose（单机）或 Kubernetes（集群）进行编排部署，因此大部分运维能力——服务的故障转移、动态扩容、资源管理——都依赖容器平台实现。FinClaw 还依赖部分成熟的开源组件作为基础设施，承担数据存储、缓存、消息、向量检索、时序持久化等能力。

运维架构图：

架构部分：

• 基础服务部分：

  • 关系数据库：PostgreSQL（平台 Schema，identity / inbox / persona / skill / document / pulse 等）
  • 时序数据库：TimescaleDB（会话存储 conversation-store）
  • 缓存与协调：Redis
  • 消息总线：NATS（JetStream，跨服务事件与可靠投递）
  • 向量检索：Qdrant（运行时按需启用）
  • 文本嵌入：TEI（Text Embeddings Inference）
  • 持久化时序工作流：Restate（ai-infra-rs 定时器与 cron）

• 容器：Docker

• 容器编排平台：Docker Compose（单机）、Kubernetes（集群）

• 日志系统：

  • 单机：fleet.sh logs 直接看容器日志
  • 集群 / 大规模：Vector + Kafka + ElasticSearch + Kibana，或 Loki + Grafana

• 监控系统：Prometheus + Grafana

  FinClaw 采用「应用交互层 — 平台管控层 — Agent 引擎层 — 基础设施底座」四层架构设计，自下而上，分别承担数据/沙箱、Agent 调度、租户与编排治理、外部接入。详见 产品简介 中的整体架构说明。

运行时分层

层级	代表服务	端口区间	说明
网关 / 入口	api-gateway、ag-ui-server、openclaw-compat-gateway、feishu-connector	261xx / 264xx	HTTP 入口、SSE 流、渠道接入
核心平台	identity-service、orchestrator、claw-fleet-manager、persona-service、skill-service	261xx	认证、流程编排、claw 生命周期、画像与技能
会话与投递	conversation-store、delivery、inbox-service、push-service、document-service、doc-toolkit	262xx / 264xx	会话存储、投递、收件箱、推送、文档
AI 运行时	ai-infra-rs	26450	推理、工具调用、记忆、调度钩子

请求路径

• 入站对话（Flow A）：api-gateway → ag-ui-server → orchestrator → ai-infra-rs → delivery →（inbox-service / push-service / AG-UI 流）

完整服务与端口清单见 部署组件。

部署模式对比

FinClaw 提供多种部署模式，以满足不同业务场景和规模需求。

部署模式	适用环境	架构设计	优点	缺点	部署说明
单节点	POC、测试、轻量生产	Docker Compose 部署全部服务	部署快、成本低	性能一般，单点故障	单台服务器部署所有服务
小集群	生产、高可用场景	Kubernetes，4 台服务器	高可用、资源利用高	资源竞争	服务均匀分布在 4 台服务器
中大规模集群	对扩展性、灾备有要求	Kubernetes 集群，多服务器，业务与基础服务分离	高可用、性能好、无资源竞争	成本较高	类似小规模，更多服务器且服务分离
双机房冷备集群	对业务连续性要求高	主机房工作、冷备机房待命接管	容灾能力强、切换灵活	成本高、维护复杂	主从机房都部署 Kubernetes 集群，主机房集群化数据服务，冷备机房做单节点同步

单节点部署模式

在单节点部署模式中，所有服务都部署在一台服务器上。本运维文档的快速安装指南即基于此模式。

操作系统与容器平台：

• Linux：作为基础操作系统，提供稳定的运行环境和资源管理。
• Docker：用于容器化各个微服务，确保服务间隔离与可移植性。
• Docker Compose v2：用 docker-compose.yml + fleet.sh 定义和编排多服务，简化启停和日志查看。

容器与系统组件：

• API Gateway：唯一对外端口（默认 26100），负责 TLS 终止、JWT 校验、限流、CSP。
• 核心 / AI 服务：identity、orchestrator、ag-ui-server、ai-infra-rs 等微服务，全部跑在 chatkit-network 容器网络中。
• 数据层：PostgreSQL、TimescaleDB、Redis、NATS、TEI、Restate，同样以容器方式启动，数据通过 Docker 卷持久化到宿主机数据盘。

服务器：

用途	CPU	内存	储存空间	部署内容	数量	参考 TPS
最低配置	8 核	16 GB	200 GB	数据库、缓存、AI 运行时与 FinClaw 微服务	1	—
推荐配置	16 核	32 GB	300 GB（SSD）	数据库、缓存、AI 运行时与 FinClaw 微服务	1	—

系统：

• 芯片架构：X86_64
• 操作系统：CentOS 8 及以上 / RHEL 8 及以上 / Ubuntu 22.04 及以上

单节点的实际吞吐严重依赖外部 LLM 提供商的可用配额与延迟，FinClaw 自身瓶颈通常出现在 ai-infra-rs 与 LLM 上游的并发能力。

集群部署模式

集群部署在高可用、可扩展性、灾备等方面提供更强的能力。

1. 小规模集群

小规模集群提供最小规模的高可用，采用 Kubernetes 部署，使用 4 台业务服务器，最多允许 1 台宕机，适合绝大部分对高可用与故障隔离有中等要求的客户。

用途	CPU	内存	储存空间	数量
业务服务	8 核	16 GB	500 GB	4 台
运维管理（可选）	8 核	16 GB	500 GB	1 台

系统：

• 芯片架构：X86_64
• 操作系统：CentOS 8 及以上 / RHEL 8 及以上 / Ubuntu 22.04 及以上

部署说明： 所有服务均匀部署在 4 台服务器上。基础设施（PostgreSQL / TimescaleDB / NATS / Redis）建议以 StatefulSet + 持久卷方式部署，FinClaw 业务微服务采用 Deployment + HPA 进行水平扩缩。

2. 大规模集群

中大规模集群适合对扩展性、灾备要求较高的客户。该架构在故障隔离、故障恢复、可扩展性方面进一步加强，服务器数量无上限，支持多活、多机房，可按业务规模与灾备要求自定义。

相比小规模集群，中大规模集群可以提供更高的 QPS、更好的整体性能与扩展性。

系统：

• 芯片架构：X86_64
• 操作系统：CentOS 8 及以上 / RHEL 8 及以上 / Ubuntu 22.04 及以上

部署说明： 与小规模部署类似，但使用更多服务器并将业务服务与基础设施服务分离——业务节点跑 FinClaw 微服务，基础设施节点专门承担 PG/Timescale/NATS/Redis/Qdrant/Temporal 等有状态组件。微服务采用更多实例数部署以承载更高的并发会话与 Pulse 触发量。

参考文档

• 快速安装指南
• 部署组件
• 产品简介