# lightcd

**Repository Path**: liuqi_li/lightcd

## Basic Information

- **Project Name**: lightcd
- **Description**: 小鱼CD(LightCD) 轻量级持续交付平台：参考 Jenkins 设计的轻量级 CI/CD 工具，聚焦拉码→构建→发布→启停核心闭环，支持 Webhook/定时触发、多机并行发布、工具链自动探测安装、内嵌 SFTP 文件服务
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小鱼CD（LightCD）· 轻量级持续交付平台

参考 Jenkins 设计的一款轻量级 CI/CD 工具，聚焦中小团队「拉码 → 构建 → 发布 → 启停」的核心闭环，开箱即用、无插件市场负担。支持 Webhook / 定时自动触发，多机并行发布，内置 SFTP 文件中转服务。

> **技术栈**：前端 Vue3 + Vite + Element Plus + Pinia；后端 Spring Boot 2.7 + Java 8 + Spring Data JPA + Spring Security；数据库 H2（默认，零配置）/ MySQL 可选。

---

## 📦 项目构成

```
lightcd/
├── backend/          # Spring Boot 2.7 后端（Java 8，端口 9090）
│   ├── Dockerfile    # 后端镜像（含 JDK 运行环境）
│   ├── pom.xml       # Maven 构建，finalName=lightcd
│   ├── lightcd-workspace/   # 运行时工作区（源码检出/产物/日志/SFTP 根目录/H2 库）
│   └── src/main/
│       ├── java/com/lightcd/
│       │   ├── config/      # 安全 / WebSocket / 定时任务 / 启动初始化
│       │   ├── security/    # JWT 认证链
│       │   ├── common/      # 统一返回 R / 分页 / 异常处理 / 基类
│       │   ├── infra/       # 基础能力：git(JGit) / ssh(JSch) / shell / log / sftp(MINA)
│       │   └── module/      # 业务模块（见下）
│       └── resources/application.yml  # 配置（h2/mysql 双 profile）
└── frontend/         # Vue3 + Vite 前端管理台（生产 nginx :80）
    ├── Dockerfile    # 前端镜像（nginx 托管静态资源 + 反向代理 API/WS）
    ├── nginx.conf
    └── src/
        ├── api/      # axios 接口封装
        ├── router/   # 路由（11 个功能页 + 登录 + 个人中心）
        ├── store/    # Pinia 认证状态
        ├── views/    # 页面组件
        └── components/ # DeployDialog 等复用组件
```

---

## 🏗️ 系统架构

```
┌──────────────┐     HTTP/WS      ┌─────────────────────────────┐
│  Vue3 管理台  │ ──────────────▶ │  Spring Boot (9090)          │
│  ElementPlus │                 │  ├─ Auth / RBAC / OAuth2     │
└──────────────┘                 │  ├─ Project (Git 配置)       │
                                 │  ├─ Pipeline 执行引擎         │
┌──────────────┐   SFTP:2222     │  ├─ Host / Service / File    │
│ 研发投递文件  │ ◀─────────────  │  ├─ Toolchain / Env          │
└──────────────┘                 │  └─ SFTP Server (MINA SSHD)  │
                                 └───────────┬─────────────────┘
                                             │ SSH / SFTP (JSch)
                                 ┌───────────▼─────────────────┐
                                 │  目标主机（生产/测试/开发）    │
                                 │  Git 拉码 → 构建 → 发布 → 启停 │
                                 └─────────────────────────────┘
```

**流水线执行链路**：
`CHECKOUT（拉取指定分支/标签/提交）→ CHANGELOG（与上次成功版本 diff 变更清单）→ README（生成发布说明）→ BUILD（注入工具链环境变量执行构建）→ ARTIFACT（收集/打包产物）→ DEPLOY（备份 → 前置命令 → 上传 → 就位/解压 → 发布 README → 后置命令 → 重启服务 → 健康检查）→ DONE`

---

## 🧩 后端模块详解（com.lightcd）

