Flarum 在国内服务器（宝塔环境）上的完整搭建指南

Flarum 是一款现代、简洁、模块化的 PHP 开源论坛软件，适合打造小型或中型兴趣社区、技术支持平台等。本文基于真实部署经验，详细讲解在国内服务器（宝塔环境）上搭建 Flarum 的完整过程，并提供常见问题的解决方案。

🧱 环境说明

操作系统：CentOS 7 / 8 或 Ubuntu 20.04 / 22.04
控制面板：宝塔面板（推荐最新版）
PHP 版本：推荐 PHP 8.1 或 8.2（Flarum 支持 7.4 以上，8.1+ 更稳定）
数据库：MySQL 5.7 / 8.0 或 MariaDB 10.2+
Web 服务器：Nginx（Apache 也可，但 Nginx 更常见）
Composer：2.8.10 或以上版本（避免 Xdebug 相关问题）
域名：已完成备案的主域名或子域名（推荐子域名，如 bbs.example.com）

📦 第一步：通过宝塔新建站点

登录宝塔面板 → 网站 → 添加站点。
填写域名（或留空使用 IP 测试）。
选择 PHP 版本为 8.1 或 8.2，数据库选择 MySQL（自动创建数据库）。
创建完成后，记下站点目录（通常为 /www/wwwroot/your-domain）。

🛠️ 第二步：预配置 PHP 环境

在安装 Composer 和 Flarum 之前，需确保 PHP 环境正确配置，包括解禁必要函数和安装所需扩展。

解禁 PHP 函数

Flarum 和 Composer 依赖 proc_open 和 putenv 函数，这些函数可能在默认 PHP 配置中被禁用。

检查禁用函数：
1
php -i | grep disable_functions
如果输出包含 proc_open 或 putenv，需要解禁。
编辑 PHP 配置文件：
编辑 PHP CLI 配置文件（通常为 /www/server/php/82/etc/php.ini）：
1
nano /www/server/php/82/etc/php.ini
找到 disable_functions 行，移除 proc_open 和 putenv（如果存在）。例如：
1
disable_functions = exec,system
保存后重启 PHP-FPM：
1
sudo systemctl restart php-fpm

验证函数解禁：

1	php -r "var_dump(function_exists('proc_open'), function_exists('putenv'));"

输出应为：

1 2	bool(true) bool(true)

安装 PHP 扩展

Flarum 要求 fileinfo 等扩展，必须提前安装。

检查已安装扩展：
1
php -m | grep -E "fileinfo|gd|mbstring|pdo_mysql|openssl|json|tokenizer|curl|zip"
确保列出 fileinfo 等扩展。如果缺少，安装以下扩展：

安装扩展：

Ubuntu/Debian：

1 2	sudo apt-get update sudo apt-get install php8.2-fileinfo php8.2-mbstring php8.2-gd php8.2-curl php8.2-zip php8.2-pdo-mysql php8.2-openssl php8.2-tokenizer

CentOS/RHEL：

1	sudo yum install php82-php-fileinfo php82-php-mbstring php82-php-gd php82-php-curl php82-php-zip php82-php-pdo-mysql php82-php-openssl php82-php-tokenizer

验证扩展：
1
php -m | grep fileinfo
确保输出包含 fileinfo。

🧰 第三步：安装 Composer 与 Flarum

安装 Composer（如未安装）

在服务器终端执行以下命令安装 Composer：

cd /www/wwwroot/your-domain
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
php -r "unlink('composer-setup.php');"

验证 Composer 是否安装成功：

1	composer -V

注意：建议以非 root 用户运行 Composer，以避免权限问题：

1 2	sudo chown -R <your-username>:<your-group> /www/wwwroot/your-domain su <your-username>

安装 Flarum 核心

在站点目录下安装 Flarum：

1 2	cd /www/wwwroot/your-domain composer create-project flarum/flarum .

注意事项：

如果仍提示 proc_open is disabled 或 putenv() 错误，重新检查第二步的函数解禁。
如果提示缺少扩展，确认第二步的扩展安装是否成功。

🔧 第四步：配置 Nginx 与 PHP

Nginx 配置

修改 Nginx 配置文件：
- 编辑站点对应的 Nginx 配置文件（通常在 /www/server/nginx/conf 或通过宝塔面板的站点设置）。
- 确保 root 指向 Flarum 的 public 目录：
  1
  root /www/wwwroot/your-domain/public;
- 在 server 块中添加自定义配置文件引用（如果需要）：
  1
  include /www/wwwroot/your-domain/.nginx.conf;
  注意：确保 /www/wwwroot/your-domain/.nginx.conf 文件存在。如果不存在，可创建一个空文件或移除此行。
伪静态规则：
在宝塔面板的站点设置中，添加以下伪静态规则：

1
2
3

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

上传限制：
在 Nginx 配置文件中添加：
1
client_max_body_size 50M;
保存后重启 Nginx：
1
sudo systemctl restart nginx

PHP 配置调整

