# devops-go

**Repository Path**: zhReimu/devops-go

## Basic Information

- **Project Name**: devops-go
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DevOps Go

一个基于 Go + Vue3 的 DevOps 管理系统，采用 DDD（领域驱动设计）架构，支持项目管理、构建部署、实施上线、容器管理等核心功能。

## 术语定义

为了避免沟通歧义，本系统严格区分以下术语：

- **构建**：拉取代码并构建 Docker 镜像
- **部署**：将镜像部署到指定环境（启动容器后即算部署成功），test 和 release 环境都允许部署
- **实施**：将 release 环境的镜像部署到 pre 环境，或将 pre 环境的镜像部署到 pro 环境。实施不会重新构建，只使用现有镜像

典型的 DevOps 流程如下：
1. 代码合并并推送到远端仓库的 dev 分支，点击构建 test 环境，test 环境测试通过
2. 代码合并并推送到远端仓库的 release 分支，点击构建 release 环境，release 环境测试通过
3. release 环境点击「实施」将其部署到 pre 环境，pre 环境测试通过
4. pre 环境点击「实施」将其部署到 pro 环境，功能成功上线

## 技术选型

### 后端
- **语言**: Go 1.26+
- **Web 框架**: Echo v5
- **ORM**: GORM
- **数据库**: SQLite（默认）/ PostgreSQL
- **Docker**: docker/docker v28 客户端库
- **Git**: go-git/go-git/v5
- **认证**: JWT (golang-jwt/jwt/v5)，密钥统一由 `internal/pkg/jwt` 管理
- **WebSocket**: gorilla/websocket
- **日志**: slog（标准库结构化日志）

### 前端
- **框架**: Vue 3 + TypeScript
- **构建工具**: Vite
- **UI 库**: Vuetify 4（Material Design，亮色主题）
- **图标**: @mdi/js（SVG 图标，无字体加载问题）
- **状态管理**: Pinia
- **路由**: Vue Router 5
- **HTTP 客户端**: Axios
- **流程图**: @vue-flow/core
- **终端**: @xterm/xterm + @xterm/addon-fit
- **图表**: ECharts + vue-echarts
- **拖拽**: vuedraggable

## 项目结构

```
devops-go/
├── cmd/
│   └── devops-go/
│       └── main.go                  # 程序入口（仅解析配置，优雅停机）
├── internal/
│   ├── config/                      # 配置管理（CLI + ENV）
│   ├── app/                         # 应用组装（初始化与启动）
│   ├── entity/                      # 实体层（统一类型定义）
│   │   ├── appconfig/               # 全局配置实体与 DTO
│   │   ├── buildflow/               # 构建流程实体与 DTO
│   │   ├── buildlog/                # 构建日志实体与 DTO
│   │   ├── credential/              # 凭据实体与 DTO
│   │   ├── dbscript/                # 数据库脚本实体与 DTO
│   │   ├── docker/                  # Docker 实体、接口与 DTO
│   │   ├── dockerregistry/          # Docker 仓库实体与 DTO
│   │   ├── environment/             # 环境配置实体与 DTO
│   │   ├── git/                     # Git 操作实体
│   │   ├── permission/              # 权限实体与 DTO
│   │   ├── project/                 # 项目实体与 DTO
│   │   ├── user/                    # 用户实体与 DTO
│   │   └── webhook/                 # Webhook 实体与 DTO
│   ├── pkg/                         # 公共包
│   │   ├── jwt/                     # JWT 密钥统一管理
│   │   └── echoutil/                # Echo 请求绑定与校验工具
│   ├── domain/                      # 领域层（仓库接口与实现，类型别名引用 entity）
│   │   ├── project/                 # 项目领域
│   │   ├── credential/              # 凭据领域
│   │   ├── appconfig/               # 全局配置领域
│   │   ├── dbscript/                # 数据库脚本领域
│   │   ├── environment/             # 环境配置领域
│   │   ├── buildflow/               # 构建流程领域
│   │   ├── buildlog/                # 构建日志领域
│   │   ├── dockerregistry/          # Docker 仓库领域
│   │   ├── webhook/                 # Webhook 领域
│   │   ├── user/                    # 用户领域
│   │   ├── permission/              # 权限领域
│   │   └── docker/                  # Docker 连接领域
│   ├── application/                 # 应用层（服务逻辑，DTO 类型别名引用 entity）
│   │   ├── project/                 # 项目服务
│   │   ├── credential/              # 凭据服务
│   │   ├── appconfig/               # 全局配置服务
│   │   ├── dbscript/                # 数据库脚本服务
│   │   ├── environment/             # 环境配置服务
│   │   ├── buildflow/               # 构建流程服务
│   │   ├── buildlog/                # 构建日志服务
│   │   ├── webhook/                 # Webhook 服务
│   │   ├── dockerregistry/          # Docker 仓库服务
│   │   ├── user/                    # 用户服务
│   │   ├── permission/              # 权限服务
│   │   └── docker/                  # Docker 服务
│   ├── infrastructure/              # 基础设施层
│   │   ├── persistence/             # 数据持久化（GORM）
│   │   ├── docker/                  # Docker 客户端
│   │   ├── git/                     # Git 操作
│   │   └── embed/                   # 嵌入前端静态文件
│   └── interfaces/                  # 接口层
│       ├── api/                     # HTTP API 处理器
│       ├── middleware/              # 中间件（JWT 鉴权/CORS）
│       └── websocket/               # WebSocket 处理器
├── frontend/                        # 前端项目
│   └── src/
│       ├── domain/                  # 领域模型
│       ├── application/             # 应用服务（Store/API）
│       ├── infrastructure/          # 基础设施（HTTP/WS）
│       └── presentation/            # 展示层（组件/视图/路由）
├── Taskfile.yml                     # 任务编排
├── go.mod
└── go.sum
```

