# Alfred

**Repository Path**: leonscript/alfred

## Basic Information

- **Project Name**: Alfred
- **Description**: Alfred workflow automation system - 工作流自动化系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-27
- **Last Updated**: 2025-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Alfred - 极简版CICD工具

Alfred是一个使用Go语言开发的轻量级CICD工具，相当于极简版本的Jenkins。它提供了Flow、Node、Action三层架构，支持GitLab webhook集成，并具备完整的HTTP API接口。

## 功能特性

- **三层架构**: Flow（工作流）-> Node（步骤）-> Action（具体操作）
- **多脚本支持**: 支持Shell和Python脚本执行
- **GitLab集成**: 内置GitLab webhook监听，支持Push和Merge Request事件
- **数据持久化**: 使用SQLite3数据库存储所有配置和执行记录
- **HTTP API**: 完整的RESTful API接口
- **实时监控**: 支持查询Flow运行状态和历史记录
- **消息通知**: 支持HTTP POST方式的消息推送通知
- **单元测试**: 使用Convey框架提供完整的单元测试覆盖

## 快速开始

### 安装依赖

```bash
go mod download
```

### 编译运行

```bash
go build -o alfred .
./alfred
```

### 命令行参数

```bash
./alfred -h
```

可用参数：
- `-port`: HTTP服务端口 (默认: 8080)
- `-db`: SQLite数据库文件路径 (默认: ./alfred.db)
- `-workdir`: 工作目录路径 (默认: ./workspace)
- `-webhook-secret`: GitLab webhook密钥 (默认: alfred-secret)
- `-mode`: 运行模式 debug/release (默认: debug)

### 示例启动命令

```bash
./alfred -port 8080 -db ./alfred.db -workdir ./workspace -webhook-secret my-secret -mode release
```

## API文档

### Flow管理

#### 创建Flow
```http
POST /api/v1/flows
Content-Type: application/json

{
  "name": "我的工作流",
  "description": "这是一个示例工作流",
  "branch": "main",
  "repo_url": "https://gitlab.example.com/user/repo.git"
}
```

#### 获取Flow列表
```http
GET /api/v1/flows
```

#### 获取单个Flow
```http
GET /api/v1/flows/{flow_id}
```

#### 更新Flow
```http
PUT /api/v1/flows/{flow_id}
Content-Type: application/json

{
  "name": "更新后的工作流",
  "description": "更新后的描述"
}
```

#### 删除Flow
```http
DELETE /api/v1/flows/{flow_id}
```

### Node管理

#### 创建Node
```http
POST /api/v1/nodes
Content-Type: application/json

{
  "flow_id": "flow-uuid",
  "name": "构建步骤",
  "description": "编译和构建代码",
  "order": 1
}
```

#### 获取Node列表
```http
GET /api/v1/nodes?flow_id={flow_id}
```

#### 获取单个Node
```http
GET /api/v1/nodes/{node_id}
```

#### 更新Node
```http
PUT /api/v1/nodes/{node_id}
```

#### 删除Node
```http
DELETE /api/v1/nodes/{node_id}
```

### Action管理

#### 创建Action
```http
POST /api/v1/actions
Content-Type: application/json

{
  "node_id": "node-uuid",
  "name": "编译代码",
  "type": "shell",
  "content": "go build -o app .",
  "order": 1
}
```

支持的Action类型：
- `shell`: Shell脚本
- `python`: Python脚本

#### 获取Action列表
```http
GET /api/v1/actions?node_id={node_id}
```

#### 获取单个Action
```http
GET /api/v1/actions/{action_id}
```

#### 更新Action
```http
PUT /api/v1/actions/{action_id}
```

#### 删除Action
```http
DELETE /api/v1/actions/{action_id}
```

### Flow执行

#### 手动执行Flow
```http
POST /api/v1/flows/{flow_id}/execute
Content-Type: application/json

{
  "commit_id": "abc123def456",
  "branch": "main"
}
```

#### 获取Flow执行状态
```http
GET /api/v1/executions/{execution_id}/status
```

#### 获取Flow执行历史
```http
GET /api/v1/flows/{flow_id}/executions
```

#### 获取所有执行记录
```http
GET /api/v1/executions
```

### 通知配置

#### 创建通知配置
```http
POST /api/v1/notifications
Content-Type: application/json

{
  "flow_id": "flow-uuid",
  "url": "https://your-webhook-url.com/notify"
}
```

#### 获取通知配置
```http
GET /api/v1/notifications?flow_id={flow_id}
```

## GitLab Webhook配置

### 1. 在GitLab项目中配置Webhook

1. 进入项目设置 -> Webhooks
2. URL: `http://your-alfred-server:8080/webhook/gitlab`
3. Secret Token: 与启动参数`-webhook-secret`保持一致
4. 触发事件: 选择"Push events"和"Merge request events"

### 2. Webhook事件处理

Alfred会自动处理以下GitLab事件：
- **Push Events**: 当代码推送到配置的分支时触发Flow执行
- **Merge Request Events**: 当创建或更新Merge Request时触发Flow执行