| 包 | 模块 | 核心类 | 职责 |
|---|------|--------|------|
| `module/auth` | 认证与用户 | AuthController / AuthService / SysUser / UserOauth / oauth.* | 账号密码登录、OAuth2 第三方登录（微信/QQ/Gitee/GitHub）、JWT 签发、用户 CRUD（RBAC）、第三方账号绑定/解绑、改密 |
| `module/project` | 部署项目 | ProjectController / ProjectService / Project | 项目（Job）配置：Git 仓库与凭据、构建命令、产物策略、部署目标、Webhook 令牌、cron 定时部署、测试仓库连通性、远端分支/标签/提交历史查询 |
| `module/pipeline` | 流水线引擎 | PipelineController / PipelineService / Build / ReadmeGenerator | 构建触发（手动/Webhook/定时/回滚/重跑）、七阶段执行、并发调度、取消、构建历史/日志/README/产物、多机并行发布、变更文件 diff |
| `module/host` | 主机管理 | HostController / HostService / Host | 主机 CRUD 与分组、连通性测试、SSH 免密登录（密钥对生成 + 公钥写入）、资源指标、运维终端（远程执行单条命令） |
| `module/service` | 服务管理 | ServiceController / ServiceManager / ManagedService | 远程服务托管：JAR / Systemd / Docker / Nginx / Shell 五种类型，一键启停重启、状态刷新、HTTP 健康检查、日志拉取与实时跟踪 |
| `module/toolchain` | 工具链 | ToolchainController / ToolchainService / ToolchainDetector / ToolchainInstaller / EnvVariable | JDK/Node/Maven/Gradle 自动探测与一键安装、工具链校验、构建环境变量预览、全局环境变量（支持加密） |
| `module/file` | 文件管理 | FileController / FileService | 双视图文件管理：平台工作区（本地上传/下载/预览/删除）+ 远程主机 SFTP（上传/下载/预览/建目录/重命名/chmod/打包/递归删除），工作区文件一键推送远端 |
| `module/dashboard` | 工作台 | DashboardController | 平台总览：项目/主机/服务/构建统计、成功率、近 7 天构建趋势、最近构建、侧边栏计数器 |
| `infra/git` | Git 能力 | GitService / GitAuth | 基于 JGit：clone/fetch、指定分支/标签/提交号检出、与上次成功版本 diff、提交历史 |
| `infra/ssh` | SSH 能力 | SshSession / SshClientFactory / SshKeyUtil | 基于 JSch：远程命令执行、SFTP 上传下载、RSA 密钥对生成 |
| `infra/shell` | 本地执行 | LocalShellExecutor | 本地构建命令执行、取消信号中断、超时控制 |
| `infra/log` | 日志中心 | LogHub / BuildLogService / LogWebSocketHandler | 构建日志分段记录、WebSocket 实时推送（断线后全量日志兜底） |
| `infra/sftp` | SFTP 服务 | SftpServerService | 内嵌 SFTP 服务端（Apache MINA SSHD），复用平台账号密码，独立虚拟目录 |
| `config` | 全局配置 | SecurityConfig / WebSocketConfig / BeanConfig / ScheduleDeployTask / DataInitializer / AppProperties | 无状态 JWT 安全链、WebSocket 注册、构建线程池（并发 3）、cron 定时部署扫描、启动初始化（内置管理员 + 工具链探测 + 中断任务修复） |

---

## 🖥️ 前端页面（11 个功能菜单）

| 路由 | 页面 | 功能点 |
|------|------|--------|
| `/dashboard` | 工作台 | 平台统计卡片、构建成功率、近 7 天成功/失败趋势图、最近 10 次构建 |
| `/projects` | 部署项目 | 项目列表（关键词搜索、分组）、新建/编辑项目（Git/构建/产物/部署/Webhook/定时六段配置）、项目详情（最近构建、部署按钮、Webhook 令牌） |
| `/builds` | 构建部署 | 构建历史分页列表（状态/触发方式/版本）、构建详情（日志实时滚动、变更文件清单、提交记录、README 查看、产物下载、回滚/重跑/取消） |
| `/hosts` | 主机管理 | 主机列表、新增/编辑主机（密码或私钥）、连通性测试、一键开启/关闭免密、资源指标、运维终端 |
| `/services` | 服务管理 | 托管服务列表（实时状态）、五种类型模板、启停/重启/状态/健康检查/日志拉取/日志实时跟踪 |
| `/toolchains` | 工具链 | JDK/Node/Maven/Gradle 列表、重新探测、一键安装、环境变量预览、全局环境变量管理 |
| `/files` | 文件管理 | 双视图文件浏览器（工作区 / 远程主机）、上传/下载/预览/建目录/重命名/chmod/打包/推送 |
| `/sftp` | SFTP 服务 | 内嵌 SFTP 服务端状态、启动/停止/重启 |
| `/users` | 用户管理（仅管理员） | 用户分页列表、新增/编辑/删除用户、角色分配 |
| `/profile` | 个人中心 | 当前用户信息、修改密码、第三方账号绑定/解绑 |
| `/login` | 登录 | 账号密码登录、微信/QQ/Gitee/GitHub 第三方登录入口（按配置自动渲染） |