## 功能模块

### 1. Docker 连接管理
- 支持 HTTP、TCP、Unix Socket 方式连接远端/本地 Docker Daemon
- 支持 SSH 隧道方式连接远程 Docker 守护进程（通过 Docker Daemon SSH 凭据）
- 动态管理多个 Docker 连接

### 2. 项目管理
- 配置项目名称、版本、Git 地址、Git 分支
- 项目通过 `build_flow_id` 关联可复用的构建流程
- 项目列表展示构建流程名称，支持分页查询
- 新建项目时可选择 Git 凭据（git/git_ssh 类型），用于拉取私有库代码
- 构建时使用项目仓库根目录的 Dockerfile 构建 Docker 镜像
- 部署时后台运行 Docker 容器，自动注入全局环境变量
- 如果项目未关联构建流程，触发构建时会报错提示

### 3. 凭据管理
- 支持 6 种凭据类型：Git（账号密码）、Git SSH（SSH 密钥拉取代码）、SSH（远程服务器连接）、Docker Registry（镜像仓库认证）、Docker Daemon（Docker 守护进程连接）、Docker Daemon SSH（Docker 守护进程 SSH 连接）
- Git 和 Git SSH 类型凭据可关联到项目，用于拉取私有库代码
- 凭据为全局配置，项目可按需引用
- Git SSH、SSH 和 Docker Daemon SSH 类型凭据只需输入私钥，系统自动从私钥推导公钥，无需手动输入公钥
- SSH 密钥一键自动生成：配置 Git SSH、SSH、Docker Daemon SSH 凭据时，可点击「自动生成」按钮生成 Ed25519 密钥对，无需手动创建
- Docker Registry 凭据需填写仓库地址、用户名、密码
- Docker Daemon 凭据需填写守护进程连接地址（支持 http://、tcp://、unix:// 协议）
- Docker Daemon SSH 凭据需填写 SSH 连接地址（ssh://user@host 格式）和 SSH 私钥，通过 Go 原生 SSH 库建立隧道连接远程 Docker 守护进程，无需本地 ssh 命令
- 环境配置通过凭据引用管理连接信息，替代原有的地址/SSH 字段

### 4. 数据库脚本管理
- 提交、编辑数据库脚本
- 二级审批流程：待审核 → 一级已审 → 二级已审/已拒绝
- 管理员可手动跳过审批节点

### 5. 配置管理
- 全局配置项管理（键值对形式）
- 支持配置分类：镜像环境变量、构建配置
- 全局镜像环境变量自动注入到所有项目容器
- 构建配置分类用于管理全局构建参数

