> ## 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.

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

## 背景

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

本文适用于 GCP 7.x 环境升级到 8.x。新建环境请参考 [在 Google Cloud 上安装 AutoMQ](/zh/automq-cloud/getting-started/install-byoc-environment/google-cloud/install-automq-on-gcp)。

## 约束

* 当前 GCP BYOC 环境仅支持部署到 GKE Standard。
* 当前不支持 GCP IaaS 和 GKE Autopilot。
* 升级前请确认原有 GKE 集群、节点池、VPC、Subnet、Cloud DNS private managed zone 等云资源仍存在。
* 升级过程需要 AutoMQ 技术人员协助生成环境元数据和 Docker 启动参数。

## 升级前检查

确认以下信息：

* 控制台 VM 可 SSH 登录。
* 原控制台数据目录仍存在，例如 `/home/admin/.cmp/data`。
* 环境 ID 和部署 Region 与当前环境一致。
* 当前 VM 绑定的 Google Service Account 仍是 AutoMQ 控制台使用的控制面身份。

GCP 升级过程中，控制台启动时需要读取部分云资源。建议确认控制台 Google Service Account 具备以下读取权限：

| 检查项                               | 推荐权限                                                                                      |
| --------------------------------- | ----------------------------------------------------------------------------------------- |
| 读取 Cloud DNS private managed zone | 至少具备 `dns.managedZones.get`。通常 `roles/dns.reader` 或 `roles/dns.admin` 可覆盖。                |
| 读取 GKE node pool                  | 至少具备 `container.nodePools.get`。通常 `roles/container.viewer` 或 `roles/container.admin` 可覆盖。 |
| 读取 Shared VPC 网络资源                | Shared VPC 场景下，需要在 Host Project 具备网络读取权限，例如 `roles/compute.networkViewer`。                |

<Tip>
  如果升级后控制台提示需要初始化权限，请按照页面中的 GCP 权限说明，为控制台 Google Service Account 补齐授权。
</Tip>

<Tip>
  7.x 版本创建的 GCP GKE 集群，数据面通常仍通过 node pool 绑定的 VM Service Account 获取云资源权限。只要该 node pool 仍使用 instance metadata，并且原 VM Service Account 的 GCS、Cloud DNS、Compute 等权限没有被移除，已有集群继续运行通常不会受到影响。

  8.x 引入的是新的 Workload Identity 权限模型：AutoMQ Pod 通过 Kubernetes ServiceAccount 绑定到实例 Google Service Account（GSA），再由该 GSA 访问 GCP 资源。该模型主要影响后续按 8.x 模式创建或更新的数据面权限配置。

  因此，升级控制台本身不要求立即修改已有 node pool 的 metadata 模式，也不要求立即移除 node pool VM Service Account 上的权限。对于已有 7.x 集群，应先保证原 node pool 授权保持不变，避免升级过程中影响正在运行的数据面。
</Tip>

## 升级步骤

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

### 1. 注册组织和账号

前往 AutoMQ 官网注册组织和账号：[https://console.automq.cloud/](https://console.automq.cloud/)。

注册后，将组织 ID 提供给 AutoMQ 技术人员。

### 2. 确认部署信息

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

* 环境 ID
* 部署 Region
* 当前控制台版本
* 安装 ID
* 控制台访问地址
* 控制台 Google Service Account

建议登录旧版 AutoMQ 控制台，前往设置页面查看上述信息。也可以从原启动脚本、systemd unit 或环境变量文件中确认。

### 3. 获取升级命令

AutoMQ 技术人员会基于当前环境信息，在 AutoMQ Cloud 中创建或补齐环境记录，并生成升级安装命令。该命令已经包含环境 ID、云厂商、Region、认证参数和 Docker 镜像地址等信息。

根据目标版本不同，升级安装命令可能使用显式环境变量，也可能使用 `CONFIG` 参数承载编码后的环境配置。请不要手工拼接这些参数。

执行前请确认命令中的云厂商、Region 和镜像版本与当前环境一致。如果镜像仓库需要登录，请同时确认已经获取 Docker registry 登录凭据。

### 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=/home/admin/cmp-migration-backup-$ts
mkdir -p "$backup_dir"

cp -a /home/admin/.cmp/data/sqlite.db* "$backup_dir"/
```

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

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

### 6. 安装 Docker

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

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

如果镜像仓库需要登录，请先完成登录并确认可以拉取镜像。

```bash theme={null}
sudo docker login <registry>
sudo docker pull <registry>/automq/automq_byoc_console:<version>
```

### 7. 启动 AutoMQ 控制台

复制第三步展示的升级安装命令，直接启动新版本的 AutoMQ 控制台。下面的命令仅为 GCP Docker 启动示例，实际升级以第三步生成的命令为准。

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

```bash theme={null}
sudo docker run -d \
  --name automq-cmp \
  --network host \
  -v /home/admin:/root \
  -e CLOUD_PROVIDER=gcp \
  -e REGION=us-central1 \
  -e ENVIRONMENT_ID=env-xxxx \
  -e OPS_BUCKET=automq-ops-xxxx \
  -e CLIENT_ID=env-xxxx \
  -e CLIENT_SECRET="<client-secret>" \
  -e CONSOLE_INITIAL_USER="<initial-user>" \
  -e CONSOLE_INITIAL_PASSWORD="<strong-initial-password>" \
  <registry>/automq/automq_byoc_console:<version>
```

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

```bash theme={null}
sudo docker ps
sudo docker logs -f automq-cmp
```

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

### 8. 更新 License

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

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

## 回滚方案

如果 Docker 启动失败且尚未执行实例更新，可回滚到原 systemd 模式。

```bash theme={null}
sudo docker rm -f automq-cmp
backup_dir="<backup-directory-from-step-5>"
cp -a "$backup_dir"/sqlite.db* /home/admin/.cmp/data/
sudo systemctl enable cmp.service
sudo systemctl start cmp.service
sudo systemctl status cmp.service --no-pager
```

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

## 常见问题

### Docker 容器无法启动

检查以下事项：

* Docker 镜像是否能拉取。
* Docker registry token 是否过期。
* 8080 或 8085 端口是否被旧进程占用。
* `/home/admin` 是否正确挂载到容器 `/root`。
* SQLite 文件权限是否允许容器读取。

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

检查以下事项：

* 控制台 VM 绑定的 Google Service Account 是否正确。
* 控制台 Google Service Account 是否具备读取 GKE、Cloud DNS、VPC、Subnet 等资源的权限。
* Shared VPC 场景下，Host Project 是否已授权网络读取权限。
* 是否已按照控制台 system-init 页面补齐推荐权限。