---

## ✨ 功能点总览

### 1️⃣ 认证与权限（RBAC）
- 账号密码登录 + BCrypt 加密存储；JWT 无状态令牌（24h 过期）
- OAuth2 第三方登录：**微信 / QQ / Gitee / GitHub** 四选一启用，策略模式自动渲染登录入口
- 三角色权限：`ADMIN`（全部）/ `DEVELOPER`（运维）/ `GUEST`（只读），用户管理仅 ADMIN 可见
- 已登录用户可绑定/解绑第三方账号，个人中心修改密码

### 2️⃣ 项目（Job）配置
- Git 仓库接入：支持 密码 / Token / SSH 私钥（AES 加密落库）三种凭据，默认分支、仓库连通性测试
- 构建配置：多行构建命令、monorepo 子目录（buildDir）、项目级环境变量（KEY=VALUE）、跳过构建、关联工具链
- 产物策略：单文件（FILE）或目录（DIR 自动打 tar.gz 并在远端解压）、产物路径支持 `target/*.jar` 通配、远端重命名
- 部署策略：多主机并行发布、远端部署目录、部署前/后命令、发布前备份（`.lightcd-backup` 保留 N 份轮转）、自动生成 `RELEASE-README.md` 并随产物发布
- 自动触发：Webhook（Gitee/GitHub/GitLab push）+ cron 定时部署（六段表达式，类似 Jenkins "Build periodically"）

### 3️⃣ 流水线执行引擎
- **七阶段执行**：CHECKOUT → CHANGELOG → README → BUILD → ARTIFACT → DEPLOY → DONE，每阶段状态实时可见
- **多触发方式**：手动、Webhook、定时、回滚、重跑，触发类型与操作人全程留痕
- **任意版本部署**：部署弹窗读取远端分支/标签列表 + 按分支拉取提交历史，精确选择任意 COMMIT 发布；支持回滚到任意历史构建
- **变更可视化**：自动 diff 上次成功版本，日志打印变更文件清单 + 提交记录，构建详情页可视化展示
- **工程化保障**：并发构建（默认 3）、单次超时（默认 60min）、任务取消（中断信号）、平台重启自动将中断任务标记失败
- **产物管理**：归档至工作区并可下载，目录型产物自动打包压缩

### 4️⃣ 主机管理
- 主机 CRUD + 分组管理，凭据（密码/私钥）AES 加密存储，接口返回掩码
- **免密登录**：平台生成 RSA 密钥对，一键写入目标机 `~/.ssh/authorized_keys`，此后测试/部署/SFTP 全链路免密
- 连通性测试、资源指标采集、运维终端（远程执行单条命令）

### 5️⃣ 服务管理（远程启停）
- 五种托管类型模板：**JAR / Systemd / Docker / Nginx / Shell 脚本**，内置启停/状态命令模板
- 一键 启动 / 停止 / 重启 / 状态刷新；HTTP 健康检查（启动后最多探测 6 次）
- 日志拉取（指定行数）+ **日志实时跟踪**（WebSocket 推送到 `service:{id}` 频道，可 tail -f 跟随）
- 流水线集成：部署前自动停服务、部署后自动启动并健康检查

### 6️⃣ 工具链与环境
- **自动探测**：扫描环境变量（`JAVA_HOME`/`MAVEN_HOME`/`NODE_HOME`/`GRADLE_HOME`）、PATH 可执行文件、常见安装目录（macOS/Linux/sdkman/nvm/Homebrew），自动识别版本
- **自动安装**：本机缺失 JDK（Adoptium Temurin）/ Node（nodejs.org，支持 latest-lts）/ Maven（Apache）时，启动自动补齐或页面一键安装到工作区
- 构建时自动注入 `JAVA_HOME`、`MAVEN_HOME`、`NODE_HOME`、`PATH`；全局环境变量支持加密存储
- 环境变量预览：选择工具链组合实时预览最终注入的构建环境

### 7️⃣ 文件管理（双视图）
- **平台工作区**：上传 / 下载 / 预览 / 删除
- **远程主机 SFTP**：上传 / 下载 / 预览 / 建目录 / 删除（含递归）/ 重命名 / chmod / 目录打包下载
- **一键推送**：工作区文件直接传输到任意远端主机目录