### 6. 构建与部署
- 构建流程：拉取代码 → 检查 Dockerfile → 构建 Docker 镜像 →（推送镜像到仓库）→ 部署容器
- 构建时根据环境关联的凭据动态创建 Docker 客户端，不再使用全局 Docker 配置
- 项目仓库根目录必须包含 Dockerfile，否则构建报错
- Docker 镜像标签使用项目版本号，格式：`项目名(小写):版本号`，如果项目未设置版本则使用 Git 提交哈希前 7 位
- 项目名自动转换为合法的 Docker 镜像名：小写化、非法字符替换为短横线、去除首尾分隔符，避免项目名含中文或空格时生成以分隔符开头的非法镜像名
- 构建时自动传递 `VERSION` 构建参数，Dockerfile 中声明 `ARG VERSION` 即可获取版本号，无需在容器内执行 `git describe`
- 构建上下文自动排除 `.git` 和 `node_modules` 目录，减小传输体积；如项目根目录存在 `.dockerignore` 则同时读取其中的规则
- 如果环境关联了 Docker 仓库，构建完成后自动推送镜像到仓库
- 所有环境构建后都自动部署到当前环境（包括 test 和 release）
- 一个环境同时只允许一个活跃构建任务，新任务发起后自动停止该环境下的老任务
- 构建日志记录发起人（触发构建的用户）和构建类型（手动触发/githook）
- 构建日志记录提交信息（commit message），方便查看每次构建对应的代码变更内容
- 构建日志实时更新，每个步骤执行后立即写入数据库，前端可轮询获取最新进度
- 构建进度状态原子化更新，避免并发读写导致进度显示异常
- 手动触发构建时，克隆完成后立即显示提交哈希到构建记录
- Webhook 触发的构建，提交哈希在创建构建记录时即写入
- 支持重新构建（基于历史构建记录的相同项目和环境）
- 支持取消正在运行的构建（构建进度条和构建记录列表均可取消）
- 构建记录列表支持分页查询
- 构建记录顶端展示流程图，可视化显示当前构建进度，存在活跃构建时自动展示最新构建的流程
- 构建进度流程图正确映射后端步骤（check_dockerfile/build_image/push_image）到流程图节点类型（build），确保当前执行步骤高亮并旋转
- 镜像构建完毕后自动删除克隆到本地的仓库目录，释放磁盘空间
- 构建日志按时间倒序排列，最新的构建记录排在最前面
- Docker 构建日志精简展示，只显示 stream 内容，不显示原始 JSON
- 构建失败时自动检测 Docker 构建输出中的错误信息，并附带最近构建输出帮助定位问题
- 项目可关联 Git 凭据，构建时优先使用项目关联的凭据拉取私有库代码
- 容器名称格式为 `项目名-版本号-提交哈希`
- test/release/pre 环境部署时直接停止并删除旧容器，重建同一版本时先移除旧容器再创建新容器
- pro 环境保留最近 5 个旧容器方便回滚，超出时自动删除最旧的；若部署相同 commit 的镜像，容器名自动添加递增后缀（-1、-2...）避免冲突
- 项目支持配置端口转发和挂载卷，部署容器时自动应用；前端采用 +/- 交互式配置，每行左侧为宿主机地址、右侧为容器内地址，点击 + 新增一对、点击 - 删除
- 构建/部署流程保存成功后给出提示

### 7. 实施
- **实施**指将 release 环境的镜像部署到 pre，或将 pre 环境的镜像部署到 pro
- release 环境只能实施到 pre 环境，pre 环境只能实施到 pro 环境
- test 环境没有实施按钮
- 实施不会重新构建，只使用现有镜像部署到目标环境
- 实施时会在目标环境增加一条构建记录
- 如果目标环境是占位符环境，实施时仅增加一条构建记录，不实际部署
- pre/pro 环境如果关联了 Docker 仓库则从仓库拉取镜像部署；否则通过 SSH 传输镜像部署

