指南

作者： Matt Connor 2026-08-21

如何在VPS上安装Flarum：PHP论坛配置

Q: Flarum 可以运行在 1 GB 的 VPS 上吗？

可以，适合小型社区。Flarum 正常运行时由 PHP-FPM 处理请求，并使用 MariaDB；启用 pm = ondemand 后，只有在有人访问时才会创建 PHP worker。资源峰值出现在安装阶段：composer create-project 会将完整的依赖关系图加载到内存中，这是最容易被 out-of-memory killer 终止的步骤。安装前创建 swap 文件，或者先在更大配置的机器上运行一次 Composer，再复制整个目录。

Q: 为什么讨论链接返回 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 的目录；查找失败后直接返回 404，根本不会调用 PHP。在 Apache 上，相同的路由由 public/.htaccess 提供；除非 block 设置了 AllowOverride All，否则该路由不会生效。

Q: 启用 HTTPS 后，为什么论坛的所有样式都消失了？

Flarum 会将基本 URL 存储在 config.php 中，该值取自您运行安装程序时使用的地址。如果通过普通 HTTP 安装，Flarum 会继续生成 http:// 资源 URL。浏览器会在 HTTPS 页面上将这些 URL 视为混合内容并阻止加载，因此页面只剩下无样式文本。将 /srv/flarum/config.php 中的 url 键修改为 https:// 地址，然后以文件所有者身份运行 php flarum cache:clear。

Q: 为什么没有人能收到注册确认邮件？

先检查邮件驱动。mail 驱动需要本地 sendmail 二进制文件，而全新安装的 Ubuntu VPS 通常没有该文件；log 驱动只会将邮件写入 storage/logs/，不会发送邮件。切换到 smtp，使用端口 587，并将加密设置为 tls，因为大多数服务提供商都会阻止出站端口 25，然后点击 Send Test Mail。如果日志显示发送成功，但邮件仍未到达，问题属于可投递性，而不是配置错误。请为发件域发布 SPF 和 DKIM 记录。

在VPS上用PHP、Composer和MariaDB安装Flarum 1.8，仅通过TLS提供/public目录，并解决邮件配置与扩展升级时常见的具体陷阱。

在 VPS 上安装带 PHP 和 MariaDB 的 Flarum

在 VPS 上安装 Flarum，即可获得一个基于 PHP 和 MariaDB 运行的论坛，不需要 Docker、Ruby 或独立的任务运行器。这正是选择它的原因。在 VPS 上安装 Discourse需要一个包含 Ruby、PostgreSQL、Redis 和后台工作进程的 Docker 堆栈；在增加备份或邮件服务之前，2 GB 内存是实际的最低配置。对于每天有数千篇帖子的活跃社区，Discourse 的资源占用是合理的。对于只有几百人的论坛，这些组件会成为每月都要付费、却始终用不上的基础设施。Flarum 可运行在您可能已经使用的 PHP 堆栈中，因此配备 nginx 和 MariaDB 的 1 GB VPS 就能与其他服务共存。如果您尚未确定方案，自托管论坛软件的完整比较会介绍其他选项。

本指南将安装版本固定为 Flarum 1.x，目前为 1.8 系列。截至 2026 年 8 月，Flarum 2.0 仍是候选发布版。因此，对于供其他用户使用的论坛，应运行 1.8。这里扩展比核心版本更重要，而且大多数扩展作者尚未迁移到 2.0。

服务器需要满足的 Flarum 1.8 要求

Flarum 的官方要求是 PHP 7.3 或更高版本、MySQL 5.6+ 或 MariaDB 10.0.5+，以及支持 mod_rewrite 的 nginx 或 Apache。Ubuntu 24.04 提供 PHP 8.3 和 MariaDB 10.11，因此无需使用第三方软件源，发行版软件包即可满足这两项要求。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 中，因此无需为它们安装软件包。grep 应输出 6 行，composer --version 应报告 2.x 版本。缺少扩展应立即修复，因为 Composer 未安装该扩展时会拒绝安装 Flarum，并在错误信息中指出扩展名称：

  Problem 1
    - flarum/core[v1.8.0, ..., v1.8.17] require ext-gd * -> it is missing from your system.
      Install or enable PHP's gd extension.

确认命令行 PHP 与 FastCGI 进程管理器（PHP-FPM）使用相同版本。Composer 在命令行二进制文件下运行，而论坛在 FPM 下运行，因此 php -v 和 sudo php-fpm8.3 -v 必须一致。如果服务器通过第三方软件源安装过多个 PHP 版本，这两个版本可能会出现偏差。这样，为其中一个版本安装的扩展对另一个版本不可见。

创建数据库和专用数据库用户

sudo mariadb-secure-installation
sudo mariadb

CREATE 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 仍是候选发布版时，这正是所需行为。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] = 17M

sudo 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 nginx

nginx -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.17

输出会列出阻止该版本的所有软件包，以及每个软件包声明的约束。接下来有两个选择：等待作者发布兼容版本，或者移除该扩展并停止使用它。这就是 Composer 模型的代价。在论坛依赖这些扩展的其他用户较多时，安装 15 个扩展前，应该先了解这一点。优先选择近期发布过版本的扩展，并将扩展列表控制在您能够逐一检查的范围内。

要备份的内容

备份数据库和项目目录。其他内容都可以重新构建。

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 的目录；查找失败后直接返回 404，根本不会调用 PHP。在 Apache 上，相同的路由由 public/.htaccess 提供；除非 <Directory> block 设置了 AllowOverride All，否则该路由不会生效。

启用 HTTPS 后，为什么论坛的所有样式都消失了？

Flarum 会将基本 URL 存储在 config.php 中，该值取自您运行安装程序时使用的地址。如果通过普通 HTTP 安装，Flarum 会继续生成 http:// 资源 URL。浏览器会在 HTTPS 页面上将这些 URL 视为混合内容并阻止加载，因此页面只剩下无样式文本。将 /srv/flarum/config.php 中的 url 键修改为 https:// 地址，然后以文件所有者身份运行 php flarum cache:clear。

为什么没有人能收到注册确认邮件？

先检查邮件驱动。mail 驱动需要本地 sendmail 二进制文件，而全新安装的 Ubuntu VPS 通常没有该文件；log 驱动只会将邮件写入 storage/logs/，不会发送邮件。切换到 smtp，使用端口 587，并将加密设置为 tls，因为大多数服务提供商都会阻止出站端口 25，然后点击 Send Test Mail。如果日志显示发送成功，但邮件仍未到达，问题属于可投递性，而不是配置错误。请为发件域发布 SPF 和 DKIM 记录。

应该安装 Flarum 1.8 还是 2.0？

安装 1.8。截至 2026 年 8 月，Flarum 2.0 仍是 release candidate。更重要的是，许多扩展仍声明了截至 1.x 的 flarum/core 约束。现在安装 2.0，意味着运行一个扩展无法统一更新的论坛，而这正是 composer why-not 用于诊断的故障。使用 flarum/flarum:^1.8.0 固定版本，等您依赖的扩展发布 2.0 版本后再重新评估。

#flarum #forum #php #自托管 #community