Flarum网站备份恢复全攻略：Ubuntu22.04+Cyberpanel环境，PHP8.4+Composer一步到位

（吐槽时间：网上那些教程动不动就“一键恢复”，结果不是权限爆炸就是Composer报错，看得我想砸键盘。所以这篇里我会把那些官方文档不说人话的地方全给你翻译成人话。）

写在前面：你需要的原材料

• ✔️ 一台装了Ubuntu22.04的VPS或者虚拟机（干净系统最好，省得环境冲突）
• ✔️ Flarum网站的根目录备份（比如 flarum_backup.zip 或者 tar.gz）
• ✔️ 数据库备份（一个 .sql 文件，从phpMyAdmin或者mysqldump倒出来的）
• ✔️ 一个不怕折腾的心 + 一杯续命咖啡

另外，Cyberpanel默认带的PHP版本可能不是8.4，但这货支持多PHP版本共存，所以咱们手动撸一个8.4出来。全程无需魔法上网，国内源照样跑。

第一步：安装Ubuntu22.04 + Cyberpanel（已知跳过，简单带过）

如果你还没装Cyberpanel，建议直接用官方一键脚本（这玩意儿安装时间够你刷10条抖音，耐心等）：

sh <(curl -sSL https://cyberpanel.net/install.sh) || sh <(wget -q -O - https://cyberpanel.net/install.sh)

安装时选择OpenLiteSpeed（默认就这个），数据库选MariaDB，其他一路默认。装完后访问 你的ip:8090 就能进面板了。注意：Cyberpanel安装过程会自动装好PHP7.4和8.1，但我们需要8.4，所以接着往下搞。

第二步：在Cyberpanel上手动安装PHP8.4（重点！）

Cyberpanel的应用商店没有直接提供PHP8.4的一键安装，但咱们可以用LiteSpeed的官方仓库来搞。SSH连上服务器，执行：

# 添加LiteSpeed仓库（支持Ubuntu22.04）
wget -O /etc/apt/trusted.gpg.d/lst_repo.gpg http://rpms.litespeedtech.com/debian/lst_repo.gpg
echo "deb http://rpms.litespeedtech.com/debian/ jammy main" > /etc/apt/sources.list.d/lst_repo.list
apt update

# 安装PHP8.4及相关扩展（Flarum必装的一堆）
apt install lsphp84 lsphp84-common lsphp84-mysqlnd lsphp84-mbstring lsphp84-zip lsphp84-gd lsphp84-curl lsphp84-dom lsphp84-xml lsphp84-tokenizer lsphp84-fileinfo

装完之后，LiteSpeed的PHP可执行文件在 /usr/local/lsws/lsphp84/bin/lsphp。接下来要去Cyberpanel里给网站指定PHP版本：进入面板 -> 网站列表 -> 你的域名 -> 修改PHP版本，选择“PHP 8.4 (LSAPI)”。如果下拉框没有8.4，先重启LiteSpeed：systemctl restart lsws。这里有个坑：你需要手动把网站目录的PHP handler改成lsphp84，否则Cyberpanel可能还用默认的。

第三步：安装Composer（PHP8.4版本）

Flarum的后台管理、扩展更新全靠Composer，但Cyberpanel默认不自带。很多小白直接 apt install composer 结果装成了系统PHP7.4版本的Composer，到时候一跑就报错。正确姿势：

# 下载最新Composer，并强制指定用PHP8.4执行
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
/usr/local/lsws/lsphp84/bin/php composer-setup.php
php -r "unlink('composer-setup.php');"
# 移到系统PATH
mv composer.phar /usr/local/bin/composer
chmod +x /usr/local/bin/composer
# 测试版本（会显示PHP8.4的信息）
composer --version

如果提示权限错误，直接 sudo 就完事了。注意：之后在Flarum根目录执行任何 composer require 都要确保用的是php8.4的cli，不然依赖安装会炸。你也可以强行改系统的默认php-cli版本（但不建议），或者用绝对路径 /usr/local/lsws/lsphp84/bin/php /usr/local/bin/composer 来执行。

第四步：恢复网站根目录文件

把你的备份压缩包传到服务器上，比如用Cyberpanel自带的文件管理器（在面板的“文件管理器”里上传），或者直接scp。假设Cyberpanel的网站默认目录是 /home/你的用户名/public_html/你的域名/，把压缩包解压进去：

# 假设压缩包叫 flarum_root.zip，放到网站根目录
unzip flarum_root.zip -d /home/你的用户名/public_html/你的域名/
# 如果备份包里有 .htaccess 或者 .user.ini，别删，但OpenLiteSpeed一般用 .htaccess 需要额外配置，后面再说

注意：Cyberpanel默认用LiteSpeed，Flarum的伪静态规则需要单独设置，稍后会在第五步补上。另外，文件所有者必须改成 nobody:nogroup 或者LiteSpeed运行的用户（一般是 nobody），否则会出现403或者500错误。直接执行：

chown -R nobody:nogroup /home/你的用户名/public_html/你的域名/

第五步：导入数据库备份

首先在Cyberpanel里新建一个数据库和用户（面板 -> 数据库 -> 创建数据库）。记下数据库名、用户名、密码。然后用 mysql 命令导入你的 .sql 文件：

mysql -u 数据库用户名 -p 数据库名 < /路径/你的备份.sql

如果备份文件超大，建议用 source 命令或者BigDump在线导入，不过一般小站没问题。导入成功后，记得修改Flarum的配置文件 config.php 里的数据库连接信息。文件位置：你的网站根目录/config.php，编辑：

'database' => [
    'driver' => 'mysql',
    'host' => 'localhost',
    'database' => '刚刚新建的数据库名',
    'username' => '数据库用户名',
    'password' => '数据库密码',
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix' => 'flarum_', // 如果你的旧表有前缀，保持一致
],

另外还要注意检查 url 这一项是不是你的新域名，如果不一致，论坛所有链接都会坏掉。直接改掉：

'url' => 'https://你的新域名.com',

（没有HTTPS就先别写https，用http）

第六步：配置LiteSpeed伪静态（Flarum专用）

这是重灾区！很多人的Flarum恢复后首页能打开，但点任何帖子都是404，就是因为没有配置伪静态。Cyberpanel里针对网站设置伪静态非常简单：进入面板 -> 网站列表 -> 你的域名 -> 伪静态（Rewrite），粘贴以下规则：

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

但是注意：LiteSpeed完全兼容Apache的mod_rewrite，所以上面这段直接复制进去就行。保存后重启LiteSpeed：systemctl restart lsws。如果还不行，检查一下网站根目录有没有 .htaccess 文件，有的话先备份再删除，因为LiteSpeed会优先读取面板里的伪静态配置。

第七步：清理缓存 + 修复权限（最后的临门一脚）

Flarum的storage和vendor目录权限要求比较变态，直接暴力解决：

cd /home/你的用户名/public_html/你的域名/
chmod -R 775 storage
chmod -R 775 vendor
# 再清一下Flarum缓存（用PHP8.4执行）
/usr/local/lsws/lsphp84/bin/php flarum cache:clear

如果执行 flarum cache:clear 提示缺少扩展，说明你漏装了某个PHP扩展（比如fileinfo或dom），回头执行 apt install lsphp84-xxx 补上。然后重启LiteSpeed和PHP进程：

systemctl restart lsws
systemctl restart lsphp84

常见翻车现场（真人血泪总结）

• 500错误：多半是文件所有者不对，或者PHP版本没有真正切换成8.4。去Cyberpanel检查网站的“PHP处理程序”是否显示lsphp84。
• Composer报错“proc_open禁用”：去Cyberpanel的“PHP配置”里把 disable_functions 中的proc_open去掉，重启PHP。
• 数据库导入后乱码：导出的sql文件如果是utf8mb4，导入时加上 --default-character-set=utf8mb4。
• 前台CSS/JS丢失：跑一下 php flarum assets:publish 以及 php flarum migrate 更新数据库结构。

基本上做到这一步，你的Flarum论坛应该已经原地复活了。如果还不成功，把你遇到的报错截图发给搜索引擎，通常Stack Overflow的前三条就能搞定。

最后吐个槽： 备份这玩意儿真的是“书到用时方恨少”。建议以后用Cyberpanel自带的“全站备份”功能，连数据库一键打包，或者用UpdraftPlus这种自动备份插件。千万别像我一样只靠临时工脑子——下次服务器炸了，至少你有这篇教程救急。