文档/构建 Runner

构建 Runner#

luma builder 管理独立的 luma-build 队列,luma runner 负责当前机器上的加入与进程管理。Runner 需要 Docker、Buildx 和 Git,无需 Nomad 或 luma node join。Linux 使用 systemd,macOS 使用系统级 launchd 服务,并保留执行命令用户的 Docker 环境。

Control 的 创建应用 → Git 仓库 表单向同一个队列提交,并在原页面跟随构建日志,无需选择集群构建节点或配置内部 Registry。Control 自动读取 luma-build 应用的公网域名(Compose 为 server 服务);Builder 部署在其他地方时,在 Control 设置 LUMA_BUILD_URL。Builder 仍需配置目标镜像仓库(例如 ACR)、Git 凭据和 Control 部署目标。

加入并启动#

在已执行 luma login 的操作员机器上,luma builder 会自动从当前 Control 登录上下文发现 Builder 地址(仅在需要覆盖或连接独立部署的 Builder 时运行 luma builder use),然后创建 runner token:

luma builder use https://build.example.com
luma builder token create my-runner --cache-mode read-write

在实际执行构建的机器上运行:

luma runner join --url https://build.example.com --token lbr_xxx
luma runner status
luma runner logs --follow

Join 先补齐并检查构建工具、验证 Docker 引擎和 token,再预热 BuildKit,不会领取排队中的构建任务。通过后才保存配置并默认启动后台服务。关闭 SSH 或终端后进程继续运行,开机自动启动,异常退出自动重启。安装和管理系统服务时,系统可能要求输入 sudo 密码。macOS 上仍需 OrbStack 或 Docker Desktop 引擎运行,因此可能需要用户先登录系统。

可以用 --token-stdin 从标准输入读取 token,或使用环境变量 LUMA_RUNNER_TOKEN。服务将其保存在 /opt/luma/runner/config.json,只允许 runner 的系统用户和 root 读取;系统服务命令中只有配置路径,不包含 token。首次 join 保存执行命令用户的 home、Docker context 和代理设置;同一用户重新 join 会刷新环境变量,start/restart 复用已保存环境。BuildKit 元数据默认保存在 ~/.luma-runner,可用 --state-dir 修改。

构建依赖与网络预检#

luma runner join 和 luma node join 都会在 apt 系 Linux 上补齐 Git/Buildx,并在实际构建使用的私有 Docker 配置中验证。新 Linux runner 缺少 Docker 时会安装引擎;仅补装 Buildx 时不替换或重启已有引擎。Docker CE 使用 docker-buildx-plugin,Ubuntu/Debian Docker 使用 docker-buildx。

macOS 先启动 OrbStack 或 Docker Desktop,再以拥有 Docker/Homebrew 的用户执行 join。缺少 Git/Buildx 时使用原生 Homebrew 安装:Apple Silicon(包括 Rosetta 终端)使用 /opt/homebrew,Intel 使用 /usr/local。构建平台仍以实际 Docker 引擎为准,保留原生 ARM 限制。

加入时会启动实际使用的持久 BuildKit 实例,并使用 # syntax=docker/dockerfile:1 和 FROM scratch 执行仅保留缓存的预检,在报告成功前准备好 BuildKit 镜像与 Dockerfile 前端,不构建或发布业务镜像。前台 runner 每次启动后、领取任务前也会执行工具检查和 BuildKit 预检。预检失败保留已有 runner 服务配置;node 的 BuildKit 准备失败会回滚注册。

Docker 有两条网络路径:Docker daemon 拉取 BuildKit 容器镜像,BuildKit 自己拉取 Dockerfile 前端和基础镜像。daemon 的代理不会自动传入 BuildKit。受限网络使用节点可达的 HTTP 代理:luma runner join --proxy http://proxy-host:7890;会复用已有 token 和参数,重新加入前等待当前构建结束。node join 使用 Control 返回的区域出口代理。若 BuildKit 容器镜像拉取失败,需先配置 daemon 的镜像拉取通路;join 会当场报错。具体业务基础镜像和依赖仍在对应构建时解析。

BuildKit 还支持按需启用的 docker.io 镜像加速(不内置硬编码第三方镜像站):

所有已配置的镜像站主机名会自动加入 BuildKit 的 NO_PROXY 列表,即使 Runner 配置了 HTTP 代理,访问镜像站时也会直连而不绕经代理。

日常命令#

luma runner stop
luma runner start
luma runner restart
luma runner status --format json
luma runner logs --lines 100
luma builder token list

