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

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

## 背景

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

本文适用于 Azure 7.x 环境升级到 8.x。新建环境请参考 [在 Azure 上安装 AutoMQ](../getting-started/install-byoc-environment/install-env-on-azure)。

## 约束

* 当前 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 前必须启用。

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

```bash theme={null}
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。

可以使用以下命令核对身份和绑定范围：

```bash theme={null}
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/](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`：

```bash theme={null}
CONSOLE_HOME="<host-mount-source-from-generated-command>"
findmnt -T "$CONSOLE_HOME"
test -r "$CONSOLE_HOME/.cmp/data/sqlite.db"
```

### 4. 停止旧版控制台

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

```bash theme={null}
sudo systemctl stop cmp.service
sudo systemctl status cmp.service --no-pager
```

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

```bash theme={null}
sudo systemctl disable cmp.service
```

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

```bash theme={null}
ps -ef | grep -E 'cmp|java' | grep -v grep
ss -ltnp | grep -E ':8080|:8085' || true
```

### 5. 备份数据库

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

```bash theme={null}
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"/
```

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

```bash theme={null}
ls -lh "$backup_dir"
echo "$backup_dir"
```

### 6. 安装 Docker

请根据 Azure Console VM 操作系统参考 [Docker Engine 官方安装说明](https://docs.docker.com/engine/install/)完成安装，然后确认 Docker 已启动：

```bash theme={null}
sudo systemctl start docker
sudo systemctl enable docker
sudo docker version
```

### 7. 启动 AutoMQ 控制台

复制第三步展示的 Azure 升级安装命令，直接启动新版本的 AutoMQ 控制台。以下命令仅说明启动形态；`<complete-base64-config>` 和镜像地址必须来自同一条生成命令。

生成的命令包含凭据。请勿共享该命令，也不要将其保存在共享的 shell history 中。

```bash theme={null}
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 容器状态和日志：

```bash theme={null}
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 服务。

```bash theme={null}
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 页面补齐推荐权限。