蓝盾v7.1-Mac构建机Task进程无法清理排查

背景

在蓝盾前端点击取消流水线任务后,任务依然会继续执行直至自然结束,无法立即终止,在一些执行时间较长的构建任务中,需等待较长时间,或者登陆构建机进行手动重启 agent。

第一部分:问题现象验证

1.1 测试场景设计

在 run shell 插件里执行下面的测试脚本:

#!/bin/bash
set -e

echo "=== 蓝盾信号测试脚本 ==="
echo "当前PID: $$"
echo "请在另一个终端执行以下任意命令进行测试:"
echo ""
echo "# 测试信号捕获:"
echo "kill -TERM $$"
echo "kill -INT $$"
echo ""

# 信号处理函数
cleanup() {
    echo "[$(date '+%H:%M:%S')] 捕获到信号,正在退出..."
    exit 0
}

# 注册信号
trap cleanup SIGTERM SIGINT

# 主循环(2分钟超时)
end_time=$(( $(date +%s) + 120 ))
count=0

while [ $(date +%s) -lt $end_time ]; do
    count=$((count + 1))
    echo "[$(date '+%H:%M:%S')] 循环第 ${count} 次执行"

    echo "执行测试命令..."
    sleep 5
done

echo "2分钟超时,正常结束"

1、会进行 SIGTERM 和 SIGINT 的捕获,如果监测到对应的信号会结束运行

2、最大等到超时阈值设置为 2 分钟,防止无法取消

测试步骤:

  1. 在 BK-CI 流水线中分别创建 linux 和 mac 构建环境的任务,执行上述脚本
  2. 运行约 30 秒后,在前端点击取消按钮
  3. 观察 Agent 日志和脚本行为

1.2 mac 环境测试结果

前端显示日志:

=== 蓝盾信号测试脚本 ===
当前PID: 17018
请在另一个终端执行以下任意命令进行测试:
# 测试信号捕获:
kill -TERM 17018
kill -INT 17018
[20:19:57] 循环第 1 次执行
执行测试命令...
[20:20:02] 循环第 2 次执行
执行测试命Start to execute the task(buildId=b-5e7077f4926647e398e82128c0f7c206|taskId=e-cfca44298b6f450c8eb34691628fe8f1)令...
Cancelled by huari
[20:20:07] 循环第 3 次执行
执行测试命令...
...继续执行直到2分钟超时...

1.3 linux 环境测试结果

前端显示日志:

=== 蓝盾信号测试脚本 ===
当前PID: 877012
[21:43:43] 循环第 1 次执行
执行测试命令...
[21:43:48] 循环第 2 次执行
执行测试命令...
[21:43:53] 循环第 3 次执行
执行测试命令...
Cancelled by huari
[21:43:58] 循环第 4 次执行
执行测试命令...
/root/bk-agent/build_tmp/devops_script_user_6992019006041720915.sh: line 28: 878285 Killed                  sleep 5

Fail to run the plugin because exit code not equal 0

第二部分:mac 环境手动测试验证

依然执行 run shell 插件的 task,然后在构建机上手动发送结束信号给 task 的进程,观察是否可以正确捕捉信号。

kill -TERM 19987
kill -INT 19987

结果:

=== 蓝盾信号测试脚本 ===
当前PID: 19987
请在另一个终端执行以下任意命令进行测试:
# 测试信号捕获:
kill -TERM 19987
kill -INT 19987
[21:17:20] 循环第 1 次执行
执行测试命令...
[21:17:25] 循环第 2 次执行
执行测试命令...
[21:17:30] 循环第 3 次执行
执行测试命令...
[21:17:35] 捕获到信号,正在退出...

备注:执行 kill -INT 19987 无法捕获到信号,无法正常退出

结论:通过蓝盾流水线的 run shell 插件执行的 task,可以正确捕捉 SIGTERM 信号。

第三部分:mac 环境 Agent 日志深度分析

3.1 任务注册与启动

[23 十二月 2025;20:19:57.394][main] INFO  c.t.devops.worker.common.Runner:loopPickup:212 - Start to execute the task(buildId=b-5e7077f4926647e398e82128c0f7c206|vmSeqId=1|status=DO|taskId=e-cfca44298b6f450c8eb34691628fe8f1|name=Shell ScriptstepId=null|type=linuxScript|paramSize=14|buildVarSize=59)
[23 十二月 2025;20:19:57.428][pool-4-thread-1] INFO  c.t.d.w.c.task.script.ScriptTask:execute:89 - Start to execute the script task(SHELL)

