为你踩坑系列：搭建Flarum论坛的一天一夜

苦了我一天一夜的前言

昨天半夜睡不着，哦不，是又犯捣鼓兴趣了，群里一堆论坛大佬，我也想搞一个论坛试试 (不能浪费一点我的服务器)。这篇文章也记录了我踩的坑和思路：

1、选择Docker还是直接框架搭建？

直觉告诉我，必须Docker，相比较直接的LNMP等框架，Docker占用内存小并且搭建很快速。

如果你偏要选择一点一点部署，好吧，我放在下面了
参考官方文档：安装 | Flarum Documentation

2、Docker搭建Flarum

我一开始选择Docker应用商店里面的Flarum的，妈的，发现设置不了账号密码，并且Docker部署的项目的数据库放在”虚拟空间“中，在宝塔里面也没有管理的方式 (可能我太菜了)，所以我选择了docker-compose进行拉取和配置文件。

2-1 创建镜像文件

docker-compose.yml 放在你想放的文件夹，比如我选择网站目录：/www/wwwroot/bbs/docker-compose.yml

另外还有 flarum.env

代码：全选

DEBUG=false
FORUM_URL=    #设置自己网站地址，刚开始也可以设置成公网IP+端口号

# Database configuration
DB_HOST=mariadb
DB_NAME=flarum
DB_USER=flarum
DB_PASS=         #和上方设置的密码保持一致
DB_PREF=flarum_
DB_PORT=3306

# User admin flarum (environment variable for first installation)
# /!\ admin password must contain at least 8 characters /!\
FLARUM_ADMIN_USER=        #网站管理员账户
FLARUM_ADMIN_PASS=    #密码和上面的密码保持一致
FLARUM_ADMIN_MAIL=       #管理员邮箱
FLARUM_TITLE=      #网站标题

然后docker-compose.yml写入内容 (vi 编辑，i 编辑，esc 退出编辑，:wq 保存编辑)

代码：全选

services:
  flarum:
    image: mondedie/flarum:stable
    container_name: flarum
    env_file:
      - flarum.env
    volumes:
      - /var/lib/docker/volumes/flarum/assets:/flarum/app/public/assets
      - /var/lib/docker/volumes/flarum/extensions:/flarum/app/extensions
      - /var/lib/docker/volumes/flarum/storage/logs:/flarum/app/storage/logs
      - /var/lib/docker/volumes/flarum/nginx:/etc/nginx/flarum
    ports:
      - 8080:8888
    depends_on:
      - mariadb

  mariadb:
    image: mariadb:10.5
    container_name: mariadb
    environment:
      - MYSQL_ROOT_PASSWORD=
      - MYSQL_DATABASE=
      - MYSQL_USER=
      - MYSQL_PASSWORD=
    volumes:
      - /var/lib/docker/mysql/db:/var/lib/mysql

2-2 拉取镜像

代码：全选

docker-compose up -d

然后给容器部署网站域名，并且添加SSL

2-3 更新Flarum

我是莫名其妙更新的，因为拉取插件的时候使用了 -W 导致直接更新到最新版本 1.8.x

3、Flarum需要的操作

让我们先到容器里面再操作：
比如宝塔的：

然后到flarum的目录：

你也可以直接：

代码：全选

# 进入容器
docker exec -it flarum sh

cd /flarum/app

3-1 添加中文

代码：全选

composer require flarum-lang/chinese-simplified
php flarum cache:clear

3-2 安装插件

代码：全选

composer require xxx

3-3 卸载插件

代码：全选

composer remove xxx

3-4 清除缓存

代码：全选

php flarum cache:clear

3-5 开启Debug

在app目录里面有config.php文件：

代码：全选

ls

然后编辑即可：

代码：全选

vi config.php

修改debug的false为true

4、出现的问题

4-1 无法写入文件

无法写入文件。请检查操作权限，重试或者直接从命令行运行命令。

代码：全选

清除缓存XHRPOST
https://bbs.tiango.wiki/api/cache
[HTTP/2 409  92ms]

