启动 registry 必须显式暴露 5000 端口并配置 insecure-registries；启用 catalog 需设 REGISTRY_CATALOG_PAGE_SIZE；config.yml 缩进错误或路径不对会导致容器反复重启。
启动 registry 容器时端口没暴露，push 就一直超时
默认 registry 镜像只监听 5000 端口，但 Docker 守护进程不会自动映射——不加 -p 参数，宿主机根本收不到请求。
- 必须显式绑定：运行时加
-p 5000:5000，别依赖EXPOSE - 如果用 systemd 或 compose 启动，检查
ports或PublishAllPorts是否为false - 云服务器还要确认安全组放行
5000端口，不只是本地防火墙
客户端 push 报错 “http: server gave HTTP response to HTTPS client”
Docker 默认只信任 HTTPS 仓库，而本地 registry 是 HTTP 协议，会直接拒绝通信。
- 在所有要 push/pull 的机器上，修改 Docker daemon 配置：
/etc/docker/daemon.json加入"insecure-registries": ["your-host:5000"] - 改完必须重启 daemon：
sudo systemctl restart docker，否则配置不生效 - 别漏掉 Mac/Windows Docker Desktop 的设置界面里也要手动添加 insecure registry
镜像 push 成功但 list 返回空，或 v2/_catalog 404
registry 默认关闭 catalog API（即镜像列表功能），且不支持匿名 list，不是 bug 是设计如此。
- 启动时加环境变量：
-e "REGISTRY_STORAGE_DELETE_ENABLED=true"和-e "REGISTRY_HTTP_ADDR=0.0.0.0:5000"是基础，但还不够 - 必须启用 catalog：在配置文件或环境变量中设
REGISTRY_CATALOG_PAGE_SIZE=100，否则v2/_catalog返回 404 - 更稳妥的做法是挂载自定义 config.yml，用
storage: filesystem+delete: enabled: true显式声明
用 compose 启动后容器反复重启，日志显示 “no basic auth credentials”
这通常不是权限问题，而是 registry 启动时读取配置失败导致进程退出，Docker 自动重启形成循环。
- 检查挂载的
config.yml路径是否正确，用docker run -it --rm -v $(pwd)/config.yml:/etc/docker/registry/config.yml registry:2 cat /etc/docker/registry/config.yml验证可读 - YAML 缩进必须用空格，不能用 tab；
storage:下的子字段如filesystem:必须对齐，差一个空格就解析失败 - 如果用了
auth:段，确保 htpasswd 文件已生成并正确挂载，否则 registry 直接 panic 退出
registry 看似简单，但它的配置加载是静态且脆弱的——没有语法校验，出错只报一句 “failed to load configuration”，真正原因得翻日志开头几行。别跳过验证 config 可读性和 YAML 格式这步。
