WebHook

WebHook 是一种用于在事件发生时触发 HTTP 请求的机制。它通常用于构建自动化流程，例如在代码仓库中触发构建、部署或通知。

本文以 Gitee WebHook + 服务器自动部署 为例，讲解从创建 WebHook、生成并部署 SSH 公钥，到服务器端自动拉取代码并构建的完整流程。你也可将本文前半部分改为 GitHub 等平台，原理相通。

完整流程概览

graph LR
  A[推送代码到 Gitee] --> B[Gitee 触发 WebHook HTTP 请求]
  B --> C[服务器接收端脚本校验密钥]
  C --> D[git pull 拉取最新代码]
  D --> E[构建并发布站点]

要打通这条链路，需要做三件事：

步骤	作用	操作位置
① 生成并部署 SSH 公钥	服务器可免密拉取私有仓库代码	服务器 + Gitee「SSH 公钥」
② 创建 WebHook	Gitee 推送时向服务器发送请求	Gitee 仓库「WebHooks」设置
③ 部署接收端脚本	接收请求、校验密钥、自动构建	服务器

顺序说明：先完成 ① 公钥部署，服务器才能免密拉取代码；再创建 ② WebHook 打通推送通知；最后 ③ 部署接收脚本完成自动构建。下面提供 界面操作 与 命令行操作 两种实现方式，按需任选其一即可完成 ①② 两步；第 ③ 步两种方式共用，见文末。

---

方式一：界面操作（Gitee 网页端）

1. 公钥生成与部署（SSH 公钥）

截图占位提示：下方 ../images/webhook/5服务器生成SSH密钥.png、../images/webhook/6Gitee添加SSH公钥.png 为待补充截图，请按步骤操作后把截图放置到此路径并修正图名。

1.1 服务器端生成 SSH 密钥对

在服务器命令行执行：

ssh-keygen -t rsa -b 4096 -C "webhook@your-server"
# 连续回车使用默认路径 ~/.ssh/id_rsa，也可设置密钥密码短语

生成后查看公钥内容（见下方图片占位）：

cat ~/.ssh/id_rsa.pub

1.2 将公钥添加到 Gitee

打开 Gitee 右上角头像 →「设置」→「安全设置 → SSH 公钥」，点击「添加公钥」，将上一步复制的公钥内容粘贴进去即可。

添加成功后，服务器即可使用 SSH 方式免密拉取该仓库代码：

git clone git@gitee.com:你的用户名/你的仓库.git
# 重新拉取使用 git pull，后续部署脚本会自动执行

2. 创建 WebHook

登录 Gitee，进入目标仓库，在「仓库管理」中开启 WebHooks 管理界面。

点击「添加 WebHook」，填写相关参数：

• URL：服务器上部署脚本的访问地址，例如 http://你的服务器域名/webhook。
• 密码：接收端脚本用于校验请求来源的密钥（相当于 WebHook 的 secret）。
• 事件：勾选「Push Hook」（推送时触发），也可按需勾选其他事件。

3. 复制密钥

保存后，复制该 WebHook 的「密码」作为密钥，供服务器端部署脚本校验使用（也可自定义为任意强密码）。

注意：此处的「密码」是 Gitee 与服务器之间的校验密钥，与步骤 1 的 SSH 公钥是两码事，请勿混淆。

至此，界面操作方式已完成 ①② 两步，可直接跳到文末「部署接收端脚本」。

---

方式二：命令行操作

1. 命令行生成并部署公钥

1.1 生成 SSH 密钥对

ssh-keygen -t rsa -b 4096 -C "webhook@your-server"
# 回车确认默认路径 ~/.ssh/id_rsa

cat ~/.ssh/id_rsa.pub
# 复制输出内容，这就是公钥

1.2 将公钥添加到 Gitee

可以通过 Gitee API 添加：

curl -X POST 'https://gitee.com/api/v5/user/keys' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "你的私人令牌",
    "title": "webhook-server",
    "key": "ssh-rsa AAAA...(上一步复制的公钥内容)"
  }'

也可以在 Gitee 网页端「设置 → 安全设置 → SSH 公钥」中手动粘贴添加，两者选其一。

1.3 验证免密拉取

ssh -T git@gitee.com          # 若返回欢迎信息，说明公钥部署成功
git clone git@gitee.com:你的用户名/你的仓库.git

