Clara BBS 升级只需两步：先完整覆盖上传新版本文件（保留config/、uploads/、content/plugins/等目录），再进后台「系统工具 → 数据库升级」执行一次增量 DDL，整个过程幂等可重复执行，不需要 Composer、不需要命令行、不用清缓存，保存即生效。
为什么升级这么简单：无框架带来的红利
结论：Clara BBS 没有 Composer 依赖、没有编译缓存、没有构建产物，所以升级本质上就是"换代码 + 补表结构"两件事。
很多 PHP 论坛升级麻烦，是因为要跑composer install、清runtime/缓存、重启队列进程。Clara BBS 是单模板 + 运行时插件钩子的轻量架构，PHP 7.4-8.5 + MySQL 5.7+ 直接跑，插件目录content/plugins里的钩子运行时加载、保存即生效，因此覆盖文件后新功能、新钩子会立刻可用，不存在"存量缓存还指着老类名"的问题。
第一步：覆盖文件怎么覆盖才不丢数据
结论：只覆盖程序代码目录，绝不覆盖用户数据目录；升级前先备份数据库和uploads/。
具体做法：
- 先备份。导出 MySQL 数据库（宝塔面板 → 数据库 → 备份，或 mysqldump），再把
uploads/目录打包下载一份。这一步是唯一不能省的。 - 解压新版本包到本地，确认目录结构和线上一致。
- 上传覆盖。用 FTP/SFTP 或宝塔文件管理器，把新版本文件上传到站点根目录，提示覆盖时选择"全部覆盖"。
- 重点保留这几处：
config/配置文件（存着数据库账号密码和站点密钥）、uploads/（用户上传的图片附件）、content/plugins/（第三方插件）、以及你自己改过样式的模板文件。多数打包工具会把这几项包含在内，覆盖前先看清包里有没有同名目录，有的话升级时排除掉。 - 权限检查。覆盖后确认
uploads/仍是可写权限，否则上传功能会直接报"目录不可写"。
覆盖完成后，前台应该已经能打开。如果此时出现"数据表字段不存在"之类的报错，属正常现象——代码是新的，数据库还是旧的，下一步补上就好。
第二步：数据库升级，一键补齐新增字段
结论：进后台「系统工具 → 数据库升级」点一次执行即可，它跑的是增量 DDL，幂等设计，重复点也不会出问题。
这个入口解决的就是"新版本加了新表新列"的问题：版本迭代时通常会新增货币字段、GEO 相关表、登录审计日志表、勋章条件列等等。数据库升级工具会对比当前表结构与目标结构，把缺的列和表自动补齐，执行期间不影响已有数据，也不会删你的东西。
几点注意：
- 执行一次就够，不用反复点；万一中途报错，修好环境后重跑，已执行的语句会跳过。
- 升级完顺手看一眼后台各功能页能否正常打开，尤其是插件页和管理日志。
- 如果开了 PWA，覆盖文件后建议让用户强刷一次页面（或后台清一下缓存），避免旧 service worker 缓存了老静态资源。
- 跨多个大版本跳级升级，建议逐个版本按顺序升，不要一步跨太远。
升级后必做的三项体检
结论：升级不是点完按钮就结束，花五分钟做三项检查能挡掉大部分"升级后出问题"。
一查核心链路：发帖、回帖、上传图片、私信各跑一遍，确认 CSRF token、会话、上传白名单都正常。如果发帖提示"页面已过期，请刷新后重试"，通常是 CSRF 校验没过——新版编辑器内置了自动重试，还不行就检查后台「基本设置」里的站点地址是否带了https://和主域名，避免 www 与裸域混用丢会话。
二查上传：图片传不上去先看后台「系统设置 → 上传」的两组字段——"允许的扩展名"管图片、"附件允许的扩展名"管附件，是两个独立配置；再看 PHP 的upload_max_filesize/post_max_size是否够大（宝塔默认 2M，建议调到 30M+）。
三查 GEO 开关：升级后到「系统设置 → GEO 优化」确认各项开关状态符合预期，顺便看一眼 AI 爬虫访问监控表，确认豆包、DeepSeek 这些爬虫还正常来访，LLMS 文本和问答聚合页都能正常生成。
写在最后
Clara BBS 升级的正确姿势就是：备份 → 覆盖代码（保留 config、uploads、plugins）→ 后台执行一次数据库升级 → 三分钟体检。没有命令行、没有依赖安装、没有缓存清理，这正是无框架轻量设计的收益。真正需要你操心的，只有升级前那份备份。