3.2 心跳机制与取消指令

[23 十二月 2025;20:20:09.218][Thread-4] INFO  c.t.d.w.common.heartbeat.Heartbeat:run:121 - Heartbeat cancel build:b-5e7077f4926647e398e82128c0f7c206,heartBeatInfo:HeartBeatInfo(projectId=demo, buildId=b-5e7077f4926647e398e82128c0f7c206, vmSeqId=1, cancelTaskIds=[e-cfca44298b6f450c8eb34691628fe8f1])

关键点: 取消指令在任务开始后 12 秒到达,任务 ID 完全匹配。

3.3 心跳和循环持续进行

Agent 在接收取消指令后仍在正常运行,心跳每 2 秒一次,脚本循环每 5 秒一次。

第四部分:linux 环境 Agent 日志深度分析

4.1 心跳检测与取消指令

[25 Dec 2025;00:00:01.000][Thread-4] INFO  c.t.d.w.common.heartbeat.Heartbeat:run:121 - Heartbeat cancel build:b-3d54c10ccf1244ffb0a8d3eb56f93167,heartBeatInfo:HeartBeatInfo(projectId=demo, buildId=b-3d54c10ccf1244ffb0a8d3eb56f93167, vmSeqId=2, cancelTaskIds=[e-4d0ea85df62140b7a422c7ca8365a478])

4.2 进程终止

[25 Dec 2025;00:00:01.082][Thread-4] INFO  com.tencent.process.BkProcessTree:log:90 - Recursively killing pid=1559839
[25 Dec 2025;00:00:01.082][Thread-4] INFO  com.tencent.process.BkProcessTree:log:90 - Killing pid=1559839
[25 Dec 2025;00:00:01.083][Exec Stream Pumper] INFO  - ##[error]/root/bk-agent/build_tmp/devops_script_user_2421826660222993218.sh: line 28: 1559839 Killed                  sleep 5

4.3 异常处理与清理

com.tencent.devops.common.api.exception.TaskExecuteException:  Script command execution failed with exit code(137)

任务因退出码 137 失败,上传日志到服务端,报告任务完成,清理临时文件,释放 Agent 运行配额。

第五部分:心跳取消流程源码分析

本文使用的是 v2.0.0-beta.32 版本查看代码,生产环境使用的是 v2.0.0-beta.34(该版本 release 已被官方删除)。

5.1 入口:心跳检测

每次检查心跳信息,如果 cancelTaskIds 不为空,则启动线程调用 KillCancelTaskProcessRunnable 进行关闭操作。

@Synchronized
fun start(jobTimeoutMills: Long = TimeUnit.MINUTES.toMillis(900), executeCount: Int = 1) {
    if (running) {
        logger.warn("The heartbeat task already started")
        return
    }
    var failCnt = 0
    executor.scheduleWithFixedDelay({
        if (running) {
            try {
                logger.info("Start to do the heartbeat")
                val heartBeatInfo = EngineService.heartbeat(executeCount)
                val cancelTaskIds = heartBeatInfo.cancelTaskIds
                if (!cancelTaskIds.isNullOrEmpty()) {
                    // 启动线程杀掉取消任务对应的进程
                    Thread(KillCancelTaskProcessRunnable(heartBeatInfo)).start()
                }
                failCnt = 0
            } catch (e: Exception) {
                // ...异常处理
            }
        }
    }, 10, 2, TimeUnit.SECONDS)
    // ...超时监控
}

5.2 关闭任务:KillCancelTaskProcessRunnable

实现了 Runnable 接口,用于异步处理取消任务:

终止进程树:

KillBuildProcessTree.killProcessTree(
    projectId = heartBeatInfo.projectId,
    buildId = buildId,
    vmSeqId = heartBeatInfo.vmSeqId,
    taskIds = cancelTaskIds,
    forceFlag = true  // 强制终止,不给进程优雅退出的机会
)

停止任务执行器:

if (!cancelTaskIds.isNullOrEmpty()) {
    val taskExecutorMap = TaskExecutorCache.getAllPresent(cancelTaskIds)
    taskExecutorMap?.forEach { taskId, executor ->
        logger.info("Heartbeat taskId[$taskId] executor shutdownNow")
        executor.shutdownNow()
        TaskExecutorCache.invalidate(taskId)
    }
}

5.3 killProcessTree:关闭构建任务拉起的进程树

