#常用 CLI 命令操作

使用 ac CLI 进行平台登录、命名空间权限管理以及 Registry 元数据操作。对于 push 和 pull 等镜像传输操作，请使用标准 OCI 客户端，例如 nerdctl。

以下示例默认假设：

• Registry 客户端地址：<REGISTRY_CLIENT_HOSTPORT>
• Registry API URL：<REGISTRY_API_URL>
• 当前命名空间：my-ns

#开始之前

在运行本文档中的命令之前，请确保：

• 已安装 ac。
• 如果需要 push 或 pull 镜像，请安装 nerdctl。
• 当前环境可以访问 ACP API 端点和 Registry 地址。
• 已登录 ACP 并选择了目标集群。
• 当前 ACP 账号，或 Pod 或 Job 中使用的 ServiceAccount，具有所需的命名空间权限。

典型的权限要求：

• 拉取镜像：system:image-puller
• 推送镜像：system:image-pusher
• 使用 ac get images 列出镜像：需要具备访问 -n 指定命名空间的权限；仅当需要扫描当前用户可访问的所有命名空间时，才使用 -A

如果在 Pod、Job 或 CronJob 中运行 ac：

• Pod 必须使用有效的 serviceAccountName。
• 挂载的 ServiceAccount token 必须可用。
• 该 ServiceAccount 必须具有访问目标集群以及 Registry 相关 API 的权限。

#身份验证的工作方式

ac 和 nerdctl 使用不同的身份验证路径：

• ac 使用当前 ACP 登录会话访问 Registry 相关 API。
• 如果 ac 在 Pod 内运行且没有可用的 ACP 会话，则可以回退使用已挂载的 ServiceAccount token。
• nerdctl 直接向 Registry 进行身份验证，通常使用已具有目标命名空间访问权限的相同 ACP 账号凭据。

本文档中的地址用法：

• <REGISTRY_CLIENT_HOSTPORT> 是 OCI 客户端（例如 nerdctl）使用的 Registry 地址。
• <REGISTRY_API_URL> 是 ac get images 使用的 Registry API 端点。
• 在外部访问场景中，ac 通常应显式指定 --registry-url，而不是依赖默认的集群内 Registry 地址。

#对 ACP 进行身份验证

在使用 ac 中与 Registry 相关的命令之前，请先登录并选择目标集群：

ac login <acp-url>
ac config get-clusters
ac config use-cluster <cluster-name>

登录后，ac 可以使用当前会话访问诸如 ac get images 之类的 Registry 相关 API。

#为用户授予命名空间权限

为用户添加命名空间拉取权限。

ac create rolebinding <binding-name> --clusterrole=system:image-puller --user=<username> -n <namespace>

为用户添加命名空间推送权限。

ac create rolebinding <binding-name> --clusterrole=system:image-pusher --user=<username> -n <namespace>

#为 ServiceAccount 授予命名空间权限

为 ServiceAccount 添加命名空间拉取权限。

ac create rolebinding <binding-name> --clusterrole=system:image-puller --serviceaccount=<namespace>:<serviceaccount-name> -n <namespace>

为 ServiceAccount 添加命名空间推送权限。

ac create rolebinding <binding-name> --clusterrole=system:image-pusher --serviceaccount=<namespace>:<serviceaccount-name> -n <namespace>

#对 OCI 客户端进行身份验证

对于镜像的 push 和 pull，请使用具有目标命名空间访问权限的相同 ACP 账号凭据：

nerdctl login <REGISTRY_CLIENT_HOSTPORT> -u <ACP-USERNAME> -p <ACP-PASSWORD>

如果 Registry 使用自签名证书或纯 HTTP，请添加全局标志 --insecure-registry。

示例：

nerdctl --insecure-registry login <REGISTRY_CLIENT_HOSTPORT> -u <ACP-USERNAME> -p <ACP-PASSWORD>

#列出镜像

为获得更好的性能，请尽可能查询特定命名空间：

ac get images -n my-ns --registry-url=<REGISTRY_API_URL>

如果当前上下文已经指定了目标命名空间，则可以省略 -n。如果当前上下文未指定命名空间，则使用 default。

ac get images --registry-url=<REGISTRY_API_URL>

仅当需要列出当前用户有权限访问的所有命名空间中的镜像时，才使用 -A。在包含大量命名空间或仓库的集群上，这可能会更慢。

ac get images -A --registry-url=<REGISTRY_API_URL>

默认情况下，输出仅包含 REPOSITORY 和 TAG 列。日常查询请保持默认输出。仅在需要创建时间和 digest 元数据时才添加 -o wide，因为这需要额外的元数据查找，并可能增加命令延迟。

当自动化流程需要机器可读数据时，请使用结构化输出：

ac get images -n my-ns -o yaml --registry-url=<REGISTRY_API_URL>

对于 JSON 和 YAML 输出，默认输出也仅包含 repository 和 tag 字段。仅在需要 digest 和创建时间元数据时才使用 -o wide。

对于大型 Registry，您可以调整 Registry catalog 的分页大小。默认值为 200。除非需要更大的 catalog 页面，否则不要增大该值。

ac get images -n my-ns --catalog-page-size=1000 --registry-url=<REGISTRY_API_URL>

当 ac 在集群外运行时，建议显式指定 --registry-url。否则，CLI 可能会回退到默认的集群内 Registry 地址，而该地址通常无法从本地工作站访问。

#拉取镜像

使用 nerdctl 从 Registry 拉取镜像：

# Pull an image from the current namespace
nerdctl pull <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest

# Pull an image from another namespace when you already have permission
nerdctl pull <REGISTRY_CLIENT_HOSTPORT>/shared-ns/base-image:latest

#推送镜像

将本地镜像推送到当前命名空间：

# Tag the local image with the target repository
nerdctl tag my-app:latest <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:v1

# Push it to the Registry
nerdctl push <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:v1

将另一个 Registry 中的镜像复制到 ACP Registry：

# Pull the source image
nerdctl pull remote.registry.io/demo/my-app:latest

# Retag it for ACP Registry
nerdctl tag remote.registry.io/demo/my-app:latest <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest

# Push it to ACP Registry
nerdctl push <REGISTRY_CLIENT_HOSTPORT>/my-ns/my-app:latest