如何在 VPS 上部署 Flarum 论坛:PHP 与 MariaDB 环境配置
本指南详细说明在 VPS 上安装 Flarum 1.8 的步骤,涵盖 PHP、Composer 与 MariaDB 配置。重点解决仅暴露 public 目录的 TLS 设置,并提供避开邮件服务配置与扩展升级陷阱的实用建议,确保论坛稳定运行。
在 VPS 上安装 Flarum,并使用 PHP 和 MariaDB
在 VPS 上安装 Flarum,即可获得一个基于 PHP 和 MariaDB 运行的论坛,不需要 Docker、Ruby 或单独的任务运行器。这正是选择它的原因。在 VPS 上安装 Discourse意味着部署一个包含 Ruby、PostgreSQL、Redis 和后台工作进程的 Docker 栈。Discourse 的安装指南建议使用 2 GB RAM;使用 1 GB 时只能依赖 swap,而且这还没算备份或邮件服务的开销。在每天有数千篇帖子的活跃社区中,Discourse 的资源占用是合理的。对于只有几百名用户的论坛,这些组件会变成每月都要付费、却几乎用不到的开销。Flarum 可以运行在现有的 PHP 栈中,因此配备 nginx 和 MariaDB 的 1 GB VPS 就能托管它,并与其他服务共存。如果还没有确定方案,自托管论坛软件的全面比较会介绍其他选项。
本指南将安装版本固定为 Flarum 1.x,目前为 1.8 系列。Flarum 2.0.0 已于 2026 年 10 月 9 日成为稳定版本,但截至 2026 年 10 月 12 日,Flarum 自己的升级指南指出,许多扩展目前仍只为 2.0 标记了 beta 版本,1.x 系列仍会获得关键错误和安全问题的修复。对于本指南,扩展比核心版本更重要。因此,对于依赖这些扩展的论坛,1.8 仍是更安全的运行版本。如果不需要第三方扩展,2.0 是当前版本:它要求 PHP 8.3 或更高版本,而 Ubuntu 24.04 已提供该版本,Flarum 文档使用 composer create-project flarum/flarum:^2.0.0 . 安装它。下面的命令针对 1.8 编写。
服务器需要满足的 Flarum 1.8 要求
Flarum 的文档要求是 PHP 7.3 或更高版本、MySQL 5.6+ 或 MariaDB 10.0.5+,以及 nginx 或 Apache,并启用 mod_rewrite。Ubuntu 24.04 提供 PHP 8.3 和 MariaDB 10.11,因此无需第三方软件源,发行版软件包即可满足这两项要求。Flarum 2.0 将最低要求提高到 PHP 8.3+、MySQL 5.7+ / 8.0.30+ 或 MariaDB 10.3+,同一套 Ubuntu 软件包也能满足这些要求。Flarum 要求的 PHP 扩展包括 curl、dom、fileinfo、gd、json、mbstring、openssl、pdo_mysql、tokenizer 和 zip。您还需要 shell 访问权限,因为这里 Composer 不是可选组件:每个 Flarum 扩展都是 Composer 软件包,不运行 Composer 就无法添加扩展。
Flarum 是一个普通的 PHP 应用。如果您已经在 Ubuntu 24.04 上运行LAMP 栈,接下来两节中的大部分组件都已安装,您可以快速浏览并直接查看数据库部分。
安装 PHP 及 Flarum 所需的扩展
sudo apt update
sudo apt install -y nginx mariadb-server composer
sudo apt install -y php8.3-fpm php8.3-cli php8.3-curl php8.3-gd php8.3-mbstring php8.3-mysql php8.3-xml php8.3-zip
php -m | grep -E 'curl|dom|gd|mbstring|pdo_mysql|zip'
composer --version软件包名称与 Flarum 的列表并不一一对应。dom扩展包含在 php8.3-xml 中,fileinfo、json、openssl 和 tokenizer 要么已内置于 Ubuntu 的 PHP 8.3 中,要么随 php8.3-common 一起安装。上面的软件包会拉取 php8.3-common,因此无需为这些扩展额外安装软件包。grep 应输出 7 行:6 个扩展,以及 random。这是 PHP 8.3 始终会加载的模块,只是其名称恰好包含 dom。composer --version 应报告 2.x 版本。现在发现缺失的扩展就应立即修复。例如,如果省略 php8.3-xml,Composer 将完全拒绝安装 Flarum,因为其某个依赖项声明需要 ext-dom,错误信息会直接显示该扩展名称。需要关注的行以以下内容结尾:
require ext-dom * -> it is missing from your system. Install or enable PHP's dom extension.不过,Composer 不会检查 Flarum 列表中的每个扩展。Flarum 1.8 使用的图像库只建议安装 gd,因此没有该扩展的服务器仍能顺利完成安装,直到 Flarum 首次处理上传的头像或徽标时才会失败。
检查命令行 PHP 与 FastCGI 进程管理器(PHP-FPM)是否使用相同版本。Composer 通过命令行二进制文件运行,而论坛通过 FPM 运行,因此 php -v 和 sudo php-fpm8.3 -v 必须一致。在从第三方软件源安装过多个 PHP 版本的计算机上,两者可能出现版本偏差。这样,为一个版本安装的扩展对另一个版本不可见。
创建数据库和专用数据库用户
sudo mariadb-secure-installation
sudo mariadbCREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flarum'@'localhost' IDENTIFIED BY 'use-a-long-random-password';
GRANT ALL PRIVILEGES ON flarum.* TO 'flarum'@'localhost';
FLUSH PRIVILEGES;
EXIT;为 Flarum 使用专用数据库用户,不要使用 root。该授权仅涵盖 flarum.*,不包含其他权限。因此,即使您未编写的扩展存在 SQL 注入漏洞,也无法读取其他数据库。字符集同样重要:utf8mb4 可以正确存储表情符号和非拉丁文字,而 MySQL 较旧的 utf8 仅使用三字节编码,遇到第一个四字节字符时会截断文章。继续操作前,请确认该用户可以正常连接。
mariadb -u flarum -p flarum -e 'SELECT DATABASE();'该命令应输出 flarum。ERROR 1045 (28000): Access denied for user 'flarum'@'localhost' 表示密码不匹配,或者创建用户时指定的主机不是 localhost。
使用 Composer 在 VPS 上安装 Flarum,并固定到 1.8
首先创建一个拥有代码文件的系统用户。以 root 身份运行 Composer 会在 vendor/ 和 storage/ 中留下 root 所有的文件,之后 PHP 无法写入自己的缓存,论坛会对每个请求返回 500 错误。
sudo useradd --system --home-dir /srv/flarum --shell /bin/bash flarum
sudo install -d -o flarum -g flarum -m 755 /srv/flarum
sudo -iu flarum上一条命令会以 flarum 用户身份进入 /srv/flarum 中的 shell。从这里直到本指南结束,所有命令都以该用户身份运行,除非命令以 sudo 开头。
composer create-project flarum/flarum:^1.8.0 .^1.8.0 约束用于固定版本。它接受 1.8.x 的补丁版本,并拒绝 2.0。这一点现在很重要,因为 2.0.0 已是稳定版本:不加此约束时,composer create-project 会安装 2.0。Composer 会下载骨架、解析 flarum/core 及其依赖项,并生成 public/、storage/、vendor/、composer.json 和一个 flarum 命令行脚本。
在小型 VPS 上,这一步最容易出问题,而且两种不同的故障看起来很相似。PHP Fatal error: Allowed memory size of 134217728 bytes exhausted 是 PHP 自身的 memory_limit,在命令前加上 COMPOSER_MEMORY_LIMIT=-1 可以在本次运行中取消该限制。单独一行出现没有 PHP 错误的 Killed,则表示内核触发了内存不足终止程序,可以使用 dmesg | tail 确认。此时说明机器确实耗尽了 RAM,因此应添加 swap:提高 PHP 限制反而会使情况恶化,因为 PHP 会在内核介入前请求更多内存。
为什么只有 /public 应面向公网
项目根目录包含明文存储数据库密码的 config.php、列出所有依赖项的 vendor/,以及包含日志和缓存会话的 storage/。这些内容都不应暴露在公网中。Flarum 将所有可通过 Web 访问的内容放在一个子目录 public/ 中,其中包含 index.php、assets/ 文件夹,除此之外几乎没有其他内容。将 Web 服务器根目录指向 /srv/flarum/public 后,目录树的其余部分会因架构设计而无法通过 HTTP 访问,不依赖您记住某条规则。
如果将根目录改为指向 /srv/flarum,就会造成实际风险。请求 /config.php 不会返回有用内容,因为 PHP 会执行该文件,而它只返回一个数组。但 /storage/logs/flarum.log 会向陌生人泄露堆栈跟踪和数据库错误,/composer.lock 则会告知对方您运行的每个软件包的确切版本,从而提供一份可用于尝试已知漏洞的清单。
为 PHP-FPM 配置独立池
Flarum 需要对 3 个路径具有写入权限:项目根目录,用于安装程序创建 config.php;storage/,用于存放日志和缓存;以及 assets/,用于存放上传的头像和徽标。文件归 flarum 用户所有,因此正确做法是配置一个以 flarum 身份运行的 PHP-FPM 池。nginx 继续以 www-data 身份运行,并且只执行读取操作。
写入 /etc/php/8.3/fpm/pool.d/flarum.conf:
[flarum]
user = flarum
group = flarum
listen = /run/php/php8.3-fpm-flarum.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = ondemand
pm.max_children = 10
pm.process_idle_timeout = 30s
php_admin_value[memory_limit] = 256M
php_admin_value[upload_max_filesize] = 16M
php_admin_value[post_max_size] = 17Msudo systemctl restart php8.3-fpm
ls -l /run/php/php8.3-fpm-flarum.sock套接字应列为 srw-rw---- 1 www-data www-data。主进程以 root 身份运行并创建套接字,因此可以将所有权交给 www-data,同时让工作进程以 flarum 身份运行。如果套接字不存在,sudo journalctl -u php8.3-fpm -n 30 会输出 “FPM rejected” 这一行。pm = ondemand 仅在收到请求时启动工作进程,因此论坛无人访问时,几乎不会占用额外内存。
nginx server 块
Flarum 在项目根目录中提供了一个名为 .nginx.conf 的 nginx 片段。该片段包含重写规则、缓存响应头和压缩设置。请直接包含该片段,不要复制其内容。这样,Flarum 升级并修改片段后,服务器会自动使用更新后的配置,无需手动编辑。
server {
listen 80;
listen [::]:80;
server_name forum.example.com;
root /srv/flarum/public;
index index.php;
client_max_body_size 16M;
include /srv/flarum/.nginx.conf;
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.3-fpm-flarum.sock;
}
}将其保存为 /etc/nginx/sites-available/flarum,然后启用该配置。
sudo ln -s /etc/nginx/sites-available/flarum /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginxnginx -t 应响应 syntax is ok 和 test is successful。人们经常遗漏 include 行。遗漏后会出现一个非常明确的现象:主页可以正常加载,但每个讨论链接都会返回 nginx 的 404。Flarum 会在 PHP 中处理类似 /d/1-hello-world 的 URL。该路径不是磁盘上的文件,因此如果没有片段中的 try_files $uri $uri/ /index.php?$query_string 规则,nginx 会查找名为 d 的目录。找不到该目录后,nginx 会在请求 PHP 之前直接返回 404。Apache 使用已经位于 public/ 中的 .htaccess 文件执行相同的路由,但只有匹配的 <Directory> 块设置了 AllowOverride All 时,该文件才会生效。
安装安装程序前先配置 TLS
现在就申请证书,不要安装后再处理。Flarum 会在安装过程中将基础 URL 写入 config.php,并从浏览器地址栏获取该 URL。通过 http:// 安装后,Flarum 生成的所有资源 URL 都会以 http:// 开头。因此,添加 TLS(传输层安全)后,浏览器会将这些请求拦截为混合内容,论坛最终只显示无样式文本,JavaScript 也无法运行。请先完成 在 nginx 上配置 Let's Encrypt certbot,确认 https://forum.example.com 能提供页面,再返回这里。
如果已经通过普通 HTTP 完成安装,只需执行一行命令即可修复。编辑 /srv/flarum/config.php,将 url 键设置为 'url' => 'https://forum.example.com',,然后以 flarum 用户身份运行 php flarum cache:clear。
运行安装程序并限制 config.php 的权限
在浏览器中打开 https://forum.example.com。Flarum 的 Web 安装程序会要求输入数据库名称、您创建的数据库用户和密码、论坛标题以及管理员帐户。安装程序会写入 config.php 并创建数据表。安装完成后,收紧当前保存数据库密码的文件权限。
sudo chmod 640 /srv/flarum/config.php该文件对 flarum 仍保持可读写;FPM 以该用户身份运行。服务器上的其他帐户均无法读取该文件。然后从 Shell 检查安装情况。
php flarum info该命令会输出核心版本、PHP 版本、已启用的扩展、邮件驱动程序以及当前使用的路径。当出现异常时,首先运行此命令。需要他人协助时,对方也通常会首先要求提供此命令的输出。
为什么注册和密码重置邮件会静默失败
本节决定论坛能否撑过上线后的第一周。新论坛发送的前两封邮件通常是注册确认邮件和密码重置邮件,而这两封邮件发送的时间,正是陌生用户判断社区是否真实可靠的时刻。两者都可能静默失败。没有收到邮件的人无法告知你,管理后台也不会显示任何红色错误提示。
Flarum 提供 4 个邮件驱动,可在“管理”下的“电子邮件”中设置:smtp、mail、mailgun 和 log。选择 smtp,并将其指向确实能够投递邮件的邮件服务。mail 驱动会将邮件交给本地 sendmail 二进制文件处理,但全新安装的 Ubuntu VPS 上通常不存在该文件,因此邮件会直接丢失,也不会产生错误。log 驱动会将邮件正文写入 storage/logs/,完全不发送邮件,因为该驱动用于开发环境。
保存设置,然后在同一页面点击 发送测试邮件 按钮。这个按钮是你唯一能获得的反馈,因此在邀请任何人之前先使用它。如果邮件没有到达,请查看日志。
tail -n 50 /srv/flarum/storage/logs/flarum.log连接被拒绝、登录被拒绝和 TLS 协商失败都会记录在这里,并包含尝试连接的主机和端口。出现 Connection could not be established with host smtp.example.com 的日志行表示端口被阻止或端口配置错误。最常见的原因是邮件服务商默认阻止出站端口 25。将端口设置为 587,并将加密字段设置为 tls,通常适用于几乎所有邮件服务。
邮件功能损坏时,注册用户会看到 Flarum 的通用失败提示 Oops! Something went wrong. Please reload the page and try again.,因为发送确认邮件时请求发生异常。无论哪种情况,该用户都无法登录,也通常不会联系你说明问题。
邮件被发送出去,与邮件被对方服务器接受,是两个不同的问题。VPS 地址发送的邮件如果没有为你的域名发布 SPF 或 DKIM 记录,可能会进入垃圾邮件文件夹,或者直接被丢弃且不返回退信。因此,日志会显示发送成功,但收件人仍然看不到邮件。从自托管应用可靠发送邮件介绍应发布哪些 DNS 记录,以及哪些中继服务值得使用。
扩展是 Composer 软件包,因此升级通过命令完成
在 Flarum 中,扩展就是 Composer 软件包。没有上传按钮,也不能将 zip 文件放入某个目录。这是有意的设计:版本之间会相互解析,确切的软件包集合会记录在 composer.lock 中,扩展依赖的 PHP 库也会正确安装。代价是,以 flarum 用户身份添加扩展需要执行 3 条命令。
composer require 'fof/upload:*'
php flarum migrate
php flarum cache:clear然后依次选择 Administration 和 Extensions 启用扩展。每条命令负责不同的工作。composer require 将代码写入磁盘。php flarum migrate 执行扩展包含的数据库迁移,这也是扩展创建自身数据表的方式。php flarum cache:clear 重新构建浏览器加载的 JavaScript 和 CSS 编译包。跳过最后一步会导致一个常见问题:扩展已列出,开关也已打开,但无论重新加载多少次,浏览器中都完全没有变化。
移除扩展时,顺序相反。先在管理面板中禁用扩展,再移除软件包。Flarum 会特意保留扩展的数据表,因此稍后重新启用扩展时不会丢失数据。如果还要删除这些数据表,请先回滚其迁移,再移除代码。
php flarum migrate:reset --extension fof-upload
composer remove fof/upload
php flarum cache:clear该命令中的扩展 id 是软件包名称将斜杠替换为连字符后的结果。如果您更愿意通过单击操作而不是输入命令,composer require 'flarum/extension-manager:*' 会添加一个封装 Composer 的官方管理页面。它以 Web 用户身份执行相同的操作,需要相同的内存和写入权限,失败原因也相同。因此发生问题时,命令行仍是可靠的处理方式。
为什么 Composer 拒绝升级 Flarum
升级 Flarum 及其所有扩展只需运行一条 Composer 命令,再运行两条 Flarum 命令。先备份数据库。
composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear请查看命令输出,不要直接假定升级成功。关键情况是 Composer 拒绝执行任何操作:
Your requirements could not be resolved to an installable set of packages.这条消息表示某个已安装扩展声明了一个 flarum/core 约束,该约束排除了你要升级到的版本。Composer 不会违反该约束,因此会将整个安装保留在旧版本,而不会组合出扩展作者明确表示无法正常工作的版本组合。请找出负责阻止升级的软件包。
composer why-not flarum/core 1.8.20输出会列出阻止该版本的所有软件包,以及每个软件包声明的约束。接下来有两个选择:等待作者发布兼容版本,或移除该扩展并放弃使用它。这是 Composer 模型带来的限制。在为其他人依赖的论坛安装十五个扩展之前,应先理解这一点。优先选择近期发布过版本的扩展,并将扩展列表控制在你能够逐一检查的范围内。
这些命令会让你保持在 1.x 系列内。从 1.8 升级到 2.0 属于重大升级,Flarum 文档中有单独的指南:该升级需要 PHP 8.3,修改 composer.json,在 MariaDB 安装中修改 config.php 的 driver,并移除所有没有 2.0 版本的扩展。
要备份的内容
备份数据库和项目目录。其他内容都可以重新构建。
mariadb-dump -u flarum -p --single-transaction flarum > flarum-$(date +%F).sql
sudo tar czf flarum-files.tgz -C /srv flarum在较旧的系统中,mariadb-dump称为mysqldump;在 Ubuntu 24.04 中,两个名称都可用。数据库保存所有帖子、用户和设置。项目目录保存config.php、composer.json(其中记录了实际运行的扩展)以及包含已上传头像和徽标的assets/。可以跳过vendor/,因为composer install会根据composer.lock重新构建它,而storage/会自行重新生成。将这两个文件复制到服务器之外,因为存放在受保护服务器上的备份不能算作备份。恢复时,需要安装相同版本的全新 Flarum、composer install,将保存的文件放回原位,然后加载 SQL 文件。
FAQ
Flarum 能运行在 1 GB 的 VPS 上吗?
可以,适合小型社区。Flarum 正常运行时由处理请求的 PHP-FPM 和 MariaDB 组成;使用 pm = ondemand 后,只有有人访问时才会创建 PHP worker。资源峰值出现在安装过程中:composer create-project 会在内存中解析完整的依赖关系图,这是最容易被 out-of-memory killer 终止的步骤。安装前创建 swap 文件,或者先在更大配置的机器上运行一次 Composer,再复制整个目录。
为什么讨论链接返回 404,而首页可以正常打开?
您的 nginx server block 缺少 include /srv/flarum/.nginx.conf;。Flarum 会在 PHP 中处理 /d/1-hello-world 之类的 URL,而该路径不是磁盘上的文件。没有片段中的 try_files $uri $uri/ /index.php?$query_string 规则时,nginx 会查找名为 d 的目录;查找失败后,nginx 会直接返回 404,根本不会调用 PHP。在 Apache 上,相同的路由由 public/.htaccess 提供;除非 <Directory> block 设置 AllowOverride All,否则该路由不会生效。
启用 HTTPS 后,为什么论坛的所有样式都消失了?
Flarum 会将基础 URL 存储在 config.php 中,该值取自运行安装程序时使用的地址。如果您通过普通 HTTP 安装,Flarum 会继续生成 http:// 资源 URL。浏览器会在 HTTPS 页面上将这些请求阻止为 mixed content,因此页面只剩下无样式的文本。将 /srv/flarum/config.php 中的 url 键修改为 https:// 地址,然后以文件所有者身份运行 php flarum cache:clear。
为什么没有人收到注册确认邮件?
先检查邮件驱动。mail 驱动需要本地 sendmail 二进制文件,而新建的 Ubuntu VPS 通常没有该文件;log 驱动会将邮件写入 storage/logs/,不会发送邮件。切换到 smtp,使用端口 587,并将加密设置为 tls,因为大多数邮件服务商会阻止出站端口 25,然后点击 发送测试邮件。如果日志显示发送成功,但邮件仍未到达,则问题属于邮件送达率,而不是配置错误。请为发信域名发布 SPF 和 DKIM 记录。
我应该安装 Flarum 1.8 还是 2.0?
如果论坛依赖第三方扩展,目前请安装 1.8。Flarum 2.0.0 于 2026 年 10 月 9 日成为稳定版本,但截至 2026 年 10 月 12 日,Flarum 升级指南称许多扩展目前只为 2.0 发布了 beta 版本,没有 2.0 版本的扩展仍声明 flarum/core 约束,并且该约束上限为 1.x。今天安装 2.0 后,Composer 会直接拒绝这些扩展;这与 composer why-not 用于诊断的约束冲突相同。使用 flarum/flarum:^1.8.0 固定版本,待您依赖的扩展发布稳定的 2.0 版本后,再按照 Flarum 升级指南迁移到 2.0。请注意,1.x 现在只会接收严重 bug 和安全问题的修复。不依赖第三方扩展的论坛今天即可使用 flarum/flarum:^2.0.0 开始安装 2.0。