### 8. 构建日志
- 实时查看构建状态（running/success/failed/cancelled）
- 构建日志实时更新，每个步骤执行后立即写入数据库
- 前端自动轮询刷新（每 3 秒），构建中状态时持续获取最新日志
- 记录构建脚本所有输出（成功/失败/已取消）
- 记录发起人（触发构建的用户名）
- 记录构建类型（手动触发 / githook 触发）
- 记录提交信息（commit message），直观展示每次构建对应的代码变更
- 按环境类型分栏显示：test / release（根据项目配置的环境动态显示）
- 无「全部日志」栏，仅显示项目已配置的环境类型
- 占位符环境的构建记录会标记为占位符
- 构建记录列表支持分页查询

### 9. 环境配置
- 支持 test、release、pre、pro 四种环境类型
- 环境为全局配置，不绑定到特定项目，可应用于所有项目
- 连接类型简化为两种：Docker Daemon 和 SSH
- 环境通过凭据引用管理连接信息，不再直接配置地址/SSH 字段
- 当连接类型选择 Docker Daemon 时，凭据下拉框筛选 docker_daemon 类型的凭据
- 当连接类型选择 SSH 时，凭据下拉框筛选 ssh 类型的凭据
- 环境可关联 Docker 仓库，关联后构建产物自动推送
- pre 环境可设置为占位符，占位符环境实施时仅增加构建记录不实际部署（适用于机器不够但仍需走流程的场景）

### 10. 构建流程配置
- 可视化拖拽配置构建流程，支持为流程命名方便引用
- 系统初始化时自动创建默认构建流程「日常构建」（开始 → 拉取代码 → 执行构建 → 部署项目 → 结束）
- 构建流程为可复用的通用配置，项目通过 `build_flow_id` 引用
- 新建/编辑项目时构建流程下拉框直接展示流程名称
- 构建流程保存成功后给出提示
- 9 个内置节点：开始、拉取代码、执行构建、部署项目、Docker Compose 部署、条件判断、Webhook 通知、邮件通知、结束
- 每个节点类型均有专属图标，清晰区分
- 开始节点支持自定义变量和系统变量（当前时间、项目信息、机器信息）
- 条件判断节点：根据上游节点执行结果（成功/失败）决定流程走向
- Webhook 通知节点：构建完成后向指定地址发送 HTTP 通知
- 邮件通知节点：构建完成后发送邮件通知
- Docker Compose 部署节点：输入 docker-compose.yml 内容部署多服务，支持使用 {{image}} 变量引用构建镜像节点的镜像 tag
- Docker Compose 部署场景下，项目详情仅展示 {{image}} 对应的容器，查看日志和进入终端只针对该容器，避免辅助服务容器干扰
- 部署项目节点和 Docker Compose 部署节点不能出现在同一条链路上（保存时校验），同一流程只能选择其中一种部署方式
- 选中节点后按 Delete 键可快速删除节点
- 支持拖动、连线自定义流程，拖拽放置节点到鼠标指定位置
- 保存流程时校验节点连线合法性，不允许存在悬空节点
- 一键格式化功能，自动排列节点布局
- 流程列表页展示流程摘要，快速了解流程走向
- 如果项目没有关联构建流程，触发构建时会报错
- 构建日志覆盖全流程：包括 git clone、docker build 的日志，以及 if 条件判断、webhook 通知、邮件通知、Docker Compose 部署等节点的执行结果
- 当流程使用 Docker Compose 部署节点时，主流程跳过单容器部署步骤，由 Docker Compose 节点统一管理多服务部署

### 11. Docker 仓库配置
- 独立配置 Docker Hub / 私有镜像仓库
- 支持填写 URL、用户名、密码等鉴权信息
- 环境可关联 Docker 仓库，关联后构建产物自动推送
- pre/pro 环境关联仓库后可从仓库拉取镜像部署，无需 SSH

### 12. Webhook 管理
- 集成 Gitea Webhook，支持接收推送事件自动触发构建
- Webhook 独立配置，可关联到具体项目
- 创建 Webhook 时自动生成回调 URL 和密钥
- 支持 HMAC-SHA256 签名验证，确保请求来自 Gitea
- 当 Gitea 推送的分支与项目配置的 Git 分支匹配时，自动触发构建
- Webhook 触发的构建类型标记为 githook，发起人为推送者
- Gitea Webhook 回调接口无需 JWT 认证（白名单放行）

