Halo 博客升级 MySQL 数据库指南 🚀

📌 导读：本文详细记录将 Halo 博客的 MySQL 数据库从 8.3.0 版本安全升级至 9.4.0 的完整操作流程。包含版本路线规划、数据备份、升级参数配置、健康检查及收尾操作，适用于生产环境下的平滑升级。

📋 导航目录

✨ 升级背景与注意事项
🔍 版本升级路线
📦 准备工作：查询可用版本标签
💾 关键第一步：整库逻辑备份（必做！）
⚙️ 跨主版本升级（8.4.2 → 9.0.1）
- 📝 修改 Docker 镜像标签
- ⚒️ 添加临时升级参数
🚀 执行升级操作
✅ 升级状态确认
🔧 收尾工作
💡 常见问题与总结

✨ 升级背景与注意事项

MySQL 8.x 至 9.x 属于跨主版本升级，涉及系统表元数据格式变更且升级过程不可逆。🔴 重要提示：生产环境升级前务必完成全量逻辑备份，避免数据丢失风险。

📝 升级特点：

✨ 性能提升：MySQL 9.x 优化了查询处理器，复杂查询性能提升显著；

🔒 增强安全：新增角色继承、密码验证策略强化等安全特性；

📊 JSON功能扩展：JSON数据类型支持更多函数和路径表达式；

💾 兼容性保障：9.0 版本兼容 8.4 的数据文件格式；

⚠️ 升级单向性：升级后会更新系统表结构以支持新特性，且不可回退；

🔧 参数要求：仅首次启动需添加 --upgrade=FORCE 参数，后续重启无需此操作。

🔍 版本升级路线

本次升级采用渐进式路径，确保兼容性稳定：

1	8.3.0 → 8.4.0 → 8.4.2 → 9.0.1 → 9.4.0

💡 提示：建议逐步升级，避免跨多个主版本直接升级，以减少意外错误。每个中间版本都解决了特定的兼容性问题，确保数据迁移的平稳性。

📦 准备工作：查询可用版本标签

使用以下命令列出所有官方 MySQL 镜像标签（8.x 和 9.x 系列），并按版本号排序：

# 查询官方仓库所有 tag（返回 JSON，用 jq 过滤更爽）
docker run --rm quay.io/skopeo/stable list-tags docker://mysql \
  | jq -r '.Tags[]' \
  | grep -E '^[8-9]\.' \
  | sort -V

🔍 功能说明：此步骤确保你获取到官方支持的所有版本标签，避免使用非稳定版或已废弃版本。建议优先选择标记为”latest”或”stable”的版本分支。

💾 关键第一步：整库逻辑备份（必做！）

⚠️ 警告：跳过备份可能导致数据无法回退！务必执行：

1	docker exec -it halodb mysqldump --all-databases --single-transaction -uroot -p'o#DwN&JSa56' > all_$(date +%F_%H-%M).sql

📌 参数说明：

--single-transaction：确保备份期间数据一致性，使用事务隔离机制；
-uroot -p'你的密码'：按实际数据库密码修改，建议使用配置文件避免密码暴露；
备份文件命名包含时间戳，便于版本管理；
🔒 安全建议：备份完成后将备份文件传输到远程存储或不同物理设备。

💡 扩展功能：考虑使用自动化备份脚本，定期执行并保留多个备份版本：

#!/bin/bash
BACKUP_DIR="/path/to/backup"
mkdir -p $BACKUP_DIR
docker exec halodb mysqldump --all-databases --single-transaction -uroot -p'password' | gzip > $BACKUP_DIR/all_$(date +%F_%H-%M).sql.gz
# 保留最近7天备份
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete

⚙️ 跨主版本升级（8.4.2 → 9.0.1）

📝 修改 Docker 镜像标签

编辑 docker-compose.yml，将 MySQL 镜像标签改为目标版本：

1	nano docker-compose.yml

# 修改前
image: mysql:8.4.2

# 修改后
image: mysql:9.0.1

📝 注意：确保使用的镜像标签存在且为官方稳定版本，避免使用latest标签可能导致的不兼容问题。

⚒️ 添加临时升级参数

在 command 部分临时添加 --upgrade=FORCE 参数：

command:
  - --upgrade=FORCE
  - --character-set-server=utf8mb4
  - --collation-server=utf8mb4_general_ci
  - --explicit_defaults_for_timestamp=true

🔧 参数详解：

--upgrade=FORCE：强制升级系统表结构，必需参数；
--character-set-server=utf8mb4：确保字符集与Halo博客兼容；
--collation-server=utf8mb4_general_ci：设置正确的排序规则；
--explicit_defaults_for_timestamp=true：解决TIMESTAMP字段的兼容性问题。

🚀 执行升级操作

拉取新版本镜像：
1
docker compose pull halodb
启动升级：
1
docker compose up -d halodb
观察升级日志（耗时约 1-3 分钟）：
1
timeout 180 docker compose logs -f halodb
✅ 成功标志：出现 [Server] /usr/sbin/mysqld: ready for connections. Version: '9.0.1' 且状态转为 healthy。

📊 升级过程监控：升级期间MySQL会执行以下操作：

检查现有数据文件的兼容性
升级系统表（mysql.*）到新格式
更新性能 schema 和 information_schema
验证所有数据库对象的完整性

✅ 升级状态确认

检查容器状态：
1
docker compose ps halodb

手动健康检查（如果状态未更新）：

1 2	docker exec halodb mysqladmin ping -h127.0.0.1 -uroot -p'o#DwN&JSa56' --silent echo $? # 返回 0 表示数据库正常运行

验证版本号：

1	docker exec -it halodb mysql -uroot -p'o#DwN&JSa56' -e "SELECT @@version;"

📌 输出应为：9.0.1

检查数据库完整性：

1	docker exec -it halodb mysqlcheck -uroot -p'o#DwN&JSa56' --all-databases

🔧 收尾工作

升级完成后务必删除临时参数 --upgrade=FORCE，避免下次重启再次执行升级流程：

编辑 docker-compose.yml，删除 --upgrade=FORCE 行；
重新部署：
1
docker compose up -d
验证常规启动：
1
docker compose logs halodb | grep -i "upgrade"
🚫 不应出现任何与upgrade相关的日志信息。