joxit/docker-registry-ui

Docker Registry 用户界面

概述

本项目旨在为私有 Docker 镜像仓库提供简洁完整的用户界面，支持多种自定义配置，核心选项 SINGLE_REGISTRY 可禁用镜像仓库动态切换功能（与旧版 static 标签行为一致）。

若从 1.x 版本迁移至 2.x，可参考 迁移指南；1.x 版本说明见 历史文档。

界面基于类 React 微型库 Riot 和组件库 riot-mui 开发。如果觉得本项目有帮助，欢迎通过 赞助 支持开发。

支持的 Docker 镜像标签

• latest：基于 nginx:alpine 的最新稳定版
• latest-debian：基于 nginx:debian 的最新稳定版
• main/master：基于 nginx:alpine 的 2.x 测试版（beta）
• main-debian/master-debian：基于 nginx:debian 的 2.x 测试版（beta）
• 2：2.x 系列最新版本（包含最新小版本和补丁版本）
• 2.x：2.x 系列指定主版本的最新版本（包含最新补丁版本）
• 2.x.y：2.x.y 具体版本

项目页面 | 在线演示 | 使用示例 | Helm Chart

!预览

隐藏功能

• 批量删除镜像：

  • 通过复选框选择多个标签删除（1.2.0 起支持，详见 #29、#79）。
  • 按住 ALT + 点击 表头复选框，选中当前页所有标签（1.2.1 起支持，详见 #80、#81）。
  • 按住 Shift + 点击 起始标签，再 Shift + 点击 结束标签，选中连续标签（2.4.0 起支持，详见 #287）。

• 鼠标悬停标签时显示 sha256 摘要。

• 标签列表支持数字排序（0.4.0 起支持，详见 #45、#46）。

• 共享界面：当 SINGLE_REGISTRY=false 时，可通过公共演示页 + URL 参数共享（例如 [***] Access-Control-Allow-Origin设为[***] 搜索框快捷键：按 Ctrl + F 或 F3 聚焦搜索框（2.1.0 起支持，详见 #213）。

• 历史页面支持多架构显示（1.5.0 起支持，详见 #130、#134）。

• 显示 Dockerfile 内容（2.4.0 起支持，详见 #286）。

• 缓存仓库请求（如 blobs 和含 sha256: 的 manifest）。

常见问题（FAQ）

• SINGLE_REGISTRY=false 与 true 的区别？
  false 时界面顶部显示仓库切换菜单，支持动态添加/切换仓库；true 时仅显示单个仓库，无切换菜单。

• 删除所有标签后，镜像为何仍显示在界面？
  Docker 仓库的垃圾回收机制不会自动删除空镜像（无标签但有残留数据）。需手动删除仓库数据目录中的对应文件夹（详见 #77）。

• 界面显示的镜像大小与 docker images 不一致？
  界面显示的是镜像压缩后的大小，而非本地解压后的大小。

• 能否通过 HTTPS 访问界面？
  可以。需在前端部署反向代理（如 Nginx）处理 HTTPS 连接。

• 是否支持认证？
  仅支持基础认证（Basic Auth）。作为纯前端应用，依赖浏览器自带的认证窗口。

• 能否搭配非安全仓库（无 HTTPS）使用？
  可以，但需先配置 Docker 客户端（详见 #76）。

• "Mixed Content" 错误是什么？
  表示界面使用 HTTPS 但仓库使用 HTTP（非加密）。HTTPS 页面无法加载 HTTP 资源，需将仓库升级为 HTTPS。

• 为何 Nginx 默认 Host 设为 $http_host？
  用于解决 #88 问题，详见 #113。

• 使用 Basic Auth 时，OPTIONS（预检请求）和 DELETE 请求返回 401 错误？
  Docker 仓库存在 bug，预检请求会返回 401，违反 W3C 预检请求规范，且官方已明确不会修复（distribution/distribution#4458）。解决方案：将界面与仓库部署在同一域名下（如 registry.example.com/ui/），或使用 NGINX_PROXY_PASS_URL，或在仓库前端部署反向代理（Nginx/Apache）并对 OPTIONS 请求返回 200。

