苦了我一天一夜的前言

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

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

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

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

2、Docker搭建Flarum

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

image.png

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需要的操作

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

然后到flarum的目录：
image.png

你也可以直接：

# 进入容器
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 数据不符合预期。通常发生在：

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