Windows Server 2022下TeamCity构建代理Docker兼容性问题排查

核心前提 #

Docker必须安装在运行TeamCity构建代理的主机上，而非TeamCity服务器。你的问题本质是代理主机未正确配置Docker环境，且当前Docker版本格式不被TeamCity识别。

分步解决 #

1. 获得代理主机的RDP访问权限 #

Windows安装程序部署的TeamCity代理默认以Local System账户运行，无法直接通过RDP登录。解决方式二选一：

• 修改代理服务运行账户：
  1. 在代理主机上（物理访问或通过其他管理方式登录）打开「服务」，找到TeamCity Build Agent服务。
  2. 右键选择「属性」→「登录」选项卡，切换为具备RDP权限的本地管理员账户，输入凭据后重启服务。
• 用PsExec工具登录Local System账户：
  1. 在可访问代理主机的机器上下载PsExec，执行命令：

     psexec \\<代理主机IP> -s cmd.exe
     

  2. 在弹出的命令行中启动远程桌面：

     mstsc /admin
     

     即可以Local System身份打开RDP会话。

2. 在代理主机安装兼容的Docker版本 #

日志显示当前Docker版本为master-dockerproject-2022-03-26，属于自定义开发版，版本格式不符合TeamCity的解析规则。需安装官方稳定版：

• 卸载现有Docker，下载Windows Server版Docker的稳定通道安装包（避免使用Edge或自定义编译版本）。
• 安装完成后验证版本输出格式：执行docker --version，需返回类似如下的标准格式：

  Docker version 24.0.6, build ed223bc
  

3. 确保代理服务账户拥有Docker访问权限 #

• 如果代理用Local System账户运行：打开Docker Desktop设置→「Resources」→「File Sharing」，确认已授权系统账户访问；或在命令行执行：

  net localgroup docker-users "NT AUTHORITY\SYSTEM" /add
  

• 如果用自定义账户运行：将该账户加入docker-users本地组，重启Docker服务和TeamCity代理服务。

4. 验证系统级PATH配置 #

代理服务使用的是系统环境变量PATH，而非用户级PATH：

1. 在代理主机上打开「系统属性」→「高级」→「环境变量」，在「系统变量」中确认PATH包含C:\Program Files\Docker。
2. 重启TeamCity Build Agent服务，让新的PATH生效。

5. 验证代理的Docker检测 #

在代理主机上，以代理服务运行的账户执行以下命令，确保能正常执行：

docker --version
docker info

如果命令能正常输出，TeamCity代理就能检测到Docker，docker.version和docker.server.version的需求就能满足。

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