• 能否通过 Electron 作为独立应用运行？
  可以，示例见 此处（详见 #129）。

• 通过界面删除镜像后，服务器上仍存在？
  界面仅删除标签引用，需运行仓库垃圾回收命令清理残留数据：registry garbage-collect config.yml 或 docker exec registry registry garbage-collect config.yml（详见 #77、#147）。

• 删除一个标签后，相同 SHA 的所有标签都被删除？
  Docker 仓库 API 限制：删除标签需通过 name 和 manifest（内容 SHA），因此相同 SHA 的标签会被批量删除。

• 能否以非特权用户运行容器？
  可以，使用 --user nginx 以 nginx 用户运行，此时监听端口自动改为 8080（详见 #224、#234）。

• 更多问题：可参考 使用示例 或提交 Issue。

配置选项

以下环境变量用于自定义界面行为（当 SINGLE_REGISTRY=true 时，部分选项仅对单仓库模式生效）：

主题自定义（2.4.0+）

通过 THEME_* 环境变量自定义主题颜色，支持以下参数（示例值为默认的亮色/暗色主题配置）：

推荐部署方式（docker-compose）

以下示例通过 docker-compose 部署界面和仓库，两者共享同一域名以规避 CORS 问题：

yaml
version: '3.8'

services:
  registry-ui:
    image: joxit/docker-registry-ui:main
    restart: always
    ports:
      - 80:80
    environment:
      - SINGLE_REGISTRY=true                   # 单仓库模式
      - REGISTRY_TITLE=Docker Registry UI      # 界面标题
      - DELETE_IMAGES=true                     # 允许删除镜像
      - NGINX_PROXY_PASS_URL=[***]  # 代理仓库地址
      - SHOW_CATALOG_NB_TAGS=true              # 显示每个镜像的标签数量
    container_name: registry-ui

  registry-server:
    image: registry:2.8.2
    restart: always
    environment:
      # 配置 CORS，允许界面域名访问
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Origin: '[[***]]'
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Methods: '[HEAD,GET,OPTIONS,DELETE]'
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Credentials: '[true]'
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Headers: '[Authorization,Accept,Cache-Control]'
      REGISTRY_STORAGE_DELETE_ENABLED: 'true'  # 允许删除镜像
    volumes:
      - ./registry/data:/var/lib/registry      # 挂载仓库数据目录
    container_name: registry-server

配置 CORS

仓库需开启 CORS 以允许界面访问，配置方式如下：

• 无需认证的仓库：

  yaml
  http:
    headers:
      Access-Control-Allow-Origin: ['*']  # 允许所有域名
  

• 需要认证的仓库：

  yaml
  http:
    headers:
      Access-Control-Allow-Origin: ['[***]']  # 界面域名（含协议和端口）
      Access-Control-Allow-Credentials: [true]
      Access-Control-Allow-Headers: ['Authorization', 'Accept', 'Cache-Control']
  

若仍有 CORS 问题，可尝试浏览器插件临时绕过（详见 #25）。

启用删除功能

需同时配置界面和仓库：

1. 界面：设置 DELETE_IMAGES=true。
2. 仓库：启用删除功能并允许 DELETE 方法：

   yaml
   storage:
     delete:
       enabled: true  # 允许删除镜像
   http:
     headers:
       Access-Control-Allow-Methods: ['HEAD', 'GET', 'OPTIONS', 'DELETE']  # 允许 DELETE 方法
       Access-Control-Expose-Headers: ['Docker-Content-Digest']  # 暴露 digest 用于删除
   

更多示例

• 将界面作为代理使用
• 独立部署界面
• 搭配 Traefik 使用
• S3 存储后端配置
• HTTPS 配置
• Electron 独立应用