在Jenkins构建Fluentd镜像时遇Gem::FilePermissionError权限错误求助

问题现象 #

在Jenkins中构建基于fluent/fluentd:v1.14.6-1.1的镜像时，执行gem install命令触发权限错误：

While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /usr/lib/ruby/gems/3.1.0 directory.
[0m[91m /usr/lib/ruby/3.1.0/rubygems/installer.rb:712:in `verify_gem_home'
    /usr/lib/ruby/3.1.0/rubygems/installer.rb:902:in `pre_install_checks'
    /usr/lib/ruby/3.1.0/rubygems/installer.rb:302:in `install'
    /usr/lib/ruby/3.1.0/rubygems/resolver/specification.rb:104:in `install'
    /usr/lib/ruby/3.1.0/rubygems/request_set.rb:194:in `block in install'
    /usr/lib/ruby/3.1.0/rubygems/request_set.rb:182:in `each'
    /usr/lib/ruby/3.1.0/rubygems/request_set.rb:182:in `install'
    /usr/lib/ruby/3.1.0/rubygems/commands/install_command.rb:210:in `install_gem'
    /usr/lib/ruby/3.1.0/rubygems/commands/install_command.rb:226:in `block in install_gems'
    /usr/lib/ruby/3.1.0/rubygems/commands/install_command.rb:219:in `each'
    /usr/lib/ruby/3.1.0/rubygems/commands/install_command.rb:219:in `install_gems'
    /usr/lib/ruby/3.1.0/rubygems/commands/install_command.rb:167:in `execute'
    /usr/lib/ruby/3.1.0/rubygems/command.rb:323:in `invoke_with_build_args'
    /usr/lib/ruby/3.1.0/rubygems/command_manager.rb:185:in `process_args'
    /usr/lib/ruby/3.1.0/rubygems/command_manager.rb:149:in `run'
    /usr/lib/ruby/3.1.0/rubygems/gem_runner.rb:51:in `run'
    /usr/bin/gem:21:in `<main>'

环境说明 #

• 基础镜像：fluent/fluentd:v1.14.6-1.1（基于Alpine 3.16）
• Docker版本：20.10.22（本地构建正常，Jenkins构建报错）
• 已确认构建阶段以root用户运行，目标目录/usr/lib/ruby/gems/3.1.0具备读写执行权限

使用的Dockerfile #

FROM fluent/fluentd:v1.14.6-1.1
USER root
RUN apk add --no-cache \
    ca-certificates

COPY cert.cer /usr/local/share/ca-certificates/
RUN update-ca-certificates

RUN apk add --update --virtual .build-deps \
        build-base ruby-dev
RUN apk add --update mariadb-dev

COPY cert.cer /usr/lib/ruby/3.1.0/rubygems/ssl_certs/cert.cer
RUN gem install  fluent-plugin-sql --no-document
RUN gem install  mysql2
RUN gem install  bigdecimal
RUN gem install elasticsearch -v 7.17.0
RUN gem install  --minimal-deps fluent-plugin-elasticsearch
RUN gem source --clear-all
RUN apk del .build-deps
USER fluent

解决方案 #

1. 自定义Gem安装目录 #

默认Gem尝试写入系统目录/usr/lib/ruby/gems/3.1.0，即使root用户也可能因镜像内部Ruby环境配置触发权限问题。可指定Gem安装到fluent用户的个人目录，修改后的Dockerfile如下：

FROM fluent/fluentd:v1.14.6-1.1
USER root
RUN apk add --no-cache \
    ca-certificates

COPY cert.cer /usr/local/share/ca-certificates/
RUN update-ca-certificates

# 配置Gem安装到用户专属目录
ENV GEM_HOME /home/fluent/.gem
ENV PATH $GEM_HOME/bin:$PATH

RUN apk add --update --virtual .build-deps \
        build-base ruby-dev mariadb-dev

COPY cert.cer /usr/lib/ruby/3.1.0/rubygems/ssl_certs/cert.cer
# 合并gem install命令减少镜像层，同时完成权限配置
RUN gem install fluent-plugin-sql --no-document \
    && gem install mysql2 \
    && gem install bigdecimal \
    && gem install elasticsearch -v 7.17.0 \
    && gem install --minimal-deps fluent-plugin-elasticsearch \
    && gem source --clear-all \
    && apk del .build-deps \
    && chown -R fluent:fluent $GEM_HOME

USER fluent

2. 排查Jenkins Docker构建环境 #

本地构建正常但Jenkins失败，需检查以下点：

• Jenkins代理的Docker用户组权限配置，确认运行Docker命令的用户具备足够权限
• 是否启用Docker用户命名空间隔离，导致容器内root权限被映射为宿主机普通用户，无法写入系统目录
• Jenkins构建任务是否额外添加--user参数强制切换用户，干扰容器内权限逻辑

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