如何为GitLab Runner的Docker执行器配置音频输入/输出权限

问题场景 #

将硬件连接到作为PC的GitLab Runner（采用Docker执行器），运行需收发音频信号的硬件自动化测试。本地测试正常，但GitLab Runner环境中无法播放/接收音频，推测是Docker容器缺少音频权限配置。

可复现的CI配置 #

stages:
  - test

test_audio_playback:
  image: ubuntu:latest
  stage: test
  before_script:
    - apt-get update
    - apt-get install -y pulseaudio-utils pulseaudio dbus-x11 sudo alsa-utils
    - useradd -m pulseuser
    - mkdir -p /run/user/1000/pulse
    - chown pulseuser:pulseuser /run/user/1000/pulse
    - export PULSE_SERVER=unix:/run/user/1000/pulse/native
    - ln -s /run/user/1000/pulse /tmp/pulse
  script:
    - sudo -u pulseuser pulseaudio --start --exit-idle-time=-1
    - ls /usr/share/sounds/alsa/
    - sudo -u pulseuser paplay /usr/share/sounds/alsa/Front_Center.wav

当前Runner挂载配置（/etc/gitlab-runner/config.toml） #

volumes = ["/cache", "/dev:/dev:rw", "/ratatat/config:/ratatat/config:ro"]

本地Docker测试成功的配置 #

Dockerfile：

FROM ubuntu:latest
RUN apt-get update && \
 apt-get install -y pulseaudio alsa-utils

CMD ["/bin/bash"]

运行命令：

sudo docker run -it --rm  -e PULSE_SERVER=unix:${XDG_RUNTIME_DIR}/pulse/native  -v ${XDG_RUNTIME_DIR}/pulse/native:${XDG_RUNTIME_DIR}/pulse/native  -v ~/.config/pulse/cookie:/root/.config/pulse/cookie <your-image-name>

容器内执行paplay /usr/share/sounds/alsa/Front_Center.wav可正常发声。

解决方案 #

1. 更新GitLab Runner的config.toml配置 #

修改[[runners]]段下的volumes和environment，添加PulseAudio相关挂载与环境变量：

[[runners]]
  # 保留原有其他配置
  environment = ["PULSE_SERVER=unix:/run/user/1000/pulse/native"]  # 替换1000为你的宿主机用户UID
  volumes = [
    "/cache",
    "/dev:/dev:rw",
    "/ratatat/config:/ratatat/config:ro",
    "/run/user/1000/pulse/native:/run/user/1000/pulse/native",  # 对应宿主机PulseAudio socket路径
    "/home/your-username/.config/pulse/cookie:/root/.config/pulse/cookie"  # 替换为你的宿主机用户home路径
  ]

2. 简化CI作业脚本 #

无需在容器内启动独立的Pulseaudio服务，直接复用宿主机的PulseAudio服务，修改.gitlab-ci.yml：

stages:
  - test

test_audio_playback:
  image: ubuntu:latest
  stage: test
  before_script:
    - apt-get update
    - apt-get install -y pulseaudio-utils alsa-utils
  script:
    - paplay /usr/share/sounds/alsa/Front_Center.wav

3. 验证与生效 #

• 检查宿主机/etc/pulse/default.pa中是否包含load-module module-native-protocol-unix（默认已配置，cookie挂载会自动处理认证）。
• 重启GitLab Runner服务：

  sudo gitlab-runner restart
  

原理说明 #

原CI脚本在容器内启动了独立的Pulseaudio实例，但该实例无法直接访问宿主机的音频硬件。通过挂载宿主机的PulseAudio socket和认证cookie，让容器直接连接宿主机的Pulseaudio服务，从而获得音频硬件的访问权限，与本地Docker测试的逻辑一致。

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