Repository navigation
fix(runner): install the Linux Docker helper on macOS - #1108
Conversation
Robert0622
left a comment
There was a problem hiding this comment.
建议合并前修复下面 4 个安装和恢复问题。
我从 4148580 编译了 Darwin/amd64 和 Linux/amd64 Runner,在 Linux 主机模拟 macOS 安装,并将安装出来的 Linux helper 放进 Alpine 容器执行。正常安装时 mcp list 和测试网关的 git-credential get 均成功。相关 Go 回归通过了 -race,仅限 macOS 的守护进程启动用例在本机跳过。各条行内评论附有额外实测结果。
| [[ ${#header} -eq 128 && "${header:0:14}" == "7f454c46020101" && | ||
| ( "${header:14:2}" == "00" || "${header:14:2}" == "03" ) && | ||
| ( "${header:32:4}" == "0200" || "${header:32:4}" == "0300" ) && | ||
| "${header:36:4}" == "$machine" ]] |
There was a problem hiding this comment.
[P2] 替换旧 helper 前请校验完整的发布产物。 这里仅检查前 64 字节。我先安装了可工作的 Linux Runner,再让发布端以 HTTP 200 返回同一 ELF 的前 64 字节,Content-Length 也为 64。--upgrade 退出码为 0,原来的 16,422,325 字节文件被覆盖。同一个 Alpine 容器执行 mcp list,升级前成功,升级后报 exec format error。建议在 mv 前校验发布清单中的完整摘要,或验证 ELF 的可加载段及其文件范围,并用这个截断场景断言原 helper 仍可运行。
| if err != nil { | ||
| return err | ||
| } | ||
| if repairOnly && validateDockerRunnerHelper(path) == nil { |
There was a problem hiding this comment.
[P2] 启动同步失败后,后续扫描需要重试版本比对。 我预装了基线提交构建的有效 helper,让首次元数据请求返回 503,然后恢复发布端。按五分钟扫描使用的 repairOnly=true 调用时,HTTP 请求数是 0,磁盘上仍是基线版本。再走一次启动检查就成功安装了 PR 版本。主 Runner 已升级的机器会因此长期使用旧版 Git/MCP helper。可以记录本次启动是否已成功对齐远端摘要,成功前持续重试。
| if runtime.GOOS != "darwin" || d.cfg.DisableAutoUpdate { | ||
| return | ||
| } | ||
| updateCtx, cancel := context.WithTimeout(ctx, 30*time.Second) |
There was a problem hiding this comment.
[P2] 给后台下载留出完整的传输时间。 这个 30 秒期限同时覆盖元数据和整个响应体,五分钟后的重试也使用同一期限。我让本地发布端以 384 KiB/s 持续发送同一个 Linux Runner:使用这里的期限在 30 秒报 context deadline exceeded,普通下载器在 41 秒完成并通过验证。缺少 helper 的机器在这种链路上每次都从头下载。建议后台沿用下载器的传输期限,把首次工作区愿意等待的时间单独限制。
| local source="${SOURCE_DIR:-$PWD}" | ||
| # A custom host runner may have a matching helper managed by its installer. | ||
| # A per-OS download URL can replace the helper when it is the selected source. | ||
| if [[ -x "$DOCKER_RUNNER_BINARY" && -f "$DOCKER_RUNNER_BINARY" && |
There was a problem hiding this comment.
[P2] 保留自定义 helper 时也应识别不兼容的文件。 我把一个有执行位的 Darwin Runner 放在 Linux helper 路径,再执行 --upgrade --from。即使发布端提供了正确的 Linux 产物,安装仍以 0 退出,Linux 下载请求数为 0,原路径留下的仍是 Mach-O。自定义安装默认关闭自动更新,Docker 工作区会持续启动失败。建议只把可在目标平台运行的文件视为已就绪;如果自定义文件不能覆盖,至少应明确报错并指出需要替换的路径。
Robert0622
left a comment
There was a problem hiding this comment.
在 Apple Silicon 上复核了 4148580,建议修复后再合并。两条新行内评论分别对应自定义产物路径和 --from 安装 Intel Runner 时的架构选择。
我也独立复现了已有评论里的两个故障。发布端以 HTTP 200 返回真实 Linux Runner 的前 4 KiB 时,--upgrade 以 0 退出并覆盖原文件,Docker 中的 MCP 进程随后收到 SIGSEGV。删除 helper 后,把同一份 14.5 MiB 产物的下载速度限制在 384 KiB/s,Runner 在约 30 秒报 context deadline exceeded,文件仍然缺失。截短产物 · 下载超时
正常路径已通过实测。用本提交编译的 macOS 和 Linux arm64 产物完成安装、升级及缺失文件的启动修复后,在 Docker 内验证了 Git 凭证查询和 MCP 调用。CodeBuddy 首轮通过 helper 读到了临时生成的 MCP 服务 ID,续聊也返回了同一 ID。相关 Go 回归通过了 -race 检查,go vet ./deploy ./internal/runner ./internal/runtime 通过。
| ENV_FILE="${RUNNER_HOME}/env" | ||
| STATE_FILE="${RUNNER_HOME}/state.json" | ||
| BINARY="${BIN_DIR}/agentflow-runner" | ||
| DOCKER_RUNNER_BINARY="${BIN_DIR}/agentflow-runner-linux-${ARCH}" |
There was a problem hiding this comment.
[P2] 安装器需要把 helper 写到工作区实际读取的路径。 我在安装和前台启动时都设置了 AGENTFLOW_RUNNER_BINARY=<root>/bundle/{os}/{arch}/agentflow-runner。安装成功后,文件位于 --bin-dir 下,PrepareMCPCall 却在 bundle/linux/arm64/agentflow-runner 报 no such file or directory。全新安装中这个父目录尚不存在,启动修复也在 os.CreateTemp 处失败。请让安装和修复都按运行时规则展开模板,并在目标目录中暂存、发布文件。可以用尚不存在的架构子目录覆盖这个回归。
| url="${DOWNLOAD_URL//\{os\}/$target_os}" | ||
| url="${url//\{arch\}/$ARCH}" | ||
| else | ||
| url="${SERVER}/runners/agentflow-runner?os=${target_os}&arch=${ARCH}" |
There was a problem hiding this comment.
[P2] --from 安装时,Linux helper 的架构需要匹配实际使用的 macOS Runner。 我在 Apple Silicon 的原生 arm64 shell 里用 --from 安装了本提交编译的 Darwin/amd64 Runner。脚本按 uname -m 只下载并安装了 agentflow-runner-linux-arm64。通过 Rosetta 运行的 amd64 进程调用 PrepareMCPCall 时会按 runtime.GOARCH 查找 agentflow-runner-linux-amd64,实测直接报文件不存在。--from 还会关闭自动更新。这条路径需要根据所选宿主二进制确定 helper 的下载架构、校验架构和文件名,或在安装时明确拦下不支持的组合。
Robert0622
left a comment
There was a problem hiding this comment.
在 Apple Silicon Mac 上从 b5b9eaf 编译并部署了原生 darwin/arm64 控制面和 Runner,使用独立 MySQL 8.4。通过平台提供的安装脚本和绑定码注册后,平台下发的 Docker SOP 在 Linux/arm64 容器里完成了 git credential fill 和 mcp call。从平台发起的两轮真实 CodeBuddy 会话也通过,第二轮诊断为 resume=true,并返回了首轮在容器里生成的随机标识。
上轮的四个复现均已通过。HTTP 200 返回前 4 KiB 时,升级保住了旧 helper。256 KiB/s 的下载在 41.6 秒后完成且摘要一致。自定义目录被删除后能在启动时重建,单架构 Intel --from 安装也正确提供了可执行的 Linux/amd64 helper。另测首次元数据返回 503,原进程在约 302 秒后自动重试并更新了旧版本。
还有一个自定义安装组合会阻断 Docker 工作流。双架构 macOS Runner 经 Rosetta 安装后,由 launchd 以 arm64 启动时找不到匹配的 Linux helper。复现和对照结果已附在安装器对应行。
| case "$header" in | ||
| cffaedfe07000001) printf '%s\n' amd64 ;; | ||
| cffaedfe0c000001) printf '%s\n' arm64 ;; | ||
| *) printf '%s\n' "$ARCH" ;; |
There was a problem hiding this comment.
[P2] 双架构 Mach-O 会回退到安装器的架构,可能与 launchd 实际启动的架构不同。 在 Apple Silicon 上,我用 lipo -create 合并本提交的 arm64 和 x86_64 Runner,然后用 Rosetta 的 /bin/bash 执行 bind-cli.sh --from <universal-runner> --service。安装目录中只有 agentflow-runner-linux-amd64。系统 launchd 按生成的 ProgramArguments 启动同一二进制,平台登记为 darwin/arm64。这台 Runner 的 Docker SOP 随即在准备阶段报 agentflow-runner-linux-arm64: no such file or directory。只补上对应的 Linux/arm64 文件,在同一个 Runner 上重跑同一 SOP 就通过了。--from 生成的服务参数含 -auto-update=false,因此不会自动补齐。
建议识别 universal Mach-O,为其中支持的两个架构提供对应 helper,或者让服务显式运行与已安装 helper 一致的架构。回归用例可以覆盖 Rosetta 安装、launchd 原生启动这组组合。
Robert0622
left a comment
There was a problem hiding this comment.
在 Apple Silicon Mac 上重新部署了 ede101a。上轮反馈的 Rosetta 安装、launchd 原生启动已经通过。在平台只提供 arm64 产物时,从 Rosetta 前台启动、执行 --no-start 打印的命令,两种方式都能跑通 Docker 里的 git credential fill 和 MCP 工具调用。iOA CodeBuddy 两轮对话也正常续接。
还有一处原地升级会在报错后留下不完整的安装。行内评论附了复现步骤和 Gate 节点的错误,建议修复后再合并。
| [[ -s "$TEMP_BINARY" ]] || fail "下载或构建的 runner 二进制为空" | ||
| chmod +x "$TEMP_BINARY" | ||
| mv -f "$TEMP_BINARY" "$BINARY" | ||
| publish_runner_binary "$BINARY" |
There was a problem hiding this comment.
[P2] 校验通用 Runner 的 helper 路径后再替换已安装的二进制。 在 Apple Silicon 上,先用 --from 安装 Intel 单架构 Runner 并启用 launchd,配置 AGENTFLOW_RUNNER_BINARY=<目录>/{os}/agentflow-runner。Docker 的 Git 和 MCP 均可用。随后执行 --upgrade --from <通用 Runner>,安装器提示路径缺少 {arch} 并返回 1,但磁盘上的 Runner 已从 x86_64 变成 x86_64 arm64,Gate helper 仍只有 amd64。重启同一个 launchd 服务后进程实际运行 arm64,平台下发的 Gate 节点失败,错误是 gate MCP binary linux/arm64 is not deployed。
建议从暂存的 Mach-O 读取架构并完成模板、路径校验,再替换 $BINARY。这个升级回归用例也可以断言,校验失败时原二进制的哈希保持一致。
Robert0622
left a comment
There was a problem hiding this comment.
在 Apple Silicon Mac 上重新部署并复测了 79ae312。上轮反馈的路径校验问题已修复。旧模板缺少 {arch} 或必需的 Gate MCP 下载失败时,升级都会保留原 Runner。重启原 launchd 服务后,Docker 里的 Git、MCP 和 Gate 仍然可用。正常升级、Rosetta 前台启动和 iOA CodeBuddy 两轮续接也已通过。
还复现了一处升级后会中断现有 Docker 工作流的问题,条件是切换了 Runner 架构,而新架构的 Linux Git/MCP helper 下载失败。复现和修复建议见行内评论。
| fi | ||
| rm -f "$TEMP_BINARY" | ||
| TEMP_BINARY="" | ||
| warn "无法获取有效的 Linux/${ARCH} Git/MCP helper,Docker 工作区需要该文件:${DOCKER_RUNNER_BINARY}" |
There was a problem hiding this comment.
[P2] 切换架构的升级需要先确认新架构的 Linux Git/MCP helper 可用。 在 Apple Silicon 上,我先用 --from 安装 Intel Runner,使用默认 helper 路径并启用 launchd,Docker 工作流中的 git credential fill 和 MCP 调用均通过。随后执行 --upgrade --from <通用 Runner>,仅让 Linux/arm64 Runner 下载返回 HTTP 503,所有 Gate 产物正常。这里打印警告后,升级仍返回 0,替换了主程序并重启服务。新进程以 arm64 运行,同一条 Docker 工作流随即报 agentflow-runner-linux-arm64: no such file or directory。--from 会关闭自动更新。恢复下载并重新执行升级后,同一 Runner 上的工作流再次通过。
建议在这种会切换架构、且已禁用自动更新的原地升级中,先验证新架构的 Linux helper 已经可用。如果下载失败又没有兼容的现有文件,就返回错误并保留当前可工作的 Runner 和服务。
Robert0622
left a comment
There was a problem hiding this comment.
在 Apple Silicon Mac 上从 d584b3f 构建并部署了原生控制面和 Runner。上轮反馈的 503 问题已通过复测。无论是 Intel 升级到通用版,还是 arm64 升级时更换 helper 目录,新 helper 下载失败都会保留旧进程、配置和绑定,原 Docker 工作流仍可完成 Git 凭据读取和 MCP 调用。恢复下载后可以原地升级。旧 Rosetta 进程、launchd 相对路径和 iOA CodeBuddy 的两轮续接也通过了实测。
还有一处启动时的可用性问题。开启自动更新后,合法的 0644 helper 在首次版本检查期间会被当成不可用,导致已经能运行的 Docker 任务超时。复现和对照结果见行内评论。
| return nil | ||
| default: | ||
| } | ||
| if validateDockerRunnerHelper(path) == nil { |
There was a problem hiding this comment.
[P2] 首次同步时应允许 Docker 直接使用可读的本地 helper。 安装器已支持权限为 0644 的 Linux ELF,沙箱也会把它复制成 0755。这里调用的 validateDockerRunnerHelper 还要求宿主源文件有执行位。
我在 Apple Silicon 上启动自动更新已开启的 arm64 Runner。本地 helper 的 SHA-256 与发布端一致,只把 Linux helper 的元数据响应延迟 12 秒,随后正常返回 HTTP 200。启动后提交的 Docker 工作流在 5.3 秒后报 Docker Git/MCP helper is still syncing: context deadline exceeded。另一次对照里,保持同一个元数据请求未完成,只把源文件从 0644 改成 0755,同一条 Git/MCP 工作流在 1.4 秒内通过。恢复 0644 后,首次同步结束时也能正常运行。
建议让启动等待逻辑按沙箱复制所需的条件判断本地文件,保留可读性、ELF 格式和架构校验,让已有可用副本的任务在后台同步期间直接运行。
Robert0622
left a comment
There was a problem hiding this comment.
在 Apple Silicon Mac 上从 a62c888 重新构建并部署了平台和 Runner。上轮的 0644 问题已修复。将 Linux helper 版本检查延迟 12 秒,使用当前版和上一版 ELF 的首个 Docker 工作流分别在 1.1 秒和 0.8 秒内完成,Git 凭据读取和 stdio MCP 调用都通过。iOA CodeBuddy 的两轮 Docker 会话也通过。
还有一处原地升级后的首任务失败,见行内评论。
| default: | ||
| } | ||
| // A workspace copy gets its own executable permissions. | ||
| if validateDockerRunnerHelper(path, false) == nil { |
There was a problem hiding this comment.
[P2] 启动时应能复用安装器已接受的脚本 helper
在 Mac 上从 d584b3f 原地升级到 a62c888,保持平台自动更新开启,把 AGENTFLOW_RUNNER_BINARY 指向预置的 #!/bin/sh 包装脚本。脚本会调用 Docker 镜像内同版本的 Linux Runner。升级时仅 Linux helper 下载返回 503,bind-cli --upgrade 接受已有脚本、保存新路径并成功退出。
重启后,我将版本检查延迟 12 秒再返回 200。此处只接受 ELF,首个工作流在 5.3 秒报 Docker Git/MCP helper is still syncing。另一轮让版本检查返回 503,确认脚本内容和权限都没变,重跑同一个工作流只用 1.4 秒就完成了 Git 凭据读取和 stdio MCP 调用。
建议让启动时的本地可用性判断与 bind-cli.sh 的 is_usable_docker_runner_helper 一致。对平台下载的文件继续做 ELF 校验,并补一个版本检查仍在进行时使用已有脚本的回归测试。
Robert0622
left a comment
There was a problem hiding this comment.
已在 Apple Silicon Mac 上重新构建并部署 552cae2,通过平台安装脚本原地升级 Runner。上轮报告的脚本 helper 启动超时已修复。
- 将 Linux helper 版本查询延迟 12 秒再返回 200 或 503,首个 Docker 工作流分别在 1.1 秒和 1.8 秒内完成。两轮都实际读取了 Git 凭据并调用了 stdio MCP 工具。返回 503 后,原脚本的哈希和权限保持一致。
- 主机上权限为
0644的脚本、当前版和上一版 ELF 均可在同步期间使用。缺失、架构不匹配或截断的 helper 在下载到有效文件后恢复。 - launchd 和 Rosetta 的安装、升级及故障恢复通过。iOA CodeBuddy 在 Docker 中完成了两轮真实对话,第二轮诊断确认续接了原会话。
GitHub 上的 16 项检查均已通过。
What changed
A macOS Runner needs a Linux executable for Git credentials and MCP calls inside Docker. The missing companion could let a conversation open a workspace and then fail before the CLI resumed.
Scope
Compatibility
Existing macOS installations receive the helper when upgraded. Intel and Apple Silicon use the artifact matching their architecture.
Validation
go test -race, plusgo vet ./deploy ./internal/runner ./internal/runtimeandpython3 scripts/check-public.py.maininstaller, and the remaining installer tests passed.Safety