核心工具函数,专门用于清理构建过程中产生的子进程。流程:

  1. 获取当前进程 ID:跨平台支持,Windows 通过 ManagementFactory,Unix 通过 shell 获取
  2. 遍历进程树:使用 BkProcessTree 获取系统进程树
  3. 进程过滤:
    • 获取进程环境变量
    • 检查 DEVOPS_DONT_KILL_PROCESS_TREE 保护标记
    • 排除自身进程
    • 匹配 PROJECT_ID + BUILD_ID + VM_SEQ_ID
    • 可选的 PIPELINE_ELEMENT_ID 任务 ID 过滤
  4. 终止进程:先递归终止子进程,再终止当前进程
if (flag) {
    osProcess.killRecursively(forceFlag)  // 递归终止子进程
    osProcess.kill(forceFlag)             // 终止当前进程
    killedProcessIds.add(osProcess.pid)   // 记录已终止的PID
}

第六部分:根因定位

6.1 前置猜测

结合代码分析,猜测问题在 killProcessTree 中因环境变量获取失败,导致匹配逻辑无法执行。

6.2 环境变量获取方式

Linux 实现: 直接读取 /proc/[pid]/environ 文件,以空字符分隔。

macOS 实现: 通过 sysctl 系统调用获取 kern.procargs2,解析进程参数和环境变量。核心步骤:

  1. 获取 kern.argmax(OID: {1, 8})确定缓冲区大小
  2. 获取 kern.procargs2(OID: {1, 49, pid})读取进程信息
  3. 解析 argc、可执行文件路径、命令行参数、环境变量

6.3 验证:kern.procargs2

编写了 C 语言工具模仿 Java 实现,调用 kern.procargs2 验证其存在性。

i5 芯片构建机(macOS Sequoia 15.7.3):kern.procargs2 存在且可正常使用,前端取消任务成功。

M3 芯片构建机:kern.procargs2 同样存在且可正常使用,但前端取消任务失败,脚本继续执行直到 2 分钟超时。

结论:根因并非 kern.procargs2 缺失。

6.4 验证:JNA 库架构不兼容

编写了 Java 测试工具,直接调用 Agent 内置的 BkProcessTree 类,触发完整的 kern.procargs2 调用链路。

i5 芯片构建机验证:

✅ 步骤1: 获取 BkProcessTree 实例成功
✅ 步骤2: 获取进程树迭代器成功
🎯 找到目标进程!
✅ 结果:成功获取到环境变量!

链路 java → BkProcessTree → JNA → kern.procargs2 调用成功。

M3 芯片构建机验证:

❌ 程序初始化失败:
java.lang.UnsatisfiedLinkError: ...jna2398815628179584771.tmp: dlopen(...):
  tried: '...' (fat file, but missing compatible architecture
  (have 'i386,x86_64,unknown', need 'arm64e' or 'arm64'))

根因确定:蓝盾 Agent worker-agent.jar 中内置的 JNA 本地库仅适用于 Intel 芯片(x86_64),无法在 ARM64 架构的 M 系列芯片上加载。

6.5 i5 vs M3 故障现象对比

对比维度 i5 (Intel) Mac M3 (Apple Silicon) Mac
流程触发 正常:Heartbeat cancel build 日志出现 正常:Heartbeat cancel build 日志出现
进程树初始化 成功:能打印 Found 678 processes 完全失败:UnsatisfiedLinkError 导致线程崩溃
kern.procargs2 持续出现 Failed to obtain ken.procargs2: Invalid argument,但以 sudo 模式安装 agent 则仅出现一次 未到达此步
任务取消结果 部分成功:执行器被 shutdownNow(),脚本以 0xDEADBEEF 被强制终止 完全失败:任务继续执行直至完成
根本原因 macOS 系统限制或权限问题,kern.procargs2 调用失败 JNA 库架构不兼容(主要)+ kern.procargs2 问题

6.6 问题总结

根因:蓝盾 Agent 在 macOS M 系列芯片上无法取消构建任务:

  1. JNA 库架构不兼容:Agent 内置的 JNA 本地库仅为 x86_64 版本,无法在 ARM64 架构的 M 芯片上加载,进程树功能完全失效
  2. macOS 系统限制或权限问题:kern.procargs2 在较新 macOS 版本中可能失败

结果对比:

结论:问题核心是 ARM64 架构兼容性缺失,需更新 JNA 库为通用或 ARM64 版本。

第七部分:官方修复

官方已在正式版本 v3.0.0 和 rc 版本 v3.0.0-rc.1 进行修复:

在升级蓝鲸 7.2 后,bk-ci 版本将从 v3.0.11.beta5 开始,该问题将解决。