# agent-cluster

**Repository Path**: aidym/agent-cluster

## Basic Information

- **Project Name**: agent-cluster
- **Description**: 基于qwenpaw的Agent集群
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-17
- **Last Updated**: 2026-04-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能体矩阵集群

基于 Docker Swarm 的智能体集群管理平台，支持动态创建和管理 Worker 智能体。

## 特性

- ✅ **Manager 主智能体** - 基于 QwenPaw 的主控智能体
- ✅ **动态 Worker** - 根据任务需求自动创建/回收
- ✅ **Matrix 通讯** - 分布式消息通讯，支持 Element Web 客户端
- ✅ **MinIO 存储** - 统一的文件存储和同步
- ✅ **Dashboard 控制台** - Web 管理界面
- ✅ **Nginx 反向代理** - 统一的访问入口
- ✅ **Higress AI 网关** - AI 模型统一网关

## 快速开始

```bash
# 1. 解压部署包
tar -xzf agent-cluster.tar.gz
cd agent-cluster

# 2. 执行部署
chmod +x deploy.sh
./deploy.sh
```

按提示完成配置后即可部署集群。

## 架构

### 服务拓扑

```
                                    ┌─────────────────┐
                                    │   用户/浏览器    │
                                    └────────┬────────┘
                                             │
                                    ┌────────▼────────┐
                                    │   Nginx (80)    │
                                    │  反向代理入口    │
                                    └────────┬────────┘
                                             │
           ┌──────────┬──────────┬──────────┼──────────┬──────────┬──────────
           │          │          │          │          │          │
    ┌──────▼─────┐ ┌──▼────┐ ┌──▼────┐ ┌───▼────┐ ┌───▼─────┐ ┌───▼─────┐
    │ Dashboard  │ │ MinIO │ │ Higress│ │Matrix  │ │ Element │ │ Manager │
    │  :3000     │ │ :9000 │ │ :8080 │ │ :8008  │ │  :80    │ │ :8088   │
    └────────────┘ └───────┘ └───────┘ └────────┘ └─────────┘ └────┬────┘
                                                                       │
                                                         ┌────────────▼────────────┐
                                                         │    Workers (动态)        │
                                                         │  worker-001, worker-002  │
                                                         └─────────────────────────┘
```

### 服务列表

| 服务 | 域名 | 端口 | 说明 |
|------|------|------|------|
| Nginx | - | 80 | 反向代理 |
| Dashboard | dashboard.{domain} | 3000 | 管理控制台 |
| MinIO | minio.{domain} | 9000 | 文件存储 |
| AI Gateway | aigateway.{domain} | 8080 | Higress AI 网关 |
| Higress Console | higress.{domain} | 8001 | Higress 控制台 |
| Matrix | matrix.{domain} | 8008 | Matrix 通讯服务 |
| Element | element.{domain} | 80 | Element Web 客户端 |
| Manager | manager.{domain} | 8088 | 主智能体 |
| PostgreSQL | postgres | 5432 | 主数据库 |
| Redis | redis | 6379 | 缓存/消息队列 |

## 目录结构

```
agent-cluster/
├── 01-infra.yml           # 基础设施服务
├── 02-manager.yml         # Manager 主智能体
├── deploy.sh              # 交互式部署脚本
├── clusterctl.sh          # 集群维护脚本
├── create-worker.sh       # Worker 创建脚本
├── uninstall.sh           # 卸载脚本
├── nginx.conf             # Nginx 主配置
├── nginx/conf.d/          # Nginx 域名配置
├── config/                # 配置文件
│   ├── AGENTS.md         # 智能体配置规范
│   ├── PROFILE.md        # 智能体身份定义
│   ├── SOUL.md           # 智能体灵魂定义
│   ├── aigateway.yaml    # Higress 配置
│   ├── manager.yaml      # Manager 配置
│   └── worker-defaults.yaml
├── templates/             # 模板文件
│   └── worker-template.yml
├── dashboard/             # Dashboard 前端
│   ├── dashboard/        # 前端页面
│   └── api/              # Flask API
├── sql/                   # 数据库脚本
├── scripts/               # 辅助脚本
└── docs/                  # 文档
```

## 使用方式

### 部署集群

```bash
./deploy.sh
```

按提示配置：
- 基础信息（数据目录、Base Domain）
- 域名配置
- 数据库配置
- MinIO 配置
- Matrix 配置
- Dashboard 配置
- AI 模型配置

### 集群管理

```bash
# 查看状态
./clusterctl.sh status

# 查看所有访问地址
./clusterctl.sh url

# 查看所有密码
./clusterctl.sh pass

# 重启服务
./clusterctl.sh restart nginx
./clusterctl.sh restart postgres

# 扩展服务
./clusterctl.sh scale manager 2

# 查看日志
./clusterctl.sh logs manager
```

### 创建 Worker

```bash
# 创建 Worker
./create-worker.sh create worker-001 my-worker frontend

# 查看 Worker 列表
./create-worker.sh list

# 移除 Worker
./create-worker.sh remove worker-001
```

## 配置 hosts

部署完成后配置 hosts 文件：

```bash
echo '192.168.x.x dashboard.ai.zhentutec.cn minio.ai.zhentutec.cn aigateway.ai.zhentutec.cn higress.ai.zhentutec.cn matrix.ai.zhentutec.cn element.ai.zhentutec.cn manager.ai.zhentutec.cn' | sudo tee -a /etc/hosts
```

## 访问信息

部署完成后显示：

- 所有服务的访问地址（域名 + IP端口）
- 所有账号密码（Dashboard、Matrix、MinIO、PostgreSQL）

使用 `./clusterctl.sh url` 和 `./clusterctl.sh pass` 随时查看。

## 通信规则

### Matrix 信息交换

- Matrix 是分布式通讯协议
- 每个智能体有唯一的 Matrix ID
- 通过 Matrix 房间（Room）进行消息传递

### MinIO 文件交换

- 私有文件：`minio://private/{agent_id}/`
- 共享文件：`minio://shared/`

### 配置同步

- 启动时从 MinIO 同步配置
- 配置修改后立即提交到 MinIO

## 技术栈

- **容器编排**: Docker Swarm
- **主智能体**: QwenPaw (agentscope)
- **AI 网关**: Higress
- **通讯服务**: Matrix Synapse
- **Web 客户端**: Element
- **数据库**: PostgreSQL
- **缓存/队列**: Redis
- **对象存储**: MinIO
- **反向代理**: Nginx
- **Dashboard**: Python Flask + Vue

## 系统要求

- Docker 20.10+
- Docker Swarm 模式
- 16+ 核 CPU
- 32+ GB 内存
- 500+ GB 磁盘

## 故障排查

```bash
# 查看服务状态
docker stack services agent-infra
docker stack services agent-manager

# 查看日志
docker logs -f $(docker ps -qf name=agent-manager_manager)

# 查看集群节点
docker node ls
```

## License

MIT