升级与迁移手册

本手册用于正式站升级、迁移和恢复时检查代码、数据库、缓存和回滚方案。

一、职责边界

升级不是简单覆盖文件。一次升级至少包含代码版本、数据库结构、模块插件状态、主题模板、静态资源和缓存状态。

项目	说明
代码版本	目标代码必须与数据库迁移版本匹配
数据库	先备份，再迁移，再验证
模块插件	检查启用状态、依赖版本和资源发布
主题模板	检查当前主题是否存在所需模板
缓存	升级后清理配置、路由、视图、模板和业务缓存

二、升级前检查

升级前建议确认：

• 当前站点可以正常登录后台。
• 已完成数据库备份和上传附件备份。
• 目标包不包含 .env、上传目录、日志、运行时缓存和本地测试文件。
• 目标代码版本高于或等于当前数据库所需版本。
• 模块和插件的 requires.tanzcms 与目标核心版本匹配。
• 当前数据库表前缀一致，不混用带前缀和不带前缀的业务表。

三、推荐流程

php artisan down
php artisan migrate --force
php artisan tanzcms:modules sync
php artisan tanzcms:plugins sync
php artisan optimize:clear
php artisan tanzcms:template-clear
php artisan up

如果站点没有启用某类能力，可以跳过对应同步命令。命令里的 php 应使用目标站点实际运行的 PHP。

四、数据库迁移

迁移前必须确认目标库和当前站点一致。不要把测试库导入正式库，也不要把正式库导入错误的开发库。

迁移失败时不要反复执行未知 SQL。先记录：

• 失败迁移文件名。
• 失败 SQL 或错误码。
• 当前 migrations 表状态。
• 是否存在重复表、缺字段或前缀不一致。

五、表前缀检查

同一站点内业务表应统一使用数据库连接配置的表前缀。发现同时存在 tz_xxx 和 xxx 时，应先判断哪一组是当前系统实际使用的数据，再做迁移或清理。

不要通过手工改 SQL 的方式把一部分表改成带前缀、一部分表保持不带前缀。

六、回滚策略

升级前至少保留：

• 代码包备份。
• 数据库备份。
• 上传附件备份。
• 当前 .env 或站点配置备份。

如果升级失败，优先回滚到同一时间点的代码和数据库组合，避免新代码配旧库或旧代码配新库。

七、升级后验收

升级完成后至少访问：

• 首页。
• 栏目页。
• 内容详情页。
• 搜索页。
• 登录注册页。
• 会员中心。
• 后台首页。
• 模块和插件关键页面。

并执行健康检查、路由检查和缓存清理确认。