架构概览

Composia 采用控制平面-代理（Control Plane-Agent）架构，支持分布式多节点服务管理。

系统架构

┌─────────────────────────────────────────────────────────────┐
│                      Control Plane                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Web UI    │  │  API Server │  │     Task Queue      │  │
│  │  (SvelteKit)│  │ (ConnectRPC)│  │     (SQLite)        │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Git Repo   │  │   Service   │  │    Node Manager     │  │
│  │  (Config)   │  │   Registry  │  │                     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
       ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
       │   Agent 1   │ │   Agent 2   │ │   Agent N   │
       │  (Node A)   │ │  (Node B)   │ │  (Node C)   │
       │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │
       │ │ Docker  │ │ │ │ Docker  │ │ │ │ Docker  │ │
       │ │ Compose │ │ │ │ Compose │ │ │ │ Compose │ │
       │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │
       └─────────────┘ └─────────────┘ └─────────────┘

核心组件

控制平面（Controller）

控制平面是系统的中心枢纽，运行在独立容器中：

功能	说明
配置管理	从 Git 仓库加载和维护服务定义
状态聚合	收集所有代理的状态信息
任务调度	将部署任务分配给适当的代理
API 服务	提供 Web UI 和外部集成接口
数据持久化	使用 SQLite 存储任务和状态

执行代理（Agent）

代理运行在目标 Docker 主机上：

功能	说明
心跳通信	定期向控制平面报告状态（默认 5 秒）
任务执行	执行部署、停止、重启等操作
日志收集	收集和转发容器日志
资源监控	监控主机和容器资源使用情况
Docker 操作	直接管理本地 Docker 容器

Web 界面

基于 SvelteKit 构建的现代化管理界面：

• 服务管理：创建、编辑、部署服务
• 节点监控：查看所有代理节点状态
• 容器操作：查看日志、执行命令
• 任务追踪：实时监控任务执行进度

通信机制

ConnectRPC

Composia 使用 ConnectRPC 进行服务间通信：

• 基于 HTTP/2 的双向流
• Protobuf 序列化
• 兼容 gRPC 和 REST 客户端
• 支持浏览器直接调用

认证方式

组件	认证方式
Web UI → Controller	CLI Token（Bearer）
Agent → Controller	Node Token
Controller → Agent	mTLS（可选）

数据流

部署流程

用户请求 → Controller 验证 → 创建任务 → Agent 拉取 → 执行部署 → 上报结果

1. 用户通过 Web UI 或 API 发起部署请求
2. Controller 验证服务定义和权限
3. 为每个目标节点创建部署任务
4. Agent 通过长轮询获取任务
5. Agent 下载服务 bundle 并执行 Docker Compose 部署
6. Agent 上报执行结果和容器状态

状态同步

Agent 采集 → 心跳上报 → Controller 聚合 → Web UI 展示

• Agent 每 5 秒发送一次心跳
• 心跳包含节点状态、容器列表、资源使用
• Controller 聚合所有代理的状态到 SQLite
• Web UI 实时展示最新状态

核心对象模型

Service (服务定义)
    │
    ├── ServiceInstance (节点实例) ── Container (Docker 容器)
    │
    └── ServiceInstance (节点实例) ── Container (Docker 容器)

对象	说明	存储位置
Service	逻辑服务定义，来源于 Git 仓库	Git Repo
ServiceInstance	服务在某个节点上的部署实例	SQLite
Container	实际的 Docker 容器	Docker Daemon
Node	执行代理对应的 Docker 主机	Controller 配置

安全性

层面	措施
认证	Token-based 身份验证
传输	支持 TLS 加密（生产环境建议启用）
权限	最小权限原则，代理只能访问被分配的服务
Secrets	使用 age 加密存储敏感信息

扩展性

• 水平扩展: 添加更多 Agent 节点管理更多 Docker 主机
• 服务扩展: 同一服务可部署到多个节点
• 负载均衡: 通过 Caddy 配置实现多实例负载均衡

部署模式

单节点模式

┌─────────────────────────────────────┐
│           单台服务器                │
│  ┌──────────┐    ┌───────────────┐  │
│  │Controller│◄──►│     Agent     │  │
│  └──────────┘    └───────┬───────┘  │
│                          │          │
│                   ┌──────▼──────┐   │
│                   │   Docker    │   │
│                   └─────────────┘   │
└─────────────────────────────────────┘

多节点模式

┌─────────────────┐
│    Controller   │
└────────┬────────┘
         │
    ┌────┴────┬────────┬────────┐
    ▼         ▼        ▼        ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
│Agent 1│ │Agent 2│ │Agent 3│ │Agent N│
└───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘
    │         │         │         │
┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│Docker │ │Docker │ │Docker │ │Docker │
│Node 1 │ │Node 2 │ │Node 3 │ │Node N │
└───────┘ └───────┘ └───────┘ └───────┘