Skip to content

feat: 支持开发板锁在 Cancel 时自动释放并补充使用文档#13

Open
yoinspiration wants to merge 7 commits intoarceos-hypervisor:mainfrom
yoinspiration:feat/board-lock-watcher
Open

feat: 支持开发板锁在 Cancel 时自动释放并补充使用文档#13
yoinspiration wants to merge 7 commits intoarceos-hypervisor:mainfrom
yoinspiration:feat/board-lock-watcher

Conversation

@yoinspiration
Copy link
Contributor

@yoinspiration yoinspiration commented Mar 4, 2026

背景

当前多组织共享同一块开发板时,通过文件锁保证同一板卡上的 Job 串行执行。但一旦某个正在持锁的 workflow 被手动 Cancel,可能遗留“幽灵锁”,导致后续等待同一板卡的 Job 长时间卡在 Waiting for lock,Cancel 也无法真正打断等待。

Fixes #12

变更内容

  • 新增锁监控脚本

    • 新增 runner-wrapper/lock-watcher.sh,在宿主机周期性检查指定仓库下的 Actions Run 状态:
      • ${RESOURCE_ID}.holder 读取当前持锁 run_id。
      • 调用 GitHub API 读取对应 run 的 statusconclusion
      • 当检测到 status=completed && conclusion=cancelled 时,强制清理 ${RESOURCE_ID}.holder 及相关 .release 文件,释放板卡文件锁。
    • 使用 Fine-grained PAT(Actions: Read-only)进行只读访问,最小化权限。
  • 补充使用文档

    • 新增 docs/board-lock-watcher.md
      • 说明 Runner 端 .env 如何启用 board 级文件锁。
      • 说明在宿主机如何配置 .env.watcher、安装 jq 并启动 lock-watcher.sh
      • 给出多组织共享同一块板卡的完整验证流程。
      • 明确“默认每个参与共享同一块板卡的仓库各启动一个 watcher 实例”的推荐用法。
    • docs/多组织共享Runner使用说明.md 中补充:只有设置了 RUNNER_RESOURCE_ID_PHYTIUMPI / RUNNER_RESOURCE_ID_ROC_RK3568_PC 的板子才会启用 runner-wrapper 与锁目录挂载,未配置的板子仍使用默认 run.sh,不参与锁协调。

行为效果

  • 多组织共享同一块板卡时:
    • 正常情况下仍通过 pre-job-lock.sh / post-job-lock.sh 实现按 Job 串行访问。
    • 当持锁的 workflow 被 Cancel 时,watcher 能在检测到 run 变为 completed + cancelled 后主动清理解锁文件,避免后续等待 Job 永久阻塞。
  • 对未启用板卡锁机制的 runner 行为无影响。

使用与部署建议

  • 对每个参与共享同一块板卡的仓库,各配置一份 .env.watcher 并启动一个对应的 lock-watcher.sh 实例。
  • 建议基于 systemd / tmux 等方式将 watcher 以守护进程方式常驻在宿主机上。

Introduce lock-watcher helper and docs so cancelled workflows can safely release board file locks across organizations.

Made-with: Cursor
@ZCShou
Copy link
Contributor

ZCShou commented Mar 6, 2026

是否可以直接与 runner.sh 集合起来简化使用,与锁一样,做成使用无感的

@yoinspiration yoinspiration changed the title feat: 支持开发板锁在 Cancel 时自动释放并补充使用文档(fix #12) feat: 支持开发板锁在 Cancel 时自动释放并补充使用文档 Mar 6, 2026
- runner.sh 新增 watcher 子命令,复用 .env,需 RUNNER_LOCK_MONITOR_TOKEN
- 使用说明:部署流程概览、tmux/screen/systemd 常驻、宿主机锁目录权限(2.1)

Made-with: Cursor
@yoinspiration yoinspiration force-pushed the feat/board-lock-watcher branch from 9c6147a to c8c9cc6 Compare March 6, 2026 03:00
- runner.sh watcher 不传参时导出 RUNNER_RESOURCE_IDS(roc + phytiumpi),传参仍为单板
- lock-watcher.sh 支持 RUNNER_RESOURCE_IDS 空格分隔多资源,每轮循环检查所有板子
- 文档改为推荐每组织一个 watcher 监控所有板子;移除 .env.watcher 及方式二说明

Made-with: Cursor
- compose 生成时若配置 RUNNER_LOCK_MONITOR_TOKEN 则加入 lock-watcher 服务(alpine + jq)
- start/stop/restart 无参时操作所有服务(含 watcher),与锁使用无感
- 文档更新:watcher 随 start 自动启动,无需 tmux/systemd

Made-with: Cursor
@yoinspiration
Copy link
Contributor Author

已按这个建议在本 PR 里实现:
现在在 .env 配好 RUNNER_LOCK_MONITOR_TOKEN 后,./runner.sh compose 生成的 compose 会自动包含一个 lock-watcher 服务,./runner.sh start/stop/restart 无参时会对所有服务执行操作,所以 watcher 会和板子 runners 一起启停,使用体验和锁一样是“无感”的。
如有特殊场景(比如只在另一台机上跑 watcher),还是可以用 ENV_FILE=.env.xxx ./runner.sh watcher 手动起一个单独的 watcher 进程。

@Josen-B
Copy link
Contributor

Josen-B commented Mar 16, 2026

LGTM

Document pre-job lock permission failure recovery in both READMEs and update .env.example to recommend a persistent host lock path under /var/tmp while keeping the container lock path unchanged.

Made-with: Cursor
- Dockerfile: 安装 cmake/clang/libclang-dev,软链 libclang.so 供 bindgen
- pre-job-lock: 创建锁目录失败或不可写时立即退出并提示修复

Made-with: Cursor
- 新增 docs/多组织部署指南.md,README 指向完整文档
- pre-job-lock: flock 阻塞时每 10s 输出等待进度;chmod 静默失败避免噪声

Made-with: Cursor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bug] file lock

3 participants