Flarum 安装指南
基于 2026年4月 官方文档
📅 最后编辑：2026-04-06
📋 一、官方最新服务器要求
| 组件 | 最低要求 | 官方推荐 / 备注 |
|---|
| Web 服务器 | Apache (mod_rewrite) / Nginx / Caddy | 三者任选，官方均提供配置示例 |
| PHP 版本 | PHP 7.3+ | 强烈推荐 PHP 8.3 最新稳定
PHP 7.3/7.4/8.0 已停止安全支持 |
| PHP 扩展 | curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip | 必要的，请启用 |
| 数据库 | MySQL 5.6+ / 8.0.23+ 或 MariaDB 10.0.5+ | MySQL 8.0 版本需 ≥ 8.0.23 |
| PHP 内存限制 | ≥128M | 建议设为 256M 或更高 |
| 其他要求 | SSH 访问 / Composer (CLI方式) | 用于执行维护命令和管理扩展 |
💡 快速检查 PHP 扩展：运行 php -m | grep -E "curl|dom|fileinfo|gd|json|mbstring|openssl|pdo_mysql|tokenizer|zip"
📥 二、两种官方安装方式
📦 方式一：压缩包安装（无SSH / 新手首选）
官方为无命令行权限或偏好简单的用户提供，只需下载、解压、配置Web服务器。
- 根据PHP版本和是否需要public目录下载对应的zip/tar.gz包（PHP 8.3 强烈推荐）。
- 有独立webroot（如 /var/www/html）选择“有public目录”包；子目录或受限主机选择“no-public-dir”包。
- 解压到目标目录：
unzip flarum-v1.x-php8.3.zip -d /var/www/flarum
- 配置Web服务器（见下一章节），浏览器访问域名完成安装向导。
💡 判断是否需要public目录：有独立根目录（如直接域名绑定文件夹）→ 需public包；安装到子目录/forum或主机限制public_html → 选no-public-dir包。
🖥️ 方式二：命令行安装 (CLI / 推荐进阶用户)
- 安装 Composer：
curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer
- 在空目录中运行：
composer create-project flarum/flarum:^1.8.0 .
- （可选）安装扩展管理器以支持后台一键安装：
composer require flarum/extension-manager:"*"
- 配置Web服务器，最后浏览器访问域名完成图形化安装。
⚠️ 安全警告：扩展管理器允许管理员安装任何Composer包，仅在你完全信任所有论坛管理员的情况下安装。
⚙️ 三、Web服务器配置（URL重写）
正确配置URL重写是Flarum正常运行的关键。
🔷 Apache
sudo a2enmod rewrite
sudo systemctl restart apache2
站点配置中添加：
<Directory "/path/to/flarum/public">
AllowOverride All
</Directory>
🔶 Nginx
include /path/to/flarum/.nginx.conf;
# 确保 root 指向 flarum/public 目录
🟢 Caddy (v2)
www.example.com {
root * /var/www/flarum/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错误、无法上传头像等。
❌ 绝对禁止使用 777 权限！
标准步骤 (Linux)
chmod 775 -R /path/to/flarum
chown -R www-data:www-data /path/to/flarum
# 将 CLI 用户加入 www-data 组（假设用户ubuntu）
sudo usermod -a -G www-data ubuntu
# 重新登录SSH使权限生效
# 如果启用了 SELinux：
chcon -R -t httpd_sys_rw_content_t /path/to/flarum
必须确保Web服务器用户(www-data) 和 CLI操作用户对 根目录、storage、assets 均有读写权限。
🧩 五、高级定制：不使用 public 目录
适用于主机限制根目录(如只能用public_html)或需安装到子目录的场景。
- 使用CLI安装后，将 public 目录下所有文件移动到网站根目录。
- 编辑根目录下的 .htaccess (Nginx则为.nginx.conf) 取消注释保护敏感资源的行。
- 修改 index.php 和 site.php 中的路径引用。
- 检查 config.php 确保 url 值正确。
🧰 或者直接下载 "no-public-dir" 压缩包解压至目标目录，无需移动步骤。
🚧 六、常见问题与解决方案
❓ 安装向导提示目录不可写？
严格按照文件权限章节设置 chmod 775 -R、chown -R www-data:www-data 并添加用户到 Web 组，重新登录 SSH。注意 SELinux 上下文：chcon -R -t httpd_sys_rw_content_t /path/to/flarum
🔄 页面循环重定向或 404？
检查 URL 重写：Apache 是否启用 mod_rewrite 并配置 AllowOverride All；Nginx 是否 include .nginx.conf；确认 .htaccess 文件存在于 public 目录。
⚪ 安装后白屏 / 500 错误？
① 运行 php -m 检查官方要求的扩展是否全部加载；② 检查 PHP memory_limit（建议 256M）；③ 查看 Web 服务器错误日志和 storage/logs 目录下的 Flarum 日志。
🧩 Composer 安装扩展后无变化？
在 Flarum 根目录执行 php flarum cache:clear 清除缓存。如果使用 Swoole 环境，需要重启 Swoole 服务。
📤 后台无法上传 logo / 头像？
确保 assets 目录拥有 Web 用户写权限：chmod 775 assets 并确保属主为 www-data:www-data。
🔄 想从旧论坛迁移数据？
官方目前无正式迁移工具，可尝试社区提供的非官方导入工具（如 phpBB 迁移器），但官方不保证其可用性且不提供支持。
🔧 如何修改上传文件大小限制？
修改 PHP 配置：upload_max_filesize = 20M 和 post_max_size = 20M，然后重启 PHP-FPM 或 Web 服务器。
📦 推荐扩展
flarum/extension-manager - 后台扩展管理器flarum/lang-english - 英语语言包flarum/flags - 标记帖子功能flarum/likes - 点赞系统flarum/tags - 标签分类系统
💡 安装扩展：composer require flarum/扩展名，然后执行 php flarum cache:clear
✅ 安装成功 Checklist
- PHP 8.3 + 必需扩展已安装
- MySQL/MariaDB 数据库已创建
- Web服务器 URL 重写已配置
- 文件权限（775 + 正确属主）已设置
- 访问域名完成安装向导
- 后台配置邮件服务（SMTP）确保用户功能正常