跳到主要内容

论坛

生如夏花论坛基于 Flarum 开源论坛框架二次开发,该框架基于 PHP,优点是其软件架构清晰,前端部分比较现代,而且可扩展性强,有大量社区扩展可供使用。生如夏花论坛以容器化的方式来运行 Flarum,其中 PHP-FPM、Nginx、MySQL 分别为一个容器,另有一个 phpMyAdmin 容器用于后台管理。

开发

请首先在本地安装 Docker Desktop

快速上手

克隆仓库后,在仓库根目录新建一个 .env 文件,设置以下变量:

MYSQL_DATABASE=flarum
MYSQL_USER=flarum
MYSQL_PASSWORD=password
MYSQL_ROOT_PASSWORD=password

这里的密码仅用于本地预览,可以随意设置。然后运行 docker compose up -d 即可在 http://localhost:4000 访问论坛。

文件结构概览

nginx/ 文件夹中包含了所有与 Nginx 相关的配置,包括整体配置(nginx/nginx.conf)和 Flarum 的配置(nginx/conf.d/flarum.conf)。在构建时,这个文件夹中的所有文件将被打包进 Nginx 容器中。这一部分目前调整过的内容主要是全局的 client_max_body_size=1024M,而 Flarum 部分基本相比 Flarum 脚手架中的内容没有变化。

flarum/php/ 文件夹中包含了所有与 PHP-FPM 相关的配置,包括 PHP 全局配置(flarum.ini)和关于进程管理的配置(zzz-flarum.conf)。在构建时,这个文件夹中的配置文件将被打包进 PHP-FPM 容器中,覆盖一些配置项。

flarum/www/ 文件中包含了论坛本身的代码。论坛是一个 Composer 项目,用 composer.json 定义了相关依赖,包括 Flarum 论坛框架的核心部分和一些插件(如果你不了解什么是 Composer,它类似于 Node.js 的 npm 或者 Python 的 pip)。依赖安装在 flarum/www/vendor/ 目录下。这个目录下面的其他几个文件为:

  • site.php 是 Flarum 的主入口文件,它被 public/index.phpflarum 同时引用,前者是面向用户的网站根目录,后者是用于服务器端的一些脚本运行(如清除缓存是运行 php flarum cache:clear
  • config.php 是 Flarum 的主配置文件,包含了一些数据库的配置和路由配置。在开发中,这里的 debug 应该设为 true,而部署时应该设为 false
  • extend.php 可以写一些简单的脚本扩展 Flarum,不过目前我们的扩展都是写成独立的 package

Flarum 插件的安装和管理

插件网站上找到需要的插件,在本地开发时用 docker exec bbs-flarum-1 /bin/sh 进入容器并运行 composer require xxx 安装,这会导致 composer.jsoncomposer.lock 文件的修改。部署时会按这两个文件的内容重新安装各插件。

Flarum 二次开发

所有目前针对生如夏花社区的论坛定制都写在 flarum/www/packages/ 目录中。目前这个目录中有一个 package,即 bbs-frontend,主要存放一些不涉及后端的用户界面定制。

如前所述,Flarum 的一大优势就是其可定制性。它有详细的开发者文档,这里只是简单介绍它的架构:

  • 后端:使用面向对象的 PHP 编写,基于 Laravel 后端框架,并且用 Composer 做依赖管理;
  • 后端使用 JSON:API 规范封装为一系列 API,可供前端或其他脚本调用;
  • 前端:基于 Mithril.js 前端框架(类似于 React)的一个单页面应用(SPA)。「单页面」的意思是指,用户从始至终只有一个 HTML 文件(即 index.html,对应于后端的 index.php 这一个页面模板),而所有页面跳转都是通过前端的路由来完成的。这种架构使得前后端更易分离,并且可以通过纯前端的定制轻易改变用户界面。

构建

待完善

部署

待完善

附录

健康检测

https://discuss.flarum.org/d/10056-migratetoflarum-lab-the-health-scanner-for-flarum

缓存的问题及解决

https://1024.day/d/1252