自托管Linux Runner中Docker-in-Docker功能无法正常使用求助

架构老林

2026-8-13

Bitbucket自托管Linux Runner无法执行Docker命令：bash: docker: command not found

问题描述

Bitbucket Pipelines中，官方托管Runner执行docker version正常，但切换到自托管Linux Runner时，出现bash: docker: command not found错误。相关Pipelines配置如下：

pipelines:
  branches:
    'master':
      - step:
          name: 'step1'
          script:
            - docker version # 此步骤在官方Runner中正常运行
          services:
            - docker
      - step:
          name: 'step2'
          runs-on:
            - self.hosted
            - linux
          script:
            - docker version # 此步骤在自托管Runner中失败
          services:
            - docker

解决步骤

自托管Runner与官方Runner的核心区别是：官方Runner是Atlassian预制的标准化环境，默认预装Docker组件；而自托管Runner依赖你自行维护的主机环境，需手动确保Docker相关组件正常可用。

检查自托管主机的Docker安装状态
直接在自托管Runner所在的Linux机器上执行docker version，若同样报错，说明主机未安装Docker。根据主机的Linux发行版（如Ubuntu、CentOS），按照官方文档完成Docker引擎和CLI的安装。
确认Docker CLI在Runner的环境PATH中
执行which docker找到Docker可执行文件路径（通常为/usr/bin/docker），确保Runner运行用户的环境变量PATH包含该路径。若路径未加入，可通过修改用户的~/.bashrc或~/.profile文件添加，之后重启Runner服务。
配置Runner用户的Docker权限
运行Docker命令需要用户具备docker组权限，执行以下命令将Runner运行用户加入docker组：
```
sudo usermod -aG docker $USER
```
完成后重启Runner服务，让权限变更生效。
放弃对services: [docker]的依赖
Pipelines的services: [docker]在官方Runner中是启动Docker-in-Docker容器，但自托管Runner不会自动处理该配置。你需要确保主机本身的Docker守护进程处于运行状态，直接使用主机的Docker环境即可。