基于自定义Docker镜像的Jenkins Agent无法运行：容器未运行错误

可能原因及解决步骤： #

1. 镜像架构不兼容
   树莓派为ARM架构，若你在x86架构的Windows机器上构建自定义镜像并推送到DockerHub，拉取到树莓派后会因架构不匹配导致容器无法启动。

• 解决方式：
  • 在树莓派本地构建镜像：进入Dockerfile所在目录，执行 docker build -t your-custom-agent .。
  • 用Docker Buildx跨平台构建ARM版本：

    docker buildx create --use
    docker buildx build --platform linux/arm64 -t your-dockerhub-username/your-custom-agent:latest --push .
    

2. 检查Agent容器的启动日志
   先手动在树莓派上启动自定义镜像，确认容器本身能否正常运行：

docker run --rm -it your-custom-agent:latest bash

如果启动失败或报错，根据日志排查镜像问题（如依赖缺失、权限错误）；若能正常启动，再排查Jenkins侧的配置。

3. 验证Jenkins主节点的Docker访问权限
   Jenkins主节点通过socat连接Docker守护进程时，可能存在权限不足的问题：

• 确认Jenkins容器是否正确挂载Docker套接字：启动Jenkins容器时需添加参数 -v /var/run/docker.sock:/var/run/docker.sock。
• 检查socat的配置是否正确，确保Jenkins能正常调用Docker API创建并启动Agent容器。

4. 检查Jenkins Docker插件兼容性
   Docker相关插件（如Docker Plugin、Docker Cloud Plugin）的版本可能和官方Agent镜像存在兼容性问题：

• 进入Jenkins插件管理页面，将Docker相关插件更新到最新稳定版，或回退到与官方jenkins/agent:jdk11匹配的版本。

5. 排查自定义镜像的用户权限
   虽然Dockerfile仅设置了USER jenkins，但可能存在用户权限冲突：

• 尝试去掉USER jenkins指令，构建镜像后再次测试，看是否能正常启动Agent容器。
• 确认官方jenkins/agent:jdk11镜像中jenkins用户的UID/GID，在自定义镜像中保持一致，避免权限问题。

内容的提问来源于stack exchange，提问作者tomek19991999