# git-hook-flow

**Repository Path**: xlyjx2012/git-hook-flow

## Basic Information

- **Project Name**: git-hook-flow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# git-hook-flow

Webhook 流程编排服务，支持多工作流管理、CodeGraph 代码智能集成、自动化 git 仓库同步等场景。

## 功能特性

### 核心功能

- **多工作流管理**：每个 hook 路径独立配置（过滤器、仓库、触发类型）
- **过滤器链**：Token 验证 → 事件类型 → 分支过滤
- **Webhook 签名验证**：支持 HMAC-SHA256 签名密钥和 WebHook 密码两种模式
- **仓库管理**：
  - 单仓库模式（git clone）
  - 多仓库模式（submodule）
  - 自动克隆和拉取最新代码
- **并发控制**：同一工作流互斥锁，防止并发执行
- **优雅关闭**：SIGTERM 后等待当前任务完成

### CodeGraph 代码智能

- **MCP 协议支持**：通过 JSON-RPC 2.0 提供代码智能查询
- **手动实例管理**：工作流列表中可手动启动/停止 CodeGraph 服务
- **自动索引同步**：Webhook 推送后自动 pull 代码并更新索引
- **代码探索**：查询符号定义、调用关系、影响范围

### 安全特性

- **管理界面认证**：Basic Auth
- **MCP 端点认证**：X-MCP-Token 请求头验证
- **Token 加密存储**：AES-256-GCM
- **脚本路径白名单校验**
- **参数注入防护**（exec.Command 数组传参）
- **路径遍历防护**（filepath.Clean）

### 运维特性

- **日志轮转**：按大小/天数自动轮转，磁盘满降级写 stderr
- **配置热更新**：fsnotify 监听 + API 触发
- **交互式初始化**：首次启动无配置时提示设置端口、用户名、密码
- **systemd 服务**：支持用户级和系统级服务

## 一键安装

### Linux

```bash
curl -fsSL https://gitee.com/xlyjx2012/git-hook-flow/raw/master/scripts/install.sh | bash
```

同时注册 systemd 系统服务（后台运行 / 开机自启，需 root）。安装过程中会**交互式引导你设置端口和管理员账号密码**：

```bash
sudo HOOKFLOW_SERVICE=1 bash -c "$(curl -fsSL https://gitee.com/xlyjx2012/git-hook-flow/raw/master/scripts/install.sh)"
```

### Windows (PowerShell)

```powershell
irm https://gitee.com/xlyjx2012/git-hook-flow/raw/master/scripts/install.ps1 | iex
```

安装后可直接用别名启动：

```bash
githookflow
```

### 手动下载

