🚀 一、版本现状与新闻动态
Flarum 正处于 2.0 RC（候选发布）阶段：API 已基本稳定，许多论坛已在生产环境运行，但它仍不是最终稳定版。正式上线前，请务必备份数据并充分测试。
| 事项 | 版本 / 状态 | 说明 |
|---|
| 最新候选版 | 2.0.0-rc.8 | 最新 RC，较 rc.7 又修复了若干问题，API 稳定 |
| 1.x 安全修复版 | 1.8.19 | 修复一个严重漏洞，官方强烈建议所有 1.x 论坛立即升级 |
| 1.x 维护策略 | 1.8.18 起 | 1.x 分支仅剩严重问题与安全修复 |
| 官方扩展发现 | Beta | Official Extension Discovery 已发布，改善扩展发现体验 |
| FoF 扩展兼容 | 进展顺利 | Friends of Flarum 扩展的 2.0 兼容工作推进顺利，向首个 2.0 beta 迈进 |
⚠️ 正在使用 1.x 的站长请立即升级到 1.8.19（严重安全漏洞修复）；新站部署建议直接评估 2.0 RC，并持续关注 2.0 RC 动态与安全更新。
💡 想参与测试或提前上手？可在测试环境安装最新 RC 体验，但生产站务必先备份、充分验证后再切换。
📋 二、服务器要求
安装前请先确认服务器满足以下条件（建议直接对照本表逐项检查）。
| 组件 | 要求 | 官方推荐 / 备注 |
|---|
| Web 服务器 | Apache（启用 mod_rewrite）或 Nginx | 需支持 URL 重写，详见第四章 |
| PHP 版本 | PHP 8.3+ | 2.0 时代的最低要求已提升至 8.3 |
| PHP 扩展 | curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip, session | 注意：新增了 session 扩展，务必启用 |
| 数据库 | MySQL 5.7+ / 8.0.30+、MariaDB 10.3+、SQLite 3.35.0+、PostgreSQL 10.0+ | 推荐 MySQL 8.4 LTS、MariaDB 11.8 LTS、PostgreSQL 15/16/17 |
| 命令行 | SSH 访问 + Composer | 用于执行维护命令和安装扩展 |
🔍 数据库驱动注意：MySQL 与 MariaDB 是两种不同驱动。安装后 config.php 中的 driver 必须与实际使用的数据库服务器一致，否则无法连接。
💡 快速检查 PHP 扩展：运行 php -m | grep -E "curl|dom|fileinfo|gd|json|mbstring|openssl|pdo_mysql|tokenizer|zip|session"
📥 三、两种安装方式
📦 方式一：解压安装包（无 SSH / 新手首选）
不需要命令行，只需下载、解压、配置 Web 服务器，适合无 SSH 权限或新手用户。
- 根据你的 PHP 版本 和是否使用 public 目录，下载对应的
zip / tar.gz 安装包。
- 解压到目标目录：
unzip flarum-v2.x-php8.3.zip -d /path/to/your/forum
- 配置 Web 服务器（见第四章），并将 webroot 指向
/path/to/your/forum/public。
- 浏览器访问域名，跟随安装向导完成配置。
🖥️ 方式二：命令行安装（CLI / 推荐进阶用户）
通过 Composer 创建项目，适合需要完整控制、准备长期维护的站点。
- 确保已安装 Composer，并进入一个空目录。
- 运行：
composer create-project flarum/flarum:^2.0.0 --stability=beta .
- 将 webroot 指向
/path/to/your/forum/public，并配置 URL 重写（见第四章）。
- 浏览器访问域名，完成图形化安装向导。
⚠️ 安全提醒：扩展管理器允许管理员安装任何 Composer 包。安装 composer require flarum/extension-manager:"*" 可在后台一键管理扩展，但仅当你完全信任所有论坛管理员时才安装。
⚙️ 四、URL 重写配置
正确配置 URL 重写是 Flarum 正常运行的关键，否则会出现 404、循环重定向等问题。
🔷 Apache
需要启用 mod_rewrite，并确保站点允许使用 .htaccess：
# Ubuntu 下启用模块并重启
sudo a2enmod rewrite
sudo systemctl restart apache2
虚拟主机 / 站点配置中添加：
<Directory "/path/to/your/forum/public">
AllowOverride All
</Directory>
🔶 Nginx
在 server 块中引入 Flarum 自带的配置文件：
include /path/to/your/forum/.nginx.conf;
# 确保 root 指向 forum/public 目录
🟢 Caddy (v2)
www.example.com {
root * /path/to/your/forum/public
php_fastcgi unix//var/run/php/php8.3-fpm.sock
header /assets/* {
+Cache-Control "public, must-revalidate, proxy-revalidate"
+Cache-Control "max-age=25000"
}
file_server
}
🔐 五、文件权限与所有权
错误的权限设置会导致白屏、500 错误、无法上传头像等。Flarum 的运行用户（Web 服务器用户）必须对 根目录、storage、assets 拥有读写权限。
❌ 绝对禁止使用 777 权限！
标准步骤 (Linux)
chmod 775 -R /path/to/your/forum
chown -R www-data:www-data /path/to/your/forum
# 将当前 SSH 用户加入 www-data 组（假设当前用户为 ubuntu）
sudo usermod -a -G www-data ubuntu
# 重新登录 SSH 使权限生效
# 如果启用了 SELinux：
chcon -R -t httpd_sys_rw_content_t /path/to/your/forum
必须确保 Web 服务器用户（如 www-data）和 CLI 操作用户对 根目录、storage、assets 均有读写权限。
🧩 六、自定义路径：子目录或受限主机
适用于将论坛安装在子目录（如 yoursite.com/forum），或主机限制根目录（如只能用 public_html）的场景。
- 解压包方式：直接选用
no-public-dir 安装包，解压到目标目录即可。
- Composer 方式：将
public 目录下所有文件（含 .htaccess）移动到网站根目录。
- 取消
.htaccess 第 9-15 行的注释（Nginx 则为 .nginx.conf 第 8-11 行），放开对敏感资源的保护。
- 修改
index.php 中的 $site = require './site.php';。
- 修改
site.php 中的 base / public / storage 路径。
- 检查
config.php 中的 url 值是否正确。
🧰 小提示：移动 public 下文件时务必保留 .htaccess，它是 URL 重写与资源保护的关键。
📤 七、数据导入与迁移
如果你已有旧论坛（如 phpBB、Discourse 等）需要迁移到 Flarum，请注意：
- 官方目前暂无正式导入工具。
- 社区提供了非官方导入器，部分工具支持先迁移到
phpBB 再转换为 Flarum。
- 官方不保证这些社区工具的可用性，也不提供技术支持。
⚠️ 迁移前务必完整备份原论坛数据，并在测试环境先行验证导入流程。
🚧 八、常见问题与推荐扩展
❓ 安装向导提示目录不可写？
严格按照第五章设置：chmod 775 -R、chown -R www-data:www-data，并将当前用户加入 Web 组后重新登录 SSH。若启用 SELinux，还需执行 chcon -R -t httpd_sys_rw_content_t /path/to/your/forum。
🔄 页面循环重定向或 404？
检查 URL 重写：Apache 是否启用 mod_rewrite 并配置 AllowOverride All；Nginx 是否 include .nginx.conf；确认 .htaccess 文件存在于 public 目录。
⚪ 安装后白屏 / 500 错误？
① 运行 php -m 检查官方要求的扩展（含新增的 session）是否全部加载；② 核对 config.php 的数据库 driver 是否与实际服务器匹配（MySQL / MariaDB 是不同驱动）；③ 查看 Web 服务器错误日志和 storage/logs 目录下的 Flarum 日志。
🆕 正在用 1.x，如何升级？
立即升级到 1.8.19（安全修复版，修复严重漏洞）。若计划升级到 2.0，请先备份数据，在测试环境验证扩展兼容性后再上线——注意 FoF 等第三方扩展的 2.0 版本仍在开发中。
🧩 安装扩展后无变化？
在 Flarum 根目录执行 php flarum cache:clear 清除缓存。若通过扩展管理器安装，确认扩展已启用并刷新缓存。
🧰 推荐扩展
flarum/extension-manager — 后台扩展管理器- Official Extension Discovery — 官方扩展发现（Beta，改善扩展浏览体验）
- Friends of Flarum (FoF) 系列扩展 — 2.0 兼容推进中，广受社区好评
flarum/tags — 标签分类、flarum/flags — 标记帖子、flarum/likes — 点赞系统
安装方式：
composer require flarum/扩展名，然后执行
php flarum cache:clear。
✅ 安装前 Checklist
- PHP 8.3+ 及全部必需扩展（含 session）已安装
- 数据库已创建，且 config.php 的 driver 与实际服务器匹配
- Web 服务器 URL 重写已配置（Apache / Nginx / Caddy）
- 文件权限已设置（775 + 正确属主，严禁 777）
- 已备份数据，并在测试环境验证
- 关注 2.0 RC 动态与 1.8.19 安全更新