### 13. 主界面功能
- 左侧菜单导航，菜单顺序：仪表盘 → 项目 → 凭据 → 环境 → 构建流程 → Docker 仓库 → 构建日志 → 配置管理 → 数据库脚本 → Webhook → 用户 → 权限
- 全局淡入淡出提示弹窗，操作成功/失败时自动显示提示信息（屏幕上方居中位置）
- 顶部项目下拉框（搜索/选择切换项目）
- 构建项目按钮（弹出环境选择对话框）
- 使用帮助按钮（右上角问号图标），点击后以流程图方式展示系统使用流程：新建凭据 → 新建环境 → Docker 仓库（可选） → 新建项目 → 构建项目
- 项目详情对话框（按已配置环境动态显示 Tab、容器状态、内存占用、镜像信息）
- 项目详情中容器列表根据环境凭据动态创建 Docker 客户端获取，确保展示正确
- 容器内存使用量通过独立 stats 接口异步获取，确保显示真实的内存占用数据
- 生产环境(pro)支持版本回滚功能，展示提交哈希和构建时间
- 容器日志和终端以弹窗形式打开，关闭后可返回项目详情页面，无需切换路由
- 容器控制台日志（WebSocket 实时查看）
- 容器终端（xterm.js WebTerminal）
- 构建记录表格（发起人、构建类型、构建结果、Git Diff 链接、实施/重新构建操作按钮）
- 按环境类型动态分栏（test / release）
- 仪表盘刷新功能，可手动刷新状态
- 构建日志实时更新，运行中自动轮询刷新
- 自定义确认对话框组件，替代浏览器原生 alert/confirm，保持 UI 一致性
- 表单密码输入框添加 autocomplete 属性，避免浏览器自动填充警告
- 所有表格空数据状态使用中文提示，下拉框无数据时显示"暂无数据"
- 分页控件"每页条数"使用中文显示
- 所有分页列表统一使用 PaginationIndicator 组件，无论有无数据均展示分页指示器，支持调整每页条数并自动重新查询，显示「第 1-20 条，共 50 条」格式的中文分页信息（项目列表、用户列表、数据库脚本列表、配置管理列表、构建日志列表、构建记录列表）

### 14. 用户与权限管理
- 用户增删改查
- 权限管理：菜单权限、项目权限
- 角色控制（admin/user）
- JWT 认证
- 管理员账号不允许禁用和删除
- 用户状态下拉框显示中文标签（启用/禁用），接口同时返回 `status` 和 `status_label` 字段

## 快速开始