Flarum\Foundation\IOException in /flarum/app/vendor/flarum/core/src/Api/Controller/ClearCacheController.php:56
Stack trace:
#0 /flarum/app/vendor/flarum/core/src/Api/Controller/AbstractDeleteController.php(24): Flarum\Api\Controller\ClearCacheController->delete()
#1 /flarum/app/vendor/flarum/core/src/Http/RouteHandlerFactory.php(41): Flarum\Api\Controller\AbstractDeleteController->handle()
#2 /flarum/app/vendor/flarum/core/src/Http/Middleware/ExecuteRoute.php(27): Flarum\Http\RouteHandlerFactory->Flarum\Http\{closure}()
#3 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\ExecuteRoute->process()
#4 /flarum/app/vendor/flarum/core/src/Api/Middleware/ThrottleApi.php(33): Laminas\Stratigility\Next->handle()
#5 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Api\Middleware\ThrottleApi->process()
#6 /flarum/app/vendor/flarum/core/src/Http/Middleware/CheckCsrfToken.php(44): Laminas\Stratigility\Next->handle()
#7 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\CheckCsrfToken->process()
#8 /flarum/app/vendor/flarum/core/src/Http/Middleware/ResolveRoute.php(69): Laminas\Stratigility\Next->handle()
#9 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\ResolveRoute->process()
#10 /flarum/app/vendor/flarum/core/src/Http/Middleware/SetLocale.php(51): Laminas\Stratigility\Next->handle()
#11 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\SetLocale->process()
#12 /flarum/app/vendor/flarum/core/src/Http/Middleware/AuthenticateWithHeader.php(58): Laminas\Stratigility\Next->handle()
#13 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\AuthenticateWithHeader->process()
#14 /flarum/app/vendor/flarum/core/src/Http/Middleware/AuthenticateWithSession.php(31): Laminas\Stratigility\Next->handle()
#15 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\AuthenticateWithSession->process()
#16 /flarum/app/vendor/flarum/core/src/Http/Middleware/RememberFromCookie.php(63): Laminas\Stratigility\Next->handle()
#17 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\RememberFromCookie->process()
#18 /flarum/app/vendor/flarum/core/src/Http/Middleware/StartSession.php(61): Laminas\Stratigility\Next->handle()
#19 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\StartSession->process()
#20 /flarum/app/vendor/flarum/core/src/Api/Middleware/FakeHttpMethods.php(29): Laminas\Stratigility\Next->handle()
#21 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Api\Middleware\FakeHttpMethods->process()
#22 /flarum/app/vendor/flarum/core/src/Http/Middleware/ParseJsonBody.php(28): Laminas\Stratigility\Next->handle()
#23 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\ParseJsonBody->process()
#24 /flarum/app/vendor/flarum/core/src/Http/Middleware/HandleErrors.php(57): Laminas\Stratigility\Next->handle()
#25 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\HandleErrors->process()
#26 /flarum/app/vendor/flarum/core/src/Http/Middleware/InjectActorReference.php(25): Laminas\Stratigility\Next->handle()
#27 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\InjectActorReference->process()
#28 /flarum/app/vendor/laminas/laminas-stratigility/src/MiddlewarePipe.php(75): Laminas\Stratigility\Next->handle()
#29 /flarum/app/vendor/middlewares/request-handler/src/RequestHandler.php(84): Laminas\Stratigility\MiddlewarePipe->process()
#30 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Middlewares\RequestHandler->process()
#31 /flarum/app/vendor/middlewares/base-path-router/src/BasePathRouter.php(99): Laminas\Stratigility\Next->handle()
#32 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Middlewares\BasePathRouter->process()
#33 /flarum/app/vendor/laminas/laminas-stratigility/src/Middleware/OriginalMessages.php(36): Laminas\Stratigility\Next->handle()
#34 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Laminas\Stratigility\Middleware\OriginalMessages->process()
#35 /flarum/app/vendor/middlewares/base-path/src/BasePath.php(73): Laminas\Stratigility\Next->handle()
#36 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Middlewares\BasePath->process()
#37 /flarum/app/vendor/flarum/core/src/Http/Middleware/ProcessIp.php(24): Laminas\Stratigility\Next->handle()
#38 /flarum/app/vendor/laminas/laminas-stratigility/src/Next.php(49): Flarum\Http\Middleware\ProcessIp->process()
#39 /flarum/app/vendor/laminas/laminas-stratigility/src/MiddlewarePipe.php(75): Laminas\Stratigility\Next->handle()
#40 /flarum/app/vendor/laminas/laminas-stratigility/src/MiddlewarePipe.php(64): Laminas\Stratigility\MiddlewarePipe->process()
#41 /flarum/app/vendor/laminas/laminas-httphandlerrunner/src/RequestHandlerRunner.php(73): Laminas\Stratigility\MiddlewarePipe->handle()
#42 /flarum/app/vendor/flarum/core/src/Http/Server.php(45): Laminas\HttpHandlerRunner\RequestHandlerRunner->run()
#43 /flarum/app/public/index.php(26): Flarum\Http\Server->listen()
#44 {main} admin.js:2:323396

