# pulsar

**Repository Path**: cdevel/pulsar

## Basic Information

- **Project Name**: pulsar
- **Description**: AI-driven Cluster Orchestration Platform.
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pulsar - 分布式服务编排平台

Pulsar 是一个基于 Raft 共识算法的分布式服务编排平台，提供多执行器支持、故障自愈、服务迁移和网络分区防护能力。如脉冲星般持续监控集群健康，确保服务高可用。

## 功能特性

### 核心功能

- **Raft 共识层** - 完整的 Raft 实现，包含 Transport 层、FSM、快照支持
- **节点管理** - 心跳检测、故障检测、资源采集
- **服务编排** - 部署、调度、健康检查、优先级策略
- **服务迁移** - 状态快照、回滚机制、进度跟踪
- **网络分区检测** - 多网段可达性检测
- **防脑裂机制** - Quorum 仲裁、Fencing 策略
- **分层子集群** - 支持分层架构和非公平选举

### 执行器支持

| 执行器 | 说明 |
|--------|------|
| `process` | 原生进程执行 |
| `docker` | Docker 容器执行 |
| `podman` | Podman 容器执行（支持 rootless 模式） |
| `systemd` | Systemd 服务管理 |
| `libvirt` | 虚拟机管理（支持实时迁移） |

## 架构

```
┌─────────────────────────────────────────────────────────┐
│                     API Layer                           │
│              ┌─────────────┬─────────────┐              │
│              │    gRPC     │    REST     │              │
│              └─────────────┴─────────────┘              │
├─────────────────────────────────────────────────────────┤
│                   Service Layer                         │
│  ┌──────────┬──────────┬──────────┬──────────────────┐  │
│  │  Node    │ Service  │Migration │    Executor      │  │
│  │ Manager  │ Manager  │ Manager  │ Factory/Plugins  │  │
│  └──────────┴──────────┴──────────┴──────────────────┘  │
├─────────────────────────────────────────────────────────┤
│                    Raft Layer                           │
│  ┌──────────────┬──────────────┬───────────────────┐   │
│  │   Transport  │     FSM      │    Snapshot       │   │
│  └──────────────┴──────────────┴───────────────────┘   │
├─────────────────────────────────────────────────────────┤
│                   Storage Layer                         │
│              ┌─────────────┬─────────────┐              │
│              │    Store    │  TTL Store  │              │
│              └─────────────┴─────────────┘              │
└─────────────────────────────────────────────────────────┘
```

## 快速开始

### 编译

```bash
# 编译所有组件
make build

# 或手动编译
go build -o bin/pulsar ./cmd/pulsar
go build -o bin/pulsarctl ./cmd/pulsarctl
```

### 配置

配置文件示例 (`configs/pulsar.yaml`):

```yaml
node_id: "node1"
bind_addr: "0.0.0.0:7000"
data_dir: "/var/lib/pulsar"
bootstrap: true
grpc_port: 7001
http_port: 7002

heartbeat:
  interval: 1s
  timeout: 5s

raft:
  heartbeat_timeout: 1s
  election_timeout: 1s
  snapshot_interval: 120s

service:
  executor_type: "process"
  default_priority: "normal"

split_brain:
  enable: true
  role: "primary"
  autonomous_shutdown: true
```

### 启动

```bash
# 单节点启动 (Bootstrap 模式)
./bin/pulsar --config configs/pulsar.yaml

# 多节点集群
# 节点1
./bin/pulsar --config configs/node1.yaml

# 节点2
./bin/pulsar --config configs/node2.yaml
```

## 服务优先级

服务支持四级优先级，在脑裂场景下决定关机策略：

| 优先级 | 关机策略 |
|--------|----------|
| `critical` | 保持运行 |
| `high` | 优雅关机 |
| `normal` | 优雅关机 |
| `low` | 立即关机 |

在服务标签中设置优先级：

```yaml
labels:
  pulsar/priority: "critical"
```

## 执行器配置

### Docker/Podman

```yaml
spec:
  image: "nginx:latest"
  ports:
    - "8080:80"
  mounts:
    - "/host/path:/container/path"
  network: "bridge"
  cpu_limit: 1.5
  memory_limit: 512  # MB
```

### Systemd

```yaml
spec:
  command: ["/usr/bin/myapp", "--config", "/etc/myapp/config.yaml"]
  working_dir: "/var/lib/myapp"
  user: "appuser"
  environment:
    LOG_LEVEL: "info"
```

### Libvirt

```yaml
spec:
  vm_image: "/var/lib/libvirt/images/myapp.qcow2"
  vm_memory: 2048  # MB
  vm_cpus: 2
  vm_network: "bridge:br0"
  vm_graphics: "vnc"
```

## API 接口

### gRPC

```protobuf
service NodeService {
  rpc RegisterNode(RegisterNodeRequest) returns (RegisterNodeResponse);
  rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse);
  rpc ListNodes(ListNodesRequest) returns (ListNodesResponse);
}

service ServiceService {
  rpc DeployService(DeployServiceRequest) returns (DeployServiceResponse);
  rpc StopService(StopServiceRequest) returns (StopServiceResponse);
  rpc MigrateService(MigrateServiceRequest) returns (MigrateServiceResponse);
}
```

### REST

```
GET    /api/v1/nodes          # 列出所有节点
GET    /api/v1/nodes/{id}     # 获取节点详情
POST   /api/v1/services       # 部署服务
GET    /api/v1/services       # 列出所有服务
DELETE /api/v1/services/{id}  # 停止服务
POST   /api/v1/services/{id}/migrate  # 迁移服务
```

## 插件系统

Pulsar 支持通过插件扩展功能：

```bash
# 插件目录结构
plugins/
├── examples/
│   ├── check_network_plugin.py
│   └── service_manager_plugin.py
└── custom/
    └── my_plugin.py
```

插件配置：

```yaml
plugin:
  enable: true
  plugins:
    - name: "network-checker"
      type: "binary"
      path: "/opt/pulsar/plugins/network_checker"
      timeout: 30s
```

## 开发

### 依赖

- Go 1.21+
- Protobuf (用于生成 gRPC 代码)

### 生成 Protobuf

```bash
./scripts/generate_proto.sh
```

### 运行测试

```bash
make test
# 或
go test ./... -v
```

### 代码覆盖

```bash
go test ./... -coverprofile=coverage.out
go tool cover -html=coverage.out
```

## 项目结构

```
pulsar/
├── cmd/
│   ├── pulsar/           # 主程序入口
│   └── pulsarctl/        # 命令行工具
├── configs/              # 配置文件
├── internal/
│   ├── config/           # 配置管理
│   ├── logger/           # 日志组件
│   └── metrics/          # 指标组件
├── pkg/
│   ├── api/
│   │   ├── grpc/         # gRPC 接口
│   │   └── rest/         # REST 接口
│   ├── node/             # 节点管理
│   ├── service/          # 服务管理
│   ├── raft/             # Raft 层
│   ├── store/            # 存储层
│   ├── partition/        # 分区检测
│   ├── plugin/           # 插件系统
│   └── cluster/          # 集群协调
├── proto/                # Protobuf 定义
├── plugins/              # 插件示例
└── scripts/              # 构建脚本
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request。