# pipeloom

**Repository Path**: Adnois/pipeloom

## Basic Information

- **Project Name**: pipeloom
- **Description**: 自托管 DevOps 平台：流水线编排 · 代码扫描 · 制品晋级 · 部署发布 · 服务器/容器运维。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-09-24
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# Pipeloom

**自托管 DevOps 平台：流水线编排 · 代码扫描 · 制品晋级 · 部署发布 · 服务器/容器运维。**
Kotlin / Spring Boot 控制面 + Vue 3 控制台 + MySQL 单一状态存储，另配一个只出不进的 Go 探针。

![Kotlin](https://img.shields.io/badge/Kotlin-2.3-A97BFF?logo=kotlin&logoColor=white)
![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.1-6DB33F?logo=springboot&logoColor=white)
![Vue](https://img.shields.io/badge/Vue-3.5-42B883?logo=vue.js&logoColor=white)
![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1?logo=mysql&logoColor=white)
![License: Private](https://img.shields.io/badge/license-Private-lightgrey)

[English](README.md) | 简体中文

</div>

---

## 为什么是 Pipeloom

内部交付链路通常是一堆工具的拼装：一台 CI、一套 SonarQube、几份 Ansible playbook、一个 Portainer 标签页、一张"这次发布谁批的"的表格，再加某个人写的告警 cron。每次工具之间交接，上下文就掉一次，最后没人能回答「生产现在跑的是哪个版本、谁放行的」。

Pipeloom 把这个闭环收进一个控制面：拉代码的流水线、给代码打分的扫描、卡环境的制品晋级、把包发出去的部署、出问题时要进的运维台，共用同一套节点目录、同一份扫描指标、同一个凭据保险库——质量门禁读的就是扫描节点写出的那些数字，制品没过该环境的审批部署就不会开始，所有写操作最后落进同一条防篡改审计流。

| | Pipeloom | Jenkins | GitLab CI + SonarQube + Ansible | 自研脚本 + cron |
|---|:---:|:---:|:---:|:---:|
| 可视化流水线编排（Stage→Job DAG） | ✅ 内置 | 插件 | 只有 `.gitlab-ci` | ❌ |
| 代码扫描 + 质量红线 | ✅ 14 个引擎 + 内置规则 | 插件 | 独立 SonarQube | ❌ |
| 制品晋级审批（按环境） | ✅ 服务端强制拦截 | ❌ | ❌ | ❌ |
| 多目标部署（SSH / Compose / Kubernetes） | ✅ 内置 | 插件 | Ansible | 自己写 |
| 服务器 / 容器运维 + Web 终端 | ✅ 内置 | ❌ | Portainer | ❌ |
| 免装 Agent 的 SSH **与** 只出不进的探针 | ✅ | ❌ | 只有 Ansible | ❌ |
| 插件市场（节点热插拔，无需重启） | ✅ | ✅ | ❌ | ❌ |
| 凭据保险库（AES-256-GCM，只存密文） | ✅ | 插件 | CI 变量 | 明文 env |
| append-only 审计（触发器硬拦 UPDATE/DELETE） | ✅ | 插件 | ❌ | ❌ |
| RBAC（ADMIN/OPERATOR/VIEWER）+ 作用域化 API 令牌 | ✅ | 插件 | ✅ | ❌ |
| 运维负担 | 1 个 jar + 1 个静态站 + MySQL | JVM + 插件 | 3+ 个服务 | 看你留了多少 |

## 界面导览

本仓库附带截图，实际会用到的页面：

- **概览** —— 流水线 / 服务器 / 探针数量、凭据数、24 小时运行量与成功率、趋势、最近运行。
![alt text](docs/screenshots/overview.png)
- **流水线** —— 两级画布（阶段横向排列、任务在阶段内纵向堆叠）、节点配置抽屉的动态字段、YAML 导入、按版本的配置历史与回滚。
![alt text](docs/screenshots/pipeline.png)
- **运行详情** —— 阶段时间线、逐步骤状态、实时日志（服务端每 2 秒落一次步骤日志，前端 2 秒轮询）、报告、制品、审批操作、重跑 / 取消 / 强杀。
![alt text](docs/screenshots/run-detail.png)
- **服务器与容器** —— SSH 与 Kubernetes 目标、跨主机容器聚合视图、镜像 / 卷 / 网络 / Stack、`system df` 与 prune、实时 stats、Web 终端。
![alt text](docs/screenshots/server-and-container.png)
- **代码扫描与质量红线** —— 节点工具矩阵、扫描规则清单、质量指标、红线规则、制品晋级审批。
![alt text](docs/screenshots/artifact-report.png)
![alt text](docs/screenshots/quality-redline.png)
- **插件市场** —— 插件包、版本、按用户安装、评论、内置的插件开发指南与 Kotlin 模板。
![alt text](docs/screenshots/plugin-marketplace.png)
- **设置** —— 用户与角色、通知渠道、API 令牌、审计日志、AI 提供商、账户，另有顶栏的站内消息中心。
![alt text](docs/screenshots/setting.png)
## 能力总览

- **🔐 安全地基** —— argon2id 口令哈希 · 登录口令 RSA-OAEP 加密传输 · 每会话 CSRF 令牌 · 登录失败锁定（默认 5 次 / 15 分钟）· 会话 Cookie 可开 `Secure` · Bearer API 令牌（`pipeline:trigger` 作用域）· `ADMIN` / `OPERATOR` / `VIEWER` 三角色在服务端强制：**读请求登录即可，写请求默认需要 OPERATOR+**（`@RequireAuth` 不写 roles 也不再对 VIEWER 放行）；凭据明文揭示、API 令牌签发、用户管理、插件与规则库、反代路由、定时调度、`docker system prune` 这类平台级动作**显式只给 ADMIN**；scope 已按路径命中的存量自动化 token 不受影响。`AuthContractTest` + `AuthInterceptorRoleTest` + `PipelineVisibilityTest` 把这套策略钉住（新增匿名端点必须登记理由；别人的 private 流水线要在列表、详情、运行历史里一起消失）。前端按钮同步按角色隐藏。
- **🗝 凭据保险库** —— git token / git 账号口令 / SSH 私钥 / SSH 口令 / 镜像仓库 / kubeconfig 六类凭据，用 `PIPELOOM_VAULT_KEY`（base64、32 字节）走 AES-256-GCM 封装，落库格式 `nonce ‖ 密文 ‖ tag`。明文既不进数据库，也不会在 GET 响应里回来。主密钥没配 → 相关能力统一返回 `503 vault_unconfigured`，而不是半死不活地跑。凭据过期每小时扫一次，提前 7 天预警。
- **🧩 流水线编排** —— Stage→Job 两级 DAG、`needs` 依赖、按拓扑分层调度（同层阶段并发执行；阶段内任务默认按声明顺序，`job.needs` 会做稳定拓扑排序并在上游失败/被跳过时连带跳过下游）、阶段级与任务级 `allowFailure`、阶段/任务 `when` 条件（分支通配、触发事件、表达式）、任务级重试（所有节点类型都生效，2 秒起指数退避；`approval` / `quality_gate` / `concurrency_group` 属于门禁控制流，不参与重试）、任务级超时（整任务预算、按调用粒度执法，见「已知边界」）、阶段级门禁与独立的 `approval` 节点、阶段级容器 `image` 与 `cachePaths` / `cacheKey` 依赖缓存、`isolatedWorkspace` 阶段独立工作目录、按 `agentId` 或 `agentLabels` 绑定构建机、`matrix` / `matrixExclude` / `matrixInclude` / `matrixFailFast` 矩阵构建。
- **🚦 触发方式** —— 手动、cron 定时（5 段表达式自动补成 Spring 的 6 段）、GitHub / GitLab / Gitea 的 Git Webhook（解析 push · tag · PR/MR · release 事件）、通用 Webhook 端点、流水线互相调用（`call_pipeline`，禁止自调用，子运行变量回传父运行）、带 Bearer 令牌的 REST 触发。入站 Webhook 强制验签（`X-Pipeloom-Signature` + 时间戳、`X-Hub-Signature-256`、或 `X-Gitlab-Token`），按 delivery id 做 5 分钟幂等去重，连续验签失败会按 IP 限流，累计 10 次自动停用该配置。运行进入终态后还会把结果回写成 GitHub / GitLab / Gitea 的 commit status（best-effort：回写失败绝不影响运行结果），开发者在 PR 上直接看到 ✓/✗ 而不必开平台。前提是这条流水线由 webhook 触发（带提交号），并且 `git_source` 节点填了 `repoUrl` 与一个 **git_token 类型**的凭据 —— 公开仓库能匿名克隆，但没有 token 就写不了状态；每种「没回写」的原因都会以独立结论写进服务端日志。
- **🏗 构建、制品与晋级** —— `git_source` 在工作区（或阶段容器）内 clone，凭据从保险库取出后注入 URL，并采集提交、作者、文件数与逐文件 diff；仓库浏览与远端 ref 列举走 JGit。`build_image` / `push_image` 以 `pipeloom-<runId>:<commitShort>` 打标签并推私有仓库；`archive_artifact` 保存构建产物的**真实字节**并可下载；运行进入终态后回收本次 workspace。搬运制品的部署节点（`deploy_ssh`、`file_distribute`）可开启**按（制品, 环境）的晋级审批**：批准的对象是制品而不是某次运行，开关没配全就**按拦截处理**，同时把被拦住的那次登记成待审批，审批人直接在运行页就能处理。
- **🔍 代码扫描与质量红线** —— `code_scan` 节点编排 14 个已注册引擎。内置规则引擎（24 条风格规则 + 16 条密钥规则）纯 JVM、始终可用；gitleaks · SpotBugs · Checkstyle · PMD · detekt · ktlint · ESLint · Pylint · cpplint · clang · gometalinter · StyleCop · OcCheck 各自走 `PATH → Docker 镜像 → 跳过` 的降级链，**跳过会被说出来**，不会静默产出空结果。`semgrep_scan` 与 `tca_scan` 单独成节点，正是因为它们需要外部环境（Semgrep 运行环境、可达的 TCA 服务端）。产出为 SARIF + 聚合问题数；扫描结果写成运行变量（`CODE_SCAN_TOTAL`、`CODE_SCAN_ERRORS`、`CODE_COMPLEXITY_MAX`、`CODE_DUPLICATION_RATIO`、`CODE_LOC_CODE` 等），`quality_gate` 节点按红线规则判定——直接失败，或阻塞等待审批。报告、逐文件下钻与 JSON 导出都挂在运行详情上。
- **🚀 部署发布** —— `deploy_ssh`（上传镜像包 → `docker load` → `docker run -d`，可配容器名、端口、启动参数）、`deploy_compose`、`file_distribute`、命令式运维的 `server_script`、`health_check`（HTTP 或命令行探测，支持重试间隔与 fatal / 非 fatal 两种结局）。Kubernetes 目标支持 `image_update`（rolling · recreate · blue-green）、`manifest_apply`（server-side apply，独立 `fieldManager`，集群级资源先应用）与 `helm_chart`（`helm upgrade --install` 并带 values）。
- **🖥 服务器与容器运维** —— SSH / Kubernetes / 本机 / 探针四类目标；跨主机容器聚合列表、创建 / inspect / prune，镜像 · 卷 · 网络 · Stack 管理，`system df` 与 prune，实时 stats，systemd 服务 start/stop/restart/status（走命令白名单），主机与容器 Web 终端，Pod exec，实时日志尾随。
- **🛰 探针（Agent）** —— 一个 `CGO_ENABLED=0` 的静态 Go 二进制，只主动外连 `GET /ws/agents/connect?token=…`，**本机不监听任何端口**。心跳上报 OS · 架构 · CPU 核数 · 内存 · 主机名，执行 `exec` / `upload` / `download` 任务并流式回传输出，按 `deploy` / `build` 分类、带 tags 与标签匹配调度。`SshExecutor` 在目标绑定探针时自动改走探针通道，探针离线就明确报错而不是悄悄回退。服务端在 `GET /api/agents/binary/{os}/{arch}` 提供对应平台的二进制。
- **📣 通知投递** —— 企业微信 · 钉钉 · 飞书 · Slack · Microsoft Teams · 通用 Webhook · 邮件，按**事件订阅**路由（`succeeded` / `failed` / `gate_pending` / `canceled` / `custom` / `concurrency_rejected` / `gate_rejected`；成功刻意默认关、失败与待审批默认开，避免通知疲劳），模板按运行变量渲染，留有投递台账，**一键重投会按当前渠道配置重新渲染**（重放旧 payload 只会把同一个错误再犯一次），另有测试发送。流水线内部还有 `notify` 节点。
- **📥 站内收件箱** —— 同一批事件会进站内消息中心，且**不依赖有没有配渠道**：一个渠道都没配的新实例照样通知得到人。分发给谁由事件语义决定，而不是由渠道订阅决定 —— 流水线归属人与运行触发者恒定收到一份，失败额外通知 ADMIN，审批类事件（`gate_pending` / `gate_rejected` / `ticket_open`）通知 ADMIN 与 OPERATOR，因为能点审批的就是这两类角色。**每个收件人各存一行、各自记已读**（甲读过一条待审批不该让乙的未读徽标消失）；不是有效启用账号的名字（API 令牌、已删用户、Git 提交作者）会被丢掉；单次事件最多 200 份。顶栏铃铛与 `/messages` 页面负责呈现，站内信随运行被保留策略一并清理。
- **🧩 插件市场与 SDK** —— 插件 = `task.json` + Kotlin/Java fat JAR（或 shell handler 脚本）。安装即向 `JobHandlerRegistry` 注册一个新节点类型、或向 `ScanRuleRegistry` 注册一条新规则，**无需重启**；卸载会把类型标记为退役，让存量流水线**带原因失败**，而不是静默成功。安装按用户隔离，版本包做 SHA-256 校验并拒绝路径穿越段，保留节点类型不允许占用；插件通过一次性、按 run 作用域的 API 令牌访问平台，且只能取回本条流水线自己声明引用的凭据。内置 4 个 Kotlin 模板与一份站内插件开发指南。
- **🤖 AI 辅助（可选、可完全降级）** —— 任意 OpenAI 兼容端点（`PIPELOOM_AI_BASE_URL` / `MODEL` / `API_KEY`，因此 DeepSeek · Moonshot · vLLM 同样可用；密钥存保险库）：按仓库生成流水线、运行失败诊断、问题修复建议，以及运维台的 NL→shell、命令解释、compose 生成、容器诊断。未配置或不可达就返回 `available=false`，前端优雅降级——CI/CD 主链路从不依赖 AI。
- **🧹 平台与日常治理** —— MySQL 8 + Flyway（`V0002`→`V0112`，共 68 个迁移）+ MyBatis-Plus，运行数据保留清理（默认 90 天），两层崩溃回收：启动时 `StaleRunRecoveryService` 把孤立的 `running` / `queued` / `canceling` 推入终态，一个 2 分钟周期的看门狗则处理心跳停更超 3 小时的步骤；另有门禁超时自动判失败、过期资源槽回收、控制台中英双语、`/api/health`、Actuator 暴露 `health,info,prometheus,metrics`、`/swagger-ui.html` 在线接口文档。
- **🩺 运行诊断与业务指标** —— 运行详情页的「运行诊断」把「为什么慢 / 卡在哪 / 是不是死了」算成结论：排队与执行时长分开、心跳静默判定失联、任务级时间预算用尽、门禁在等谁、第一个失败步骤带日志末行与是否被 `allowFailure` 容忍、瓶颈步骤占比、平台中断代号翻译成人话。判定阈值只存在于服务端一处（`RunDiagnosisService`），前端只展示。`/actuator/prometheus` 里除了框架自身的 JVM/HTTP 指标，现在有流水线业务指标：终态计数（按状态与触发方式）、排队与执行时长分布、重试次数、超时预算耗尽、`when`/`needs` 跳过、门禁批准与驳回、矩阵展开组合数、Git 回写结论、晋级拦截、活跃运行数 gauge。标签一律取代码里的有穷集合，**不含 pipelineId / runId / 用户名 / 步骤名**——那些走诊断接口看明细。
- **⚖️ 并发控制** —— 流水线级互斥组（`deploy-prod`、`deploy-${branch}` 支持插值）在触发时直接以 `409` 拒绝并点名占用者；阶段级资源槽由 `concurrency_group` 节点租约占用，租约到期自动清扫。

> 安全不打折：密文存储、命令白名单或数组化、Webhook 必验签、会话与令牌按作用域收敛、审计记录改不掉也删不掉。

## 安装 / 部署

前置：**服务端 Gradle toolchain 需要 JDK 25**（本地没有时 Gradle 会自动下载；插件 SDK 固定 17，保证插件可移植）、**MySQL 8.0+**、构建控制台需要 **Node.js 22+**；只有真要用到容器隔离构建、镜像部署、容器运维时才需要 Docker。

### ① Docker Compose（自托管推荐）

```bash
git clone https://gitee.com/Adnois/pipeloom.git && cd pipeloom
cp .env.example .env            # 首次 up 之前先把 DB / 管理员 / vault 主密钥填好
docker compose up -d --build    # mysql + server + web
open http://localhost:8092      # 登录：admin / $PIPELOOM_ADMIN_PASSWORD
```

`web` 服务是 nginx：静态控制台在 `8092`，`/api/` 反代到 `server:8888`，`/ws/` 带 upgrade 头反代并把读超时设为 24 小时。数据落在 `mysql-data`、`artifacts`、`plugins` 三个命名卷。服务端镜像以 UID `10001` 非 root 运行，与 K8s 清单里的 `runAsUser` 对齐。

### ② Kubernetes

```bash
kubectl apply -f k8s/namespace.yaml
# 先改 k8s/secret.yaml：数据库口令、管理员初始口令、vault 主密钥
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/mysql.yaml
kubectl apply -f k8s/server.yaml   # PVC：制品 20Gi、插件 5Gi
kubectl apply -f k8s/web.yaml
kubectl apply -f k8s/ingress.yaml  # 换成自己的域名并按需打开 TLS
```

`k8s/server.yaml` 里显式写死 `SERVER_PORT=8888` 是必要的：名为 `server` 的 Service 会被 Kubernetes 注入 `SERVER_PORT=tcp://…`（Docker link 兼容行为），Spring Boot 的宽松绑定会把它当成 `server.port` 从而启动失败。存活/就绪探针都打 `/api/health`。`replicas` 保持 `1`——cron 调度与在跑的运行由进程自己驱动，见[已知边界](#已知边界诚实清单)。

### ③ 源码启动（开发调试）

```bash
# 1. 建库
mysql -u root -p -e "CREATE DATABASE pipeloom CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 2. 后端 —— http://localhost:8888，启动时 Flyway 自动迁移
cd server && ./gradlew bootRun

# 3. 控制台 —— http://localhost:5173，/api 与 /ws 自动代理到 :8888
cd web && npm ci && npm run dev
```

口令类配置一律走环境变量；本地开发也可以复制 `server/src/main/resources/application-local.yml.example` 为 `application-local.yml`（已在 `.gitignore` 里，勿提交），以 `--spring.profiles.active=local` 启动。构建产物：`./gradlew bootJar`（→ `server/target/pipeloom-server.jar`）与 `npm run build`（→ `web/dist`）。

探针是独立的 Go module：

```bash
cd agent && make                 # pipeloom-agent-linux-amd64 / -linux-arm64 / -darwin-amd64 / -darwin-arm64
# 控制台 → 探针管理 → 新建探针 → 复制连接命令
./pipeloom-agent-darwin-arm64 -server=http://localhost:8888 -token=<token> -v
```

### 配置（环境变量）

日常部署真正要填的只有 `.env` 里那三个（DB 口令 / 管理员初始口令 / vault 主密钥），再加上对外地址 `PIPELOOM_API_URL`；其余变量都有可用默认值。

**核心**

| 变量 | 说明 | 默认值 |
|---|---|---|
| `PIPELOOM_ADMIN_PASSWORD` | **仅首次启动**用来创建管理员的初始口令（之后请在账户设置里改）。至少 8 位；无默认值，已有管理员时不会被使用 | 无（首启必填） |
| `PIPELOOM_ADMIN_USERNAME` | 首次启动创建的管理员用户名 | `admin` |
| `PIPELOOM_VAULT_KEY` | base64 编码的 32 字节保险库主密钥。不设不会阻断启动，但影响面远超「凭据」一项：凭据 CRUD、SSH/Web 终端、K8s exec、AI 配置与全部 AI 能力都不可用（`503 vault_unconfigured` / WS 连不上） | 无 |
| `PIPELOOM_API_URL` | 对外可访问的基础 URL，用于通知里的详情链接与 Webhook 的 `curl` 示例 | `http://localhost:8888` |
| `PIPELOOM_AUTH_COOKIE_SECURE` | 部署到 HTTPS 后置 `true` | `false` |
| `SERVER_PORT` | HTTP 监听端口 | `8888` |

**数据库**

| 变量 | 说明 | 默认值 |
|---|---|---|
| `PIPELOOM_DB_HOST` | MySQL 地址 | `localhost` |
| `PIPELOOM_DB_USERNAME` | MySQL 用户 | `root` |
| `PIPELOOM_DB_PASSWORD` | MySQL 口令。compose / K8s 都要显式提供；`application.yml` 目前仍留有一个本地开发兜底默认值，生产部署不要依赖它 | 环境变量（compose 从 `.env` 取） |

**运行、插件与清理**

| 变量 | 说明 | 默认值 |
|---|---|---|
| `PIPELOOM_RETENTION_RUNS_MAX_AGE_DAYS` | 终态运行保留天数，超期由清理任务连同步骤日志、制品、报告、通知记录与站内信一并删除 | `90` |
| `PIPELOOM_PLUGIN_STORAGE` | 插件包存储目录 | `./data/plugins` |
| `PIPELOOM_PLUGIN_EXEC_TIMEOUT_SECONDS` | 插件执行超时上限（单节点可用 `pluginTimeoutSeconds` 覆盖，夹在 1s–24h） | `3600` |
| `pipeloom.agent-binary-dir` | 服务端查找探针二进制的目录 | `./agent` |
| `pipeloom.server.local-bootstrap.enabled` | 启动时把自身所在主机注册为 `local` 目标（无需 SSH 凭据） | `true` |
| `pipeloom.security.ws.allowed-origins` | WebSocket 来源白名单（防 CSWSH），部署域名要加进来 | `localhost` / `127.0.0.1` 模式 |

**AI（可选）**

| 变量 | 说明 | 默认值 |
|---|---|---|
| `PIPELOOM_AI_BASE_URL` | OpenAI 兼容 base URL | `https://api.openai.com/v1` |
| `PIPELOOM_AI_API_KEY` | API Key；留空 = AI 能力未启用（不阻断启动） | 空 |
| `PIPELOOM_AI_MODEL` | 模型名 | `gpt-4o-mini` |
| `PIPELOOM_AI_TIMEOUT_SECONDS` | 请求超时 | `120` |

## 流水线参考

画布上可选的节点类型，以及谁来执行它们：

| 分类 | 节点 | 执行者 |
|---|---|---|
| 源码 | `trigger` | 引擎（固定首阶段：事件、cron、并发互斥） |
| 源码 | `git_source` | 引擎（`git clone` + 提交/diff 采集；仓库浏览走 JGit） |
| 构建 | `build_image`、`push_image`、`archive_artifact` | 引擎（Docker；镜像仓库凭据来自保险库） |
| 构建 | `script`、`custom`、`test` | **平台保留类型** —— 需安装市场里对应的插件 |
| 部署 | `deploy_ssh`、`deploy_compose`、`file_distribute`、`server_script` | 内置 Handler（SSH 或探针通道） |
| 部署 | `deploy_k8s` | 内置 Handler（fabric8：镜像滚动 / manifests / Helm） |
| 质量 | `code_scan`、`semgrep_scan`、`tca_scan`、`quality_gate`、`health_check` | 内置 Handler |
| 流程 | `approval`、`concurrency_group`、`call_pipeline` | 内置 Handler |
| 通知 | `notify` | 内置 Handler（走你配置的渠道） |

`script` / `custom` / `test` 是**刻意保留**的占位类型：留着是为了不让存量流水线一夜变红，但它们**什么都不做**，除非装了提供该类型的插件。画布、保存校验和运行详情页都会直接说明这点（占位类型的「成功」步骤带「空操作」徽标），而不是让你在跑到那一步时才发现。

可在命令、环境变量与节点配置里插值的内置变量（`${VAR}` 与 `${VAR:-默认值}`）：`RUN_ID`、`PIPELINE_ID`、`PIPELINE_NAME`、`BRANCH`、`COMMIT_SHA`、`COMMIT_SHORT`、`TRIGGER_TYPE`、`TRIGGER_ACTOR`、`STAGE_NAME`、`JOB_NAME`、`WORKSPACE`，再加上节点通过运行变量发布的值（制品名、扫描指标、矩阵轴、子流水线输出）。

## 插件市场速览

```json
{
  "name": "hello-world",
  "description": "Hello World 示例插件",
  "nodeType": "hello_world",
  "version": "1.0.0",
  "category": "custom",
  "execution": { "language": "java", "packagePath": "build/libs/hello-world-1.0.0.jar" },
  "fields": [{ "key": "message", "label": "消息内容", "kind": "text" }],
  "outputs": [{ "name": "RESULT", "desc": "输出结果" }],
  "defaultConfig": { "message": "Hello, Pipeloom!" }
}
```

```bash
gradle jar
zip hello-plugin.zip task.json build/libs/hello-world-1.0.0.jar
# 控制台 → 插件市场 → 上传插件包（支持拖拽/粘贴）→ 安装
```

插件实现 `server/plugin-sdk` 里的 `PluginTask<P : PluginParam>`；平台把节点配置注入为 `PLG_*` 环境变量加 `$PLG_INPUT_FILE`，再从 `$PLG_OUTPUTS_FILE`（变量）、`$PLG_REPORT_FILE`（结构化报告）与 `$PLG_API_URL` + `$PLG_API_TOKEN`（一次性、run 结束即失效的令牌）读回结果。模板：`tpl-kotlin-basic`、`tpl-kotlin-deploy`、`tpl-kotlin-notify`、`tpl-kotlin-scan`。

## 技术栈

- **后端** —— Kotlin 2.3 · Spring Boot 4.1（web / websocket / mail / flyway / actuator）· MyBatis-Plus 3.5 · MySQL 8 + Flyway · BouncyCastle · sshj（SSH）· fabric8 `kubernetes-client` · Eclipse JGit · Jackson 3（`tools.jackson`）· springdoc OpenAPI · Micrometer/Prometheus · ArchUnit 分层守卫 · 构建期 ktlint + detekt。
- **控制台** —— Vue 3.5 `<script setup>` · TypeScript · Vite 8（Rolldown）· naive-ui · vue-router + Pinia · vue-i18n（简体中文 / English）· Monaco + CodeMirror · xterm.js 终端 · Tabler 图标。
- **探针** —— Go 1.23 + `gorilla/websocket`，`CGO_ENABLED=0`，一个 `Makefile` 出四个 `GOOS/GOARCH` 目标。
- **运行时** —— JDK 25 toolchain（执行引擎用虚拟线程），nginx 托管静态控制台，eclipse-temurin 作为服务端镜像，MySQL 存状态。

## 架构

```
pipeloom/
├── server/                         # Kotlin / Spring Boot 控制面（约 330 个文件）
│   ├── src/main/kotlin/com/pipeloom/server/
│   │   ├── controller/             # 42 个 REST Controller：auth · account · project · pipeline
│   │   │                           #   server · credential · notification · marketplace · agent · ai
│   │   │                           #   audit · dashboard · proxy · system
│   │   ├── service/                # 领域服务，一个聚合一个包
│   │   │   ├── pipeline/           # spec · 运行 · DAG 引擎 · 制品 · 晋级 · 质量 · webhook
│   │   │   │   └── handler/        # JobHandler SPI + ScannerRegistry + ScanRuleRegistry
│   │   │   ├── marketplace/        # 插件生命周期 · 运行时 API · 自定义节点
│   │   │   ├── server/             # SSH 目标 · 容器 · KubeClientService · 运维
│   │   │   ├── notification/       # 渠道 · sender · 投递台账 · 模板
│   │   │   ├── credential/         # VaultCrypto（AES-256-GCM）+ 凭据 CRUD
│   │   │   ├── agent/              # 探针注册表 + 连接管理
│   │   │   └── auth/ · account/ · audit/ · ai/ · dashboard/ · project/
│   │   ├── components/             # SshExecutor · AgentExecutor · CommandWhitelist · CSRF
│   │   ├── websocket/              # SSH 终端 · 容器终端 · kube exec · 日志尾随 · 探针
│   │   ├── schedule/               # 保留清理 · 门禁超时 · 槽位清扫 · 僵死运行恢复 · 过期检查
│   │   ├── interceptor/ · aspect/  # @RequireAuth · @Audit · 统一错误信封
│   │   └── runner/                 # 管理员引导 · 本机目标引导
│   ├── src/main/resources/
│   │   ├── application.yml
│   │   ├── db/migration/           # V0002 … V0112
│   │   ├── builtin-plugins/        # code-scan 编排脚本 + 各引擎独立脚本
│   │   └── plugin-templates/       # 4 个 Kotlin 插件模板
│   └── plugin-sdk/                 # Kotlin/Java 17：PluginTask / PluginContext / PluginParam / PluginResult
├── web/                            # Vue 3 控制台（37 个视图、56 个组件、33 个 API 模块）
├── agent/                          # Go 探针：外连 WebSocket，exec/upload/download
├── k8s/                            # namespace · secret · mysql · server · web · ingress
├── docker-compose.yml              # mysql + server + web
└── .github/workflows/ci.yml        # compile · ktlint · detekt · test · vue-tsc · build
```

依赖方向固定为 `controller → service → mapper/entity`，由 ArchUnit 测试把守：HTTP 关注点不渗进 service，service 也不该知道表单长什么样。执行内核（`PipelineRunService` + `RunDispatcher` + `JobHandlerRegistry`）是**唯一**决定「一个节点做什么」的地方，节点类型一律经注册表分发——所以市场插件走的执行路径和内置 Handler 完全同一条，没有旁路。

## 开发

```bash
cd server && ./gradlew compileKotlin      # 编译
cd server && ./gradlew test               # 单测 + ArchUnit 分层测试
cd server && ./gradlew ktlintCheck detekt # 静态检查（CI 两项都跑）
cd web    && npm run typecheck            # vue-tsc --noEmit
cd web    && npm run build                # 生产构建
cd agent  && make                         # 探针多平台二进制
```

迁移脚本在 `server/src/main/resources/db/migration/`，命名 `V<NNNN>__<描述>.sql`；Flyway 以 `baseline-on-migrate` + `out-of-order` 运行，因此**追加新号**而不是改历史脚本。本地配置写进 `server/src/main/resources/application-local.yml`（已被 git 忽略），别塞进 `application.yml`。另需知道：Gradle 产物落在 `server/target/` 而不是 `server/build/`，而当前 `.gitignore` 里有一行被写成了 `server/targetlogs/`（`server/target` 和 `logs/` 连在了一起，少了换行），所以 `server/target/` **实际上没被忽略** —— 不要提交它。接口文档在服务起来后看 `/swagger-ui.html`。

## 已知边界（诚实清单）

- **单实例。** cron 调度与在跑运行的状态都在进程内，服务端只跑一个副本。崩溃/重启遗留的运行会被显式回收：启动时 `StaleRunRecoveryService` 把孤立的 `running` / `queued` / `canceling` 判为失败并写 `interrupt_reason`，每 2 分钟运行的看门狗则处理心跳停更超 3 小时的步骤；`waiting`（等待审批）的运行会被保留。
- **`matrixMaxParallel` 当前不生效，而且原因不是「还没排上」。** 矩阵组合按声明顺序执行，保存期 `matrix_parallel_blocked` 与运行日志都给出同一个原因代号（`ParallelSafety`）。硬约束是**工作目录**：`_WORKSPACE_DIR` 是 run 级变量，第一个建好它的阶段写定路径，之后所有阶段共用——容器构建机也只是 `-v $workspace:$workspace` 挂同一个宿主目录。因此「把组合拆成并列阶段」并不是并行方案，只会把显式限制换成静默的产物互相覆盖；引擎会在保存期用 `parallel_stages_share_workspace` 点名这类同层、同执行目标、且都读写工作目录的阶段。并行已经有一半落地：**`stage.isolatedWorkspace` 可以给某个阶段一份独立工作目录**（挂在同一个 per-run 基目录下，按执行目标回收，重启后靠 run 变量账本继续回收），并列阶段因此可以安全并发；剩下的前提是「组合粒度独立工作区 + 门禁等待状态从 run 级单槽改为按挂起目标计数」，所以矩阵组合之间仍然只能顺序执行。`matrixFailFast` 是生效的。
- **阶段内任务是串行的。** 并发只发生在阶段级（同一拓扑层）与运行之间。
- **`job.timeoutMinutes` 是「整个任务」的时间预算，按调用粒度执法。** 任务开始时建立一次截止时刻，全部重试共用同一份预算；每次命令或远端调用只能领取剩余时间，预算用尽后不再起跑任何新工作（`call_pipeline` 会停止等待并取消子流水线运行）。它无法把已经阻塞中的某一次调用精确掐断到秒 —— 那部分由该调用自身的超时机制负责。门禁类节点（`approval` / `quality_gate` / `concurrency_group`）豁免：它们的等待属于引擎控制流，由 `gateTimeoutMinutes` 管。
- **文件传输已有硬上限，但默认值是固定的。** `SshExecutor.uploadFile` / 下载现在带 `timeoutSeconds` 参数（默认 30 分钟），到点强制断开 SSH 连接，任务以明确原因失败而不是永远挂起；`deploy_ssh` 的镜像上传会领取任务剩余预算（`ctx.budget`），其余调用点暂用默认上限而非任务截止时刻。
- **重试不是幂等重放。** `retryCount` 对所有节点类型生效（此前只有 handler 型节点消费得到），但 `call_pipeline` 每重试一次就真的多起一条子流水线运行 —— 新的运行编号、新的通知，若子流水线含部署还会重复发布。保存期会就此给出提醒。
- **收件箱的可达范围由运行记录里已有的信息决定。** 收件人取自 `pipelines.owner_username` 与 `pipeline_runs.trigger_actor`，所以一条没有归属人、又由 API 令牌触发的运行，只会发给该事件点名的角色组 —— 这是正确行为而不是 bug，但它意味着「我一条都没收到」常常等于「这条流水线没人认领」。不是有效启用账号的名字会被直接丢弃，而不是写进一个没人能登录查看的黑洞。单次事件最多写 200 份，超出会在日志里点名告警而不是静默少写。站内信随运行被保留清理删除，没有独立的收件箱保留期：比保留期更久的消息对所有人都已不存在。
- **资源级隔离目前只覆盖流水线。** `pipelines` 已有 `owner_username` + `visibility`：`public`（默认）对全体登录用户可见，`private` 只有归属人和 ADMIN 能看见，而且这条流水线的**运行记录也一并从全局运行列表消失**；对看不见的流水线一律回 `404`（不是 `403`），免得泄漏「它存在」。归属列为空的历史数据视为团队资产（仍全员可见），但只有 ADMIN 能改它的配置——把它设为 `private` 时自动认领给当前操作人。API 令牌不受可见性约束，否则 CI 令牌连自己该触发的流水线都看不见；令牌的边界仍是 scope。`servers` / `credentials` / 构建机还没有归属列，Team 实体也不存在，所以这是「个人级」而不是「团队级」隔离：两个 OPERATOR 之间仍彼此可见可改。
- **`stage.isolatedWorkspace` 会切断阶段之间的文件传递。** 默认所有阶段共用一份 run 级 checkout，「前面 clone、后面构建」依赖这一点；勾选独立目录后本阶段看不到上游留下的任何文件（`needs` 只保证顺序，不做拷贝），保存期 `isolated_workspace_hides_upstream` 会提示这一点。要跨阶段传东西请走制品，或者让本阶段自己 `git_source`。

- **阶段缓存（`cachePaths` / `cacheKey`）现在按组合隔离，并且真的有上限。** 命名空间由 `CacheGovernance` 统一推导，恢复与保存同源 —— 过去两处各抄一遍 `take(64)`，前 64 位相同的两个键会静默共用一个目录。矩阵阶段在**组合边界**恢复与保存：此前保存发生在矩阵变量恢复之后，键里的 `${os}` 那时已不在作用域，等于「按建议配了缓存却永不命中」；失败组合不写缓存，免得下一轮以「命中」的名义把装坏的依赖取回来。恢复会如实区分命中 / 未命中（过去无论目录存不存在都打「缓存恢复」），计数进 `/actuator/prometheus` 的 `pipeloom.cache.restore{result}` / `pipeloom.cache.save{result}` / `pipeloom.cache.evict{reason}`。容量与过期由 `pipeloom.cache.*` 控制（根目录、`ttl-days` 默认 14、`max-bytes` 默认 10 GiB），本次刚写入的命名空间永不淘汰。`cachePaths` 按工作目录内的相对路径解释，写成绝对路径会被挪进工作目录（保存期 `cache_path_relocated_into_workspace` 点名）；只填 `cacheKey` 不填目录不会缓存任何东西（`cache_key_without_paths`）。跨运行共享的前提仍是**同一个执行目标** —— 两台构建机上的同一路径是两个目录。

- **反向代理 / 自动 HTTPS 与 DNS Provider 目前是桩实现。** 控制台会渲染这些面板，但接口返回空对象或占位值，不会签发证书；面板顶部现在有醒目的「后端尚未实现」横幅，占位的路由与证书状态不会再被误当成真实配置。先别围绕它们做规划。
- **`helm_chart` 部署需要控制节点上装了 `helm`**；Helm 模式下的蓝绿属于 chart values 层面的事（节点只会记录策略并给出提示）。
- **`stage.post`（阶段后置步骤）与 `stage.services`（旁挂服务）依然不执行——但不再静默放行。** 引擎没有执行它们的分支，因此保存声明了这些字段的流水线会被校验器拦下（`stage_post_not_executed` / `stage_services_not_executed`），经 Webhook/直连 API 绕过校验的运行会在该阶段显式失败而不是假装跑过。`cachePaths` / `cacheKey`、`allowFailure`、`when`、`retryCount`、`gateTimeoutMinutes` 都是真实生效的。
- **远端（委托脚本）扫描覆盖的引擎比本机少。** 内置规则之外，没有远端实现的工具会被报出来，而不是静默跳过。
- **部分扫描指标只在本机执行路径产出**（例如 Semgrep 的分级计数）；门禁读到缺失指标时报「未找到」，不会当成 0。
- **`script` / `custom` / `test` 不装插件等于空节点**（见上文节点表），这是最容易踩的一条。
- **探针二进制从 `pipeloom.agent-binary-dir` 提供** —— 在 `agent/` 里 `make`，或把文件放进去；缺文件就是 404，不会回退到别的地方。

## 开发状态

内部自用、持续迭代中：`server` 版本 `0.0.1-SNAPSHOT`，数据库结构到 Flyway `V0112`，提交频率接近每日。它已经在真实承载流水线、扫描、部署与日常运维；`main` 是移动目标，部署时请钉住你实际验证过的提交。服务端启动后可通过 `/swagger-ui.html` 查看实时 API 面。

## 贡献

从 `main` 开分支，保持 CI 绿（`ktlint`、`detekt`、`test`、`vue-tsc`），任何结构变更都**追加一个新的 Flyway 迁移**而不是改历史脚本。提交信息沿用带类型的约定式前缀（`feat:` · `fix:` · `refactor:` · `style:` · `test:`），必要时带作用域（`fix(pipeline): …`）。密钥要格外小心：`application-local.yml`、`data/`、`logs/`、`*.db*` 已列入 `.gitignore`，但 **`.env` 目前仍在这个仓库的跟踪列表里**，所以不要把生产口令或 vault 主密钥写进去 —— 部署用的真实密钥走另外的下发通道，`.env` 只留本地占位值。

## License

Private — 仅限内部使用。

---

<div align="center">
<sub>Pipeloom —— 把 CI、质量门禁、部署与运维收进同一个控制面。</sub>
</div>