Docker Registry UI 部署问题排查与解决方案

问题背景

在使用Docker Registry UI项目时，用户遇到了前端界面无法正常加载的问题。该问题表现为页面长时间加载后出现nginx错误提示，随后又转变为404错误和CORS跨域问题。本文将详细分析问题原因并提供完整的解决方案。

问题分析

初始配置问题

用户最初的docker-compose配置存在几个关键问题：

1. NGINX_PROXY_PASS_URL设置不当：用户将其设置为外部域名而非容器内部地址
2. CORS配置缺失：当直接访问Registry API时未正确配置跨域访问
3. 认证机制冲突：Registry启用了基础认证但UI未配置相应凭证

错误发展过程

1. 第一阶段：nginx代理错误导致页面无法加载
2. 第二阶段：修改REGISTRY_URL后出现404错误
3. 第三阶段：添加CORS配置后仍然报跨域错误

解决方案

正确的docker-compose配置

version: '3'
services:
  registry:
    image: registry:latest
    container_name: REGISTRY-APP
    volumes:
      - ./auth:/auth
      - ./registry-data:/registry-data
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/registry.password
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /registry-data
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Origin: ['*']
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Methods: ['HEAD', 'GET', 'OPTIONS', 'DELETE']
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Headers: ['Authorization', 'Accept']
      REGISTRY_HTTP_HEADERS_Access-Control-Max-Age: ['1728000']
      REGISTRY_HTTP_HEADERS_Access-Control-Allow-Credentials: ['true']
      REGISTRY_HTTP_HEADERS_Access-Control-Expose-Headers: ['Docker-Content-Digest']

  registry-ui:
    image: joxit/docker-registry-ui:main
    depends_on:
      - registry
    environment:
      - SINGLE_REGISTRY=true
      - NGINX_PROXY_PASS_URL=http://registry:5000
      - DELETE_IMAGES=true
      - SHOW_CONTENT_DIGEST=true
      - REGISTRY_SECURED=true
      - REGISTRY_USERNAME=admin
      - REGISTRY_PASSWORD=password

关键配置说明

1. NGINX_PROXY_PASS_URL：必须设置为Registry服务的容器名称和端口（如http://registry:5000），这样UI服务可以通过Docker内部网络直接访问Registry，避免CORS问题。

2. CORS配置：虽然使用proxy_pass后理论上不需要CORS配置，但完整配置可以确保其他访问方式的兼容性。注意Access-Control-Allow-Credentials为true时，Access-Control-Allow-Origin不能使用通配符*。

3. 认证配置：当Registry启用认证时，UI服务需要通过REGISTRY_USERNAME和REGISTRY_PASSWORD环境变量提供凭证。

常见问题排查

1. 404错误：检查Registry服务是否正常运行，确认config.yml文件包含正确的version字段（version: 0.1）。

2. CORS错误：确保所有必要的CORS头信息已正确配置，特别注意值的格式（使用数组形式）。

3. 认证失败：验证UI服务中配置的用户名密码与Registry的htpasswd文件一致。

最佳实践建议

1. 对于生产环境，建议启用HTTPS并配置有效的证书。

2. 考虑使用Docker Secret管理认证信息，避免在compose文件中明文存储密码。

3. 定期检查并更新Docker Registry和UI的镜像版本，确保安全补丁及时应用。

4. 对于大规模部署，建议配置适当的存储后端（如S3）而非本地文件系统。

通过以上配置和注意事项，用户可以顺利部署功能完整的Docker Registry管理界面，实现对私有镜像仓库的便捷管理。