进阶 docs.flarum.org 2026-10-15 14:50:53 · 19 阅读
第18章 安装 Flarum
第18章：安装
版本：2.x
快速体验？
欢迎到我们的演示论坛上试试 Flarum。或者，通过 Free Flarum 在几秒钟内搭建一个属于自己的论坛。这是一个免费的社区服务，与 Flarum 官方团队没有隶属关系。
服务器要求
在安装 Flarum 之前，务必确认服务器满足以下要求。运行 Flarum 需要：
* Apache（启用 mod_rewrite）或 Nginx
* PHP 8.3 或更高版本，需包含以下扩展：curl, dom, fileinfo, gd, json, mbstring, openssl, pdo_mysql, tokenizer, zip, session
* 以下数据库之一：
* MySQL 5.7+ / 8.0.30+
* MariaDB 10.3+
* SQLite 3.35.0+
* PostgreSQL 10.0+
* SSH（命令行）访问权限，用于执行可能必要的软件维护命令。如果你打算使用命令行安装和管理 Flarum 扩展，还需要安装 Composer。
推荐数据库版本
上述版本仅为 Flarum 支持的最低要求。MySQL 5.7 和 MariaDB 10.x 等旧版本即将（或已经）结束上游技术支持，不建议用于新安装。为了获得最佳性能和最长支持周期，我们建议运行当前长期支持（LTS）级别的版本：
* MySQL 8.4 LTS
* MariaDB 11.8 LTS
* PostgreSQL 15、16 或 17
这些是 Flarum 积极开发和测试所针对的版本。请注意，Flarum 将 MySQL 和 MariaDB 视为不同的数据库驱动程序——请确保你的 config.php 中的驱动设置与实际连接的服务器类型一致。
安装
通过解压归档文件安装
如果没有服务器的 SSH 访问权限，或者你不习惯使用命令行，可以通过解压归档文件来安装 Flarum。以下是可用的归档文件列表，请选择与你 PHP 版本及公共路径设置（或无公共路径偏好）相匹配的文件。
此处仅详述最新的 Flarum 2.x 版本，若要查看以往版本请浏览归档仓库。
使用命令行安装
Flarum 使用 Composer 来管理依赖项和扩展。如果你不熟悉它，请阅读我们的指南以了解其用途及配置方法。然后，在你希望安装 Flarum 的空目录下运行以下命令：
composer create-project flarum/flarum:^2.0.0 .
命令运行期间，你可以先配置 Web 服务器。确保网站根目录（webroot）设置为 /path/to/your/forum/public，并按照下面的说明配置 URL 重写（URL Rewriting）。 一切就绪后，用浏览器访问你的论坛，按提示完成安装。 如果想在后台管理面板中安装和更新扩展，还需要安装 Extension Manager 扩展。 composer require flarum/extension-manager:"*"
warning 扩展管理器允许管理员安装任意 composer 包。只有在完全信任所有论坛管理员时才应安装它。 URL 重写 Apache Flarum 在 public 目录中自带了一个 .htaccess 文件——请确保它已正确上传。如果 mod_rewrite 未启用，或 .htaccess 不被允许，Flarum 将无法正常运行。请向你的主机商（或 VPS 服务商）确认这些功能已开启。如果你自己管理服务器，可能需要在站点配置中添加以下内容以允许 .htaccess 文件生效：
AllowOverride All
这样可以允许 .htaccess 覆盖默认配置，使 Flarum 能正确重写 URL。 启用 mod_rewrite 的方法因操作系统而异：在 Ubuntu 上运行 sudo a2enmod rewrite 即可；CentOS 默认已启用。修改完成后别忘了重启 Apache！ Nginx Flarum 自带一个 .nginx.conf 文件——请确保它已正确上传。然后，假设你已在 Nginx 中配置好 PHP 站点，将以下内容添加到 server 配置块中： include /path/to/flarum/.nginx.conf;
Caddy 只需非常简单的配置，Caddy 就能让 Flarum 正常运行。注意把其中的 URL 替换为你自己的域名，路径替换为你自己的 public 目录。如果使用其他版本的 PHP，还需将 fastcgi 路径改为指向你正确的 PHP socket 或 URL。 www.example.com {
root * /var/www/flarum/public
php_fastcgi unix//var/run/php/php7.4-fpm.sock
header /assets/* {
+Cache-Control "public, must-revalidate, proxy-revalidate"
+Cache-Control "max-age=25000"
Pragma "public"
}
file_server
}
文件夹所有权 在安装过程中，Flarum 可能会要求你授予特定目录的写权限。 现代操作系统通常支持多用户环境，这意味着你登录使用的用户账户与 Flarum 运行所依赖的用户账户可能不同。 Flarum 运行所依赖的用户必须具备对以下目录的读写权限： 根安装目录，以便 Flarum 能够修改 config.php 文件。 storage 子目录，以便 Flarum 能够编辑日志并存储缓存数据。 assets 子目录，以便能够将 logo 和头像上传至文件系统。 扩展插件可能需要其他目录的权限，因此建议你递归地授予整个 Flarum 根安装目录的写权限。 你需要运行若干条命令来设置文件权限。请注意，如果执行其中部分命令后安装过程不再出现警告，则无需执行剩余命令。 首先，你需要允许对目录的写访问。在 Linux 上执行： chmod 775 -R /path/to/directory
如果这还不够，你可能需要检查文件的所有者是否属于正确的组和用户。默认情况下，在大多数 Linux 发行版中，PHP 和 Web 服务器都以 www-data 作为其所属的用户和组。你需要根据具体的发行版和 Web 服务器配置情况进行确认。在大多数 Linux 操作系统中，你可以通过运行以下命令来更改文件夹的所有者： chown -R www-data:www-data /path/to/directory
如果 Web 服务器使用的是其他用户/组，请相应地替换 www-data。 此外，你需要确保你的命令行用户（即你登录终端所用的用户）拥有所有权，这样你才能通过 CLI 安装扩展并管理 Flarum 安装。为此，使用 usermod -a -G www-data YOUR_USERNAME 将当前用户（whoami）添加到 Web 服务器组（通常是 www-data）。此更改可能需要注销并重新登录才能生效。 最后，如果上述方法仍无效，你可能需要配置 SELinux 以允许 Web 服务器向该目录写入数据。执行以下命令： chcon -R -t httpd_sys_rw_content_t /path/to/directory
To find out more about these commands as well as file permissions and ownership on Linux, read this tutorial. If you are setting up Flarum on Windows, you may find the answers to this Super User question useful. Environments may varyYour environment may vary from the documentation provided, please consult your web server configuration or web hosting provider for the proper user and group that PHP and the web server operate under. Never use permission 777You should never set any folder or file to permission level 777, as this permission level allows anyone to access the content of the folder and file regardless of user or group. Customizing Paths By default Flarum's directory structure includes a public directory which contains only publicly-accessible files. This is a security best-practice, ensuring that all sensitive source code files are completely inaccessible from the web root. However, if you wish to host Flarum in a subdirectory (like yoursite.com/forum), or if your host doesn't give you control over your webroot (you're stuck with something like public_html or htdocs), you can set up Flarum without the public directory. If you intend to install Flarum using one of the archives, you can simply use the no-public-dir (Public Path = No) archives and skip the rest of this section. If you're installing via Composer, you'll need to follow the instructions below. Simply move all the files inside the public directory (including .htaccess) into the directory you want to serve Flarum from. Then edit .htaccess and uncomment lines 9-15 in order to protect sensitive resources. For Nginx, uncomment lines 8-11 of .nginx.conf. You will also need to edit the index.php file and change the following line: $site = require './site.php';
Edit the site.php and update the paths in the following lines to reflect your new directory structure: 'base' => __DIR__,
'public' => __DIR__,
'storage' => __DIR__.'/storage',
Finally, check config.php and make sure the url value is correct. Importing Data If you have an existing community and don't want to start from scratch, you may be able to import your existing data into Flarum. While there are no official importers yet, the community has made several unofficial importers: FluxBB MyBB phpBB SMF2 These can be used for other forum software as well by migrating to phpBB first, then to Flarum. Be aware that we can't guarantee that these will work nor can we offer support for them.
| Flarum 版本 | PHP 版本 | 公共路径 | 类型 | 归档文件 |
|---|---|---|---|---|
| 2.0.1 | 8.5 | 否 | TAR.GZ | flarum-v2.0.1-no-public-dir-php8.5.tar.gz |
| 2.0.1 | 8.5 | 否 | ZIP | flarum-v2.0.1-no-public-dir-php8.5.zip |
| 2.0.1 | 8.5 | 是 | TAR.GZ | flarum-v2.0.1-php8.5.tar.gz |
| 2.0.1 | 8.5 | 是 | ZIP | flarum-v2.0.1-php8.5.zip |
| 2.0.1 | 8.4 | 否 | TAR.GZ | flarum-v2.0.1-no-public-dir-php8.4.tar.gz |
| 2.0.1 | 8.4 | 否 | ZIP | flarum-v2.0.1-no-public-dir-php8.4.zip |
| 2.0.1 | 8.4 | 是 | TAR.GZ | flarum-v2.0.1-php8.4.tar.gz |
| 2.0.1 | 8.4 | 是 | ZIP | flarum-v2.0.1-php8.4.zip |
| 2.0.1 | 8.3 | 否 | TAR.GZ | flarum-v2.0.1-no-public-dir-php8.3.tar.gz |
| 2.0.1 | 8.3 | 否 | ZIP | flarum-v2.0.1-no-public-dir-php8.3.zip |
| 2.0.1 | 8.3 | 是 | TAR.GZ | flarum-v2.0.1-php8.3.tar.gz |
| 2.0.1 | 8.3 | 是 | ZIP | flarum-v2.0.1-php8.3.zip |
命令运行期间，你可以先配置 Web 服务器。确保网站根目录（webroot）设置为 /path/to/your/forum/public，并按照下面的说明配置 URL 重写（URL Rewriting）。 一切就绪后，用浏览器访问你的论坛，按提示完成安装。 如果想在后台管理面板中安装和更新扩展，还需要安装 Extension Manager 扩展。 composer require flarum/extension-manager:"*"
warning 扩展管理器允许管理员安装任意 composer 包。只有在完全信任所有论坛管理员时才应安装它。 URL 重写 Apache Flarum 在 public 目录中自带了一个 .htaccess 文件——请确保它已正确上传。如果 mod_rewrite 未启用，或 .htaccess 不被允许，Flarum 将无法正常运行。请向你的主机商（或 VPS 服务商）确认这些功能已开启。如果你自己管理服务器，可能需要在站点配置中添加以下内容以允许 .htaccess 文件生效：
AllowOverride All
这样可以允许 .htaccess 覆盖默认配置，使 Flarum 能正确重写 URL。 启用 mod_rewrite 的方法因操作系统而异：在 Ubuntu 上运行 sudo a2enmod rewrite 即可；CentOS 默认已启用。修改完成后别忘了重启 Apache！ Nginx Flarum 自带一个 .nginx.conf 文件——请确保它已正确上传。然后，假设你已在 Nginx 中配置好 PHP 站点，将以下内容添加到 server 配置块中： include /path/to/flarum/.nginx.conf;
Caddy 只需非常简单的配置，Caddy 就能让 Flarum 正常运行。注意把其中的 URL 替换为你自己的域名，路径替换为你自己的 public 目录。如果使用其他版本的 PHP，还需将 fastcgi 路径改为指向你正确的 PHP socket 或 URL。 www.example.com {
root * /var/www/flarum/public
php_fastcgi unix//var/run/php/php7.4-fpm.sock
header /assets/* {
+Cache-Control "public, must-revalidate, proxy-revalidate"
+Cache-Control "max-age=25000"
Pragma "public"
}
file_server
}
文件夹所有权 在安装过程中，Flarum 可能会要求你授予特定目录的写权限。 现代操作系统通常支持多用户环境，这意味着你登录使用的用户账户与 Flarum 运行所依赖的用户账户可能不同。 Flarum 运行所依赖的用户必须具备对以下目录的读写权限： 根安装目录，以便 Flarum 能够修改 config.php 文件。 storage 子目录，以便 Flarum 能够编辑日志并存储缓存数据。 assets 子目录，以便能够将 logo 和头像上传至文件系统。 扩展插件可能需要其他目录的权限，因此建议你递归地授予整个 Flarum 根安装目录的写权限。 你需要运行若干条命令来设置文件权限。请注意，如果执行其中部分命令后安装过程不再出现警告，则无需执行剩余命令。 首先，你需要允许对目录的写访问。在 Linux 上执行： chmod 775 -R /path/to/directory
如果这还不够，你可能需要检查文件的所有者是否属于正确的组和用户。默认情况下，在大多数 Linux 发行版中，PHP 和 Web 服务器都以 www-data 作为其所属的用户和组。你需要根据具体的发行版和 Web 服务器配置情况进行确认。在大多数 Linux 操作系统中，你可以通过运行以下命令来更改文件夹的所有者： chown -R www-data:www-data /path/to/directory
如果 Web 服务器使用的是其他用户/组，请相应地替换 www-data。 此外，你需要确保你的命令行用户（即你登录终端所用的用户）拥有所有权，这样你才能通过 CLI 安装扩展并管理 Flarum 安装。为此，使用 usermod -a -G www-data YOUR_USERNAME 将当前用户（whoami）添加到 Web 服务器组（通常是 www-data）。此更改可能需要注销并重新登录才能生效。 最后，如果上述方法仍无效，你可能需要配置 SELinux 以允许 Web 服务器向该目录写入数据。执行以下命令： chcon -R -t httpd_sys_rw_content_t /path/to/directory
To find out more about these commands as well as file permissions and ownership on Linux, read this tutorial. If you are setting up Flarum on Windows, you may find the answers to this Super User question useful. Environments may varyYour environment may vary from the documentation provided, please consult your web server configuration or web hosting provider for the proper user and group that PHP and the web server operate under. Never use permission 777You should never set any folder or file to permission level 777, as this permission level allows anyone to access the content of the folder and file regardless of user or group. Customizing Paths By default Flarum's directory structure includes a public directory which contains only publicly-accessible files. This is a security best-practice, ensuring that all sensitive source code files are completely inaccessible from the web root. However, if you wish to host Flarum in a subdirectory (like yoursite.com/forum), or if your host doesn't give you control over your webroot (you're stuck with something like public_html or htdocs), you can set up Flarum without the public directory. If you intend to install Flarum using one of the archives, you can simply use the no-public-dir (Public Path = No) archives and skip the rest of this section. If you're installing via Composer, you'll need to follow the instructions below. Simply move all the files inside the public directory (including .htaccess) into the directory you want to serve Flarum from. Then edit .htaccess and uncomment lines 9-15 in order to protect sensitive resources. For Nginx, uncomment lines 8-11 of .nginx.conf. You will also need to edit the index.php file and change the following line: $site = require './site.php';
Edit the site.php and update the paths in the following lines to reflect your new directory structure: 'base' => __DIR__,
'public' => __DIR__,
'storage' => __DIR__.'/storage',
Finally, check config.php and make sure the url value is correct. Importing Data If you have an existing community and don't want to start from scratch, you may be able to import your existing data into Flarum. While there are no official importers yet, the community has made several unofficial importers: FluxBB MyBB phpBB SMF2 These can be used for other forum software as well by migrating to phpBB first, then to Flarum. Be aware that we can't guarantee that these will work nor can we offer support for them.