从 [Gitee Releases](https://gitee.com/xlyjx2012/git-hook-flow/releases) 下载对应平台的二进制文件：

| 平台 | 架构 | 文件名 |
|------|------|--------|
| Linux | x86_64 | `git-hook-flow_*_linux_amd64.tar.gz` |
| Windows | x86_64 | `git-hook-flow_*_windows_amd64.zip` |

## 快速开始

### 编译

Windows:
```bash
go build -o git-hook-flow.exe .
```

Linux:
```bash
GOOS=linux GOARCH=amd64 go build -o git-hook-flow .
```

### 首次运行

```bash
./git-hook-flow
```

首次运行会进入交互式初始化向导：

```
======================================================
          git-hook-flow 初始化向导
======================================================

? Webhook 监听端口 (默认 9000):
? 管理界面用户名 (默认 admin):
? 管理界面密码:
```

也可以只初始化配置而不启动服务（重跑一次即重置账号密码，用于忘记密码的场景）：

```bash
./git-hook-flow init
```

### 访问

- Web UI: http://localhost:9000
- Webhook: http://localhost:9000/webhook/:path
- MCP: http://localhost:9000/webhook/:path/mcp
- Health: http://localhost:9000/health

## API 文档

### 健康检查（无需认证）

```
GET /health
```

### Webhook 接收（无需认证）

```
POST /webhook/:hookPath
```

### MCP 端点（需 X-MCP-Token 认证）

```
POST /webhook/:hookPath/mcp              # JSON-RPC 请求（实例未运行时自动启动）
GET  /webhook/:hookPath/mcp/status       # 查询 CodeGraph 实例状态
POST /webhook/:hookPath/mcp/stop         # 停止 CodeGraph 实例
```

请求头：
```
X-MCP-Token: <工作流的 MCP Token>
```

> MCP Token 在工作流启用 CodeGraph 时自动生成，可通过管理 API 重置。

### 管理接口（需 Basic Auth 认证）

```
# 工作流管理
GET    /api/flows                    # 获取所有工作流
POST   /api/flows                    # 创建工作流（幂等）
POST   /api/flows/sse                # 创建工作流（SSE 模式，实时推送进度）
GET    /api/flows/:id                # 获取单个工作流
PUT    /api/flows/:id                # 更新工作流
PUT    /api/flows/:id/sse            # 更新工作流（SSE 模式，实时推送进度）
DELETE /api/flows/:id                # 删除工作流

# CodeGraph 实例管理
GET    /api/flows/:id/codegraph/status   # 查询 CodeGraph 状态
POST   /api/flows/:id/codegraph/start    # 启动 CodeGraph 实例
POST   /api/flows/:id/codegraph/stop     # 停止 CodeGraph 实例

# MCP Token 管理
POST   /api/flows/:id/mcp-token/reset    # 重置 MCP Token

# 批量操作
POST   /api/flows/batch              # 批量启用/禁用/删除

# 配置管理
GET    /api/config                   # 获取配置
PUT    /api/config                   # 更新配置
POST   /api/config/reload            # 热更新

# 导入导出
GET    /api/export                   # 导出配置
POST   /api/import                   # 导入配置

# 日志
GET    /api/logs                     # 日志列表
GET    /api/logs/:id                 # 日志详情
DELETE /api/logs                     # 清空日志
DELETE /api/logs/:id                 # 删除单条日志

# 状态
GET    /api/status                   # 服务状态

# Token 生成
GET    /api/token/generate           # 生成随机 token
```

## 工作流配置

### 仓库类型

| 类型 | 说明 | 操作 |
|------|------|------|
| 0 | 无 | 不做仓库操作 |
| 1 | 多仓库 | 使用 submodule 模式 |
| 2 | 单仓库 | 使用 git clone 模式 |

### 触发类型

| 类型 | 说明 | Webhook 行为 |
|------|------|-------------|
| CodeGraph | 代码智能 | 自动 pull 代码，CodeGraph 服务需手动启动 |
| 执行脚本 | 脚本执行 | 执行配置的脚本文件 |
| 无 | 仅记录 | 不做任何操作 |

### CodeGraph 模式

当工作流启用 CodeGraph 时：

1. **保存工作流**：自动初始化 CodeGraph 索引（不启动服务）
2. **启动方式**：
   - 手动启动：在工作流列表中点击"启动"按钮
   - 自动启动：MCP 请求时若实例未运行会自动启动
3. **Webhook 推送**：自动 pull 对应仓库代码
4. **文件监听**：CodeGraph 自动检测文件变化并更新索引

MCP 调用示例：

```bash
curl -X POST http://localhost:9000/webhook/my-project/mcp \
  -H "Content-Type: application/json" \
  -H "X-MCP-Token: your-secret-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "codegraph_explore",
      "arguments": {
        "query": "AuthService loginUser"
      }
    }
  }'
```

## 脚本参数

所有脚本执行时，默认传递以下参数：

**位置参数：**

```bash
./script.sh <仓库名称> <事件类型> <分支名称> <推送者> <提交信息>
```

- `$1` - 仓库名称
- `$2` - 事件类型（如 `Push Hook`、`Tag Push Hook`）
- `$3` - 分支名称
- `$4` - 推送者用户名
- `$5` - 最新提交信息

**环境变量：**

```bash
GIT_HOOK_FLOW_REPO_NAME=project-a
GIT_HOOK_FLOW_EVENT_TYPE=Push Hook
GIT_HOOK_FLOW_BRANCH=main
GIT_HOOK_FLOW_PUSHER=zhangsan
GIT_HOOK_FLOW_COMMIT_MESSAGE="feat: add login"
GIT_HOOK_FLOW_WORK_DIR=/workspace/project-a
GIT_HOOK_FLOW_ID=flow-001
```

### 示例脚本：test-hook.sh

用于验证 webhook 是否正确触发并传递参数，将收到的位置参数和环境变量写入日志文件，便于排查。

```bash
#!/usr/bin/env bash
# 测试脚本：验证 webhook 是否正确触发并传递参数
# 将收到的参数和环境变量写入日志文件，便于排查

LOG_FILE="${GIT_HOOK_FLOW_WORK_DIR:-.}/test-hook.log"

{
    echo "=========================================="
    echo "触发时间: $(date '+%Y-%m-%d %H:%M:%S')"
    echo "=========================================="
    echo ""
    echo "--- 位置参数 ---"
    echo "  \$1 仓库名称: $1"
    echo "  \$2 事件类型: $2"
    echo "  \$3 分支名称: $3"
    echo "  \$4 推送者:   $4"
    echo "  \$5 提交信息: $5"
    echo ""
    echo "--- 环境变量 ---"
    env | grep ^GIT_HOOK_FLOW_ | sort
    echo ""
    echo "--- 脚本信息 ---"
    echo "  脚本路径: $0"
    echo "  工作目录: $(pwd)"
    echo "  执行用户: $(whoami)"
    echo ""
} >> "$LOG_FILE"

echo "[test-hook] 已记录到 $LOG_FILE"
```

触发后日志输出示例：

```
==========================================
触发时间: 2026-08-05 07:06:06
==========================================

--- 位置参数 ---
  $1 仓库名称: project-a
  $2 事件类型: Push Hook
  $3 分支名称: main
  $4 推送者:   zhangsan
  $5 提交信息: feat: add login

--- 环境变量 ---
GIT_HOOK_FLOW_BRANCH=main
GIT_HOOK_FLOW_COMMIT_MESSAGE=feat: add login
GIT_HOOK_FLOW_EVENT_TYPE=Push Hook
GIT_HOOK_FLOW_ID=flow-001
GIT_HOOK_FLOW_PUSHER=zhangsan
GIT_HOOK_FLOW_REPO_NAME=project-a
GIT_HOOK_FLOW_WORK_DIR=/workspace/project-a

--- 脚本信息 ---
  脚本路径: /workspace/test-hook.sh
  工作目录: /workspace/project-a
  执行用户: root
```

> **⚠️ 注意：脚本必须添加执行权限，否则服务无法调用。**
>
> ```bash
> chmod +x ./test-hook.sh
> ```

## 配置说明

配置文件 `config.json`：

```json
{
  "port": 9000,
  "hook_flows": [],
  "security": {
    "admin_username": "admin",
    "admin_password_hash": "$2a$10$...",
    "exec_user": "",
    "token_encrypt_key": "base64-encoded-32-bytes-key"
  },
  "work_dir": "/home/workspace",
  "log_max_size": 100,
  "log_max_days": 30,
  "log_compress": true
}
```

## 部署

### Windows 服务（后台运行 / 开机自启）

```powershell
# 在 exe 所在目录先完成交互式初始化(生成 config.json;重跑即重置密码)
cd <安装目录>
.\git-hook-flow.exe init

# 以管理员权限注册 / 管理服务
.\git-hook-flow.exe service install   # 注册服务(开机自启)
.\git-hook-flow.exe service start     # 启动
.\git-hook-flow.exe service stop      # 停止
.\git-hook-flow.exe service remove    # 删除服务
```

服务运行时工作目录自动切换为 exe 所在目录,`config.json`、`data/`、`logs/`、`web/` 需与 exe 同目录。

### systemd 系统服务（curl 一键安装，需 root）

安装时加 `HOOKFLOW_SERVICE=1`，安装过程会交互式引导设置端口和管理员账号密码，随后自动启用并启动服务：

```bash
sudo HOOKFLOW_SERVICE=1 bash -c "$(curl -fsSL https://gitee.com/xlyjx2012/git-hook-flow/raw/master/scripts/install.sh)"

systemctl status git-hook-flow               # 查看状态
systemctl stop git-hook-flow                 # 停止

# 忘记密码:重跑 init 即重置(配置在 ~/.git-hook-flow/config.json)
cd ~/.git-hook-flow && githookflow init && systemctl restart git-hook-flow
```

### systemd 系统服务（手动部署，需 root）

```bash
# 复制二进制文件
sudo cp git-hook-flow /opt/git-hook-flow/

# 首次先完成交互式初始化(生成 config.json,不启动服务)
cd /opt/git-hook-flow && sudo ./git-hook-flow init

# 创建用户
sudo useradd -r -s /bin/false hookflow

# 创建目录
sudo mkdir -p /opt/git-hook-flow/{data,logs}
sudo chown -R hookflow:hookflow /opt/git-hook-flow

# 安装服务(单元文件在仓库 scripts/git-hook-flow.service,也可直接 curl 下载)
sudo cp scripts/git-hook-flow.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable git-hook-flow
sudo systemctl start git-hook-flow
```

### 配置 Gitee Webhook

在 Gitee 仓库设置中添加 Webhook：

- URL: `http://your-server:9000/webhook/your-hook-path`
- 密码: 在工作流配置中设置的 Token
- 事件: 根据需要选择

## 目录结构

```
git-hook-flow/
├── main.go                  # 入口 + 交互式初始化 + 服务启动
├── config/
│   └── config.go            # 配置管理（加载/保存/热更新）
├── handlers/
│   ├── webhook.go           # Webhook 处理（无需认证）
│   ├── mcp.go               # MCP 端点处理（X-MCP-Token 认证）
│   ├── api.go               # 管理 API（Basic Auth 认证）
│   └── web.go               # Web UI + 认证中间件
├── models/
│   └── models.go            # 数据模型
├── services/
│   ├── codegraph.go         # CodeGraph 实例管理
│   ├── filter.go            # 过滤器逻辑
│   ├── script.go            # 脚本执行
│   ├── executor.go          # 并发控制
│   ├── crypto.go            # 加密解密
│   ├── repo.go              # 仓库操作
│   ├── flow_setup.go        # 工作流保存设置
│   └── logger.go            # 日志记录
├── web/
│   ├── embed.go             # go:embed 嵌入静态资源
│   └── index.html           # 主页面（嵌入二进制）
├── scripts/                 # 示例脚本 + 安装/发布脚本
│   ├── git-pull.sh          # Git 拉取示例
│   ├── codegraph-sync.sh    # CodeGraph 同步示例
│   ├── notify.sh            # 通知示例
│   ├── test-hook.sh         # Webhook 测试脚本
│   ├── install.sh           # Linux 一键安装
│   ├── install.ps1          # Windows 一键安装
│   ├── git-hook-flow.service # systemd 服务文件
│   └── gitee-release.sh     # Gitee Release 发布
├── data/                    # 数据目录
│   └── git-hook-flow.db     # BoltDB 数据库
├── logs/                    # 日志目录
│   └── app.log              # 应用日志
├── config.json              # 配置文件（运行时生成）
└── README.md
```

## 技术栈

- Go 1.26+
- Gin (HTTP 框架)
- BoltDB (嵌入式数据库)
- lumberjack (日志轮转)
- fsnotify (文件监听)
- bcrypt (密码哈希)
- AES-256-GCM (Token 加密)
- Tailwind CSS + Alpine.js (前端)
- CodeGraph (代码智能)

## License

MIT