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

.env.example

@@ -24,8 +24,10 @@ GH_PAT=
 # 多组织共享同一块板时显式设相同 ID：
 # RUNNER_RESOURCE_ID_PHYTIUMPI=board-phytiumpi
 # RUNNER_RESOURCE_ID_ROC_RK3568_PC=board-roc-rk3568-pc
+# 容器内路径，通常保持默认：
 # RUNNER_LOCK_DIR=/tmp/github-runner-locks
-# RUNNER_LOCK_HOST_PATH=/tmp/github-runner-locks
+# 宿主机路径，建议使用持久目录避免 /tmp 清理导致权限漂移：
+# RUNNER_LOCK_HOST_PATH=/var/tmp/github-runner-locks
 
 # ---------- 可选：注册 token 缓存 ----------
 # REG_TOKEN_CACHE_FILE=.reg_token.cache

Dockerfile

@@ -55,10 +55,20 @@ RUN apt-get update \
        python3-pip \
        python3-tomli \
        python3-sphinx \
+       cmake \
+       clang \
+       libclang-dev \
        ninja-build \
        libslirp0 \
     && rm -rf /var/lib/apt/lists/*
 
+# Ensure bindgen can find libclang.so in a stable location.
+RUN set -eux; \
+    libclang_path="$(ls -1 /usr/lib/llvm-*/lib/libclang.so 2>/dev/null | head -n1)"; \
+    if [ -n "${libclang_path}" ]; then \
+      ln -sf "${libclang_path}" /usr/lib/libclang.so; \
+    fi
+
 # Build and install QEMU 10.1.2 from source 
 RUN mkdir -p /tmp/qemu-build \
     && cd /tmp/qemu-build \

README.md

@@ -112,6 +112,48 @@ RUNNER_RESOURCE_ID_PHYTIUMPI=board-phytiumpi
 
 **Note**: Serialization is a hardware limitation. This approach transforms "chaotic contention" into "ordered queuing" without reducing throughput. Different boards using their own lock IDs can run in parallel.See [runner-wrapper/README.md](runner-wrapper/README.md) for details. Reference: [Discussion #341](https://github.com/orgs/arceos-hypervisor/discussions/341).
 
+### Troubleshooting: `Permission denied` in `pre-job-lock.sh`
+
+If job logs show errors like:
+
+- `chmod: changing permissions of '/tmp/github-runner-locks': Operation not permitted`
+- `/tmp/github-runner-locks/board-xxx.lock: Permission denied`
+
+the host lock directory permissions are usually incorrect, or the lock directory is placed under host `/tmp` and gets cleaned up by the system, causing permission drift.
+
+Recommended configuration (keep consistent across organizations):
+
+- `RUNNER_LOCK_HOST_PATH=/var/tmp/github-runner-locks` (persistent host directory)
+- `RUNNER_LOCK_DIR=/tmp/github-runner-locks` (container path, keep default)
+
+One-time fix:
+
+```bash
+# 1) Create host directory and set sticky-bit permissions (1777)
+sudo mkdir -p /var/tmp/github-runner-locks
+sudo chown root:root /var/tmp/github-runner-locks
+sudo chmod 1777 /var/tmp/github-runner-locks
+
+# 2) Update each org's .env
+# RUNNER_LOCK_HOST_PATH=/var/tmp/github-runner-locks
+# RUNNER_LOCK_DIR=/tmp/github-runner-locks
+
+# 3) Regenerate compose and recreate containers to apply mounts
+ENV_FILE=.env.<org1> ./runner.sh compose
+ENV_FILE=.env.<org1> ./runner.sh stop
+ENV_FILE=.env.<org1> ./runner.sh start
+```
+
+Verify:
+
+```bash
+ls -ld /var/tmp/github-runner-locks
+# expected: drwxrwxrwt
+
+docker inspect <runner-container-name> --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
+# expected to include: /var/tmp/github-runner-locks -> /tmp/github-runner-locks
+```
+
 ## Contributing
 
 ```bash

README_CN.md

@@ -79,6 +79,8 @@ name:label1[,label2];name2:label1
 
 ## 多组织共享
 
+> **完整文档**：参见 [docs/多组织部署指南.md](docs/多组织部署指南.md)，含部署方式、环境变量、故障排查等。
+
 当前脚本实现了在同一台主机上运行多个 Docker 容器，分别注册到不同的 GitHub 组织，即使这些容器需要访问同一物理硬件（如开发板、串口、电源控制等），也不会导致 CI 会导致资源冲突。
 
 ### 场景说明
@@ -112,6 +114,48 @@ RUNNER_RESOURCE_ID_PHYTIUMPI=board-phytiumpi
 
 **注意**：串行是硬件本身的限制，本方案把「无秩序抢占」变为「有序排队」，不额外降低吞吐。不同板子使用各自锁 ID 可并行执行。详见 [runner-wrapper/README.md](runner-wrapper/README.md)，参考 [Discussion #341](https://github.com/orgs/arceos-hypervisor/discussions/341)。
 
+### 常见问题：`pre-job-lock.sh` 报 `Permission denied`
+
+如果 Job 日志中出现类似报错：
+
+- `chmod: changing permissions of '/tmp/github-runner-locks': Operation not permitted`
+- `/tmp/github-runner-locks/board-xxx.lock: Permission denied`
+
+通常是宿主机锁目录权限不正确，或把锁目录放在宿主机 `/tmp` 后被系统清理导致权限漂移。
+
+推荐配置（多组织保持一致）：
+
+- `RUNNER_LOCK_HOST_PATH=/var/tmp/github-runner-locks`（宿主机持久目录）
+- `RUNNER_LOCK_DIR=/tmp/github-runner-locks`（容器内路径，保持默认）
+
+一次性修复步骤：
+
+```bash
+# 1) 在宿主机创建并设置目录权限（sticky bit 1777）
+sudo mkdir -p /var/tmp/github-runner-locks
+sudo chown root:root /var/tmp/github-runner-locks
+sudo chmod 1777 /var/tmp/github-runner-locks
+
+# 2) 修改每个组织对应 .env
+# RUNNER_LOCK_HOST_PATH=/var/tmp/github-runner-locks
+# RUNNER_LOCK_DIR=/tmp/github-runner-locks
+
+# 3) 重新生成 compose，并重建容器使挂载生效
+ENV_FILE=.env.<org1> ./runner.sh compose
+ENV_FILE=.env.<org1> ./runner.sh stop
+ENV_FILE=.env.<org1> ./runner.sh start
+```
+
+验证：
+
+```bash
+ls -ld /var/tmp/github-runner-locks
+# 期望：drwxrwxrwt
+
+docker inspect <runner-container-name> --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
+# 期望包含：/var/tmp/github-runner-locks -> /tmp/github-runner-locks
+```
+
 ## 贡献
 
 ```bash