Azure BYOC 控制台升级 8.x 版本操作指南

背景

AutoMQ Console 8.x 使用 Docker 镜像分发和启动。对于已经在 Azure 上运行的旧版本 AutoMQ BYOC 环境，升级目标是在保留原有环境数据和实例的前提下，将控制台服务迁移到 Docker 镜像模式。本文适用于 Azure 7.x 环境升级到 8.x。新建环境请参考在 Azure 上安装 AutoMQ。

约束

当前 Azure BYOC 环境使用 AKS 作为数据面 Kubernetes 集群。
升级前请确认原有 AKS 集群、节点池、VNet、Subnet、Azure Private DNS Zone、Storage Account 和 Blob containers 等云资源仍存在。
升级过程需要 AutoMQ 技术人员协助生成 Azure 环境元数据和 Docker 启动参数。
本文中的 Azure 资源名称来自示例环境；实际环境请以 Terraform output 和 Azure 资源为准。

升级前检查

确认以下信息：

控制台 VM 可 SSH 登录。
原控制台数据目录仍存在，例如 /home/admin/.cmp/data，且其 host path 位于已挂载的持久盘。
环境 ID 和部署 Region 与当前环境一致。
控制台 VM 绑定的 User-assigned Managed Identity 仍是 AutoMQ 控制台使用的身份。
包含控制台 home directory 的持久盘已挂载，且 SQLite 数据库的 -wal、-shm 文件可访问。

检查 AKS 身份配置

升级控制台前，检查 AKS 身份配置。在更新已有 Instance 到 8.x 或创建新的 8.x Instance 前，确保数据面身份所需的功能已启用：

Microsoft Entra integration：推荐启用。启用后，控制台可以使用 Console UAMI 访问 AKS，无需依赖静态 clusterAdmin kubeconfig。如果未启用，升级期间继续使用现有的静态管理员访问方式。
Azure RBAC for Kubernetes Authorization：启用 Microsoft Entra integration 时推荐启用。启用后，可以通过 Azure IAM 管理控制台的 Kubernetes 权限。如果未启用，升级后可以由集群管理员为 Console UAMI 对应的 principal 创建并维护 Kubernetes ClusterRoleBinding。
OIDC issuer：Instance 使用 Azure Workload Identity 前必须启用。
Workload Identity：Instance 使用 Azure Workload Identity 前必须启用。

使用以下命令检查这四项配置：

az aks show \
  --resource-group <aks-resource-group> \
  --name <aks-name> \
  --query '{entraIntegration:aadProfile.managed,azureRbac:aadProfile.enableAzureRbac,oidcIssuer:oidcIssuerProfile.enabled,workloadIdentity:securityProfile.workloadIdentity.enabled}' \
  -o yaml

执行 Instance update 前，确认 oidcIssuer 和 workloadIdentity 均为 true。同时建议将 entraIntegration 和 azureRbac 设置为 true。升级控制台前不需要补充新的 8.x 权限；保持现有 Console UAMI 权限和数据面身份不变。控制台升级本身不要求修改现有 workload UAMI 及其权限。新建 8.x Instance 时，需要配置 subject 与 Kubernetes ServiceAccount 匹配的 AKS OIDC Federated Identity Credential。可以使用以下命令核对身份和绑定范围：

az vm show -g <resource-group> -n <console-vm> --query identity
az network private-dns zone show -g <resource-group> -n <private-dns-zone>
az storage account show -g <resource-group> -n <storage-account>

如果升级后控制台提示需要初始化权限，请按照页面中的 Azure 权限说明，为控制台 User-assigned Managed Identity 补齐授权。

7.x 版本创建的 Azure AKS 集群可能仍通过 node pool VMSS 的身份访问 Azure 资源。升级控制台本身不要求立即修改已有 node pool 的 VMSS identity 或 Workload Identity 配置。对于已有 7.x 集群，应先保持原有数据面授权不变，避免升级过程中影响正在运行的数据面。新建 8.x Instance 使用 Azure Workload Identity。

升级步骤

整体步骤分为：注册 AutoMQ 账号、确认部署信息、获取升级命令、停止旧版控制台、备份数据库、安装 Docker、启动并验证新版本控制台、更新 License。