问题可能：

代码：全选

HTTP 409 状态码
代表 “冲突”（Conflict），Flarum 的 ClearCacheController 返回这个错误通常是 缓存正在被占用或锁定。
可能是之前清理缓存的操作未完成，或者某个进程正在写缓存。

IOException
指的是 Flarum 在写入缓存文件时失败。
缓存目录不存在或不可写
缓存目录里残留了被锁定的文件
文件系统不支持锁（某些容器卷挂载方式可能不支持文件锁）

容器卷挂载问题
如果 /storage 或 /public/assets 挂载到宿主机卷上，宿主机文件系统可能 不支持 flock 或锁操作，导致清缓存失败。

查看 storage/cache 目录是否存在锁文件：

代码：全选

/flarum/app # ls -lh /flarum/app/storage/cache

total 16K  
drwxr-xr-x 3 991 991 4.0K Sep 6 09:47 02  
drwxr-xr-x 3 991 991 4.0K Sep 6 09:47 37  
drwxr-xr-x 3 991 991 4.0K Sep 6 09:47 77  
drwxr-xr-x 3 root root 4.0K Sep 6 09:44 ee  
/flarum/app #

显然出现锁文件root用户的：

代码：全选

rm -rf /flarum/app/storage/cache/ee

4-2 无法连接部署的sonic

添加中文搜索功能使用docker部署的sonic项目

具体操作：
出现下面报错：

代码：全选

PHP Warning: stream_socket_client(): Unable to connect to tcp://127.0.0.1:1491 (Connection refused) in /flarum/app/vendor/ppshobi/psonic/src/Client.php on line 66 Invalid sonic server detail!

可能是docker网络连接问题：
可以通过创建网络：

代码：全选

docker network create flarum-net

把 sonic 加入：

代码：全选

docker network connect flarum-net heuristic_visvesvaraya

把 flarum 也放进同一个网络（我的 flarum 容器叫 flarum）：

代码：全选

docker network connect flarum-net flarum

在 flarum 配置里改 Sonic 地址：

代码：全选

    'host' => 'heuristic_visvesvaraya',
    'port' => 1491,
    'password' => 'SecretPassword', // 跟 sonic.cfg 里保持一致

重新执行：

代码：全选

    php flarum sonic:addtoindex

4-3 插件更新容易出现的JS问题

代码：全选

TypeError: can't access property "type", t is undefined
    pushObject Store.ts:125
    pushPayload Store.ts:103
    preloadedApiDocument Application.tsx:367
    ...

说明 Flarum 在加载数据时，后端返回的 API 数据不符合预期。通常发生在：

插件更新后 API schema 变了，但前端 js 还是旧的，导致 Store.pushPayload 收到的 JSON 数据里缺少 type 属性。
缓存问题：前端还在加载老版本的 JS，和后端新版不匹配。
插件 bug 或冲突：某个扩展返回了错误的 JSON（比如返回 null 或者结构不完整）。
数据库字段缺失/迁移没跑：插件升级后需要执行 php flarum migrate，不然返回的数据格式异常。

代码：全选

php flarum migrate
php flarum cache:clear