## 工作流示例

### 创建一个完整的CI/CD工作流

1. **创建Flow**
```bash
curl -X POST http://localhost:8080/api/v1/flows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Go项目CI/CD",
    "description": "Go项目的持续集成和部署",
    "branch": "main",
    "repo_url": "https://gitlab.example.com/myteam/myproject.git"
  }'
```

2. **创建构建Node**
```bash
curl -X POST http://localhost:8080/api/v1/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "your-flow-id",
    "name": "构建阶段",
    "description": "编译和测试代码",
    "order": 1
  }'
```

3. **添加构建Actions**
```bash
# 下载依赖
curl -X POST http://localhost:8080/api/v1/actions \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "your-node-id",
    "name": "下载依赖",
    "type": "shell",
    "content": "go mod download",
    "order": 1
  }'

# 运行测试
curl -X POST http://localhost:8080/api/v1/actions \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "your-node-id",
    "name": "运行测试",
    "type": "shell",
    "content": "go test ./...",
    "order": 2
  }'

# 构建应用
curl -X POST http://localhost:8080/api/v1/actions \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "your-node-id",
    "name": "构建应用",
    "type": "shell",
    "content": "go build -o app .",
    "order": 3
  }'
```

4. **配置通知**
```bash
curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "your-flow-id",
    "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
  }'
```

## 通知消息格式

### 失败通知
```json
{
  "status": "failed",
  "flow_id": "flow-uuid",
  "flow_execution_id": "execution-uuid",
  "flow_name": "Go项目CI/CD",
  "branch": "main",
  "commit_id": "abc123def456",
  "error_message": "构建失败: exit status 1",
  "timestamp": "2024-01-15T10:30:00Z"
}
```

### 成功通知
```json
{
  "status": "success",
  "flow_id": "flow-uuid",
  "flow_execution_id": "execution-uuid",
  "flow_name": "Go项目CI/CD",
  "branch": "main",
  "commit_id": "abc123def456",
  "timestamp": "2024-01-15T10:35:00Z"
}
```

## 开发和测试

### 运行单元测试

```bash
# 运行所有测试
go test ./...

# 运行特定包的测试
go test ./models
go test ./database
go test ./executor
go test ./api
go test ./webhook
go test ./notification

# 运行测试并显示覆盖率
go test -cover ./...

# 生成测试覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

### 使用Convey测试框架

项目使用[GoConvey](https://github.com/smartystreets/goconvey)测试框架，提供了更好的测试组织和报告。

启动Convey Web界面：
```bash
$GOPATH/bin/goconvey
```

然后访问 http://localhost:8080 查看测试结果。

## 项目结构

```
Alfred/
├── main.go                 # 主程序入口
├── go.mod                  # Go模块定义
├── README.md               # 项目文档
├── models/                 # 数据模型
│   ├── models.go
│   └── models_test.go
├── database/               # 数据库操作
│   ├── database.go
│   ├── node_operations.go
│   ├── action_operations.go
│   ├── execution_operations.go
│   └── database_test.go
├── executor/               # 执行引擎
│   ├── executor.go
│   └── executor_test.go
├── api/                    # HTTP API
│   ├── handlers.go
│   ├── execution_handlers.go
│   ├── routes.go
│   └── handlers_test.go
├── webhook/                # Webhook处理
│   ├── webhook.go
│   └── webhook_test.go
└── notification/           # 通知服务
    ├── notification.go
    └── notification_test.go
```

## 配置说明

### 环境变量

可以通过环境变量配置Alfred：

```bash
export ALFRED_PORT=8080
export ALFRED_DB_PATH=./alfred.db
export ALFRED_WORK_DIR=./workspace
export ALFRED_WEBHOOK_SECRET=my-secret
export ALFRED_MODE=release
```

### 数据库

Alfred使用SQLite3作为数据库，自动创建以下表：
- `flows`: 工作流配置
- `nodes`: 工作流步骤
- `actions`: 具体操作
- `flow_executions`: 工作流执行记录
- `node_executions`: 步骤执行记录
- `action_executions`: 操作执行记录
- `notification_configs`: 通知配置

## 故障排除

### 常见问题

1. **Webhook不触发**
   - 检查GitLab webhook配置中的URL和Secret
   - 确认Alfred服务正在运行且端口可访问
   - 查看Alfred日志中的webhook事件

2. **Action执行失败**
   - 检查Action的脚本内容是否正确
   - 确认执行环境中有必要的依赖（如python、shell等）
   - 查看Action执行记录中的错误信息

3. **通知不发送**
   - 检查通知配置中的URL是否正确
   - 确认目标服务器可以接收HTTP POST请求
   - 查看Alfred日志中的通知发送记录

### 日志查看

Alfred在debug模式下会输出详细的日志信息，包括：
- HTTP请求和响应
- Webhook事件处理
- Flow/Node/Action执行过程
- 数据库操作
- 通知发送结果

## 贡献

欢迎提交Issue和Pull Request来改进Alfred！

## 许可证

MIT License