Clara BBS 升级指南：上传新代码后数据库升级怎么做

Clara BBS 升级只需两步：覆盖上传新代码文件，然后进后台「系统工具 → 数据库升级」点一次执行即可，增量 DDL 幂等可重复执行，新增的列和表会自动补齐。

为什么必须执行数据库升级

结论：Clara BBS 的升级分成「文件」和「数据库结构」两条线，只传文件不执行升级，新功能会因为缺字段、缺表而报错。

新版代码里会引用新增的数据库列或表（比如新加的某个配置项、某张统计表）。这些结构变更被打包成一串增量 DDL 语句放在系统工具里，只有你手动点一次执行，程序才会去比对当前库结构，把缺的补上。所以「文件已更新但功能打不开」几乎都是漏了这一步。

它和很多系统不一样的地方在于：不需要 Composer、不需要命令行、不需要编译缓存，所以升级不涉及依赖安装和构建流程，风险点基本只剩「有没有执行数据库升级」这一件事。

具体操作步骤

结论：按「备份 → 覆盖上传 → 执行升级 → 核对」四步走，全程在后台完成，不需要 SSH。

1. 备份数据库。进宝塔或 phpMyAdmin 导出一份 SQL 备份，这是唯一的后悔药。文件层面也建议保留一份旧版本压缩包。
2. 覆盖上传新代码。用面板文件管理或 FTP，把新版本文件覆盖到网站根目录。注意 `config` 之类的配置目录和 `uploads` 附件目录通常不要用旧包覆盖，按官方发布说明处理。
3. 执行数据库升级。登录后台 → 「系统工具」→ 「数据库升级」，点执行一次即可。等待提示完成。
4. 核对版本与功能。刷新前台确认能正常打开，进后台「系统设置→GEO 优化」等页面看看新增项是否出现，再随手发一帖验证写入正常。

幂等设计意味着什么

结论：数据库升级是幂等的，重复执行不会重复建表或重复加列，所以「不确定有没有点过」时，再点一次比不点更安全。

幂等（同一操作执行多次，结果与执行一次相同）是这套升级机制的核心保障。系统工具执行时是「先检测、后补齐」的逻辑：该列已存在就跳过，不存在才加。因此即使你中途刷新了页面、担心第一次没跑完，重跑一次也不会产生副作用，更不会把已有数据清空。

顺带一提：增量 DDL 只做「加」不做「删」，所以升级不会因为版本变化而丢掉你的帖子、用户和配置数据。

常见问题与注意点

结论：升级出问题，九成出在环境或缓存层，而不是升级脚本本身。

• 环境要求：PHP 7.4–8.5、MySQL 5.7+。如果服务器 PHP 版本过低，先升级 PHP 再覆盖新代码，否则可能出现白屏或语法错误。
• 页面报「页面已过期，请刷新后重试」：这是 CSRF 校验未通过（防跨站请求伪造的令牌校验），后台长时间停留后容易出现。刷新页面重新登录再执行即可。
• 确认站点地址正确：后台「基本设置」里的站点地址要带 `https://` 且用主域名，避免 www 和裸域混用导致登录态丢失，进而在后台操作时反复掉线。
• 改完即生效：Clara BBS 是运行时插件钩子体系，保存即生效、无需清缓存；如果确实怀疑缓存，可去「系统工具→缓存清理」手动清一次。
• 插件同步更新：如果你用了 AI 智能回复、GEO 问答工厂等官方插件，注意 `content/plugins` 目录下插件文件是否也需要一并更新到新版本。

收尾

升级 Clara BBS 的动作就一句话：覆盖上传新代码后，到后台「系统工具 → 数据库升级」执行一次，增量 DDL 幂等，重复执行无副作用。真正要上心的是两件事——升级前备份数据库，以及确认服务器 PHP 7.4+ / MySQL 5.7+ 达标。做完这两件，升级基本不会翻车。