stop 停止本机服务并关闭开机自启,保留配置;start 复用配置启动并恢复开机自启;restart 重启进程。空闲长轮询会在 stop/restart 时中断,无需等待服务端的 15 秒长轮询返回。每台机器管理一份 runner 服务,重复 join 更新这份服务,不会新增另一份。构建期间 stop/restart 会取消本机构建;不希望中断时先等待构建结束。

macOS 服务日志写入 /opt/luma/runner/logs/runner.log,按 10 MiB 轮转,保留 5 份备份;Linux 使用 journald。luma runner logs --follow 可跨日志轮转继续跟随。

runner status 查看的是本机服务,builder token list 查看的是服务端观察到的心跳,在线阈值为 90 秒。服务进程运行不等于网络、认证正常,需要结合日志和远端列表判断。luma runner run 明确表示调试或容器使用的前台运行;旧命令 luma builder runner 保留为前台兼容入口。

恢复启动失败的 Linux 服务#

Luma 0.2.81 修复了旧版 Runner 服务生成的 WorkingDirectory 引号。如果 systemd 报 WorkingDirectory= path is not absolute,先升级该 Runner 机器的 CLI,再执行 luma runner start;它会重写服务定义,保留已保存的 token 和参数。命令从哪个目录执行不影响结果。Linux 日志通过 journald 读取(luma runner logs),不使用 macOS 日志文件路径。服务命令失败时会显示具体操作和脱敏后的诊断。

迁移已加入的 Runner#

原有注册记录和名称继续有效。先升级 runner 机器上的 Luma CLI,并部署新版 builder 服务;对旧前台命令按 Ctrl-C(或停止旧 Docker 容器),再用原 token 执行 luma runner join。无需新建另一个名称。手动安装的 luma-build-runner.service 会在验证成功后替换为 CLI 管理的服务。

如果原 token 丢失,在操作员机器上按原名称轮换:

luma builder token create my-runner --rotate

然后在该 runner 机器上用新 token 执行 luma runner join。轮换保留名称和 ID,旧 token 立即失效。有自定义权重、并发数和缓存策略时,轮换命令需同时传入这些参数。旧进程需升级到本次 runner 版本,才能在旧 token 被拒绝后自动退出。

删除 Runner#

在 builder 控制台点击删除,或运行:

luma builder token delete my-runner

删除会把注册记录和 token 从列表移除,同时取消正在该 runner 上构建的任务,以及明确固定给它的排队任务。已完成的构建历史保留,已构建完成、等待部署的镜像继续走部署队列。新版 builder 启动时会清理历史已吊销记录。旧 token revoke 命令和 API 保留为删除兼容别名,不再产生吊销记录。

新版 runner 收到 HTTP 401/403 认证拒绝后,会取消本地工作并正常退出,systemd、launchd 和本文的 Docker 重启策略不会反复拉起它。网络超时和 HTTP 5xx 仍会重试。删除后需要重新接入时,创建新 token 再 join。删除不会清理机器上的 BuildKit 缓存,也不会卸载 Luma。

缓存与容器#

家庭 Mac 上传带宽较小时,可使用只读远端缓存:

luma runner join --url https://build.example.com --token lbr_xxx --cache-mode read-only --cache-keep-gb 25

独立 builder 的缓存亲和等待默认 3 秒(LUMA_BUILD_AFFINITY_SECONDS),与 Control 自身的构建调度不同。本地 BuildKit 缓存默认 20 GiB。--workers 控制本机工作槽位,token 的 --concurrency 限制服务端派发并发数。

Linux 也可以用独立 runner 镜像,以容器方式运行:

docker run -d --name luma-runner --restart=on-failure --network=host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v luma-runner-state:/var/lib/luma-runner \
  -e LUMA_BUILD_URL=https://build.example.com \
  -e LUMA_RUNNER_TOKEN=lbr_xxx \
  ghcr.io/liutianjie/luma-build-runner:v0.2.76

Docker 的 on-failure 策略不会在 Docker 引擎或主机重启后自动启动容器。需要主机开机自启时使用 luma runner join。如果要求删除后进程保持停止,不要使用 --restart=always。

升级顺序#

Luma/Control 与独立 builder 分别发版。先升级控制面和 Luma CLI,再部署对应 builder 版本,最后迁移或重启 runner 进程。runner join 依赖 builder 的 /v1/runner/join 接口,旧服务会收到明确的升级提示。单独升级 Control 不会部署 builder,也不会重启独立 runner。见发版指南与 builder 部署文件。