2. 通过 Gitee API 创建 WebHook

Gitee 提供了 OpenAPI，可通过命令行创建 WebHook。需要先在 Gitee 私人令牌 页面生成一个私人令牌（access_token）。

curl -X POST 'https://gitee.com/api/v5/repos/你的用户名/你的仓库名称/hooks' \
  -H 'Content-Type: application/json' \
  -d '{
    "access_token": "你的私人令牌",
    "url": "http://你的服务器域名/webhook",
    "password": "WebHook密钥",
    "add_events": ["Push Hook"],
    "active": true
  }'

• 若返回 201 Created，说明 WebHook 创建成功。
• 查看/管理已创建的 WebHook：

# 列出仓库的所有 WebHook
curl 'https://gitee.com/api/v5/repos/你的用户名/你的仓库名称/hooks?access_token=你的私人令牌'

参数说明：add_events 为触发事件，Push Hook 表示推送时触发；password 即接收端脚本用于校验的密钥。

到这里，命令行方式也完成了 ①② 两步，接下来进入共用环节。

---

部署接收端脚本（自动构建）

下方路径 ../images/webhook/7部署接收端脚本.png 为待补充的部署示意图占位。

负责接收 WebHook 请求并在服务器上自动拉取代码、构建发布。下面以 Python + Flask 为例：

项目目录结构（以本文 VitePress 站为例）：
/server/
  ├─ deploy_server.py        # WebHook 接收端脚本
  ├─ webhook.secret          # 保存 WebHook 密钥，权限 600
  └─ site/                   # 服务器上的站点代码目录（已 git clone）

deploy_server.py 示例：

# -*- coding: utf-8 -*-
import hmac
import hashlib
import subprocess

from flask import Flask, request, abort

app = Flask(__name__)

# 从文件读取 WebHook 密钥（与 Gitee 上配置的密码保持一致）
with open("/server/webhook.secret", "r", encoding="utf-8") as f:
    WEBHOOK_SECRET = f.read().strip()

BUILD_DIR = "/server/site"   # 服务器上的站点代码目录


@app.route("/webhook", methods=["POST"])
def deploy():
    """
    接收 Gitee 推送触发的 WebHook 请求，校验密钥后自动拉取并构建。
    Gitee 调用时会把「密码」放在请求头 X-Gitee-TOKEN 中。
    """
    token = request.headers.get("X-Gitee-TOKEN", "")
    # 用 hmac 比对，避免直接字符串比较带来的时序攻击
    if not hmac.compare_digest(token, WEBHOOK_SECRET):
        abort(403, "invalid webhook token")

    # 1. 拉取最新代码
    subprocess.run(["git", "pull"], cwd=BUILD_DIR, check=True)
    # 2. 安装依赖并构建（此处为 VitePress 站点示例）
    subprocess.run(["pnpm", "docs:install"], cwd=BUILD_DIR, check=True)
    subprocess.run(["pnpm", "docs:build"], cwd=BUILD_DIR, check=True)
    # 3. 如需对外发布，可再加一步同步 dist 到部署目录的命令
    return "deploy ok"


if __name__ == "__main__":
    # 仅部署内网示例；生产环境建议使用 Gunicorn/uvicorn 并以反向代理暴露
    app.run(host="0.0.0.0", port=80)

启动前准备：

# 1. 创建密钥文件并写入与 Gitee 配置一致的密码
echo '你的WebHook密钥' > /server/webhook.secret
chmod 600 /server/webhook.secret

# 2. 安装依赖
pip install flask gunicorn

# 3. 以 gunicorn 常驻运行（后台服务）
gunicorn -w 1 -b 0.0.0.0:80 deploy_server:app --daemon

提示：

• 生产环境建议在 WebHook URL 中使用 HTTPS，并通过 Nginx 等反向代理把 /webhook 转发到该服务。
• X-Gitee-TOKEN 是 Gitee 传递 WebHook 密码的请求头名称；若使用其他平台，可调整为其对应的签名请求头。

验证

全部配置完成后，在本地向 Gitee 仓库推送一次代码：

git add .
git commit -m "test trigger webhook"
git push origin master

观察服务器日志或访问站点，若能自动更新，则说明「Gitee WebHook → 服务器 → 自动部署」链路已打通。