AutoMQ Console 8.x 使用 Docker 镜像分发和启动。对于已经在 Google Cloud 上运行的旧版本 AutoMQ BYOC 环境，升级目标是在保留原有环境数据和实例的前提下，将控制台服务迁移到 Docker 镜像模式。
本文适用于 GCP 7.x 环境升级到 8.x。新建环境请参考 在 Google Cloud 上安装 AutoMQ。
- 当前 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 具备以下读取权限：
如果升级后控制台提示需要初始化权限，请按照页面中的 GCP 权限说明，为控制台 Google Service Account 补齐授权。
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 授权保持不变，避免升级过程中影响正在运行的数据面。
升级步骤
整体步骤分为：注册 AutoMQ 账号、确认部署信息、获取升级命令、停止旧版控制台、备份数据库、安装 Docker、启动新版本控制台、更新 License。
1. 注册组织和账号
前往 AutoMQ 官网注册组织和账号：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，停止旧版控制台服务。这样可以避免旧进程在备份期间继续写入数据库，也可以避免两个控制台进程同时占用端口。
如果旧服务配置了自动拉起，建议在升级窗口内临时禁用：
确认旧进程和端口已经释放：
5. 备份数据库
停止旧版控制台后，备份本地 SQLite 数据库。通配符会同时包含 WAL/SHM 文件。
确认备份文件已经生成，并记录备份目录，供回滚时使用：
6. 安装 Docker
请根据 VM 操作系统参考 Docker Engine 官方安装说明完成安装，然后确认 Docker 已启动：
如果镜像仓库需要登录，请先完成登录并确认可以拉取镜像。
7. 启动 AutoMQ 控制台
复制第三步展示的升级安装命令，直接启动新版本的 AutoMQ 控制台。下面的命令仅为 GCP Docker 启动示例，实际升级以第三步生成的命令为准。
生成的命令包含凭据。请勿共享该命令，也不要将其保存在共享的 shell history 中。
执行升级安装命令后，检查 Docker 容器状态和日志：
观察到 Docker 容器正常运行，且 8080 端口正常联通，即可通过浏览器访问 AutoMQ 控制台服务。
8. 更新 License
由于 8.x 更换了安装介质和启动方式，新版本安装 ID 可能发生变化。登录新版本控制台后，如果页面提示 License 失效，请复制页面展示的安装 ID，并联系 AutoMQ 技术人员更新 License 信息。
升级过程中出现 License 失效提示，不会影响已有集群继续运行。
回滚方案
如果 Docker 启动失败且尚未执行实例更新，可回滚到原 systemd 模式。
如果已经执行过实例更新，请先联系 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 页面补齐推荐权限。