1. 注册组织和账号

前往 AutoMQ 官网注册组织和账号：https://console.automq.cloud/。注册后，将组织 ID 提供给 AutoMQ 技术人员。

2. 确认部署信息

确认当前 BYOC 控制台的部署信息，并发送给 AutoMQ 技术人员，用于迁移环境元数据和生成安装命令。需要收集的信息包括：

环境 ID
部署 Region
当前控制台版本
安装 ID
控制台访问地址
Azure Subscription ID
Resource Group、AKS 名称
Storage Account 和 ops Blob container
控制台 VM 的 User-assigned Managed Identity

建议登录旧版 AutoMQ 控制台，前往设置页面查看环境 ID、安装 ID 和版本。Azure 资源信息可以从 Terraform output、Azure Portal 或 Azure CLI 中确认。

3. 获取升级命令

AutoMQ 技术人员会基于当前环境信息，在 AutoMQ Cloud 中创建或补齐环境记录，并生成 Azure 8.x 升级安装命令。该命令包含完整的 Base64 CONFIG、CLOUD_PROVIDER=azure、初始管理员信息和 Docker 镜像地址。请直接复制完整命令，不要解码、拆分或手工拼接 CONFIG。执行前请让 AutoMQ 技术人员确认该命令对应当前环境和目标版本。记录生成命令中的 host mount source，并在后续命令中复用。确认 host mount source 位于持久盘，且 container target 是 /root：

CONSOLE_HOME="<host-mount-source-from-generated-command>"
findmnt -T "$CONSOLE_HOME"
test -r "$CONSOLE_HOME/.cmp/data/sqlite.db"

4. 停止旧版控制台

登录控制台 VM，停止旧版控制台服务。这样可以避免旧进程在备份期间继续写入数据库，也可以避免两个控制台进程同时占用端口。

sudo systemctl stop cmp.service
sudo systemctl status cmp.service --no-pager

如果旧服务配置了自动拉起，建议在升级窗口内临时禁用：

sudo systemctl disable cmp.service

确认旧进程和端口已经释放：

ps -ef | grep -E 'cmp|java' | grep -v grep
ss -ltnp | grep -E ':8080|:8085' || true

5. 备份数据库

停止旧版控制台后，备份本地 SQLite 数据库。通配符会同时包含 WAL/SHM 文件。

ts=$(date -u +%Y%m%dT%H%M%SZ)
backup_dir="$CONSOLE_HOME/cmp-migration-backup-$ts"
mkdir -p "$backup_dir"

sudo cp -a "$CONSOLE_HOME"/.cmp/data/sqlite.db* "$backup_dir"/

确认备份文件已经生成，并记录备份目录，供回滚时使用：

ls -lh "$backup_dir"
echo "$backup_dir"

6. 安装 Docker

请根据 Azure Console VM 操作系统参考 Docker Engine 官方安装说明完成安装，然后确认 Docker 已启动：

sudo systemctl start docker
sudo systemctl enable docker
sudo docker version

7. 启动 AutoMQ 控制台

复制第三步展示的 Azure 升级安装命令，直接启动新版本的 AutoMQ 控制台。以下命令仅说明启动形态；<complete-base64-config> 和镜像地址必须来自同一条生成命令。生成的命令包含凭据。请勿共享该命令，也不要将其保存在共享的 shell history 中。

sudo docker run -d \
  --name automq-cmp \
  --restart unless-stopped \
  -v "$CONSOLE_HOME:/root" \
  --net=host \
  -e CONFIG="<complete-base64-config>" \
  -e CLOUD_PROVIDER=azure \
  -e CONSOLE_INITIAL_USER=admin \
  -e CONSOLE_INITIAL_PASSWORD="<strong-initial-password>" \
  <image-from-generated-command>

执行升级安装命令后，检查 Docker 容器状态和日志：

sudo docker ps
sudo docker logs -f automq-cmp

观察到 Docker 容器正常运行，且 8080 端口正常联通，即可通过浏览器访问 AutoMQ 控制台服务。

8. 验证升级结果

在执行任何 Instance update 前，完成以下检查：

