---
title: "镜像与仓库"
description: "配置镜像标签、私有仓库凭据，并处理拉取和版本更新问题。"
---

> Documentation Index
> Fetch the complete documentation index at: https://cdelivery.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 镜像与仓库

镜像决定应用运行的程序及默认启动方式。先从镜像发布者的文档确认标签、监听端口、数据目录和必需环境变量，再填写应用配置。

## 镜像名称

| 示例 | 含义 |
| --- | --- |
| `nginx:stable-alpine` | 公开镜像及标签，适合入门演示 |
| `registry.example.com/team/api:1.2.3` | 指定私有仓库、路径和版本 |
| `registry.example.com:5000/team/api:1.2.3` | 仓库使用非默认端口 |

不填写 `https://` 前缀。仓库路径使用符合界面校验的名称；当前输入不接受 `@sha256:...` 摘要引用。部署重要业务时，优先使用能明确区分发布版本的标签。

平台不会持续轮询仓库，自动把同名标签的新镜像发布到应用。仓库中覆盖旧标签也不会自动改变已经运行的容器。

## 私有仓库认证

创建或编辑应用，打开镜像设置，填写仓库用户名和密码或访问令牌。优先使用只具有拉取权限的专用凭据。

平台不会在读取应用信息时回显密码。当前界面在用户名非空时要求填写密码或令牌：如果只是查看已有认证，关闭编辑框即可；需要更换认证时，重新填写用户名和令牌并确认。

在未修改凭据且仓库作用域不变时，已有凭据可以保留。切换到不同仓库后不要假定旧凭据仍有效，应按新仓库重新配置。清除认证前先确认镜像确实允许匿名拉取。

## 更新镜像

1. 发布并确认目标标签存在。
2. 打开应用配置，修改镜像标签及相应参数。
3. 检查[更新策略](/docs/zh-cn/guides/release-safety/update-strategy/)，确认副本和容量允许更新。
4. 保存后查看副本、日志及 XHealth 结果。
5. 启用 Guardian 的应用，按[发布验证](/docs/zh-cn/guides/release-safety/guardian/)查看候选配置是否通过。

只保存未变化的镜像字符串不会强制重部署。需要重新创建容器时使用[更新与重启](/docs/zh-cn/guides/apps/lifecycle/)中的重启操作；要确保发布版本可追踪，仍应使用新的版本标签。

## 拉取失败排查

| 错误方向 | 检查内容 |
| --- | --- |
| 未授权或拒绝访问 | 用户名、令牌权限、仓库路径及令牌是否过期 |
| 标签不存在 | 仓库中的实际标签、大小写及镜像推送是否完成 |
| 连接或证书失败 | 服务器出站网络、DNS、仓库 TLS 配置 |
| 平台架构不匹配 | 镜像是否提供目标服务器 CPU 架构 |
| 只有部分服务器失败 | 分别检查这些服务器到仓库的连接和镜像支持 |

不要把仓库密码写入镜像名称、环境变量示例或共享故障截图。公开镜像使用方式可参考 [Nginx 官方镜像](https://hub.docker.com/_/nginx)。

Source: https://cdelivery.dev/docs/zh-cn/guides/apps/images/index.mdx