魔方财务通用升级检查与修复工具使用教程

升级魔方财务时，如果遇到“数据库升级失败，版本号未推进”，或者升级完成后想检查数据库是否缺少表、字段和索引，可以使用本工具进行检查。

工具使用独立入口 repair.php，不修改原来的官方升级脚本和 SQL 文件。打开页面会先校验，只有用户确认后才执行升级或补齐操作。

一、使用前须知

本工具会修改数据库，请先在测试环境验证，并备份数据库和网站文件。

本工具已完成实际环境测试，升级、结构校验及页面提示运行正常。正式使用前，仍请备份数据库和网站文件，建议先在测试环境验证与当前站点的兼容性。

“通用”主要指自动读取官方版本记录、识别待升级 SQL，以及检查可识别的数据库结构。如果后续官方增加 PHP 业务迁移，仍需适配，不能保证所有未来版本直接可用。

二、准备升级文件

正式操作前：

1. 备份完整数据库，保留可恢复的备份文件。
2. 备份网站程序及数据库配置文件。
3. 暂停网站写入和定时任务，避免升级期间产生新订单或其他数据。
4. 按官方要求上传完整升级包。

如果只是检查已经升级完成的网站，请保留该版本对应的官方升级文件。

三、上传修复工具

解压修复包，将以下 4 个 PHP 文件上传到网站的 public/upgrade 目录：

文件	用途
repair.php	检查与修复入口
repair_helpers.php	SQL 解析、结构对比和页面展示
repair_catalog.php	读取版本记录、确定待升级文件
repair_config.php	访问密码及兼容配置

原目录中的这些文件保持不动：

• upgrade.php
• upgrade.log
• 各版本的 .sql 文件
• 官方升级页面及其他资源

不要上传 ACCESS_PASSWORD.txt。 该文件包含访问密码，只能保存在本地。README.md 是说明文件，也不需要上传。

服务器上的站点私有 data 目录必须存在且可写，用于保存执行状态记录。

四、打开检查页面

浏览器访问：

https://你的域名/upgrade/repair.php

例如网站域名是 example.com，访问地址就是：

https://example.com/upgrade/repair.php

首次访问需要输入 ACCESS_PASSWORD.txt 中的密码。建议通过 HTTPS 访问，并在服务器上限制升级目录仅管理员可访问。

密码验证有效期为 30 分钟。同一会话连续输错 5 次，会暂停尝试 5 分钟。

工具密码只保护修复入口，不会替官方原升级入口设置访问限制。

五、查看自动校验结果

验证后，页面会自动读取官方 upgrade.log，识别数据库当前版本和升级包目标版本，并展示可识别结构的检查结果。

页面状态	含义	建议操作
已存在／检查通过	检查项已存在，所检查的结构符合预期	无需补齐该项
缺失／待修复	缺少可识别的表、字段或索引	备份后确认修复
差异／需核对	已有结构与预期存在差异	人工核对，不强制修改

可以搜索表名或字段名，也可以筛选“只看待修复”或“只看需核对”。

页面统计按检查项计算，包含表、字段和索引。缺少整张表时，其字段和索引也会分别列出。

“已存在”说明当前检查通过，不能判断它是在什么时候升级的。

六、判断是否需要执行

当前版本低于目标版本

页面会显示待执行版本。即使已检查的表结构没有缺失，仍可能需要执行官方数据迁移和必要的业务迁移。

确认已上传完整官方升级包、完成备份后，再执行升级。

当前版本已经达到目标，且没有缺失或差异

页面会提示“无需升级或修复”，隐藏执行按钮，不重复执行升级 SQL。

当前版本已达到目标，但仍有缺失结构

页面会列出缺失项。用户确认后，工具尝试补齐可识别建表定义中的缺失表、字段和索引。

当前版本已达到目标，仅有人工核对项

工具不会为了这些差异重复执行升级 SQL。请核对已有字段类型或索引定义，再决定是否需要人工处理。

提示官方升级程序发生变化

工具会暂停升级，要求核对新增或变更的 PHP 业务迁移。

不要仅修改配置中的文件指纹来绕过提示。 应先检查官方升级逻辑，补充必要适配后再更新兼容配置。

七、确认执行升级或修复

需要执行时：

1. 查看页面上的版本和差异信息。
2. 确认数据库、网站文件已备份，并暂停网站写入。
3. 勾选确认选项。
4. 点击修复或升级按钮。
5. 在弹窗中再次确认。

执行期间请等待，不要重复点击、刷新页面或关闭请求。

执行确认有效期为 15 分钟。工具会绑定当前版本、目标版本、SQL 内容和配置；这些信息发生变化后，需要重新校验并确认。

八、完成后的检查与清理

执行完成后，工具会重新检查结构，并回读版本配置，显示复核结果。

完成后依次操作：

1. 确认版本已达到目标。
2. 查看是否仍有需要人工核对的差异。
3. 检查后台登录、订单、产品和其他关键功能。
4. 手动删除服务器上的整个 public/upgrade 目录。
5. 再访问官方升级入口和 /upgrade/repair.php，确认页面已经不存在或被拒绝访问。
6. 确认网站正常后，恢复定时任务和网站写入。

关闭浏览器页面不会删除升级文件。工具不会自动删除网站目录。

九、升级失败怎么办

如果页面提示失败，请记录失败阶段，并查看服务器 PHP 错误日志。

不要连续重复执行。MySQL 已完成的建表、字段修改等操作，可能无法通过事务回滚。

工具会在站点私有 data 目录保存类似下面的执行标记：

repair-state-xxxxxxxxxxxxxxxxxxxxxxxx.json

如果执行异常中断，标记会保留，并阻止自动重试。它用于提示执行未确认完成，不是自动续跑记录。

正确处理方式是：

1. 保留数据库备份、错误日志和执行标记。
2. 核对失败原因及已经执行的操作。
3. 恢复备份，或者由维护人员确认数据库状态。
4. 确认可以重新执行后，再手动删除对应标记并重新校验。

不要未排查就删除执行标记。 在排查完成前，也不要急于删除整个升级目录。

十、检查范围与限制

工具检查可识别建表定义中的表、字段是否存在、字段类型，以及索引字段顺序和唯一性。

以下内容不保证完整校验或自动修复：

• 业务数据是否正确。
• 字段默认值、注释和字符集。
• 加密 PHP 迁移内部的变更。
• 后续 ALTER、DROP、RENAME 改变过的历史表结构。
• 所有未来官方版本的特殊升级逻辑。

校验通过表示当前可识别范围通过，不代表整个网站和所有历史迁移都已完整验证。