### 8️⃣ 内嵌 SFTP 服务端
- Apache MINA SSHD 实现，独立端口（默认 2222），**复用平台账号密码**，每人独立虚拟目录
- 研发无需登录平台即可通过 SFTP 客户端直接投递安装包，web 页面可启停/重启服务

### 9️⃣ 工作台与运维洞察
- 平台总览：项目 / 主机 / 服务（含运行中）/ 构建（总数/成功/失败/运行中）统计
- 近 7 天构建成功 / 失败趋势、最近 10 次构建动态

### 🔟 Webhook 与定时部署
- Webhook：项目配置开启后生成独立令牌，`/api/builds/webhook/{code}?token=xxx&branch=main` 推送即触发
- 定时部署：cron 表达式（秒 分 时 日 月 周）每分钟扫描命中，页面提供「计算下次触发时间」校验

---

## 🚀 快速开始

### 方式一：Docker Compose（推荐）

```bash
cd lightcd
docker compose up -d --build
# 前端：http://localhost    （nginx :80）
# 后端 API：http://localhost:9090
# 内嵌 SFTP：localhost:2222
```

### 方式二：本地开发

```bash
# 1. 启动后端（需 JDK 8）
cd lightcd/backend
mvn spring-boot:run          # 默认 H2 文件库，零配置
# 或打包运行
mvn -DskipTests package && java -jar target/lightcd.jar

# 2. 启动前端
cd lightcd/frontend
npm install
npm run dev                  # http://localhost:5173，已代理 /api 与 /ws 到 9090
```

### 默认账号

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | admin123 | ADMIN（管理员） |

> 首次启动自动创建管理员账号；自动探测本机工具链，缺失则后台自动安装；自动将上次中断的构建任务标记为失败。

---

## ⚙️ 关键配置（`backend/src/main/resources/application.yml`）

| 配置项 | 说明 | 默认 |
|--------|------|------|
| `server.port` | 后端端口 | 9090 |
| `spring.profiles.active` | h2 / mysql | h2 |
| `lightcd.workspace` | 工作区：检出、产物、日志、SFTP 根目录 | ./lightcd-workspace |
| `lightcd.jwt.secret` / `expire-hours` | JWT 密钥（生产务必更换 ≥32 位）/ 过期时间 | 内置示例 / 24h |
| `lightcd.crypto.key` | AES 密钥（16/32 位，加密主机密码/私钥/Git 凭据） | 内置示例 |
| `lightcd.sftp-server.enabled/port` | 内嵌 SFTP 开关与端口 | true / 2222 |
| `lightcd.build.concurrency/timeout-minutes/keep-builds` | 构建并发数 / 超时（分钟）/ 日志保留条数 | 3 / 60 / 200 |
| `lightcd.toolchain.auto-install/jdk-version/node-version/maven-version` | 工具链自动安装开关与版本 | true / 17 / latest-lts / 3.9.9 |
| `lightcd.oauth.clients.*` | 微信 / QQ / Gitee / GitHub 的 client-id/secret（开启后登录页出现对应按钮） | 全部关闭 |

**使用 MySQL**：`java -jar target/lightcd.jar --spring.profiles.active=mysql`，按需修改 mysql profile 连接信息。

---

## 🔔 Webhook 触发部署

1. 项目配置中开启「启用 Webhook」，保存后查看 / 重置令牌。
2. 在 Gitee / GitHub / GitLab 仓库设置中添加 Webhook：
   - URL：`http://<你的域名>/api/builds/webhook/<项目code>?token=<项目令牌>&branch=main`
   - 触发事件：Push（推送）
3. 每次推送自动触发部署，无需登录。

---

## 🔐 免密登录配置流程

1. 主机管理 → 添加主机（IP、用户名、密码或私钥）→ 保存。
2. 点击「开启免密」→ 平台生成密钥对并把公钥写入目标机 `~/.ssh/authorized_keys`。
3. 之后连通性测试、部署、SFTP 全链路免密。

---

## 🛡️ 安全说明

- 密码与凭据使用 AES/GCM 加密落库，接口返回一律掩码（`******`）。
- JWT 无状态鉴权（BCrypt 存储密码），Webhook 走独立项目令牌校验。
- 内置 `admin/admin123`，首次登录后请立即修改；生产环境务必更换 JWT 密钥与 AES 密钥。
- SFTP 服务复用平台用户密码认证，建议仅在内网或经堡垒机暴露。

---

## 📄 开源协议

本项目采用 [Apache License 2.0](LICENSE)，允许自由使用、修改、分发与商用（含专利授权），修改后需保留版权与协议声明。

- Copyright 2026 liuqi-li (磊追浪)