Git 钩子自动化部署完全指南：掌握 post-receive 触发机制与生产实践

Git 钩子自动化部署完全指南：掌握 post-receive 触发机制与生产实践

---

一、核心机制剖析

1.1 触发三要素

要素	说明
文件名约定	必须严格命名为post-receive（大小写敏感）
路径规范	仅生效于裸仓库的hooks/目录（路径示例：/repo/project.git/hooks/）
执行权限	必须赋予可执行权限：chmod +x post-receive

1.2 触发时序图

开发者 裸仓库 钩子引擎 post-receive 部署系统 应用服务 git push origin main 完成所有引用更新 标准输入传递变更数据 执行checkout/构建/重启 文件实时生效 开发者 裸仓库 钩子引擎 post-receive 部署系统 应用服务

---

二、配置全流程详解

2.1 目录结构规范

/repo/
├── project.git/          # 裸仓库
│   ├── objects/
│   └── hooks/
│       └── post-receive  # 核心钩子
/deploy/
└── production/           # 工作目录
    ├── index.html
    └── static/

2.2 权限控制矩阵

对象	裸仓库	工作目录	Web服务
git 用户	读写	读写	-
www-data	-	读	执行
开发团队	只读	-	-

2.3 标准脚本模板

#!/bin/sh
DEPLOY_PATH="/deploy/production"
LOG_FILE="/var/log/git_deploy.log"

# 记录完整输入数据
echo "[$(date)] 触发日志" >> $LOG_FILE
cat - | tee -a $LOG_FILE

# 处理主分支变更
while read oldrev newrev ref
do
  if [ "$ref" = "refs/heads/main" ]; then
    echo "正在部署main分支..." | tee -a $LOG_FILE
    GIT_WORK_TREE=$DEPLOY_PATH git checkout -f 2>&1 | tee -a $LOG_FILE
    systemctl reload nginx | tee -a $LOG_FILE
  fi
done

---

三、高阶调试技巧

3.1 手动触发测试

# 模拟分支更新（在裸仓库执行）
echo "0000000 1111111 refs/heads/main" | hooks/post-receive

# 强制重置环境
GIT_WORK_TREE=/deploy/production git reset --hard HEAD

3.2 智能日志追踪

# 记录全量上下文
exec > >(tee -a /var/log/git_deploy.log) 2>&1
echo "===== 部署开始 [$(date +%Y-%m-%dT%H:%M:%S)] ====="

# 关键操作记录
set -x  # 开启执行追踪
GIT_WORK_TREE=$DEPLOY_PATH git checkout -f
set +x

---

四、生产级部署方案

4.1 多环境分流策略

case "$ref" in
  "refs/heads/main")
    DEPLOY_ENV="/deploy/prod"
    ;;
  "refs/heads/staging")
    DEPLOY_ENV="/deploy/stage"
    ;;
  "refs/heads/dev")
    DEPLOY_ENV="/deploy/dev"
    ;;
esac

GIT_WORK_TREE=$DEPLOY_ENV git checkout -f

4.2 安全回滚机制

# 保留最近5个版本
DEPLOY_PATH="/deploy/prod"
BACKUP_DIR="/backup/prod/$(date +%Y%m%d%H%M%S)"
cp -r $DEPLOY_PATH $BACKUP_DIR
find /backup/prod -maxdepth 1 -mtime +5 -exec rm -rf {} \;

---

五、故障应急手册

5.1 常见问题速查

现象	快速检测命令	解决方案
钩子未触发	ls -l hooks/post-receive	检查文件权限与路径
文件检出失败	ls -ld /deploy/production	验证目录所有权
环境变量失效	echo $GIT_WORK_TREE	使用绝对路径声明变量
部分文件未更新	git log -1 --stat	检查提交内容，强制重置

5.2 监控指标配置

# 部署成功率监控
部署次数=$(grep -c "触发日志" /var/log/git_deploy.log)
失败次数=$(grep -c "ERROR" /var/log/git_deploy.log)
成功率=$(( ($部署次数 - $失败次数) * 100 / $部署次数 ))

# 文件完整性校验
find /deploy/prod -type f -exec md5sum {} + > /tmp/prod_checksum
diff /tmp/prod_checksum /tmp/expected_checksum

---

六、性能优化建议

1. 增量部署：结合git diff-tree识别变更文件

   changed_files=$(git diff-tree --no-commit-id --name-only -r $newrev)
   

2. 并行处理：使用&后台执行耗时操作

   (npm install --production > npm.log 2>&1 &)
   

3. 缓存加速：建立node_modules缓存目录

   ln -s /cache/node_modules /deploy/prod/node_modules