一台 2 核 4G 的机器，装个论坛至于折腾一晚上吗？至于。开源论坛系统本地部署这件事，卡住人的从来不是代码，是 webroot 指错、目录不可写、URL 重写没生效这三样。下面按「报错 → 排查 → 根因 → 修复」的顺序走一遍，以 Flarum 为例，命令与参数请以官方文档最新说明为准。
典型症状：装完打不开，报错长得都差不多
先说现象，看看你撞的是哪一种：
- 访问域名直接 403 或者把目录列出来了——webroot 没指到 public。
- 首页能开，点任何链接都 404——URL 重写没生效。
- 安装向导提示某些目录不可写——属主不是 Web 服务运行用户。
- 能装上，一装扩展就白屏或者报依赖错误——Composer 版本或 PHP 扩展缺。
- 装上能跑，日志每天被一堆 deprecation 刷满——PHP 版本比框架新。
这五类基本覆盖九成。之前整理 Docker Compose 部署那篇时我留过一句「我按这 6 类报错逐个拆掉」，思路是一样的：先把报错分类，再逐类找根因，比盯着一行日志死磕快得多。
排查路径：从外到内，别一上来就翻代码
第一步，核对环境。官方安装文档给的服务端要求是这几条：Apache（启用 mod_rewrite）或 Nginx；PHP 7.3 以上，扩展要带 curl、dom、fileinfo、gd、json、mbstring、openssl、pdo_mysql、tokenizer、zip；数据库 MySQL 5.6+ / 8.0.23+ 或 MariaDB 10.0.5+；还要有 SSH 命令行权限和 Composer（Flarum 官方安装文档）。
扩展别靠眼睛看，直接跑：
php -v
php -m | grep -E "curl|dom|fileinfo|gd|json|mbstring|openssl|pdo_mysql|tokenizer|zip"
composer -V
mysql --version缺哪个补哪个，这一步省不掉。装 PHP 扩展这种事，开发环境搭建的排查顺序里讲过，先确认用的是哪一套 php.ini（命令行和 FPM 经常不是同一份），装完记得重启 FPM。
第二步，拉代码。在一个空目录里执行：
composer create-project flarum/flarum:^1.8.0 .目录必须是空的，包含隐藏文件。如果机器没有 SSH 或者不想用命令行，官方也提供按 PHP 版本打包的归档文件（有无 public 目录两种规格），解压后配好 Web 服务器即可。
第三步，建库。先建一个空数据库和专用账号，字符集用 utf8mb4。这里有个容易忽略的点：MySQL 和 MariaDB 在配置里是两种不同的 driver，装完之后 config.php 里的 driver 必须跟你实际用的数据库对上，对不上就是连不上。
第四步，配 Web 服务器，见下一节。
根因定位：三个真正常见的坑
坑一：webroot 指错了目录
Flarum 的目录结构里有一个 public 子目录，官方明确说这是安全实践——敏感源码文件完全不在 Web 根目录下。你的站点根目录必须指向 /你的路径/flarum/public，指向上一层就会出现目录列表或者直接 403。
坑二：URL 重写没生效
Apache 下，public 目录里有个 .htaccess，官方原话是「mod_rewrite 没启用或者 .htaccess 不被允许的话，Flarum 不能正常工作」。自建服务器要在站点配置里加：
<Directory "/path/to/flarum/public">
AllowOverride All
</Directory>Nginx 则是把仓库里那个 .nginx.conf 包含进来：include /path/to/flarum/.nginx.conf;。忘了这行，首页能开、内页全 404，是最典型的表现。
坑三：目录属主不对
官方要求运行 Flarum 的那个用户对三个位置有读写权限：安装根目录（要写 config.php）、storage 子目录（日志和缓存）、assets 子目录（logo 和头像）。多数 Linux 上 Web 服务的用户是 www-data，常用两条命令：
chmod 775 -R /path/to/flarum
chown -R www-data:www-data /path/to/flarum装扩展之后如果新扩展要写别的目录，可能还得再放行一次。
修复动作：逐条怎么改
上面三条改完，重跑安装向导基本就通了。剩下几个高频问题单独说。
日志被 deprecation 刷屏。官方在 PHP 配置那一节写得很明白：Flarum 1.x 能跑在到 8.5 为止的 PHP 上，但它建立在较旧的框架栈上，在现代 PHP 下部分依赖会产生弃用提示，这属于预期行为、不影响功能。官方建议配上：
error_reporting = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED同时官方的实践结论是：1.x 跑在 PHP 8.3 上效果最好——既有安全支持，稳定性也够。另外官方已经声明 1.x 处于维护末期，只收关键和安全修复，2.0 处在发布候选阶段，新站可以直接评估 2.x 路线。（2.x 的环境要求，比如中文社区整理的 PHP 8.3 起、新增 session 扩展、可选 SQLite 与 PostgreSQL，属于社区整理，动手前请回官方 2.x 文档确认。）
想在后台直接装扩展。官方命令是 composer require flarum/extension-manager:"*"，但文档挂了一条警告：这个扩展允许管理员安装任意 composer 包，只有在你信任全部管理员时才装。生产环境我倾向于不上这个扩展，扩展统一走命令行加版本锁定。
只能放在子目录，或者主机不给改 webroot。官方给了「无 public 目录」方案：把 public 里的文件（含 .htaccess）全部移到你要服务的目录，然后取消注释 .htaccess 的第 9–15 行（Nginx 是 .nginx.conf 的第 8–11 行）来保护敏感文件，再改 site.php 里的 base、public、storage 三个路径，最后检查 config.php 里的 url 值。
老论坛要迁过来。官方没有提供官方导入器，社区有 FluxBB、MyBB、phpBB、SMF2 几个非官方导入器，官方明确不保证可用也不提供支持。稳妥做法是先迁到 phpBB 再迁 Flarum，迁移前一定先在副本上跑一遍——这一点跟批量改名先跑一遍复制模式是同一个道理，先在副本上验证，再对生产动手。
怎么防止再犯
三条纪律，成本都很低。
第一，安装路径别用中文、别带空格。这条在不少开源项目上都会踩，路径相关的兼容问题排查起来特别费时间，之前专门记过一次。
第二，把环境要求写成清单，部署前逐项打勾。扩展列表、PHP 版本、数据库版本、Composer 版本，四行就够，比凭记忆强。真正上线之前，还要按部署成服务的那个检查表再过一遍：进程怎么守护、日志往哪落、备份多久一次。
第三，先在测试目录完整走一遍。空目录、建库、改配置、装扩展，全流程在测试环境跑通再上生产。我一般是先跑一遍写文档，第二次照着文档做，第三次才敢交给别人做。
最后说一句资源预期。论坛这类应用吃的是 PHP 进程和数据库，2 核 4G 起步能跑，但上了量之后瓶颈基本在数据库和缓存，别等到页面变慢才想起来加。同类项目的部署过程我在报表工具那篇部署复盘里也写过，对照着看会省事。
常见问题
没有 SSH 权限还能装吗？
能。官方提供按 PHP 版本打的归档包，有「带 public 目录」和「不带 public 目录」两种规格，解压后配好 Web 服务器，浏览器访问跟着向导走就行。代价是后续装扩展会麻烦，因为没有命令行跑 Composer。
装完首页正常，登录和发帖都 404，是哪一步没做？
URL 重写。Apache 检查 mod_rewrite 是否启用、AllowOverride 是不是 All；Nginx 检查有没有 include 那个 .nginx.conf。改完记得重载服务。
数据库用 MariaDB 行不行？
行，官方要求 MariaDB 10.0.5 以上。只是配置里 driver 要跟实际数据库类型一致，MySQL 和 MariaDB 在 Flarum 里是两套驱动，写错就连不上。
现在新站该装 1.x 还是等 2.0？
官方口径是 1.x 处于维护末期，只收关键和安全修复，2.0 处于发布候选、已有站点在生产运行。要马上上线且不折腾，选 1.x 配 PHP 8.3；新项目不着急，可以先跟 2.x 文档评估。
扩展装多了会不会拖慢？
会。每个扩展都是实打实加载进来的代码。建议按「非装不可」的标准筛，装完做一次前后对比，别一次装十几个。生产环境慎用后台扩展管理器，改走命令行并锁定版本。
