fix: docker images build

Author: soulteary

Dockerfile.runner

@@ -1,4 +1,5 @@
 # Runner 容器镜像（容器模式用）：仅包含 Agent + Runner 运行依赖，Runner 目录由 Manager 挂载到 /runner
+# Agent 二进制必须放在非 /runner 路径（如 /app/runner-agent），否则挂载 -v host_path:/runner 会覆盖镜像内 /runner，导致入口程序丢失
 # 使用 BUILDPLATFORM 在宿主机(amd64)上构建，TARGETOS/TARGETARCH 交叉编译，避免 QEMU 下 go build 失败
 ARG BUILDPLATFORM=linux/amd64
 FROM --platform=$BUILDPLATFORM golang:1.26-bookworm AS builder
@@ -34,9 +35,13 @@ RUN install -m 0755 -d /etc/apt/keyrings \
 
 RUN groupadd -g 1001 app && useradd -r -u 1001 -g app -d /runner -s /bin/bash app
 
+# Agent 放在 /app，避免被 -v mountSrc:/runner 挂载覆盖导致 exec 找不到入口
+RUN install -m 0755 -d /app
+COPY --from=builder /app/runner-agent /app/runner-agent
+RUN chown app:app /app/runner-agent
+
 WORKDIR /runner
-COPY --from=builder /app/runner-agent /runner/runner-agent
-RUN chown -R app:app /runner
+RUN chown app:app /runner
 
 ENV RUNNER_INSTALL_DIR=/runner
 ENV AGENT_PORT=8081
@@ -45,4 +50,4 @@ USER app
 EXPOSE 8081
 HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
     CMD curl -fsS http://127.0.0.1:8081/health || exit 1
-ENTRYPOINT ["/runner/runner-agent"]
+ENTRYPOINT ["/app/runner-agent"]

docs/docker.md

@@ -143,7 +143,7 @@ docker run -d --name runner-manager \
 ### 机制简述
 
 - **Manager**：通过宿主机 Docker（挂载 `docker.sock`）创建/启停 Runner 容器，并与 Runner 容器处于同一网络，通过 HTTP 访问容器内 **Agent** 获取 Runner 进程状态。
-- **Runner 容器**：基于 `Dockerfile.runner` 构建的镜像，内含 **Runner Agent**（提供 `/status`、`/start`、`/stop`）和 Runner 运行依赖；Runner 安装目录由 Manager 挂载到容器内 `/runner`。
+- **Runner 容器**：基于 `Dockerfile.runner` 构建的镜像，内含 **Runner Agent**（提供 `/status`、`/start`、`/stop`）和 Runner 运行依赖；Agent 入口为 `/app/runner-agent`（故意不在 `/runner` 下，避免挂载 `-v host_path:/runner` 时覆盖入口）。Runner 安装目录由 Manager 挂载到容器内 `/runner`。
 - **启停**：点击「启动」时 Manager 执行 `docker create`（若不存在）+ `docker start`，并请求 Agent 的 `POST /start` 启动 Runner 进程；「停止」时 `docker stop` 该容器。
 
 ### 配置与构建
@@ -167,6 +167,8 @@ docker run -d --name runner-manager \
    docker build -f Dockerfile.runner -t ghcr.io/soulteary/runner-fleet-runner:main .
    ```
 
+   若曾用旧版镜像创建过 Runner 容器且出现 `stat /runner/runner-agent: no such file or directory`，需先删除该容器（如 `docker rm -f github-runner-<名称>`），再在界面点击「启动」由 Manager 用新镜像重新创建。
+
 3. **部署要求**：
    - **Manager 必须使用宿主机 Docker**（`unix:///var/run/docker.sock`）创建/启停 Runner 容器，**不能**把 `DOCKER_HOST` 设为 DinD（`tcp://runner-dind:2375`）。DinD 仅供 **Runner 容器内** Job 的 `docker build` 等使用；若在 `.env` 中设置了 `DOCKER_HOST=tcp://runner-dind:2375`，点击「启动」会报错，请移除或注释该行。宿主机需挂载 `docker.sock` 并设置 `DOCKER_HOST=unix:///var/run/docker.sock`（仓库内 `docker-compose.yml` 默认已配置）。Manager 以非 root（UID 1001）运行，访问 socket 需加入宿主机 **docker 组**：`group_add: [ "${DOCKER_GID:-999}" ]`，GID 不对时在 `.env` 设 `DOCKER_GID=`；或改为 `user: "0:0"` 以 root 运行。
    - Runner 容器与 Manager、DinD 在同一网络（如 `runner-net`），以便 Manager 访问 Agent、Runner Job 内访问 DinD。