### 环境要求
- Go 1.26+
- Node.js 18+
- [Task](https://taskfile.dev/)（推荐，用于任务编排）
- Docker（可选，用于容器管理）

### 使用 Task 构建（推荐）

```bash
# 安装前端依赖并构建前端
task frontend:build

# 构建后端（会自动构建前端）
task build

# 运行所有代码检查
task lint

# 单独运行各项检查
task fmt         # 格式化代码
task vet         # 静态代码检查
task modernize   # 现代化写法检查

# 清理构建产物
task clean

# 运行测试
task test
```

### 手动构建

```bash
# 构建前端（需要先构建前端以嵌入静态文件）
cd frontend
pnpm install
pnpm build
cd ..

# 构建后端
go build -o devops-go ./cmd/devops-go/

# 运行
./devops-go
```

### 前端开发

```bash
cd frontend
pnpm install
pnpm run dev  # 开发模式，自动代理 API 到 localhost:8080
pnpm build    # 构建生产版本（输出到 ../internal/infrastructure/embed/web/dist）
```

## 配置

支持命令行参数和环境变量两种配置方式，命令行参数优先级高于环境变量。

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-address` | HTTP 服务监听地址 | 127.0.0.1 |
| `-port` | HTTP 服务端口 | 8080 |
| `-jwt-secret` | JWT 签名密钥 | (空) |
| `-db-driver` | 数据库驱动（sqlite/postgres） | sqlite |
| `-db-dsn` | 数据库连接字符串 | devops.db |
| `-build-dir` | 构建工作目录 | /tmp/devops-builds |
| `-admin-password` | 默认管理员密码 | admin123 |
| `-db-log-level` | 数据库日志级别（silent/error/warn/info） | warn |

### 环境变量

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `SERVER_ADDRESS` | HTTP 服务监听地址 | 127.0.0.1 |
| `SERVER_PORT` | 服务端口 | 8080 |
| `JWT_SECRET` | JWT 密钥 | (空) |
| `DB_DRIVER` | 数据库类型（sqlite/postgres） | sqlite |
| `DB_DSN` | 数据库连接字符串 | devops.db |
| `BUILD_DIR` | 构建工作目录 | /tmp/devops-builds |
| `ADMIN_PASSWORD` | 默认管理员密码 | admin123 |
| `DB_LOG_LEVEL` | 数据库日志级别（silent/error/warn/info） | warn |

### 配置优先级

命令行参数 > 环境变量 > 默认值

### 使用示例

```bash
# 通过命令行参数指定端口和数据库
./devops-go -port 9090 -db-driver postgres -db-dsn "host=localhost user=devops password=devops dbname=devops port=5432 sslmode=disable"

# 通过环境变量配置
export SERVER_PORT=9090
export DB_DRIVER=postgres
./devops-go

# 混合使用（命令行参数覆盖环境变量）
export SERVER_PORT=9090
./devops-go -port 8080  # 实际使用 8080

# 开启数据库全部 SQL 日志（调试模式）
./devops-go -db-log-level info

# 关闭数据库日志
./devops-go -db-log-level silent
```

### 默认账号
- 用户名: `admin`
- 密码: `admin123`

## 鉴权机制

系统采用基于路径前缀白名单的鉴权策略：

- **默认行为**：所有 `/api/` 和 `/ws/` 路径都需要 JWT 认证
- **白名单**：`/api/auth/` 前缀（用于登录）和 `/api/webhooks/gitea/` 前缀（用于 Gitea Webhook 回调）允许匿名访问
- **JWT 密钥**：统一由 `internal/pkg/jwt` 包管理，确保签名和验证使用同一密钥
- 登录接口 `POST /api/auth/login` 无需认证，登录后获取 JWT 令牌
- 其他所有接口需在请求头中携带 `Authorization: Bearer <token>`

## Taskfile 任务说明

| 任务 | 说明 |
|------|------|
| `task` / `task default` | 构建项目（当前平台） |
| `task deps` | 下载并整理 Go 模块依赖 |
| `task frontend:install` | 安装前端依赖 |
| `task frontend:build` | 构建前端项目 |
| `task frontend:dev` | 启动前端开发服务器 |
| `task build` | 构建当前平台后端 |
| `task build-all` | 构建所有平台 |
| `task clean` | 清理构建产物（含前端 dist） |
| `task test` | 运行测试 |
| `task fmt` | 格式化代码 |
| `task vet` | 静态代码检查 |
| `task modernize` | 现代化写法自动修复 |
| `task lint` | 运行所有代码检查（fmt + vet + modernize） |

## API 接口

| 路径 | 说明 |
|------|------|
| `POST /api/auth/login` | 用户登录 |
| `GET/POST /api/users` | 用户管理 |
| `GET/POST /api/projects` | 项目管理 |
| `GET /api/projects/all` | 获取全部项目（不分页） |
| `GET/POST /api/credentials` | 凭据管理 |
| `POST /api/credentials/generate-ssh-key` | 生成 SSH 密钥对 |
| `GET/POST /api/app-configs` | 全局配置管理 |
| `GET/POST /api/db-scripts` | 数据库脚本管理 |
| `GET/POST /api/environments` | 环境管理 |
| `GET /api/environments/all` | 获取全部环境（不分页） |
| `GET/POST /api/build-flows` | 构建流程管理 |
| `GET /api/build-flows/all` | 获取全部构建流程（不分页） |
| `GET/POST /api/build-logs` | 构建日志管理 |
| `POST /api/build-logs/trigger` | 触发构建 |
| `POST /api/build-logs/:id/rebuild` | 重新构建 |
| `POST /api/build-logs/:id/implement` | 实施镜像到目标环境 |
| `POST /api/build-logs/:id/rollback` | 回滚到指定版本（仅 pro 环境） |
| `POST /api/build-logs/:id/cancel` | 取消构建 |
| `GET /api/build-logs/project/:projectId/versions` | 获取项目构建版本历史 |
| `GET/POST /api/docker-registries` | Docker 仓库管理 |
| `GET/POST /api/webhooks` | Webhook 管理 |
| `GET /api/webhooks/all` | 获取全部 Webhook（不分页） |
| `GET /api/webhooks/project/:projectId` | 获取项目的 Webhook |
| `POST /api/webhooks/gitea/:webhookID` | Gitea Webhook 回调（无需认证） |
| `GET/POST /api/permissions` | 权限管理 |
| `GET/POST /api/docker/connections` | Docker 连接管理 |
| `GET /api/docker/containers` | 容器列表 |
| `GET /api/docker/environments/:environmentId/containers` | 按环境获取容器列表（根据环境凭据动态创建 Docker 客户端，compose_image 参数可选，传入时仅返回镜像匹配的容器） |
| `WS /ws/terminal/:connectionId/:containerId` | 容器终端 |
| `WS /ws/logs/:connectionId/:containerId` | 容器日志 |

## DDD 架构说明

项目严格遵循 DDD 分层架构：

- **Entity（实体层）**：统一定义领域模型、值对象、DTO 和仓库接口，按领域子目录组织，避免类型定义分散在业务文件中
- **Domain（领域层）**：通过类型别名引用 entity 包的类型，保留仓库接口的实现（GORM），不依赖任何基础设施
- **Application（应用层）**：编排业务逻辑，协调领域对象，DTO 通过类型别名引用 entity 包
- **Infrastructure（基础设施层）**：实现仓库接口，对接外部系统（数据库、Docker、Git）
- **Interfaces（接口层）**：处理 HTTP/WebSocket 请求，调用应用服务

前端同样遵循 DDD：
- **Domain**：TypeScript 接口和枚举定义
- **Application**：Pinia Store 和 API 调用
- **Infrastructure**：Axios 配置和 WebSocket 客户端
- **Presentation**：Vue 组件、视图和路由

## 代码规范

- 后端日志统一使用 `log/slog`（Go 标准库结构化日志）
- 日志结构化键名使用英文（如 `error`、`port`、`log_id`）
- 命令行参数解析使用 `flag` 标准库
- 配置优先级：命令行参数 > 环境变量 > 默认值
- `cmd` 包只负责解析配置，业务组装在 `app` 包中完成
- JWT 密钥统一由 `internal/pkg/jwt` 包管理，禁止在各包中重复定义
- 所有注释、日志消息、文档均使用中文
- 鉴权中间件通过路径前缀白名单判断，默认所有 API 接口需要认证
- 请求参数绑定与校验使用 `internal/pkg/echoutil` 泛型工具方法，避免重复代码
- 遵循 Go 命名最佳实践：类型名不重复包名前缀（如 `dbscript.Script` 而非 `dbscript.DBScript`），包名即是类型名的一部分
- import 别名只在必要时使用，避免 `domainenvironment` 等冗长别名

## 注意事项

- `internal/infrastructure/embed/web/dist` 目录由前端构建自动生成，不纳入版本控制
- 构建后端前必须先构建前端，否则嵌入的静态文件将为空
- 前端使用 SVG 图标（@mdi/js），通过自定义 Vuetify 图标集（defineComponent + h() 返回 VNode）将 kebab-case 图标名直接解析为 SVG path 数据，不依赖字体文件，避免浏览器加载警告和 [object Object] 渲染问题
- 数据库日志默认仅打印慢查询（warn 级别），如需打印全部 SQL 请设置 `-db-log-level info` 或环境变量 `DB_LOG_LEVEL=info`
- 构建时使用项目仓库根目录的 Dockerfile，如未提供 Dockerfile 则构建失败并在日志中报错
- Docker 镜像标签使用项目版本号，格式为 `项目名(小写):版本号`，项目名自动转换为小写并替换非法字符；如果项目未设置版本则使用 Git 提交哈希前 7 位
- 全局镜像环境变量通过「配置管理」页面添加（分类选择「镜像环境变量」），会自动注入到所有项目容器
- 环境为全局配置，不绑定到特定项目，构建时选择目标环境即可
- 构建时根据环境关联的凭据动态创建 Docker 客户端，支持 Docker Daemon（http/tcp/unix）和 Docker Daemon SSH（ssh://）两种连接方式
- 构建流程为可复用的通用配置，项目通过 `build_flow_id` 引用构建流程
- 如果项目未关联构建流程，触发构建时会报错提示
- 部署项目节点和 Docker Compose 部署节点互斥，不能出现在同一条链路上
- 当流程使用 Docker Compose 部署节点时，主流程自动跳过单容器部署步骤
- Docker Compose 部署场景下，项目详情仅展示 {{image}} 对应的容器，查看日志和进入终端只针对该容器
- **部署**：将镜像部署到指定环境（启动容器），test 和 release 环境都允许部署
- **实施**：将 release 的镜像部署到 pre，或将 pre 的镜像部署到 pro。test 环境没有实施按钮
- 占位符环境：设置 pre 环境为占位符时，从 release 实施到 pre 仅增加构建记录不实际部署，但仍允许从 pre 实施到 pro 以完成流程
- pre/pro 环境如关联了 Docker 仓库则从仓库拉取镜像部署，否则通过凭据管理的 SSH 连接信息进行部署
- 实施操作不会重新构建，只使用现有镜像部署到目标环境
- 构建完成后自动清理克隆到本地的仓库目录，释放磁盘空间
- Docker 镜像名自动转为小写并替换非法字符，同时去除首尾分隔符，避免因项目名包含中文、空格或大写字母导致生成非法镜像名
- 支持优雅停机：收到 SIGINT/SIGTERM 信号后等待正在处理的请求完成（最多 10 秒），然后关闭 Docker 客户端缓存和数据库连接
- 构建过程中可随时取消，取消后构建状态将标记为 cancelled
- 凭据不再关联项目，为全局配置；环境连接信息通过凭据引用管理
- 项目可关联 Git 凭据（git/git_ssh 类型），构建时优先使用项目关联的凭据拉取代码
- 容器名称格式为 `项目名-版本号-提交哈希`，test/release/pre 环境重建时直接移除旧容器；pro 环境保留最近 5 个旧容器方便回滚，相同 commit 的镜像部署时容器名自动添加后缀（-1、-2...）
- 项目可配置端口转发和挂载卷，部署容器时自动应用；前端采用 +/- 交互式配置（宿主机地址:容器内地址），点击 + 新增、点击 - 删除
- 生产环境(pro)支持回滚到指定版本，展示提交哈希和构建时间
- 构建流程保存成功后给出提示
- 系统初始化时自动创建默认构建流程「日常构建」（开始 → 拉取代码 → 执行构建 → 部署项目 → 结束）
- Docker 构建日志精简展示，不显示原始 JSON
- 构建失败时自动检测错误，正确标记构建状态
- Gitea Webhook 集成：配置 Webhook 后，代码推送可自动触发构建
- 全局淡入淡出提示弹窗：操作成功/失败时在屏幕上方居中显示提示信息，3 秒自动消失
- 构建时根据环境关联的 Docker 凭据动态创建 Docker 客户端，移除了全局 Docker 配置参数（--docker-host、--docker-tls-skip-verify）
- Docker Daemon SSH 凭据：通过 Go 原生 SSH 库建立隧道连接远程 Docker 守护进程，无需本地 ssh 命令，无需修改 ~/.ssh/config，地址和私钥为必填项
- 构建时自动传递 `VERSION` 构建参数给 Docker，Dockerfile 中声明 `ARG VERSION` 即可获取版本号，无需在容器内执行 `git describe`
- 构建上下文默认排除 `.git` 和 `node_modules` 目录以减小体积，同时支持项目仓库根目录的 `.dockerignore` 文件进行自定义排除规则
- 构建进度状态（current_step、status）使用原子化数据库更新，避免并发读写导致前端进度显示异常
- 构建记录展示提交信息（commit message），方便查看每次构建对应的代码变更
- 构建记录列表支持分页查询
- 构建流程的 Nodes/Edges 字段使用 GORM serializer:json 标签确保正确序列化为 JSON 存入数据库
- 项目详情中容器列表根据环境凭据动态创建 Docker 客户端获取，确保展示正确的容器信息
- 容器内存使用量通过 Docker stats 接口异步获取，列表接口仅返回容器基本信息，stats 接口按需请求每个运行中容器的实际内存占用
- 构建日志和仪表盘页面的自动轮询在浏览器标签页隐藏时自动暂停，避免后台页面频繁唤醒浏览器导致任务栏闪烁

## License

MIT