Gitaly进程收TERM信号后未正常退出

Question

Gitaly进程在收到TERM信号后未能正常退出，常见于GitLab实例关闭或重启过程中。该问题通常由挂起的RPC请求、未释放的文件锁或后台goroutine未正确处理中断信号导致。当Gitaly未能及时响应SIGTERM，系统可能最终发送SIGKILL，引发服务异常终止和潜在的数据一致性风险。排查时需检查日志中是否存在长时间运行的操作、gRPC超时配置是否合理，以及资源清理逻辑是否完善。

Answer 1

一、问题背景与现象分析

Gitaly 是 GitLab 架构中的核心组件，负责处理所有与 Git 存储相关的操作。在 GitLab 实例关闭或重启过程中，系统会向 Gitaly 进程发送 SIGTERM 信号以请求其优雅退出。然而，在某些情况下，Gitaly 进程未能及时响应该信号，导致进程挂起，最终被强制 SIGKILL 终止。

这种异常终止可能引发以下风险：

• 正在进行的 Git 操作（如 push、fetch）中断，造成仓库数据不一致
• 文件锁未释放，影响后续服务启动时的读写访问
• gRPC 客户端连接堆积，产生“僵尸请求”
• 监控系统误判为节点宕机，触发不必要的告警或故障转移

二、根本原因分层剖析

1. 挂起的 RPC 请求：gRPC 调用未设置合理的超时机制，导致长时间运行的操作（如大仓库 clone）阻塞退出流程。
2. 文件锁未释放：Gitaly 在执行 git pack 操作或 ref 更新时持有文件锁，若未通过 defer 或 context cancel 正确释放，将阻止进程退出。
3. 后台 goroutine 泄露：部分 goroutine 未监听 context.Done() 事件，无法响应主进程的中断信号。
4. 日志同步阻塞：日志写入磁盘时发生延迟（如 I/O 压力大），sync.Mutex 阻塞主线程。
5. 依赖服务无响应：Gitaly 与 Praefect、Redis 或对象存储通信超时，shutdown 流程卡在等待外部资源释放。

三、排查路径与诊断方法

排查项	检查方式	预期结果
是否存在长运行操作	grep "started=" /var/log/gitlab/gitaly/*.log	无超过 30s 的未完成请求
gRPC 超时配置	查看 gitaly.rb 中 grpc_timeout	建议设置为 30s~60s
goroutine 状态	pprof 分析 /debug/pprof/goroutine	无永久阻塞的协程
文件锁残留	lsof | grep gitaly && fuser -v /var/opt/gitlab/git-data	无锁定的 .lock 文件
shutdown 日志	搜索 "shutting down" 和 "graceful stop"	记录完整退出流程

四、解决方案与最佳实践

# 示例：优化 Gitaly 配置 (gitlab.rb)
gitaly['env'] = {
  "GITALY_TIMEOUT_DEFAULT" => "30s",
  "GITALY_TIMEOUT_CALLS" => "60s"
}

# 启用 graceful shutdown 超时
gitaly['shutdown_timeout'] = 60

# 强制回收空闲连接
gitaly['socket_path'] = "/var/opt/gitlab/gitaly/gitaly.socket"
gitaly['listen_addr'] = ""
    

五、架构级改进与监控增强

为从根本上提升 Gitaly 的健壮性，建议从架构层面进行优化：

graph TD A[SIGTERM Received] --> B{正在处理请求?} B -->|是| C[标记为 draining] B -->|否| D[立即退出] C --> E[拒绝新请求] E --> F[等待活跃请求完成 or 超时] F --> G[释放文件锁 & 关闭数据库连接] G --> H[退出进程] F -->|超时| I[强制终止剩余 goroutine] I --> H

六、自动化检测脚本示例

#!/bin/bash
# 检测 Gitaly 是否能正常响应 TERM
PID=$(pgrep gitaly)

if [ -z "$PID" ]; then
    echo "Gitaly not running"
    exit 0
fi

kill -TERM $PID
sleep 10

if kill -0 $PID 2>/dev/null; then
    echo "Gitaly still alive after 10s, sending KILL"
    kill -KILL $PID
    exit 1
else
    echo "Gitaly stopped gracefully"
fi