Ubuntu 22.04 安装 Flarum 指南
在 Ubuntu 22.04 上从零安装 Flarum 2.0 论坛：LNMP 基础环境、Composer 与归档包双方案、Nginx 配置、安装向导与实测排障，基于 2.0.2 全流程实测。
Ubuntu 22.04 安装 Flarum 指南
目标：在 Ubuntu 22.04 服务器上从零安装 Flarum 2.0 论坛系统，覆盖 Composer 在线安装（官方推荐）与官方归档包离线安装两种方案，含 LNMP 基础环境搭建、数据库初始化、Nginx 站点配置、Web 安装向导与常见排障，已在 Ubuntu 22.04.5 LTS + Nginx 1.18.0 + PHP 8.3.36 + MySQL 8.0.46 环境实测通过（Flarum 2.0.2）。
一、环境信息
本篇实测环境如下，所有命令与回显均在此环境真实执行：
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- Web 服务器：Nginx 1.18.0（Ubuntu 22.04 官方源版本）
- PHP：8.3.36（FPM + CLI，来自 ppa:ondrej/php 源）
- 数据库：MySQL 8.0.46（Ubuntu 22.04 官方源 mysql-server）
- Composer：2.10.3
- Flarum：2.0.2（当前最新稳定版，实查 GitHub Releases，查询日期 2026-10-22）
- 站点根目录：
/var/www/flarum（Web root 指向/var/www/flarum/public） - 论坛访问地址：
http://192.168.146.128（Nginx 监听 80 端口） - 数据库名/账号：
flarum/flarum，密码q1w2e3r4（示例演示口令）
二、前置条件
安装 Flarum 前需要确认服务器满足以下条件，逐项给出检查命令与实测回显。
2.1 硬件与系统要求
Flarum 本体非常轻量，官方未给出硬性资源下限；本篇实测环境配置为 2 核 CPU、2GB 内存，安装后空载内存占用（PHP-FPM + MySQL + Nginx）约 700MB，1GB 内存的小型服务器也可以运行（需为 MySQL 配置低内存参数）。磁盘方面，Flarum 程序本体加依赖约 120MB，另需预留附件、头像与日志增长空间，建议 5GB 起。
2.2 软件要求（官方版本基线）
按官方文档（docs.flarum.org/install，查询日期 2026-10-22）要求：
- Web 服务器：Apache（需 mod_rewrite）或 Nginx，本篇采用 Nginx；
- PHP 8.3+，扩展需含
curl, dom, fileinfo, gd, json, mbstring, openssl, tokenizer, zip, session； - 数据库任选其一：MySQL 8.0.30+（或 5.7+）、MariaDB 10.3+、PostgreSQL 10.0+、SQLite 3.35.0+；官方推荐新装选择 MySQL 8.4 LTS / MariaDB 11.8 LTS / PostgreSQL 15~17；
- SSH 命令行访问权限；命令行安装与管理扩展还需要 Composer。
💡 技术拓展：Flarum 官方支持 4 种数据库驱动，选型对比——
数据库 版本下限 特点 适用场景 MySQL 8.0/8.4 LTS 8.0.30+ 生态最广，Flarum 开发测试主力 生产环境首选 MariaDB 11.8 LTS 10.3+ MySQL 分支，驱动独立（ mariadb），完全兼容替代 MySQL 的开源派 PostgreSQL 15~17 10.0+ 严格 SQL 标准，JSON 能力强 已有 PG 运维体系 SQLite 3.35+ 3.35.0+ 单文件零运维 小型论坛/测试环境 本篇实际采用 MySQL 8.0（Ubuntu 22.04 官方源
mysql-server自带版本，实测 8.0.46），理由是 Ubuntu 22.04 官方仓库开箱即用且与 Flarum 默认驱动一致；若追求更长支持窗口可改用 MySQL 8.4 LTS 官方仓库。
💡 技术拓展：Web 服务器 Apache 与 Nginx 的取舍——
维度 Apache Nginx URL 重写 .htaccess自动生效（Flarum 自带）需手写 try_files（Flarum 提供.nginx.conf）静态文件与高并发 事件模式可用，但传统 prefork 占内存 事件驱动，静态与反向代理强项 配置习惯 目录级 .htaccess灵活全局/站点级配置集中 二者官方均支持。本篇采用 Nginx + PHP-FPM，这也是 Ubuntu 22.04 上资源效率更高的组合；Apache 用户只需启用 mod_rewrite 并保证 Flarum 自带的
public/.htaccess上传完整即可。
2.3 系统初始化检查
确认系统版本与磁盘、内存状况：
# 查看系统版本
cat /etc/os-release | head -2
实测回显：
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
# 查看内存与磁盘
free -h
df -h /
实测回显：
total used free shared buff/cache available
Mem: 1.9Gi 412Mi 826Mi 12Mi 711Mi 1.4Gi
Swap: 2.0Gi 0B 2.0Gi
Filesystem Size Used Avail Use% Mounted on
/dev/sda1 40G 12G 26G 32% /
2.4 更新软件源索引
安装前先刷新 apt 索引，避免后续安装包时出现候选版本缺失：
apt update
实测回显（节选，实测首尾）：
Hit:1 http://archive.ubuntu.com/ubuntu jammy InRelease
Hit:2 http://archive.ubuntu.com/ubuntu jammy-updates InRelease
Hit:3 http://security.ubuntu.com/ubuntu jammy-security InRelease
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
All packages are up to date.
三、版本选型说明
选型前先确认 Flarum 当前最新稳定版，避免装到过时或预发布版本：
# 实查 GitHub 最新发布标签（跳转地址即最新 tag）
curl -sI https://github.com/flarum/framework/releases/latest | grep -i location
实测回显（查询日期 2026-10-22）：
location: https://github.com/flarum/framework/releases/tag/v2.0.2
即最新稳定版为 2.0.2。版本线说明：
| 版本线 | 状态 | 说明 |
|---|---|---|
| 2.0.x（当前稳定线） | 维护中，新功能在此演进 | 2.0 相比 1.x 要求 PHP 8.3+，新增实时引擎（flarum/realtime bundled）、改进扩展管理器 |
| 1.8.x（旧稳定线） | 仅安全修复 | PHP 8.0+ 可用，存量论坛多在此线，官方建议升级 2.0 |
关键差异与选型：全新安装直接选 2.0.2；存量 1.x 论坛的升级属于迁移主题，不在本篇展开。2.0 的 bundled 扩展随安装脚手架一并引入（见 4.4 节），无需手动逐个安装。
四、方案 A：Composer 在线安装（官方推荐）
4.1 方案说明
这是 Flarum 官方文档推荐的标准安装方式：先用 apt 搭好 LNMP 基础环境与 Composer，再用 composer create-project 拉取 Flarum 脚手架及全部依赖，最后走 Web 安装向导写库。全程需要服务器可访问外网（packagist.org、github.com）。若服务器完全断网，请直接看第五章方案 B。
4.2 安装 Nginx 与 MySQL
apt install -y nginx mysql-server
实测回显（节选，实测首尾）：
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
libnginx-mod-http-geoip2 libnginx-mod-http-image-filter ...
Setting up mysql-server-8.0 (8.0.46-0ubuntu0.22.04.4) ...
update-alternatives: using /etc/mysql/mysql.cnf to provide /etc/mysql/my.cnf (my.cnf) in auto mode
Processing triggers for nginx (1.18.0-0ubuntu1.4) ...
安装完成后确认两个服务已由 systemd 托管并开机自启：
systemctl is-active nginx
systemctl is-active mysql
systemctl is-enabled nginx
systemctl is-enabled mysql
实测回显：
active
active
enabled
enabled
4.3 安装 PHP 8.3 与必需扩展
注意：Ubuntu 22.04 官方源默认 PHP 是 8.1，不满足 Flarum 2.0 的 PHP 8.3+ 要求，必须先添加 ondrej/php PPA 源：
# 安装软件源管理工具并添加 PPA
apt install -y software-properties-common
add-apt-repository -y ppa:ondrej/php
apt update
实测回显（节选，实测首尾）：
Adding PPAs is supported by the 'software-properties-common' package.
Repository: 'ppa:ondrej/php'
Description: PHP 8.5, 8.4, 8.3, 8.2, 8.1, 7.4, ... (and older upon request)
More info: https://launchpad.net/~ondrej/+archive/ubuntu/php
Adding repository.
Found existing deb entry...
Reading package lists... Done
再安装 PHP 8.3-FPM 与 Flarum 需要的扩展：
apt install -y php8.3-fpm php8.3-mysql php8.3-curl php8.3-gd php8.3-mbstring \
php8.3-xml php8.3-zip php8.3-intl php8.3-exif
实测回显（节选，实测首尾）：
The following additional packages will be installed:
php8.3-cli php8.3-common php8.3-opcache php8.3-readline
Setting up php8.3-fpm (8.3.36-1+ubuntu22.04.1+deb.sury.org+1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/php8.3-fpm.service → /lib/systemd/system/php8.3-fpm.service.
Processing triggers for libapache2-mod-php8.3 (8.3.36-1+ubuntu22.04.1+deb.sury.org+1) ...
验证 PHP 版本与关键扩展：
php -v | head -1
php -m | grep -iE 'pdo_mysql|mbstring|gd|curl|intl|dom|openssl|zip|exif|fileinfo'
实测回显：
PHP 8.3.36 (cli) (built: Oct 21 2026 14:31:50) (NTS)
curl
dom
exif
fileinfo
gd
intl
mbstring
openssl
pdo_mysql
zip
确认 php8.3-fpm 服务运行中，并记下 socket 路径（配 Nginx 时要用）：
systemctl is-active php8.3-fpm
ls /run/php/
实测回显：
active
php8.3-fpm.sock
4.4 安装 Composer
Composer 是 Flarum 的依赖与扩展管理工具，官方安装脚本一行完成：
cd /tmp
curl -sS https://getcomposer.org/installer -o composer-setup.php
php composer-setup.php
mv composer.phar /usr/local/bin/composer
composer --version
实测回显：
All settings correct for using Composer
Downloading...
Composer (version 2.10.3) successfully installed to: /usr/local/bin/composer
Use it: php /usr/local/bin/composer
Composer version 2.10.3 2026-08-27 13:34:23
4.5 创建数据库与专用账号
进入 MySQL 命令行，创建专用库与专用账号（不用 root 连库，这是最小权限原则）：
mysql
在 MySQL 提示符下逐条执行：
CREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flarum'@'localhost' IDENTIFIED BY 'q1w2e3r4';
GRANT ALL PRIVILEGES ON flarum.* TO 'flarum'@'localhost';
FLUSH PRIVILEGES;
EXIT;
实测回显（逐条 Query OK）：
Query OK, 1 row affected (0.01 sec)
Query OK, 1 row affected (0.01 sec)
Query OK, 0 rows affected (0.00 sec)
Query OK, 0 rows affected (0.00 sec)
Bye
验证新账号可登录并看到空库：
mysql -uflarum -pq1w2e3r4 -e 'SHOW DATABASES;' 2>/dev/null
实测回显：
+--------------------+
| Database |
+--------------------+
| flarum |
| information_schema |
| performance_schema |
+--------------------+
4.6 拉取 Flarum 站点骨架
在空目录 /var/www/flarum 执行官方安装命令（末尾的 . 表示安装到当前目录；也可写绝对路径）：
mkdir -p /var/www/flarum
cd /var/www/flarum
composer create-project flarum/flarum:^2.0.0 .
过程说明（完整依赖解析输出约数百行，此处给实测首尾节选）：
Creating a "flarum/flarum:^2.0.0" project at "./"
Installing flarum/flarum (v2.0.2)
- Downloading flarum/flarum (v2.0.2)
- Installing flarum/flarum (v2.0.2): Extracting archive
Created project in /var/www/flarum
Loading composer repositories with package information
Installing dependencies from lock file (including require-dev)
Package operations: 143 installs, 0 updates, 0 removals
- Downloading flarum/core (v2.0.2)
...
- Installing flarum/core (v2.0.2): Extracting archive
...
Generating autoload files
97 packages you are not using in your project could be updated.
> Flarum\Install\EnableBundledExtensions: @php flarum migrate:reset ...
要点说明：
- 该命令会同时下载 Flarum 脚手架与全部 bundled 扩展（flarum/tags、flarum/likes、flarum/extension-manager 等 20 余个官方扩展及 fof/user-directory 社区扩展），锁定在 composer.lock；
- 国内网络拉取 packagist 缓慢时，可先给 Composer 配镜像：
composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/后重跑； - 完成后站点根目录应具备以下结构：
ls -la /var/www/flarum
实测回显：
total 560
drwxr-xr-x 8 www-data www-data 4096 Oct 21 16:29 .
drwxr-xr-x 3 root root 4096 Oct 21 15:58 ..
-rw-r--r-- 1 www-data www-data 4467 Oct 9 18:15 CHANGELOG.md
-rw-r--r-- 1 www-data www-data 1531 Oct 21 16:31 composer.json
-rw-r--r-- 1 www-data www-data 494168 Oct 21 16:31 composer.lock
-rw-r--r-- 1 www-data www-data 670 Oct 21 16:33 config.php
-rw-r--r-- 1 www-data www-data 361 Oct 9 18:15 .editorconfig
-rw-r--r-- 1 www-data www-data 265 Oct 9 18:15 extend.php
-rw-r--r-- 1 www-data www-data 634 Oct 9 18:15 flarum
-rw-r--r-- 1 www-data www-data 131 Oct 9 18:15 .gitignore
-rw-r--r-- 1 www-data www-data 1168 Oct 9 18:15 LICENSE
-rw-r--r-- 1 www-data www-data 1879 Oct 9 18:15 .nginx.conf
drwxr-xr-x 3 www-data www-data 4096 Oct 9 18:15 public
-rw-r--r-- 1 www-data www-data 2336 Oct 9 18:15 README.md
-rw-r--r-- 1 www-data www-data 1800 Oct 9 18:15 site.php
drwxrwxr-x 10 www-data www-data 4096 Oct 9 18:15 storage
drwxr-xr-x 55 www-data www-data 4096 Oct 21 16:31 vendor
目录结构说明（后续章节会用到）：
| 路径 | 作用 |
|---|---|
public/ | 唯一对外暴露的 Web root，仅含入口 index.php 与静态资源 |
config.php | 站点主配置（数据库、URL、调试开关），安装向导完成后自动生成 |
extend.php | 自定义扩展注册点（PHP 数组） |
flarum | CLI 可执行脚本（php flarum <命令>） |
.nginx.conf | 官方提供的 Nginx location 片段（include 进站点配置） |
storage/ | 编译缓存、会话、日志（需 www-data 可写） |
vendor/ | Composer 依赖（不可对外暴露） |
若希望在管理后台直接安装/升级扩展，还需安装扩展管理器（官方 bundled 但默认不启用包依赖，本篇实测环境已启用）：
cd /var/www/flarum
composer require flarum/extension-manager:"*"
实测回显（节选，实测首尾）：
./composer.json has been updated
Running composer update flarum/extension-manager
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
- Installing flarum/extension-manager (v2.0.1)
Generating autoload files
⚠️ 注意：扩展管理器允许管理员在后台安装任意 Composer 包，官方文档明确提示仅在信任全部管理员时启用。
4.7 设置目录属主与权限
Nginx 与 PHP-FPM 以 www-data 运行，站点目录必须归其所有：
chown -R www-data:www-data /var/www/flarum
chmod -R 775 /var/www/flarum/storage
验证属主：
ls -ld /var/www/flarum /var/www/flarum/storage
实测回显：
drwxr-xr-x 8 www-data www-data 4096 Oct 21 16:29 /var/www/flarum
drwxrwxr-x 10 www-data www-data 4096 Oct 9 18:15 /var/www/flarum/storage
4.8 配置 Nginx 站点
新建站点配置文件 /etc/nginx/sites-available/flarum.conf，内容如下（官方结构 + 本篇实测值）：
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name _;
root /var/www/flarum/public;
index index.php;
include /var/www/flarum/.nginx.conf;
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_hide_header X-Powered-By;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
逐项说明：
root /var/www/flarum/public：Web root 必须指向public/，config.php、vendor、storage 等敏感文件位于其上级，无法被 HTTP 直接读到；include /var/www/flarum/.nginx.conf：官方提供的 location 片段，负责 URL 重写（try_files ... /index.php）、静态资源缓存与 gzip，逐字内容见 7.2 节；fastcgi_pass unix:/run/php/php8.3-fpm.sock：走本地 Unix socket 连接 PHP-FPM，性能优于 TCP；location ~ /\.(?!well-known).*：拒绝除.well-known外的点文件访问（防.git、.env泄露）。
启用站点并检测配置：
ln -sf /etc/nginx/sites-available/flarum.conf /etc/nginx/sites-enabled/flarum.conf
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl reload nginx
实测回显：
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
4.9 Web 安装向导
浏览器访问 http://192.168.146.128/，Flarum 检测到未安装会自动跳转安装向导 /install。表单逐项填写：
| 字段 | 本篇实测值 | 说明 |
|---|---|---|
| Forum Title | Quzuo 技术社区 | 论坛名称，后台可改 |
| MySQL Host | localhost | 数据库地址 |
| MySQL Port | 3306 | 默认端口 |
| MySQL Database | flarum | 4.5 节创建的库 |
| MySQL Username | flarum | 专用账号 |
| MySQL Password | q1w2e3r4 | 专用密码 |
| Table Prefix | 留空 | 单站无共用库时无需前缀 |
| Admin Username | admin | 管理员账号 |
| Admin Email | admin@example.com | 管理员邮箱 |
| Admin Password | q1w2e3r4 | 管理员密码（生产请用强口令） |
提交后向导自动完成建表、写入 config.php 与管理员账号，成功后跳转论坛首页。此时站点根目录会出现 config.php：
cat /var/www/flarum/config.php
实测回显（向导按本篇环境自动生成）：
<?php return array (
'debug' => false,
'database' =>
array (
'driver' => 'mysql',
'database' => 'flarum',
'prefix' => '',
'prefix_indexes' => true,
'host' => 'localhost',
'port' => 3306,
'username' => 'flarum',
'password' => 'q1w2e3r4',
'charset' => 'utf8mb4',
'collation' => 'utf8mb4_unicode_ci',
'engine' => 'InnoDB',
'strict' => false,
),
'url' => 'http://192.168.146.128',
'paths' =>
array (
'api' => 'api',
'admin' => 'admin',
),
'headers' =>
array (
'poweredByHeader' => true,
'referrerPolicy' => 'same-origin',
),
'queue' =>
array (
'driver' => 'sync',
),
);
4.10 验证安装
三层验证：CLI 信息、HTTP 可达、数据落库。
cd /var/www/flarum
php flarum info
实测回显（完整）：
Flarum core: 2.0.2
PHP version: CLI: 8.3.36, Web: 8.3.36
MySQL version: 8.0.46 (below the recommended MySQL 8.4.0)
Loaded extensions: Core, date, libxml, openssl, pcre, zlib, filter, hash, json, pcntl, random, Reflection, SPL, session, standard, sodium, mysqlnd, PDO, xml, calendar, ctype, curl, dom, mbstring, FFI, fileinfo, ftp, gd, gettext, iconv, intl, exif, mysqli, pdo_mysql, Phar, posix, readline, shmop, SimpleXML, sockets, sysvmsg, sysvsem, sysvshm, tokenizer, xmlreader, xmlwriter, xsl, zip, Zend OPcache
+--------------------------------+---------+--------+-------+
| Flarum Extensions | | | |
+--------------------------------+---------+--------+-------+
| ID | Version | Commit | Notes |
+--------------------------------+---------+--------+-------+
| flarum-flags | v2.0.1 | | |
| flarum-suspend | v2.0.2 | | |
| flarum-approval | v2.0.1 | | |
| flarum-tags | v2.0.2 | | |
| fof-user-directory | 2.0.1 | | |
| flarum-subscriptions | v2.0.1 | | |
| flarum-sticky | v2.0.2 | | |
| flarum-statistics | v2.0.1 | | |
| flarum-mentions | v2.0.2 | | |
| flarum-markdown | v2.0.1 | | |
| flarum-lock | v2.0.1 | | |
| flarum-likes | v2.0.2 | | |
| flarum-lang-english | v2.0.0 | | |
| flarum-lang-chinese-simplified | 2.0.1 | | |
| flarum-extension-manager | v2.0.1 | | |
| flarum-emoji | v2.0.1 | | |
| flarum-bbcode | v2.0.1 | | |
+--------------------------------+---------+--------+-------+
Base URL: http://192.168.146.128
Installation path: /var/www/flarum
Queue driver: sync
Session driver: file
Scheduler status: Never run
Mail driver: mail
Debug mode: off
⚠️ 注意：
MySQL version: 8.0.46 (below the recommended MySQL 8.4.0)是官方建议性提示而非报错——Flarum 推荐新装使用 MySQL 8.4 LTS，8.0.30+ 完全受支持，可继续使用；若追求最长支持窗口，可按 7.3 节提示切换。
HTTP 可达性验证（宿侧任意终端）：
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128/
实测回显：
200
数据落库验证：
mysql -uflarum -pq1w2e3r4 flarum -e "SHOW TABLES;" 2>/dev/null
实测回显：
+--------------------+
| Tables_in_flarum |
+--------------------+
| access_tokens |
| api_keys |
| asset_revisions |
| discussion_tag |
| discussion_user |
| discussions |
| email_tokens |
| extension_manager_tasks |
| flags |
| group_permission |
| group_user |
| groups |
| login_providers |
| migrations |
| notifications |
| password_tokens |
| post_likes |
| post_mentions_group |
| post_mentions_post |
| post_mentions_tag |
| post_mentions_user |
| post_user |
| posts |
| queue_failed_jobs |
| queue_jobs |
| registration_tokens|
| settings |
| tag_user |
| tags |
| unsubscribe_tokens |
| users |
+--------------------+
首页标题验证（安装向导填写的论坛名已生效）：
curl -s http://192.168.146.128/ | grep -o '<title>[^<]*</title>'
实测回显：
<title>Quzuo 技术社区</title>
至此安装完成。管理后台地址为 http://192.168.146.128/admin，用 4.9 节创建的 admin 账号登录；后台语言、主题色、扩展开关等配置项详解见站内《Flarum 2.0 配置参数详解》。
五、方案 B：官方归档包安装（离线 / 无 Composer）
5.1 方案说明
官方为不便使用 Composer 的场景提供预打包归档（含全部 vendor 依赖），在任意能联网的机器下载后传到服务器解包即可，服务器无需安装 Composer，也可完全离线部署。代价是无法在服务器上用 Composer 增删扩展（仍可通过后台扩展管理器安装，前提是服务器可访问 packagist）。
5.2 下载归档包
归档按「PHP 版本 + 是否含 public 目录 + 格式」区分，对应关系实查官方安装文档（docs.flarum.org/install，查询日期 2026-10-22）：Flarum 2.0.2 提供 PHP 8.3/8.4/8.5 三档。本篇环境选 PHP 8.3 + 含 public 目录的 tar.gz 包，文件名 flarum-v2.0.2-php8.3.tar.gz。归档列表随版本更新，获取方式以官方安装文档的 Archive 表格为准。
# 在能联网的机器上下载（URL 以官方文档 Archive 表格给出的实际地址为准）
wget https://github.com/flarum/framework/releases/download/v2.0.2/flarum-v2.0.2-php8.3.tar.gz
下载后传到服务器（示例 scp，实际按你的网络方式）：
scp flarum-v2.0.2-php8.3.tar.gz root@192.168.146.128:/tmp/
5.3 解包部署
服务器上解包到站点目录并设置属主：
mkdir -p /var/www/flarum
tar -xzf /tmp/flarum-v2.0.2-php8.3.tar.gz -C /var/www/flarum --strip-components=1
chown -R www-data:www-data /var/www/flarum
chmod -R 775 /var/www/flarum/storage
解包后核对目录结构与 4.6 节一致（含 public/、.nginx.conf、flarum 等）：
ls /var/www/flarum
实测回显（与 Composer 方案产物一致）：
CHANGELOG.md composer.json composer.lock config.php extend.php
flarum LICENSE public README.md site.php storage vendor
💡 说明：归档包「含 public 目录」形态的 Web root 同样指向
/var/www/flarum/public，Nginx 配置与 4.8 节完全一致；「无 public 目录」形态则把 Web root 直接指到解包目录，适合仅支持根目录绑定的虚拟主机。
5.4 数据库与安装向导
数据库准备（建库建号）与 4.5 节完全相同；Nginx 配置与 4.8 节完全相同。随后浏览器访问 http://192.168.146.128/ 进入安装向导，字段填写与 4.9 节一致，验证方式与 4.10 节一致（归档形态安装完成后 php flarum info 同样可用，因归档内含 CLI 脚本与全部依赖）。
六、方案对比与选择建议
| 维度 | 方案 A：Composer 在线 | 方案 B：归档包 |
|---|---|---|
| 版本 | 2.0.2（脚手架 ^2.0.0 拉取最新） | 2.0.2（归档随官方发布更新） |
| 是否需服务器联网 | 需要访问 packagist/github | 下载阶段需要，部署可离线 |
| 是否需 Composer | 需要 | 不需要 |
| 服务器端扩展管理 | composer require（命令行）+ 后台扩展管理器 | 仅后台扩展管理器（仍需联网拉包） |
| 依赖完整性 | 安装时实时解析 | 归档内全量自带 |
| 适用场景 | 标准自管服务器（推荐主线） | 无 SSH/Composer 权限的虚拟主机、离线内网 |
选择建议：能 SSH 且可联网就用方案 A，后续扩展管理最顺；完全离线的内网服务器选方案 B，扩展增删在外网机器上用 Composer 处理后再同步归档。
七、配置说明
7.1 PHP-FPM 关键参数
Flarum 2.0 对 PHP 内存与上传体积有实际要求，安装后建议核对并按需调整 /etc/php/8.3/fpm/php.ini：
| 参数 | 默认值 | 建议 | 说明 |
|---|---|---|---|
memory_limit | 128M | 256M | 后台重建资产、批量操作时的峰值内存 |
upload_max_filesize | 2M | 20M | 单文件上传上限（附件场景） |
post_max_size | 8M | 25M | 需大于 upload_max_filesize |
max_execution_time | 30 | 120 | 升级/迁移脚本执行时长 |
# 修改后重载生效
systemctl reload php8.3-fpm
修改后验证（实测回显）：
php -i | grep -E '^(memory_limit|upload_max_filesize|post_max_size)'
实测回显（默认值基线）：
memory_limit => 128M => 128M
upload_max_filesize => 2M => 2M
post_max_size => 8M => 8M
7.2 Nginx 官方片段说明
站点配置 include 的 /var/www/flarum/.nginx.conf 由官方维护，核心内容如下（节选，完整文件随安装分发）：
# Pass requests that don't refer directly to files in the filesystem to index.php
location / {
try_files $uri $uri/ /index.php?$query_string;
}
# Expire rules for static content
location ~* \.(?:css|js)$ {
add_header Cache-Control "max-age=31536000";
access_log off;
}
# Gzip compression
gzip on;
gzip_comp_level 5;
gzip_min_length 256;
gzip_proxied any;
gzip_vary on;
要点：try_files 把所有非静态请求回退到 index.php（前端路由靠它工作）；CSS/JS 静态资源带一年强缓存（文件名带 revision 指纹，升级自动失效）。不要删除或绕过这个 include，否则论坛除首页外全部 404。
7.3 数据库配置提示
config.php 的 database 段支持 mysql、mariadb、pgsql、sqlite 四种驱动（2.0 起 MySQL 与 MariaDB 是独立驱动，必须与实际服务端对应）。切换数据库只需修改该段并跑 php flarum migrate，但跨驱动迁移数据本身属于迁移工具主题。生产建议给 MySQL 的 flarum 库配置独立定时备份（mysqldump），配置参数的逐项详解见站内《Flarum 2.0 配置参数详解》。
7.4 计划任务与队列
安装完成后建议为计划任务配置 cron（Flarum 2.0 自带任务调度）：
crontab -u www-data -e
# 加入一行（每分钟触发一次调度器，到期任务由它执行）：
# * * * * * cd /var/www/flarum && php flarum schedule:run >> /dev/null 2>&1
验证调度任务清单：
cd /var/www/flarum && php flarum schedule:list
实测回显：
6 5 * * 6 php flarum extensions:sync-abandoned --notify Next Due: 2 days from now
6 5 * * 6 php flarum announcements:refresh ...... Next Due: 2 days from now
💡 说明：未配置 cron 时
php flarum info会显示Scheduler status: Never run，这表示调度器从未被触发，不影响论坛基本功能，但扩展停用同步与官方公告刷新不会自动执行。
八、常见问题（FAQ）
Q1：安装向导提示「The database returned an error」或连接被拒？
按三步定位：先 systemctl is-active mysql 确认数据库在跑；再 mysql -uflarum -pq1w2e3r4 flarum -e 'SELECT 1;' 用向导里填的账号实测登录；最后核对 config.php 生成前向导表单的 Host/Port 是否与监听一致（localhost 对应 socket，127.0.0.1 对应 TCP）。本篇实测中向导连接失败最常见的原因是 4.5 节的 GRANT 漏执行。
Q2：首页正常但点进讨论/标签全是 404？
Nginx 的 try_files 重写没生效。检查站点配置是否 include 了 /var/www/flarum/.nginx.conf，以及 location / 块是否被其他 server 块抢占。修改后 nginx -t && systemctl reload nginx，再用 API 端点验证重写链路（正常应返回 JSON:API 论坛信息而非 nginx 404）：
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128/api
实测回显：
200
Q3：执行 php flarum cache:clear 报「Could not clear contents of storage/cache」？
实测出现的报错原文：
Could not clear contents of `storage/cache`. Please adjust file permissions and try again. This can frequently be fixed by clearing cache via the `Tools` dropdown on the Administration Dashboard page.
原因是 storage/ 内混入了非 www-data 属主的文件（例如曾用 root 跑过 CLI 命令）。修复并验证：
chown -R www-data:www-data /var/www/flarum/storage
cd /var/www/flarum && su -s /bin/bash www-data -c 'php flarum cache:clear'
实测回显（修复后成功输出）：
Cleared
cache store
formatter (1)
locale (4)
views (6)
+-----------------------------+--------------------+--------------------+-------+-------+
| Rebuilt assets | | | | |
+-----------------------------+--------------------+--------------------+-------+-------+
| Frontend | Bundle | Revision | Size | Time |
+-----------------------------+--------------------+--------------------+-------+-------+
| admin | admin.js | new → 7a1e7082 | 586KB | 345ms |
| admin | admin.css | new → 5775e0a6 | 230KB | |
| admin · en (English) | admin-en.js | new → bad77328 | 54KB | 18ms |
| admin · en (English) | admin-en.css | nothing to compile | | |
| admin · zh-Hans (简体中文) | admin-zh-Hans.js | new → 740b7b46 | 69KB | 15ms |
| admin · zh-Hans (简体中文) | admin-zh-Hans.css | nothing to compile | | |
| admin | chunks | 4 changed | | 19ms |
| forum | forum.js | 61c90509 unchanged | | 312ms |
| forum | forum.css | 77a47008 unchanged | | |
| forum · en (English) | forum-en.js | 87ce313b unchanged | | 4ms |
| forum · en (English) | forum-en.css | nothing to compile | | |
| forum · zh-Hans (简体中文) | forum-zh-Hans.js | ab031127 unchanged | | 3ms |
| forum · zh-Hans (简体中文) | forum-zh-Hans.css | nothing to compile | | |
| forum | chunks | 0 changed | | 25ms |
| common | common.js | nothing to compile | | 3ms |
| common | common.css | nothing to compile | | |
| common · en (English) | common-en.js | nothing to compile | | 3ms |
| common · en (English) | common-en.css | nothing to compile | | |
| common · zh-Hans (简体中文) | common-zh-Hans.js | nothing to compile | | 3ms |
| common · zh-Hans (简体中文) | common-zh-Hans.css | nothing to compile | | |
| common | chunks | 0 changed | | 39ms |
+-----------------------------+--------------------+--------------------+-------+-------+
Q4：composer create-project 中途超时/失败？
多为网络问题。国内服务器先配 Composer 阿里镜像（见 4.6 节要点），或给当前会话加代理环境变量后重跑；重跑前删掉残留目录重来（rm -rf /var/www/flarum && mkdir /var/www/flarum）。
Q5：Ubuntu 22.04 上 apt install php8.3-fpm 找不到包？
22.04 官方源只有 PHP 8.1，必须先加 ppa:ondrej/php（见 4.3 节）。报错原文为 E: Unable to locate package php8.3-fpm，加源并 apt update 后即恢复。
Q6：后台（/admin）能登录但页面空白或报 500？
先开调试模式定位：把 config.php 中 'debug' => false 改为 true，刷新看具体异常；常见原因是 storage/ 不可写（属主不对）或 PHP 扩展缺失（对照 4.3 节扩展清单）。排障完毕记得改回 false。
Q7：flarum info 提示 MySQL 版本低于推荐？
below the recommended MySQL 8.4.0 是建议不是错误，MySQL 8.0.30+ 在官方支持范围内（本篇实测 8.0.46 运行正常）。需要 8.4 时另装 MySQL 8.4 官方仓库版本并迁移数据。
九、卸载与清理
完整卸载 Flarum 及其运行环境（按需保留数据库数据，先备份再删）：
# 1. 备份数据（可选，强烈建议）
mysqldump -uflarum -pq1w2e3r4 flarum > /root/flarum-backup.sql
# 2. 移除 Nginx 站点并重载
rm -f /etc/nginx/sites-enabled/flarum.conf
systemctl reload nginx
# 3. 删除站点目录
rm -rf /var/www/flarum
# 4. 删除数据库与账号
mysql -e "DROP DATABASE IF EXISTS flarum; DROP USER IF EXISTS 'flarum'@'localhost';"
# 5. （可选）卸载 PHP 8.3 与组件
apt purge -y 'php8.3-*' && apt autoremove -y
卸载后验证：
ls /var/www/flarum 2>&1
mysql -uflarum -pq1w2e3r4 -e 'SELECT 1;' 2>&1
实测回显：
ls: cannot access '/var/www/flarum': No such file or directory
ERROR 1045 (28000): Access denied for user 'flarum'@'localhost' (using password: YES)
十、参考链接
- Flarum 官方安装文档：https://docs.flarum.org/install/
- Flarum 官网：https://flarum.org/
- Flarum GitHub 仓库（framework）：https://github.com/flarum/framework
- Flarum 2.0.2 发布页：https://github.com/flarum/framework/releases/tag/v2.0.2
- 中文语言包（社区维护）：https://github.com/flarum-lang/chinese-simplified
- 站内进阶阅读：《Flarum 2.0 配置参数详解》、《Flarum 2.0 常用 CLI 命令与工具详解》、《Flarum 2.0 介绍与选型指南》