TeamCity代理Docker运行时，如何以非root用户执行镜像内构建步骤？

这种 Docker 组 GID 不匹配导致的权限问题很常见，核心原因是 TeamCity Agent 需要访问主机的 Docker Socket（/var/run/docker.sock），而该 Socket 默认归 docker 组所有。当主机和 Agent 镜像内的 docker 组 GID 不一致时，容器内的非 root 用户（比如 node:lts 镜像默认的 node 用户）没有权限访问 Socket，就会触发 docker.server.osType 相关的检查失败。

下面是几种无需以 root 身份运行 Agent 的安全解决方案：

方案1：构建 Agent 镜像时同步主机 Docker 组 GID #

在构建自定义 TeamCity Agent 镜像时，直接将镜像内的 docker 组 GID 改为与主机一致：

# 基于 node:lts 构建自定义 Agent 镜像
FROM node:lts

# 接收主机 Docker 组 GID 作为构建参数，默认值设为镜像原有 GID 999
ARG DOCKER_GID=999

# 删除原有 docker 组，用主机 GID 重建并将 node 用户加入
RUN groupdel docker && groupadd -g $DOCKER_GID docker
RUN usermod -aG docker node

# 后续添加 TeamCity Agent 的安装配置...

构建镜像时自动获取主机 Docker 组 GID 并传入：

docker build --build-arg DOCKER_GID=$(getent group docker | cut -d: -f3) -t custom-teamcity-agent .

方案2：启动容器时动态映射主机 Docker 组 #

无需修改镜像，启动 Agent 容器时直接让容器内的 node 用户加入主机的 docker 组：

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e TEAMCITY_SERVER_URL=http://your-teamcity-server:8111 \
  --user node:$(getent group docker | cut -d: -f3) \
  custom-teamcity-agent

这条命令会让容器内的 node 用户同时属于原有用户组和主机的 docker 组，从而获得 Docker Socket 的访问权限。

方案3：调整主机 Docker 组 GID 匹配镜像（不推荐） #

如果主机是专门用于 TeamCity 构建的测试环境，可以修改主机的 docker 组 GID 为镜像内的 999：

# 先移除所有用户从原 docker 组
for user in $(getent group docker | cut -d: -f4 | tr ',' ' '); do
  gpasswd -d $user docker
done
# 删除原 docker 组
groupdel docker
# 新建 GID 为 999 的 docker 组
groupadd -g 999 docker
# 将需要的用户（比如当前用户）重新加入
gpasswd -a $USER docker
# 重启 Docker 服务生效
systemctl restart docker

此方案可能影响主机上其他依赖 docker 组的应用，仅在特殊场景下使用。

优先选择方案1或2，既能解决权限问题，又能避免以 root 身份运行容器带来的安全风险。

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