# BeaverCI

**Repository Path**: huaguoguo/BeaverCI

## Basic Information

- **Project Name**: BeaverCI
- **Description**: BeaverCI - A simple CI/CD platform
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BeaverCI

![Version](https://img.shields.io/badge/version-1.2.0-blue)
![Go](https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go)
![License](https://img.shields.io/badge/license-MIT-green)

**BeaverCI v1.2.0** - 一个轻量级的持续集成（CI）系统，基于 Go 语言开发，提供项目构建管理、Docker 镜像构建和实时构建日志查看等功能。

> 🔧 **v1.2.0 Docker配置功能上线** - 支持自定义端口映射和卷挂载

📋 **[查看完整版本更新日志 →](CHANGELOG.md)**

## 💡 为什么叫"河狸"？

**河狸（Beaver）** 是自然界最著名的"工程师"和"建筑师"：

- 🏗️ **修建水坝**：河狸能够建造复杂的水坝系统，改变河流走向
- 🔧 **工程能力**：它们使用树枝、泥土等材料，构建坚固耐用的结构
- 👷 **勤劳工作**：河狸不知疲倦地工作，不断完善自己的家园
- 🌊 **水流管理**：精确控制水流，创造适合生存的环境

**BeaverCI** 就像数字世界的河狸：

- 🏗️ **构建流水线**：自动化构建和部署，如同河狸修建水坝
- 🔧 **工程管理**：管理代码构建过程，确保每个环节稳固可靠
- 👷 **持续集成**：不知疲倦地执行构建任务，保证代码质量
- 🌊 **流程控制**：精确控制构建流程，让代码像水流一样顺畅流动

> *"像河狸一样，我们也在构建数字世界的基础设施！"* 🦫

## ✨ 核心功能

### 🚀 构建管理
- **项目构建管理**：创建、编辑、删除和查看构建项目
- **Git 仓库集成**：自动克隆 Git 仓库并触发构建
- **智能配置获取** ✨：自动从Git仓库获取分支列表、Dockerfile和.env文件，一键填充表单
- **Docker 镜像构建**：自动构建 Docker 镜像，支持多阶段构建
- **停止构建**：支持手动停止正在进行的构建任务
- **构建历史记录**：查看和管理历史构建记录

### 🔧 配置管理
- **环境变量配置**：支持为项目配置 .env 文件，自动传递给 Docker 容器
- **灵活的环境变量**：支持自定义构建环境变量和运行时配置
- **数据持久化**：SQLite 数据库存储项目和构建信息

### 🐳 Docker配置 ⭐
- **端口映射**：自定义宿主机和容器端口的映射关系 (-p)
- **卷挂载**：配置宿主机目录到容器的挂载 (-v)
- **Web界面配置**：友好的可视化配置界面
- **API支持**：完整的RESTful API支持
- **向后兼容**：现有项目无需修改即可正常工作

### 📊 实时监控
- **实时构建日志**：通过 WebSocket 实时查看构建过程和日志
- **构建状态追踪**：实时监控构建状态（pending/running/success/failed/stopped）
- **Web 控制台**：提供现代化的 Web 管理界面

### 🧪 测试与质量
- **E2E 自动化测试**：使用 Playwright 进行端到端自动化测试
- **版本管理**：完善的版本控制系统，支持语义化版本
- **Docker 支持**：完整的 Docker 构建和部署方案

## 🛠️ 技术栈

- **后端**：Go 1.26+ + Gin Framework
- **数据库**：SQLite (go-sqlite3)
- **容器**：Docker Engine API
- **前端**：HTML5 + CSS3 + JavaScript (原生)
- **实时通信**：WebSocket (gorilla/websocket)
- **版本控制**：Git (go-git)
- **测试框架**：Playwright (E2E)

## 🚀 快速开始

### 方式一：Docker 运行（推荐）

```bash
# 拉取镜像（或从源码构建）
docker build -t beaverci:1.1.1 -t beaverci:latest .

# 运行容器
docker run -d \
  --name beaverci \
  -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./data:/app/data \
  -v ./build:/tmp/beaverci \
  beaverci:latest

# 访问 http://localhost:8080
```

### 方式二：本地编译运行

#### 环境要求

- Go 1.26+
- Docker
- Git
- Make（可选，但推荐）

#### 安装与运行

```bash
# 克隆项目
git clone https://gitee.com/huaguoguo/BeaverCI.git
cd BeaverCI

# 方式 A：使用 Makefile（推荐）
make build      # 构建应用
make run        # 运行应用

# 方式 B：手动构建
go build -o beaverci ./cmd/server
./beaverci

# 访问 http://localhost:8080
```

## 📁 项目结构

```
beaverci/
├── cmd/server/          # 服务入口
├── internal/
│   ├── config/         # 配置管理
│   ├── database/       # 数据库操作
│   ├── docker/         # Docker 镜像构建
│   ├── git/            # Git 仓库操作
│   ├── handler/        # HTTP 处理器
│   ├── model/          # 数据模型
│   └── version/        # 版本管理 ⭐
├── web/                # 前端资源
│   ├── index.html
│   └── static/
│       ├── css/        # 样式文件
│       └── js/         # 脚本文件
├── tests/              # E2E 测试
├── data/               # 数据目录（挂载点）
├── build/              # 构建目录（挂载点）
├── Dockerfile          # Docker 构建配置
├── Makefile            # 构建自动化 ⭐
├── go.mod
├── VERSION.md          # 版本管理文档
└── RELEASE.md          # 发布指南
```

> ⭐ 标记的为 v1.1.0+ 新增功能

## 🔌 API 接口

### 项目管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/projects | 获取项目列表 |
| POST | /api/projects | 创建项目 |
| PUT | /api/projects/:id | 更新项目 |
| DELETE | /api/projects/:id | 删除项目 |

### 构建管理

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/projects/:id/build | 触发构建 |
| POST | /api/builds/:id/stop | 停止构建 |
| GET | /api/builds | 获取所有构建 |
| GET | /api/projects/:id/builds | 获取项目构建历史 |
| GET | /api/builds/:id/log | 获取构建日志 |

### Docker配置 ⭐

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/projects/:id | 获取项目信息（包含Docker配置） |
| PUT | /api/projects/:id | 更新项目的Docker配置 |

### 用户认证 ⭐

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/auth/login | 用户登录 |
| POST | /api/auth/logout | 用户登出 |
| GET | /api/auth/status | 获取当前用户状态 |

### 其他

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/version | 获取版本信息 |
| GET | /ws/build/:id | WebSocket 连接 |
| GET | /login | 登录页面 ⭐ |
| GET | / | Web 控制台（需认证） |

## ⚙️ 配置说明

### 环境变量

| 环境变量 | 默认值 | 描述 |
|----------|--------|------|
| PORT | 8080 | 服务监听端口 |
| DB_PATH | /app/data/beaverci.db | 数据库文件路径 |
| BUILD_DIR | /tmp/beaverci | 构建工作目录 |

### Docker 卷挂载

推荐挂载以下目录以实现数据持久化：

```bash
-v ./data:/app/data      # 数据库文件
-v ./build:/tmp/beaverci # 构建临时文件
-v /var/run/docker.sock:/var/run/docker.sock  # Docker 通信
```

### Docker配置 (v1.2.0+) ⭐

BeaverCI v1.2.0+ 支持为每个项目配置自定义的 Docker 运行参数：

#### 端口映射 (docker_ports)
- **格式**: `host_port:container_port;host_port2:container_port2`
- **示例**: `8080:3000;9090:4000`
- **说明**: 多个端口映射用分号分隔，留空则自动从 Dockerfile EXPOSE 读取

#### 卷挂载 (docker_volumes)
- **格式**: `host_path:container_path;host_path2:container_path2`
- **示例**: `/data:/app/data;/logs:/app/logs`
- **说明**: 多个卷挂载用分号分隔，留空则不配置额外卷挂载

详细文档请查看：[Docker配置指南](docs/DOCKER_CONFIG_GUIDE.md)

## 📖 使用指南

### 基本流程

1. **添加项目**：在 Web 界面点击"添加项目"，填写：
   - 项目名称
   - Git 仓库地址
   - 分支名称
   - Docker 镜像名称
   - 环境变量配置（可选）

2. **触发构建**：选择项目后点击"触发构建"按钮

3. **查看日志**：构建过程中日志会实时显示在日志面板中

4. **管理构建**：
   - 查看构建历史
   - 停止正在进行的构建
   - 查看构建详情

### 高级用法

#### 使用 Makefile

```bash
# 查看所有可用命令
make help

# 构建应用
make build

# 构建 Docker 镜像
make docker-build

# 查看版本信息
make version

# 运行应用
make run
```

#### 版本管理

详细文档请查看：
- [VERSION.md](VERSION.md) - 版本管理规范
- [RELEASE.md](RELEASE.md) - 发布新版本指南
- [CHANGELOG.md](CHANGELOG.md) - 版本更新日志 ⭐

```bash
# 查询当前版本
curl http://localhost:8080/api/version
```

## 🧪 测试

### E2E 自动化测试

本项目包含使用 Playwright 编写的端到端测试，可以自动验证完整构建流程。

```bash
# 进入测试目录
cd tests

# 运行所有测试
./run-tests.sh

# 使用 UI 模式进行可视化调试
./run-tests.sh --ui
```

详细文档请查看：[tests/README.md](tests/README.md)

### 测试覆盖

- ✅ 项目 CRUD 操作
- ✅ 构建触发与执行
- ✅ 构建状态更新
- ✅ 实时日志推送
- ✅ 停止构建功能
- ✅ 日志持久化

## 📝 版本历史

📋 **查看完整的版本更新日志**: [CHANGELOG.md](CHANGELOG.md)

---

### v1.2.0 (2026-04-16) 🐳

**Docker配置功能上线！**

> 📄 详细变更内容请查看：[CHANGELOG.md - v1.2.0](CHANGELOG.md#120---2026-04-16)

#### ✨ 新功能
- ✅ Docker端口映射配置 (`-p`): 自定义宿主机和容器端口的映射关系
- ✅ Docker卷挂载配置 (`-v`): 配置宿主机目录到容器的挂载
- ✅ Web界面友好配置：在创建/编辑项目时可直接配置Docker参数
- ✅ API完整支持：通过RESTful API管理Docker配置
- ✅ 智能默认值：未配置时自动从Dockerfile EXPOSE指令读取端口
- ✅ 向后兼容：现有项目无需修改即可正常工作

#### 🎨 界面优化
- ✅ 在项目表单中添加Docker配置区域
- ✅ 清晰的标签和示例占位符
- ✅ 帮助提示文字说明配置格式

#### ⚙️ 技术实现
- ✅ 数据库schema更新：projects表新增docker_volumes和docker_ports字段
- ✅ 数据模型扩展：Project结构体及相关请求结构体支持新字段
- ✅ Docker运行时增强：支持自定义配置的容器运行函数
- ✅ 解析器实现：端口映射和卷挂载字符串解析

---

### v1.1.1 (2026-04-15) 🔐

**用户认证系统上线！**

> 📄 详细变更内容请查看：[CHANGELOG.md - v1.1.1](CHANGELOG.md#111---2026-04-15)

#### ✨ 新功能
- ✅ 登录/登出功能（邮箱+密码认证）
- ✅ Session 管理（Cookie-based，7天自动续期）
- ✅ 认证中间件保护所有 API
- ✅ 深色主题登录页（与主页配色一致）
- ✅ 河狸品牌 Logo + 功能特性展示
- ✅ bcrypt 密码加密
- ✅ 默认管理员账户 (admin@beaverci.com)

#### 🎨 界面优化
- ✅ 左右分栏登录页布局
- ✅ 毛玻璃效果卡片
- ✅ 响应式设计
- ✅ 新增登出按钮

#### ⚠️ 破坏性变更
- 所有 API 需要认证后才能访问
- 未登录访问主页会重定向到登录页
- WebSocket 连接需要携带 Session Cookie

---

### v1.1.0 (2026-04-14) 🚀

**功能增强版本发布！**

> 📄 详细变更内容请查看：[CHANGELOG.md - v1.1.0](CHANGELOG.md#110---2026-04-14)

#### ✨ 新功能
- ✅ 主页面布局重构（三列改两列）
- ✅ 操作面板整合优化
- ✅ 智能构建按钮直接显示
- ✅ 构建详情头部信息展示
- ✅ 自定义滚动条样式
- ✅ 响应式设计优化
- ✅ UI/UX 全面改进

#### ♻️ 技术优化
- JavaScript 逻辑重构
- CSS 样式优化
- 移除冗余代码
- 性能优化

#### 📚 文档
- 新增页面重构说明文档
- 更新相关技术文档

---

### v1.0.0 (2026-04-13) 🎉

**第一个正式版本发布！**

> 📄 详细变更内容请查看：[CHANGELOG.md - v1.0.0](CHANGELOG.md#100---2026-04-13)

#### ✨ 新功能
- ✅ 项目管理系统（CRUD）
- ✅ Git 仓库集成与自动克隆
- ✅ Docker 镜像构建（支持多阶段构建）
- ✅ 实时构建日志（WebSocket）
- ✅ 构建历史记录与状态追踪
- ✅ 停止构建功能
- ✅ 环境变量配置（.env 文件支持）
- ✅ 数据持久化（SQLite）
- ✅ 版本管理系统
- ✅ E2E 自动化测试框架
- ✅ Docker 容器化部署
- ✅ Makefile 构建自动化

#### 🛠️ 技术特性
- 响应式 Web 界面
- RESTful API 设计
- 实时双向通信
- 容器隔离构建
- 日志流式输出

#### 📚 文档
- 完整的使用文档
- API 接口文档
- 版本管理指南
- 发布流程说明

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📚 相关文档

- 📘 [README.md](README.md) - 项目说明（当前文档）
- 📗 [CHANGELOG.md](CHANGELOG.md) - 版本更新日志 ⭐
- 📙 [VERSION.md](VERSION.md) - 版本管理规范
- 📕 [RELEASE.md](RELEASE.md) - 发布新版本指南
- 📔 [tests/README.md](tests/README.md) - E2E 测试文档
- 📖 [docs/DOCKER_CONFIG_GUIDE.md](docs/DOCKER_CONFIG_GUIDE.md) - Docker配置指南 ⭐
- 📖 [docs/DOCKER_CONFIG_IMPLEMENTATION.md](docs/DOCKER_CONFIG_IMPLEMENTATION.md) - Docker配置实现细节 ⭐

## 📄 许可证

MIT License

---

**Made with ❤️ by BeaverCI Team**