Bytebase 上架 Azure Marketplace 实战指南从 Helm Chart 改造到 CNAB 发布全流程【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebase本指南以 Bytebase 仓库中的 scripts/azure-marketplace/README.md 为主体结合 scripts/azure-marketplace/ 下的 manifest、ARM 模板、部署 UI 定义、打包脚本以及 helm-charts/bytebase/ 的源码实现系统讲解如何将 Bytebase 以Azure Container OfferKubernetes 应用的形式发布到 Azure Marketplace。读者学完后将掌握从 Helm Chart 镜像适配、ACR 镜像推送、CNAB 打包校验到 Partner Center 创建与提审的全套流程并理解 CNAB/OCI 制品格式这一关键约束的底层原理。一、方案总览Azure Container Offer 与 CNABAzure Marketplace 的Azure Container Offer针对 Kubernetes 应用要求发布方提交的不是普通 Docker 镜像而是一个CNABCloud Native Application Bundle制品。该制品将以下三部分打包在一起Helm ChartBytebase 的部署清单helm-charts/bytebase/ARM 模板mainTemplate.json声明部署时向 AKS 集群安装的 Kubernetes 集群扩展部署 UI 定义createUiDefinition.json决定用户在 Azure 门户中填写的表单。CNAB 制品由微软提供的CPAcontainer-package-app工具生成并发布到你的 ACRAzure Container RegistryPartner Center 只接受这种格式。部署时Azure 会基于 mainTemplate.json 创建Microsoft.KubernetesConfiguration/extensions集群扩展并通过configurationSettings把用户在门户中填写的参数映射为 Helm values最终在 AKS 上以扩展方式拉起 Bytebase。仓库中的目录结构如下bytebase/ ├── scripts/azure-marketplace/ │ ├── manifest.yaml # 包元数据版本、镜像、扩展参数 │ ├── createUiDefinition.json # Azure 门户部署 UI │ ├── mainTemplate.json # ARM 模板集群扩展声明 │ ├── values-azure.yaml # Azure 特有 Helm values │ ├── push-to-acr.sh # 镜像推送自动化脚本 │ ├── package.sh # CNAB 打包自动化脚本 │ ├── PARTNER_CENTER_GUIDE.md # Partner Center 逐字段配置指南 │ └── README.md # 本指南对应的主文档 ├── helm-charts/bytebase/ # Bytebase 的 Helm Chart └── scripts/ └── Dockerfile # Bytebase 镜像构建文件二、前置条件发布前需要准备Azure 账户体系有效的 Azure 订阅具有发布者权限的 Partner Center 账户位于发布租户内的 Azure Container RegistryACR。技术环境本地安装 Docker安装并登录 Azure CLIaz具备向 ACR 推送镜像的权限具备 Kubernetes 基础知识用于部署测试微软的 CPA 打包工具以 Docker 镜像mcr.microsoft.com/container-package-app:latest提供。三、Step 1让 Helm Chart 支持 Azure Marketplace 镜像重打标Azure Marketplace 要求应用镜像遵循global.azure.images取值模式以便微软在认证阶段将镜像重打标retag并托管到其自有注册表。原文档 README.md 描述的修改方式是直接编辑 statefulset.yaml 中的镜像引用块加入对global.azure.images.bytebase的判断分支{{- if .Values.global.azure.images.bytebase }} # Azure Marketplace image path image: {{ .Values.global.azure.images.bytebase.registry }}/{{ .Values.global.azure.images.bytebase.repository }}:{{ .Values.global.azure.images.bytebase.tag }} {{- else if $registryMirrorHost }} # Registry mirror path image: {{ trimSuffix / $registryMirrorHost }}/bytebase/bytebase:{{ $version }} {{- else }} # Default Docker Hub path image: bytebase/bytebase:{{ $version }} {{- end }}需要说明的是当前仓库实际已经将该逻辑封装为 Helm 模板函数效果与原文档描述的目标一致且更具可维护性。在 helm-charts/bytebase/templates/_helpers.tpl 中定义了bytebase.image模板其解析优先级从低到高为默认 Docker Hub 路径bytebase/bytebase:version镜像源覆盖若设置bytebase.registryMirrorHost则使用registryMirrorHost/bytebase/bytebase:versionAzure Marketplace 覆盖最高优先级若设置global.azure.images.bytebase含registry、image、tag三个字段则使用registry/image:tag。而 statefulset.yaml 中容器镜像统一通过image: {{ include bytebase.image . }}引用该模板。因此发布 Azure Marketplace 时只需通过values-azure.yaml注入global.azure.images无需改动模板文件同时完全兼容既有部署不设置该值时行为不变。四、Step 2搭建 Azure Container Registry# 登录 Azure az login # 创建资源组如需要 az group create --name bytebase-marketplace --location eastus # 创建 ACR建议 Premium SKU以支持扩展特性 az acr create \ --resource-group bytebase-marketplace \ --name bytebaseacr \ --sku Premium \ --location eastus # 登录 ACR az acr login --name bytebaseacr # 获取 ACR 登录服务器地址 ACR_LOGIN_SERVER$(az acr show --name bytebaseacr --query loginServer --output tsv) echo ACR Login Server: $ACR_LOGIN_SERVER五、Step 3推送 Bytebase 镜像到 ACR方案 A直接使用官方镜像推荐# 拉取官方镜像 docker pull bytebase/bytebase:3.11.1 # 打上 ACR 标签 docker tag bytebase/bytebase:3.11.1 $ACR_LOGIN_SERVER/bytebase/bytebase:3.11.1 # 推送 docker push $ACR_LOGIN_SERVER/bytebase/bytebase:3.11.1方案 B从源码构建# 在仓库根目录构建 docker build -f scripts/Dockerfile -t bytebase/bytebase:3.11.1 . # 打标签并推送 docker tag bytebase/bytebase:3.11.1 $ACR_LOGIN_SERVER/bytebase/bytebase:3.11.1 docker push $ACR_LOGIN_SERVER/bytebase/bytebase:3.11.1关于镜像构建可参考 scripts/Dockerfile采用多阶段构建先用node:24.18.1-slim构建前端产物再用golang:1.27.1-alpine3.23以release,embed_frontend,docker标签编译后端并嵌入前端资源最后落到alpine:3.24单体镜像内置 PostgreSQL 组件默认以--port 8080 --data /var/opt/bytebase启动并提供/healthz健康检查。这解释了 Helm 模板中默认数据目录与端口取值的来源。自动化脚本仓库提供了 push-to-acr.sh一键完成镜像检查、ACR 登录、打标、推送与仓库验证./scripts/azure-marketplace/push-to-acr.sh该脚本内置了ACR_NAMEbytebase、ACR_LOGIN_SERVERbytebase.azurecr.io、BYTEBASE_VERSION3.11.1等默认配置使用前请按你的实际 ACR 名称调整。脚本会依次检查本地镜像是否存在、Azure CLI 是否安装、执行az acr login、docker tag、docker push最后用az acr repository show与az acr repository show-tags验证推送结果。六、Step 4按你的 ACR 修改 manifest.yaml编辑 manifest.yaml把镜像与注册表替换为你自己的 ACRregistries: - name: your-acr-name.azurecr.io url: your-acr-name.azurecr.io images: - image: your-acr-name.azurecr.io/bytebase/bytebase:3.11.1 platform: linux/amd64该文件是 CPA 工具的入口配置其余关键字段以仓库默认值为例含义如下字段默认值说明applicationNamebytebase应用名将作为扩展类型名的一部分version3.11.1与镜像 tag、Helm Chart 中的版本保持一致helmChart../helm-charts/bytebase指向 Helm Chart 目录必须是解包后的目录而非 .tgzclusterArmTemplatemainTemplate.json集群级 ARM 模板uiDefinitioncreateUiDefinition.json门户部署 UI 定义registryServerbytebase.azurecr.io应用镜像所在注册表extensionRegistrationParametersnamespace 为bytebase、extensionType: bytebase、releaseTrain: stableAKS 集群扩展注册参数clusterTypes[managedClusters]支持的集群类型可选managedClustersAKS或connectedClustersArc 启用集群七、Step 5用 CPA 工具构建并发布 CNAB Bundle自动化脚本推荐cd scripts/azure-marketplace ./package.shpackage.sh 的完整执行流程为检查docker、az、helm是否安装az/helm缺失仅告警校验 6 个必需制品是否存在manifest.yaml、createUiDefinition.json、mainTemplate.json、values-azure.yaml、helm-charts/bytebase/Chart.yaml、helm-charts/bytebase/values.yaml拉取mcr.microsoft.com/container-package-app:latest以仓库根目录挂载到容器的/data执行cpa verify校验制品交互式询问是否继续确认后执行cpa buildbundle构建并上传 CNAB 到 ACR。手动流程Step 5a校验制品docker run --rm \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $(pwd):/data \ -w /data/scripts/azure-marketplace \ mcr.microsoft.com/container-package-app:latest \ cpa verifyStep 5b构建并发布 CNAB Bundle关键注意点CPA 工具自身必须完成推送手动docker push无法生成 Partner Center 所需的 CNAB/OCI 清单格式。且cpa buildbundle需要 Azure CLI 认证必须把本地 Azure 凭据挂载进容器# 确保已登录 az login az acr login --name your-acr-name # 挂载 Azure 凭据运行 CPA docker run --rm \ -v /var/run/docker.sock:/var/run/docker.sock \ -v $(pwd)/..:/data \ -v $HOME/.azure:/root/.azure \ -w /data/scripts/azure-marketplace \ mcr.microsoft.com/container-package-app:latest \ /bin/bash -c az acr login --name your-acr-name cpa buildbundle --force该命令会把 Helm Chart ARM 模板 UI 定义打包为 CNAB创建带正确 OCI 注解的 Porter 调用镜像以 CNAB 兼容清单发布到 ACR最终产物 tag 为your-acr-name.azurecr.io/bytebase:3.11.1。验证产物az acr manifest show --registry your-acr-name --name bytebase:3.11.1 | grep io.cnab应看到类似注解io.cnab.runtime_version: 1.2.0、org.opencontainers.artifactType: application/vnd.cnab.manifest.v1。常见认证问题CPA 无法访问 Docker 凭据、Azure CLI 会话未正确挂载、ACR 权限未配置。核心原则是——必须由 CPA 工具执行推送手动docker push生成的 Docker v2 清单会被 Partner Center 拒绝。八、Step 6测试部署 UIcreateUiDefinition提交前先在 Azure 门户的CreateUI Sandbox中验证部署表单打开 Azure 门户的 CreateUIDefinition Sandbox 页面将 createUiDefinition.json 内容粘贴并测试整个表单流程确认所有字段、校验规则与输出映射正确。从 createUiDefinition.json 的源码可以看到表单由三个步骤构成这些输出会直接映射到 mainTemplate.json 的参数Basics基础信息通过ArmApiControl调用 AKS 列表接口以下拉框让用户选择目标 AKS 集群Bytebase ConfigurationKubernetes 命名空间默认bytebase、端口默认8080、外部访问 URL必填校验 HTTP/HTTPS 格式、Bytebase 版本默认3.11.1要求X.Y.Z格式Database Configuration提供两种 PostgreSQL 连接方式——连接串postgresql://user:passwordhost:5432/database或独立参数host、port、username、password、databasepassword 使用PasswordBox组件Storage Configuration是否启用持久化存储默认启用、存储大小默认10Gi支持Gi/Mi/Ti单位、存储类可留空使用默认。mainTemplate.json 中的Microsoft.KubernetesConfiguration/extensions资源会把上述参数通过configurationSettings映射为 Helm values如bytebase.version、bytebase.option.port、bytebase.option.external-url、bytebase.option.externalPg.url、bytebase.persistence.enabled等连接串优先、否则由独立参数拼接生成pgUrlValue同时预留了plan-name、plan-publisher、plan-offerID、releaseTrain等DONOTMODIFY占位变量发布时由市场平台自动替换。九、Step 7在 Partner Center 创建 Offer详细的逐字段操作指引见 PARTNER_CENTER_GUIDE.md这里给出快速概览访问 Partner Center登录 Partner Center 的 Commercial Marketplace 控制台创建 OfferCommercial Marketplace → New offer →Azure ContainerOffer IDbytebase永久不可修改需在发布者命名空间内唯一配置各分区Offer Properties属性主类别Databases、次类别Developer Tools以及法律文档标准合同或自定义条款、隐私政策 URLOffer Listing列表名称、摘要≤100 字符、短描述≤256 字符、长描述≤3000 字符、截图与 LogoPreview Audience预览受众添加测试订阅 IDTechnical Configuration技术配置选择 AKS 托管集群类型包类型选CNAB填入your-acr-name.azurecr.io/bytebase:3.11.1并点击Grant access授权微软访问你的 ACR 以复制镜像Plan Overview计划至少创建一个计划首次上线建议使用 BYOL 计划Review and publish提交进入认证流程。必需材料清单法律文档隐私政策与服务条款的公开 URL、Logo 文件48x48、90x90、216x216、255x115 的 PNG、截图至少 1 张、最多 5 张1280x720 或 1920x1080 的 PNG、支持联系方式。文档给出的预估认证周期为2-4 周。十、Step 8-9提审与发布在 Partner Center 中确认所有分区无红色告警后点击Review and publish提交认证过程中微软会对镜像做安全扫描、审查市场元数据、测试部署流程典型周期 2-4 周如需整改按反馈修复例如解决高危漏洞后重新提交认证通过后先在预览版中完成验收再点击Go live正式发布。发布后验证可使用预览订阅在 Azure 门户中搜索到该 Offer 并执行部署然后通过kubectl get pods -n bytebase与外部 URL 验证 Bytebase 实例正常。十一、发布前的本地部署测试正式提交前可用 values-azure.yaml 在本地集群验证 Helm Chart# 用 Azure values 安装 helm install bytebase-test ./helm-charts/bytebase \ -f scripts/azure-marketplace/values-azure.yaml \ --set bytebase.option.externalPg.urlpostgresql://user:passhost:5432/db \ --set bytebase.option.external-urlhttps://test.example.com \ --namespace bytebase \ --create-namespace # 验证部署 kubectl get pods -n bytebase kubectl logs -n bytebase -l appbytebase # 清理 helm uninstall bytebase-test -n bytebasevalues-azure.yaml 的关键取值可作为参数参考global.azure.images.bytebasetag: 3.11.1、image: bytebase/bytebase、registry: bytebase.azurecr.io——对应_helpers.tpl中最高优先级的镜像解析分支bytebase.option.externalPg支持直接提供url或提供pgHost/pgPort/pgUsername/pgPassword/pgDatabase由模板拼接连接串也可通过existingPgURLSecret/existingPgPasswordSecret引用已有 SecretescapePassword: false时启用密码转义对应 statefulset.yaml 中 initContainer 对密码做 URL 百分号编码的预处理逻辑bytebase.persistenceenabled: true、storage: 10Gi、storageClass留空使用默认存储类bytebase.resourceslimits 为 2000m CPU / 4Gi 内存requests 为 1000m / 1Gi可作为 BYOL 计划中建议 2 vCPU 4GB 内存的依据。十二、定价策略考量BYOL自带许可推荐首发优点上线快、实现简单、无需集成 Azure Metering API、定价调整灵活缺点计费不并入 Azure 账单需自建许可证管理体系。Marketplace 计量计费Metered Billing优点统一 Azure 账单、由 Azure 处理支付、更易获得企业客户信任缺点需要在应用中集成 Azure Metering API、实现与测试更复杂、认证周期更长。按原文档说明微软对可交易型 Offer 抽取约 20% 的平台佣金IP 联合销售co-sell资质可降至约 3%BYOL 类 Offer 也需缴纳约 3% 的列示费。具体费率请以微软现行政策为准。十三、关键约束CNAB Bundle 格式Partner Center 要求 CNAB Bundle 必须是正确的 OCI 制品格式而不是普通的 Docker v2 清单。这意味着✅ 必须由 CPA 工具cpa buildbundle发布❌ 手动docker push会生成错误的清单类型无法通过认证✅ Bundle 必须带io.cnab.runtime_version、org.opencontainers.artifactType等 OCI 注解。验证方式az acr manifest show --registry your-acr-name --name bytebase:3.11.1正确结果应包含annotations.io.cnab.runtime_version: 1.2.0annotations.org.opencontainers.artifactType: application/vnd.cnab.manifest.v1清单的mediaType: application/vnd.oci.image.manifest.v1json若看到mediaType: application/vnd.docker.distribution.manifest.v2json说明推送方式有误Partner Center 会报错The artifact you selected is not a valid Cloud Native Application Bundle (CNAB)。解决办法是删除错误产物按 Step 5b 的认证方式用 CPA 工具重新发布。十四、常见问题与解决方案问题原因/现象解决方案Partner Center 拒绝 Bundle报 not a valid CNAB用az acr manifest show检查格式若为 Docker v2 清单删除后用 CPA 工具非 docker push重新发布按 Step 5b 完成认证打包时拉取镜像失败ACR 未登录执行az acr login --name acr-namecpa buildbundle认证失败CPA 容器内无 Azure 凭据先az login、az acr login运行 CPA 时挂载-v $HOME/.azure:/root/.azurecpa verify校验失败Helm Chart 打包问题确保 Chart 是解包目录非 .tgz、Chart.yaml的apiVersion为v2仓库默认即 v2、模板引用有效门户 UI 不加载createUiDefinition 问题校验 JSON 语法、确认参数引用与 ARM 模板一致、分段注释排查安全扫描不过存在高危漏洞更新 Dockerfile 基础镜像、提交前本地docker scan、处理所有 HIGH/CRITICAL 漏洞十五、Offer 的版本更新发布后若要发布新版本构建带新版本 tag 的 Docker 镜像并推送到 ACR更新 manifest.yaml 中的版本与镜像引用重新执行cpa buildbundle生成新 CNAB在 Partner Center 中更新 Technical Configuration 的 CNAB 路径、递增计划版本重新提交认证。总结将 Bytebase 发布到 Azure Marketplace 的完整链路可以概括为改造 Helm Chart 支持 Azure 镜像覆盖 → 推送应用镜像到 ACR → 配置 manifest 与 ARM/UI 定义 → 用 CPA 工具构建 CNAB 制品 → 在 Partner Center 创建 Offer 并提审。其中两个最关键的坑位是镜像引用必须走global.azure.images模式当前仓库已通过 _helpers.tpl 的模板函数封装好以及 CNAB 制品必须由 CPA 工具发布到 OCI 格式。按照本文步骤与仓库中 package.sh、push-to-acr.sh 两个脚本配合操作即可完成从打包到上线的全流程。【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考