安装指南

本指南将 Artifact Hub Shim 作为 ACP 集群插件进行安装。标准安装完全离线，并将 API、内置目录和 template-render 扩展部署到 artifacthub-shim-system。

前提条件

您拥有 ACP 平台管理员权限，并且可以访问集群插件管理。
您已在可访问 ACP 平台的操作主机上安装了 violet CLI。
您已将 Artifact Hub Shim 集群插件包下载到操作主机。
如果集群将通过 Tekton 或 Pipelines as Code 使用目录资源，则已安装 Alauda DevOps Pipelines v4.0 或更高版本。
您可以使用具有集群管理员权限的 kubectl 来验证安装。

如果集群中已经存在 Tekton Hub 或其他 Artifact Hub 端点，请在切换消费者到 Artifact Hub Shim 之前记录其配置。

使用 Violet 上传集群插件

推荐使用 violet push 上传集群插件。该命令会将打包好的 OCI chart 和相关镜像传输到 ACP global registry，并创建或更新包中包含的 ModulePlugin 资源。

请在包含插件包的目录中运行以下命令：

violet push <plugin-package>.tgz \
  --platform-address <platform-address> \
  --platform-username <platform-username> \
  --platform-password <platform-password> \
  --clusters <cluster-name> \
  --force

请按如下方式替换占位符：

参数或占位符	说明
`<plugin-package>.tgz`	适用于目标架构的 Artifact Hub Shim 集群插件包。
`<platform-address>`	ACP 平台 URL。
`<platform-username>`	平台管理员用户名。
`<platform-password>`	平台管理员账户密码。
`<cluster-name>`	必须可用该插件版本的集群。多个集群时使用英文逗号分隔的列表。
`--force`	覆盖 registry 中现有的制品和固定标签镜像，使上传的包内容生效。

请勿将平台凭据放入脚本或源代码管理中。命令完成后，打开 Platform Management > Marketplace Management > Cluster Plugins，并确认 Alauda Artifact Hub Shim 已列出且版本为上传的版本。

从 Web 控制台安装集群插件

标准初始安装请使用以下值：

设置	推荐值	用途
Install Namespace	`artifacthub-shim-system`	使用 Pipelines 集成所期望的标准 Service 名称。
Replica Count	`1`	使用默认的单从节点拓扑。
ACP Global Cluster Mode	Disabled	仅当工作负载运行在 ACP global 集群上时启用。
Enable Built-in Catalog	Enabled	使打包的 Task、Pipeline 和 StepAction 目录可用。
Install Catalog Extra Resources	Enabled	同步打包的模板和 tool-image ConfigMaps。
Enable Template Render Extension	Enabled	启用模板渲染和 resolver 可见性准入。
Source Workdir Type	`emptyDir`	使用 pod 本地存储，并且与未来增加从节点数量保持兼容。
Enable Content Store	Disabled	从活动的内存快照提供 manifests。
Refresh Interval	`10m`	定期刷新已注册的 Git 源。
Log Level / Format	`info` / `json`	提供面向生产环境的结构化日志。

有关持久化存储、自定义认证、Ingress 和高级运行时设置，请参见 Chart 配置。

以平台管理员身份登录 ACP。
打开目标集群并进入集群插件管理。
选择 Alauda Artifact Hub Shim。
选择适用于您的环境且已批准的最新可用版本。
应用上方推荐配置。如果目标是 ACP global 集群，请启用 ACP Global Cluster Mode。
开始安装，并等待插件状态报告为 Running。

对于常规安装，请不要直接创建或编辑 ModulePlugin、ModuleConfig、ModuleInfo、ClusterPluginInstance，或派生出的 AppRelease。ACP 会在集群插件生命周期内管理这些资源。

验证安装

以下命令假设使用默认安装命名空间、Helm release 名称以及生成的资源名称。如果您自定义了这些值，请在命令中替换相应的命名空间和资源名称。

检查 API Deployment 是否可用：

kubectl get deployment -n artifacthub-shim-system
kubectl rollout status deployment/artifacthub-shim \
  -n artifacthub-shim-system \
  --timeout=5m

如果您在安装期间禁用了 Enable Template Render Extension，请跳过以下命令。否则，请验证扩展 Deployment：

kubectl rollout status deployment/artifacthub-shim-extension \
  -n artifacthub-shim-system \
  --timeout=5m

在不对外暴露的情况下检查集群内 Service 和 API 健康状态：

kubectl get service artifacthub-shim-api -n artifacthub-shim-system

kubectl get --raw \
  '/api/v1/namespaces/artifacthub-shim-system/services/http:artifacthub-shim-api:80/proxy/healthz'

kubectl get --raw \
  '/api/v1/namespaces/artifacthub-shim-system/services/http:artifacthub-shim-api:80/proxy/readyz'

健康检查请求应成功，且就绪响应中应包含 "status":"ready"。

在需要验证源加载时，检查当前活动快照：

kubectl get --raw \
  '/api/v1/namespaces/artifacthub-shim-system/services/http:artifacthub-shim-api:80/proxy/api/v1/snapshot'

请勿为 Tekton 集成将该 Service 对外发布。Tekton 和 Pipelines as Code 应使用集群内 Service URL。

连接 Tekton

插件就绪后，配置 TektonConfig 并验证一个远程 Task。标准安装使用以下端点：

http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local

如需最小化验证，请参阅快速开始；如需 Tekton 和 Pipelines as Code 设置，请参阅配置 Tekton 集成。

自定义安装

如需添加内部目录，请参阅配置自定义 Git 仓库。
如需更改存储或认证，请参阅 Chart 配置。
如需运行多个 API 从节点，请在增加 replicaCount 之前遵循高可用性。
如需更改日志详细程度或编码格式，请参阅日志。

卸载 Artifact Hub Shim

卸载该插件会移除 Tekton resolver、Pipelines as Code 和 DevOps Hub UI 使用的本地端点。这可能会中断流水线并移除由插件管理的资源。请使用 ACP 集群插件管理中显示的删除风险信息，并遵循您组织批准的卸载操作步骤。

在卸载之前，请重新配置或禁用所有指向 Artifact Hub Shim Service 的消费者，通过经批准的安全流程备份用户管理的仓库定义和凭据，并确保没有活动的 PipelineRun 或 TaskRun 依赖该端点。切勿将导出的凭据存储在源代码管理中。

#安装指南

#目录

#前提条件

#使用 Violet 上传集群插件

#从 Web 控制台安装集群插件

#验证安装

#连接 Tekton

#自定义安装

#卸载 Artifact Hub Shim