curl http://localhost:5000/v2/_catalog {"errors":[{"code":"UNAUTHORIZED","message":"authentication required","detail":[{"Type":"registry","Class":"","Name":"catalog","Action":"*"}]}]}
时间: 2025-07-01 10:54:58 浏览: 7
### 解决 Docker Registry V2 认证失败问题并访问 `/v2/_catalog`
Docker Registry V2 在启用认证后,访问 `/v2/_catalog` 等资源时需要通过 Bearer Token 验证身份。如果未正确配置认证流程或客户端请求方式不当,将导致 `unauthorized: authentication required` 错误。
#### 启用 Bearer 认证机制
在启动 Registry 容器时,需确保已配置基于 Bearer 的认证机制,并正确设置 Realm 地址和认证服务路径:
```bash
docker run -d \
--name registry \
-p 5000:5000 \
-v /opt/registry/auth:/auth \
-v /opt/registry/data:/var/lib/registry \
-e "REGISTRY_AUTH=htpasswd" \
-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
-e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
registry:latest
```
此配置启用了基于 `htpasswd` 的 Basic Auth,并为 `/v2/` 路径下的所有请求设置了认证保护[^1]。
#### 获取有效的 Bearer Token
要访问 `/v2/_catalog` 接口,必须先通过 `/v2/token` 接口获取 Bearer Token。首先使用用户名和密码进行认证,获取临时令牌:
```bash
curl --user <username>:<password> -k -X GET https://localhost:5000/v2/token?service=Docker-registry
```
该请求将返回一个类似如下的 JSON 响应:
```json
{
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx"
}
```
随后,使用该 token 发起对 `/v2/_catalog` 的请求:
```bash
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx" -k https://localhost:5000/v2/_catalog
```
若成功,将返回仓库中所有镜像的列表,格式如下:
```json
{
"repositories": ["my-image", "another-image"]
}
```
#### 处理 TLS 握手失败问题
若出现 `Received fatal alert: handshake_failure` 错误,说明客户端与服务器之间的 SSL/TLS 协议版本不兼容。建议更新基础镜像至较新版本(如 Ubuntu 16.04、OpenJDK 8)以支持更高版本的 TLS 协议[^3]。此外,在客户端可尝试添加 `--insecure-registry` 参数信任私有仓库的证书:
```bash
sudo dockerd --insecure-registry localhost:5000
```
然后重启 Docker 服务以应用更改:
```bash
systemctl restart docker
```
#### 验证及排错
可通过以下命令验证 Registry 是否正常运行:
```bash
docker start registry
docker exec -it registry registry serve /home/jojo/register/config-example.yml
```
此命令将启动 Registry 并加载指定的配置文件,可用于测试认证逻辑是否生效。
#### 相关问题
阅读全文