必要扩展：已在上一步安装，确认以下扩展已启用：
- fileinfo
- pdo_mysql
- mbstring
- openssl
- json
- tokenizer
- curl
- gd
- zip
上传限制：在宝塔的 PHP 设置中，修改：
- upload_max_filesize = 50M
- post_max_size = 50M

权限设置：确保 public/assets 和 storage 目录对 Web 服务器用户（通常为 www 或 nginx）可写：

chown -R www:www /www/wwwroot/your-domain/storage
chmod -R 775 /www/wwwroot/your-domain/storage
chown -R www:www /www/wwwroot/your-domain/public/assets
chmod -R 775 /www/wwwroot/your-domain/public/assets

🌐 第五步：访问安装页面

浏览器访问：http://your-ip/ 或 https://bbs.example.com（需配置 SSL）。
填写以下信息：
- 数据库连接信息（宝塔自动创建的数据库名、用户、密码）。
- 管理员邮箱和密码。
- 网站标题等。
点击“安装”，等待 Flarum 配置数据库和初始数据。

注意：建议启用 HTTPS，可通过宝塔的免费 Let’s Encrypt SSL 配置。

🔌 第六步：推荐插件及配置建议

.publisher_id {
color: #c0c0c0 !important;
}
以下插件适合中文社区，增强功能并提升用户体验：

插件名称	作用说明
`flarum-tags`	话题分类，类似论坛分区
`flarum-likes`	帖子点赞功能
`flarum-mentions`	支持 @ 用户提及
`fof/upload`	文件/图片上传，支持水印、防盗链
`fof/gamification`	积分排行和点赞榜单
`fof/sitemap`	自动生成站点 sitemap，提升 SEO
`fof/analytics`	接入 Google Analytics
`fof/pages`	自定义页面，如“关于我们”
`fof/links`	导航栏添加外链，适合链接 Blog 等
`fof/emoji` + `emoji-picker`	表情支持与可视化选择器
`flarum/online-users`	实时显示在线用户

安装插件：

1	composer require <插件名称>:"*"

例如：

1	composer require flarum-tags:"*"

⚠️ 常见问题与解决方案

1. Composer 报错 `proc_open is disabled`

原因：PHP 禁用了 proc_open，导致 Composer 无法调用 unzip 或 7z。

解决：

编辑 /www/server/php/82/etc/php.ini，找到 disable_functions，移除 proc_open。

安装 unzip：

# Ubuntu/Debian
sudo apt-get install unzip
# CentOS/RHEL
sudo yum install unzip

重启 PHP-FPM：
1
sudo systemctl restart php-fpm

2. Composer 报错 `putenv()`

原因：PHP 禁用了 putenv 函数。

解决：

编辑 /www/server/php/82/etc/php.ini，移除 disable_functions 中的 putenv。
重启 PHP-FPM：
1
sudo systemctl restart php-fpm

3. 缺少 `fileinfo` 扩展

原因：Flarum 依赖 fileinfo 扩展，但未安装或启用。

解决：

参考“第二步：预配置 PHP 环境”中的扩展安装步骤。

4. 文件权限问题（如 `public/assets` 或 `storage` 不可写）

原因：Web 服务器用户对 public/assets 或 storage 目录没有写权限。

解决：

确保目录权限正确：

chmod -R 775 /www/wwwroot/your-domain/storage
chown -R www:www /www/wwwroot/your-domain/storage
chmod -R 775 /www/wwwroot/your-domain/public/assets
chown -R www:www /www/wwwroot/your-domain/public/assets

替换 www 为实际的 Web 服务器用户（可通过 ps aux | grep nginx 或 ps aux | grep php-fpm 确认）。

5. 后台清除缓存提示 `Could not write to filesystem`

原因：Web 服务器用户对 storage/cache 目录没有写权限。

解决：

修复 storage/cache 目录权限：

1 2	chown -R www:www /www/wwwroot/your-domain/storage/cache chmod -R 775 /www/wwwroot/your-domain/storage/cache

从命令行清除缓存：

1 2	cd /www/wwwroot/your-domain php flarum cache:clear

替换 www 为实际的 Web 服务器用户。
确认后重新尝试后台清除缓存。

6. Composer 下载缓慢

解决：配置国内镜像源：

1	composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

🔐 性能优化建议

启用 Redis 缓存：安装 Redis 和 PHP Redis 扩展，配置 Flarum 使用 Redis：
1
composer require flarum/cache
使用 CDN：配合 Cloudflare 或国内 CDN（如阿里云 CDN）加速访问，启用 HTTPS。
数据库优化：在宝塔设置计划任务，定期优化 MySQL 数据库：
1
mysqlcheck -o --all-databases
统计分析：安装 flarum/statistics 插件，监控社区增长。

✅ 小结

Flarum 是一款轻量、现代的论坛软件，适合构建如《模拟人生 4》模组分享、汉化交流等中文社区。凭借简洁的界面和丰富的插件生态，只要环境配置得当，后续维护非常轻松。

下一篇文章将介绍如何将 Cloudflare R2 上的模组和图片资源迁移至本地 Cloudreve 图床，实现私有化存储和分发优化。