控制台展示的 Environment ID、Region 和 Console version 与目标环境一致。
原有 Instances 均可见，并保持升级前的健康状态。
System Initialization 状态正常。升级完成后打开该页面，按照页面当前要求为 Console UAMI 补充角色和 scope；升级前不需要预先补齐这些 8.x 权限。
Console logs 中没有持续的数据库、Azure authentication 或 cloud resource permission 错误。
原有 AKS workloads 保持健康，且现有业务 Kafka 连接正常。

完成这些检查前，不要修改或升级 Instance。此时如果验证失败，仍可按下方方案回滚控制台；执行 Instance update 后需要先联系 AutoMQ 技术人员判断云资源状态。

9. 更新 License

由于 8.x 更换了安装介质和启动方式，新版本安装 ID 可能发生变化。登录新版本控制台后，如果页面提示 License 失效，请复制页面展示的安装 ID，并联系 AutoMQ 技术人员更新 License 信息。

升级过程中出现 License 失效提示，不会影响已有集群继续运行。

回滚方案

如果 Docker 启动或 Instance update 前的验证失败，且尚未执行 Instance update，停止并移除新的 Docker 容器，恢复 SQLite 备份，然后启动原 systemd 服务。

sudo docker rm -f automq-cmp
backup_dir="<backup-directory-from-step-5>"
sudo cp -a "$backup_dir"/sqlite.db* "$CONSOLE_HOME/.cmp/data/"
sudo systemctl enable cmp.service
sudo systemctl start cmp.service
sudo systemctl status cmp.service --no-pager

如果已经执行过实例更新，请先联系 AutoMQ 技术人员确认 Helm release、AKS/Kubernetes 资源、Azure RBAC、Blob 和 Private DNS 状态，再决定是否回滚数据库。不要在不了解云资源终态时直接覆盖数据库。

常见问题

Docker 容器无法启动

检查以下事项：

Docker 镜像是否能拉取。
8080 或 8085 端口是否被旧进程占用。
$CONSOLE_HOME 是否正确挂载到容器 /root，且仍位于持久盘。
SQLite 文件权限是否允许容器读取。
Azure Managed Identity 是否能读取 AKS、Private DNS 和 Blob 资源。

控制台启动后提示权限不足

检查以下事项：

控制台 VM 绑定的 User-assigned Managed Identity 是否正确。
Managed Identity 是否具备读取 AKS、VMSS、Private DNS、VNet、Subnet 和 Storage Account 的权限。
Blob endpoint 与 ops container 是否匹配。
Private DNS Zone 是否已链接到正确的 VNet。
是否已按照控制台 system-init 页面补齐推荐权限。

产品介绍

快速开始

AutoMQ on Kubernetes

订阅和计费

管理环境

管理账号成员

管理 AutoMQ

迁移到 AutoMQ

安全配置

Kafka Connect

监控报警

Table Topic

最佳实践

消除跨可用区数据传输

版本记录

服务支持

附录

Azure BYOC 控制台升级 8.x 版本操作指南

背景

约束

升级前检查

检查 AKS 身份配置

升级步骤

1. 注册组织和账号

2. 确认部署信息

3. 获取升级命令

4. 停止旧版控制台

5. 备份数据库

6. 安装 Docker

7. 启动 AutoMQ 控制台

8. 验证升级结果

9. 更新 License

回滚方案

常见问题

Docker 容器无法启动

控制台启动后提示权限不足

​背景

​约束

​升级前检查

​检查 AKS 身份配置

​升级步骤

​1. 注册组织和账号

​2. 确认部署信息

​3. 获取升级命令

​4. 停止旧版控制台

​5. 备份数据库

​6. 安装 Docker

​7. 启动 AutoMQ 控制台

​8. 验证升级结果

​9. 更新 License

​回滚方案

​常见问题

​Docker 容器无法启动

​控制台启动后提示权限不足

背景

约束

升级前检查

检查 AKS 身份配置

升级步骤

1. 注册组织和账号

2. 确认部署信息

3. 获取升级命令

4. 停止旧版控制台

5. 备份数据库

6. 安装 Docker

7. 启动 AutoMQ 控制台

8. 验证升级结果

9. 更新 License

回滚方案

常见问题

Docker 容器无法启动

控制台启动后提示权限不足