TeamCity Agent连接Docker守护进程套接字时权限被拒绝

问题背景 #

通过docker-compose部署TeamCity Server和Agent，执行推送Docker镜像到Azure容器注册表的构建步骤时，Agent触发权限拒绝错误：

Cannot login to registry xxx.azurecr.io
An error occurred while executing 'docker login -u "TeamCity" --password-stdin xxx.azurecr.io':
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/auth": dial unix /var/run/docker.sock: connect: permission denied

已确认buildagent用户在容器内的docker组中，尝试添加teamcity.docker.use.sudo=true后，Agent无法被识别为具备Docker环境的可用Agent。

解决方案 #

方案1：调整Agent容器用户的GID匹配主机Docker组 #

Windows Docker Desktop的/var/run/docker.sock所属组GID与WSL环境中的docker组一致，需让容器内buildagent用户的GID与该组匹配：

1. 在Windows的WSL终端（或Docker Desktop内置终端）执行命令，获取主机docker组的GID：

   getent group docker | cut -d: -f3
   

   假设返回结果为1001
2. 修改docker-compose.yml的agent服务，添加user参数指定UID:GID（buildagent默认UID为1000）：

   agent:
     image: jetbrains/teamcity-agent:latest
     environment:
       - SERVER_URL=http://server:8111
     volumes:
       - C:\TeamCity\agent\conf:/data/teamcity_agent/conf
       - C:\TeamCity\agent\logs:/opt/buildagent/logs
       - /var/run/docker.sock:/var/run/docker.sock
     user: "1000:1001" # 替换为你查到的GID
   

3. 重启Agent容器：docker-compose up -d agent

方案2：修改容器内Docker组的GID匹配主机 #

若无法调整用户GID，可直接修改容器内docker组的GID：

1. 按方案1步骤获取主机docker组的GID（比如1001）
2. 修改docker-compose.yml的agent服务，自定义entrypoint调整组GID：

   agent:
     image: jetbrains/teamcity-agent:latest
     environment:
       - SERVER_URL=http://server:8111
     volumes:
       - C:\TeamCity\agent\conf:/data/teamcity_agent/conf
       - C:\TeamCity\agent\logs:/opt/buildagent/logs
       - /var/run/docker.sock:/var/run/docker.sock
     entrypoint: >
       sh -c "groupmod -g 1001 docker && exec /run-services.sh" # 替换为你查到的GID
   

3. 重启Agent容器，此时容器内docker组GID与主机一致，buildagent用户即可正常访问socket

方案3：正确配置sudo执行Docker命令 #

若要使用sudo方式，需先给buildagent配置免密sudo权限，再启用TeamCity的sudo设置：

1. 进入运行中的Agent容器：

   docker exec -it <你的Agent容器名称> bash
   

2. 编辑sudoers文件（使用visudo避免语法错误）：

   visudo
   

3. 在文件末尾添加一行，允许buildagent免密执行docker命令：

   buildagent ALL=(ALL) NOPASSWD: /usr/bin/docker
   

4. 保存退出后，在Agent的conf/buildAgent.properties文件中添加：

   teamcity.docker.use.sudo=true
   

5. 重启Agent容器，此时TeamCity会用sudo执行Docker命令，且能正确识别Agent的Docker环境

额外检查 #

• 确保Docker Desktop的Settings -> Resources -> WSL Integration中已开启对应WSL发行版的集成，保证/var/run/docker.sock正常可用
• 重启Docker Desktop后再测试，避免缓存的权限问题

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