linuxserver/retroarch

RetroArch 是一个模拟器、游戏引擎和媒体播放器的前端，通过Docker容器化部署，可在多种计算机和游戏机上运行经典游戏，提供流畅的图形界面。LinuxServer.io团队维护的此镜像包含定期应用更新、用户映射支持、自定义基础镜像及每周安全更新。

支持的架构

该镜像利用Docker清单实现多平台支持，拉取 lscr.io/linuxserver/retroarch:latest 会自动获取对应架构的镜像，也可通过标签指定特定架构：

应用设置

应用可通过以下地址访问：

• [***]

注意事项

• 纯CPU模式：RetroArch会使用LLVMPipe进行菜单渲染，可在设置中配置菜单刷新率或挂载Nvidia GPU。首次使用Nvidia GPU时，需右键桌面并重新启动RetroArch。
• 严格反向代理：默认使用自签名证书（https协议），若反向代理验证证书，需禁用容器证书检查。
• 系统调用限制：现代GUI桌面应用可能受Docker系统调用限制影响，旧内核或libseccomp版本主机可使用 --security-opt seccomp=unconfined 允许相关系统调用。

安全警告

[!WARNING] 此容器提供对主机系统的特权访问，请勿暴露在互联网中，除非已正确配置安全措施。

• HTTPS要求：完整功能需HTTPS，现代浏览器功能（如WebCodecs）不支持不安全的HTTP连接。
• 认证配置：默认无认证，可选 CUSTOM_USER 和 PASSWORD 环境变量启用基本HTTP认证（仅适用于可信局域网）。互联网暴露时，强烈建议使用反向代理（如SWAG）增强认证。
• 终端访问：Web界面包含无密码sudo权限的终端，任何访问GUI的用户可获取容器内root权限，需谨慎配置访问控制。

Selkies基础镜像通用选项

基于Docker Baseimage Selkies，支持以下环境变量和运行配置：

可选环境变量

可选运行配置

语言支持 - 国际化

通过LC_ALL环境变量设置桌面会话语言，例如：

• -e LC_ALL=zh_CN.UTF-8 - 中文
• -e LC_ALL=ja_JP.UTF-8 - 日语
• -e LC_ALL=ko_KR.UTF-8 - 韩语
• -e LC_ALL=ar_AE.UTF-8 - 阿拉伯语
• -e LC_ALL=ru_RU.UTF-8 - 俄语
• -e LC_ALL=es_MX.UTF-8 - 西班牙语（拉丁美洲）
• -e LC_ALL=de_DE.UTF-8 - 德语
• -e LC_ALL=fr_FR.UTF-8 - 法语
• -e LC_ALL=nl_NL.UTF-8 - 荷兰语
• -e LC_ALL=it_IT.UTF-8 - 意大利语

DRI3 GPU加速

挂载渲染设备实现应用/游戏加速，命令： --device /dev/dri:/dev/dri

支持的开源GPU驱动：

DRINODE环境变量可指定特定GPU，aarch64架构需容器内安装对应芯片组驱动。

Nvidia GPU支持

注意：Alpine基础镜像不支持Nvidia。

通过Zink实现OpenGL支持，兼容Nvidia GPU时自动用于硬件加速视频编码（x264enc全帧配置文件），降低CPU负载。

启用Nvidia支持的运行时标志：

Docker Compose配置需先设置Nvidia为默认运行时：

sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
sudo systemctl restart docker

compose.yaml中配置GPU：

services:
  retroarch:
    image: lscr.io/linuxserver/retroarch:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [compute,video,graphics,utility]

应用管理

PRoot Apps（持久化，推荐）

原生安装包（如apt-get install）在容器重建后不持久，推荐使用proot-apps安装到用户持久$HOME目录：

proot-apps install filezilla

支持的应用列表见此处。

Native Apps（非持久化）

通过universal-package-install mod安装系统原生包（增加启动时间，不持久），compose.yaml配置：

environment:
  - DOCKER_MODS=linuxserver/mods:universal-package-install
  - INSTALL_PACKAGES=libfuse2|git|gdb

使用方法

docker-compose（推荐）

---
services:
  retroarch:
    image: lscr.io/linuxserver/retroarch:latest
    container_name: retroarch
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - /path/to/config:/config
    ports:
      - 3000:3000
      - 3001:3001
    shm_size: "1gb"
    restart: unless-stopped

docker cli

docker run -d \
  --name=retroarch \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 3000:3000 \
  -p 3001:3001 \
  -v /path/to/config:/config \
  --shm-size="1gb" \
  --restart unless-stopped \
  lscr.io/linuxserver/retroarch:latest

参数说明

环境变量文件（Docker secrets）

使用FILE__前缀从文件设置环境变量：

-e FILE__MYVAR=/run/secrets/mysecretvariable

MYVAR值将设为/run/secrets/mysecretvariable文件内容。

应用运行的Umask设置

通过-e UMASK=022覆盖默认umask，详情见umask说明。

用户/组ID

卷挂载时，权限问题可通过指定PUID（用户ID）和PGID（组ID）解决，确保主机卷目录所有者与指定ID一致。使用id your_user查看：

id your_user

输出示例：

uid=1000(your_user) gid=1000(your_user) groups=1000(your_user)

Docker Mods

支持信息

• 容器运行时Shell访问：

  docker exec -it retroarch /bin/bash
  

• 实时监控容器日志：

  docker logs -f retroarch
  

• 容器版本号：

  docker inspect -f '{{ index .Config.Labels "build_version" }}' retroarch
  

• 镜像版本号：

  docker inspect -f '{{ index .Config.Labels "build_version" }}' lscr.io/linuxserver/retroarch:latest
  

更新方法

通过Docker Compose

• 更新镜像：

  • 所有镜像：

    docker-compose pull
    

  • 单个镜像：

    docker-compose pull retroarch
    

• 更新容器：

  • 所有容器：

    docker-compose up -d
    

  • 单个容器：

    docker-compose up -d retroarch
    

• 清理旧镜像：

  docker image prune
  

通过Docker Run

• 更新镜像：

  docker pull lscr.io/linuxserver/retroarch:latest
  

• 停止运行中的容器：

  docker stop retroarch
  

• 删除容器：

  docker rm retroarch
  

• 使用相同参数重新创建容器（/config目录映射正确则设置保留）

• 清理旧镜像：

  docker image prune
  

镜像更新通知 - Diun

[!TIP] 推荐使用Diun获取更新通知，不建议使用自动更新容器的工具。

本地构建

git clone [***]
cd docker-retroarch
docker build \
  --no-cache \
  --pull \
  -t lscr.io/linuxserver/retroarch:latest .

跨架构构建（如x86_64构建ARM）：

docker run --rm --privileged lscr.io/linuxserver/qemu-static --reset

然后使用 -f Dockerfile.aarch64 指定架构Dockerfile。

版本历史

• 25.05.25: - 初始版本。