1. 为什么我选择用 Docker 来跑 Flarum 论坛如果你曾经手动部署过 PHP 论坛程序大概能理解那种“配环境配到怀疑人生”的感觉。Nginx、PHP-FPM、MySQL、各种扩展、目录权限、伪静态规则每一步都可能卡住你半天。而 Flarum 这个论坛程序本身对运行环境还有一定要求——PHP 7.3 以上、特定的扩展、Composer 依赖管理手动装一遍下来快则两小时慢则一整天都在排查各种报错。用 Docker 来搭建 Flarum核心思路就是把“环境配置”这件事从你的宿主机上彻底剥离出去。你不需要关心宿主机上装的是 PHP 几点几、有没有装某个扩展、MySQL 是什么版本因为这些全部由容器镜像来保证。你要做的只是写好一个编排文件把几个容器串起来然后一条命令启动。这篇文章适合哪些人看如果你是一个有一定 Linux 基础、想给自己或者小团队搭一个轻量级论坛的人但又不希望把大量时间花在环境配置和后期迁移上那 Docker Flarum 这套组合会非常合适。如果你完全没接触过 Docker也不用担心我会把每一步的命令和参数都解释清楚你照着操作就能跑起来。我自己的使用场景是这样的需要一个界面现代、加载速度快、支持 Markdown 发帖、有良好移动端适配的论坛系统用来做小范围的知识沉淀和讨论。Flarum 恰好满足这些需求它的前端是基于 Mithril 的单页应用交互体验比传统论坛流畅很多。而 Docker 则解决了部署和迁移的问题——我可以在测试机上跑通然后把整个编排文件复制到正式服务器上几分钟就能完成迁移。提示Flarum 的官方推荐部署方式其实也提到了容器化方案但官方文档写得比较简略很多细节需要自己踩坑。这篇文章会把那些坑提前给你标出来。2. 搭建之前的整体设计思路拆解2.1 容器编排方案的选择为什么用 Docker Compose 而不是单容器Flarum 的运行需要至少三个核心组件Web 服务器通常是 Nginx 或 Apache、PHP 运行环境、数据库MySQL 或 MariaDB。虽然理论上你可以把这三个东西塞进一个容器里但这样做有几个明显的问题。第一单容器意味着所有服务共享同一个文件系统和进程空间一旦某个服务出问题整个容器都会挂掉。第二单容器不利于水平扩展比如你以后想单独升级数据库版本就得重建整个容器。第三也是最重要的一点单容器方案把数据库数据也放在了容器内部容器一删数据就没了除非你手动做数据卷映射但那样又增加了复杂度。Docker Compose 的方案则是把每个服务拆成独立的容器通过一个 YAML 文件定义它们之间的关系。Web 容器负责处理 HTTP 请求PHP 容器负责执行 Flarum 的代码数据库容器负责存储数据。它们之间通过 Docker 的内部网络通信对外只暴露 Web 容器的端口。这样做的好处是每个服务可以独立升级、独立重启数据库数据通过数据卷持久化容器删了数据还在。我最终选择的镜像是Web 服务器用 Nginx 官方镜像PHP 用自己构建的基于 php:8.1-fpm 的镜像因为需要装 Flarum 要求的扩展数据库用 MariaDB 10.6。为什么不用 MySQL 而是 MariaDB因为 MariaDB 在同等配置下内存占用略低而且和 MySQL 的兼容性足够好Flarum 跑在上面没有任何问题。2.2 Flarum 版本选择与 PHP 版本的匹配关系Flarum 的版本迭代比较快不同版本对 PHP 的要求不一样。截至我写这篇文章的时候Flarum 1.8 是稳定版要求 PHP 8.1 以上。如果你用的是 Flarum 1.6 或更早的版本PHP 7.4 也能跑但我不建议这么做因为新版本在性能和安全性上都有改进。这里有一个容易踩的坑PHP 8.1 和 8.2 虽然都是 8.x但某些扩展的行为有细微差别。比如mysqli扩展在 8.2 里对某些参数的类型检查更严格如果你的 Flarum 版本比较老可能会报错。所以我的建议是PHP 版本不要盲目追新选 Flarum 官方文档里明确写支持的那个版本最稳妥。另外Flarum 需要以下几个 PHP 扩展curl、dom、fileinfo、gd、json、mbstring、openssl、pdo_mysql、tokenizer、zip。这些在 php:8.1-fpm 官方镜像里并不是全部默认安装的需要自己用docker-php-ext-install命令来装。具体怎么装我在下一章会给出完整的 Dockerfile。2.3 数据库的选型与数据持久化策略数据库这块我选择 MariaDB 而不是 MySQL除了前面说的内存占用原因之外还有一个考虑是 MariaDB 的官方镜像在 ARM 架构上支持得更好。如果你用的是 Apple Silicon 的 Mac 或者 ARM 服务器MariaDB 的镜像可以直接跑不需要额外配置。数据持久化方面我用的是 Docker 的命名卷named volume而不是绑定挂载bind mount。命名卷的好处是 Docker 会帮你管理存储位置你不需要关心数据具体存在宿主机的哪个目录下。而且命名卷在容器重建时不会丢失除非你手动删除卷。绑定挂载虽然更直观但在不同操作系统上的路径写法不一样容易出错。数据库的字符集我设置为utf8mb4排序规则用utf8mb4_unicode_ci。为什么不用utf8mb4_general_ci因为unicode_ci在排序和比较时更准确尤其是涉及到多语言内容的时候。Flarum 支持多语言用unicode_ci可以避免一些奇怪的排序问题。2.4 网络与端口规划Docker Compose 默认会为每个项目创建一个独立的桥接网络所有在这个项目里定义的容器都会加入这个网络。容器之间可以用服务名作为主机名互相访问比如 PHP 容器里可以直接用db这个主机名来连接数据库容器。对外暴露的端口我只暴露了 Web 容器的 8080 端口映射到宿主机的 8080。为什么不用 80因为 80 端口在大多数系统上需要 root 权限而且如果你宿主机上已经有其他 Web 服务在跑80 端口可能被占用。用 8080 更灵活后面如果要上 HTTPS可以在前面再加一层反向代理。PHP 容器的 9000 端口和数据库容器的 3306 端口都不需要暴露到宿主机它们只在 Docker 内部网络里通信。这样做更安全也避免了端口冲突。3. 核心文件与配置细节逐项解析3.1 目录结构规划在开始写配置文件之前先规划好目录结构。我习惯把项目放在~/docker/flarum下面目录结构是这样的flarum/ ├── docker-compose.yml ├── php/ │ └── Dockerfile ├── nginx/ │ └── flarum.conf └── app/ └── (Flarum 的代码会放在这里)app目录用来存放 Flarum 的源代码这样即使容器重建代码也不会丢。php目录放 PHP 的 Dockerfilenginx目录放 Nginx 的站点配置文件。3.2 PHP 镜像的 Dockerfile 编写这是整个搭建过程中最关键的一步。Flarum 需要的 PHP 扩展比较多而且有些扩展的安装方式不太一样。下面是我用的 DockerfileFROM php:8.1-fpm RUN apt-get update apt-get install -y \ libfreetype6-dev \ libjpeg62-turbo-dev \ libpng-dev \ libzip-dev \ libonig-dev \ unzip \ git \ docker-php-ext-configure gd --with-freetype --with-jpeg \ docker-php-ext-install -j$(nproc) \ gd \ zip \ pdo_mysql \ mbstring \ exif \ pcntl \ bcmath COPY --fromcomposer:2 /usr/bin/composer /usr/bin/composer WORKDIR /var/www/html这里有几个细节需要解释。第一docker-php-ext-configure gd这一步是必须的因为 GD 库需要指定 freetype 和 jpeg 的路径否则装出来的 GD 不支持这些格式。第二pcntl和bcmath这两个扩展 Flarum 本身不强制要求但一些第三方扩展会用到提前装上可以避免后面再重建镜像。第三Composer 是从官方镜像里复制过来的这样比自己下载安装更干净。注意docker-php-ext-install后面的-j$(nproc)表示用所有可用的 CPU 核心并行编译可以显著加快安装速度。如果你的服务器核心数很少可以去掉这个参数。3.3 Nginx 配置文件的要点Nginx 的配置文件需要处理 Flarum 的伪静态规则。Flarum 的前端是单页应用所有请求都需要转发到index.php但静态资源除外。下面是我用的配置server { listen 80; server_name _; root /var/www/html/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass php:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2)$ { expires 30d; add_header Cache-Control public, immutable; } location ~ /\. { deny all; } }这里fastcgi_pass php:9000里的php就是 Docker Compose 里 PHP 服务的名字。root指向的是public目录因为 Flarum 的入口文件在public/index.php而不是根目录下的index.php。这一点和很多 PHP 程序不一样配置错了会直接 404。静态资源的缓存策略我设置了 30 天并且加了immutable标记。Flarum 的静态资源文件名通常带哈希值所以可以放心地设置长期缓存。3.4 docker-compose.yml 的完整编排这是把所有东西串起来的核心文件version: 3.8 services: web: image: nginx:1.25-alpine ports: - 8080:80 volumes: - ./app:/var/www/html - ./nginx/flarum.conf:/etc/nginx/conf.d/default.conf depends_on: - php restart: unless-stopped php: build: ./php volumes: - ./app:/var/www/html depends_on: - db restart: unless-stopped db: image: mariadb:10.6 environment: MYSQL_ROOT_PASSWORD: your_root_password MYSQL_DATABASE: flarum MYSQL_USER: flarum MYSQL_PASSWORD: your_flarum_password volumes: - db_data:/var/lib/mysql command: --character-set-serverutf8mb4 --collation-serverutf8mb4_unicode_ci restart: unless-stopped volumes: db_data:几个关键点depends_on只保证启动顺序不保证服务已经就绪。也就是说PHP 容器启动时数据库可能还没准备好。这个问题在第一次安装 Flarum 时会遇到解决办法是等数据库完全启动后再执行安装命令。restart: unless-stopped保证容器在意外退出时自动重启但手动停止后不会自动拉起。数据库的密码不要用我上面写的示例值自己生成一个强密码。如果你打算把这个论坛放到公网上数据库密码强度不够是一个很大的安全隐患。4. 从零到跑通的完整实操流程4.1 环境准备与 Docker 安装确认首先确认你的机器上已经装了 Docker 和 Docker Compose。用下面两条命令检查docker --version docker compose version如果输出里能看到版本号说明已经装好了。如果没有先去 Docker 官网看安装文档。这里不展开讲 Docker 的安装因为不同操作系统的安装方式差别比较大。确认 Docker 服务正在运行systemctl status docker如果显示active (running)就没问题。如果没启动用systemctl start docker启动。4.2 创建目录与编写配置文件按照前面说的目录结构依次创建文件夹和文件mkdir -p ~/docker/flarum/{php,nginx,app} cd ~/docker/flarum然后把前面给出的 Dockerfile、Nginx 配置、docker-compose.yml 分别写入对应文件。写完之后可以用tree命令检查一下目录结构是否正确。4.3 启动容器并验证服务状态在docker-compose.yml所在的目录下执行docker compose up -d-d表示后台运行。第一次执行会拉取镜像并构建 PHP 镜像可能需要几分钟。执行完成后用下面的命令查看容器状态docker compose ps你应该能看到三个容器都在运行。如果某个容器状态是Exit或者Restarting用docker compose logs 服务名查看日志排查。数据库容器第一次启动会比较慢因为它需要初始化数据目录。你可以用下面的命令确认数据库已经就绪docker compose exec db mysqladmin ping -u root -p输入密码后如果返回mysqld is alive说明数据库已经可以接受连接了。4.4 安装 Flarum 的详细步骤Flarum 的安装是通过 Composer 完成的。首先进入 PHP 容器docker compose exec php bash然后在容器内执行安装命令composer create-project flarum/flarum . --stabilitystable这个命令会把 Flarum 的最新稳定版下载到/var/www/html目录也就是宿主机的app目录。下载完成后需要设置目录权限chown -R www-data:www-data /var/www/html chmod -R 755 /var/www/html chmod -R 775 /var/www/html/storage /var/www/html/public/assetsFlarum 需要对storage和public/assets目录有写权限所以这两个目录的权限要单独设置。接下来在浏览器里访问http://你的服务器IP:8080应该能看到 Flarum 的安装向导。安装向导会要求你填写数据库信息按照下面的填配置项填写内容数据库驱动MySQL数据库主机db数据库端口3306数据库名flarum数据库用户名flarum数据库密码你设置的密码表前缀留空或自定义管理员账号的信息自己填好记住密码。安装完成后Flarum 会自动生成config.php文件。4.5 安装后的基础配置调整安装完成后有几件事需要做。第一删除安装向导的入口文件防止被人重新安装rm /var/www/html/public/install.php第二设置 Flarum 的 URL。如果你后面要用域名访问需要在config.php里把url改成你的域名。第三开启缓存和优化php flarum cache:clear php flarum assets:publish这两个命令在 PHP 容器里执行。cache:clear清除缓存assets:publish重新发布前端资源。提示每次修改了 Flarum 的配置或者安装了扩展之后都建议执行一次php flarum cache:clear否则改动可能不生效。5. 常见问题与排查技巧实录5.1 数据库连接失败的各种可能这是最常见的问题表现是安装向导页面报“无法连接数据库”或者“Access denied”。排查思路按顺序来先确认数据库容器是否在运行docker compose ps。如果数据库容器没起来看日志docker compose logs db常见原因是数据目录权限问题或者端口被占用。如果数据库容器正常运行但 PHP 容器连不上检查docker-compose.yml里数据库的主机名是不是db。在 Docker Compose 的网络里服务名就是主机名不能用localhost或127.0.0.1。如果提示密码错误确认MYSQL_PASSWORD和安装向导里填的密码一致。注意MYSQL_PASSWORD只在数据库第一次初始化时生效如果你改了docker-compose.yml里的密码但数据库已经初始化过了新密码不会生效。解决办法是删除数据卷重新初始化或者进入数据库手动改密码。5.2 权限问题导致的 500 错误Flarum 对目录权限比较敏感。如果访问页面出现 500 错误先看 PHP 容器的日志docker compose logs php如果日志里出现Permission denied或者failed to open stream说明是权限问题。Flarum 需要storage和public/assets目录可写。在 PHP 容器里执行chown -R www-data:www-data /var/www/html chmod -R 775 /var/www/html/storage chmod -R 775 /var/www/html/public/assets注意www-data是 php-fpm 镜像里默认的运行用户。如果你自己构建镜像时改了用户这里要对应修改。5.3 静态资源 404 与 Nginx 配置检查如果页面能打开但样式全乱了按 F12 看控制台大概率是 CSS 和 JS 文件 404。这种情况通常是 Nginx 的root配置错了。确认root指向的是/var/www/html/public而不是/var/www/html。另外检查try_files规则是否正确Flarum 需要把所有不存在的路径都转发到index.php。还有一个可能的原因是public/assets目录下没有文件。Flarum 安装后需要执行php flarum assets:publish来生成前端资源。如果这个命令没执行或者执行失败静态资源就是空的。5.4 容器重启后数据丢失的预防如果你发现每次docker compose down之后再up论坛数据就没了那说明数据库没有做持久化。检查docker-compose.yml里数据库服务是否配置了volumes并且卷名是否在顶层的volumes里声明了。另外docker compose down默认不会删除命名卷但如果你加了-v参数卷就会被删除。所以执行down的时候要小心不要随手加-v。5.5 常见问题速查表问题现象可能原因解决方法安装向导无法连接数据库主机名填错数据库主机填db页面 500 错误目录权限不对设置 storage 和 assets 目录可写静态资源 404Nginx root 配置错误root 指向 public 目录容器重启后数据丢失未配置数据卷检查 volumes 配置修改配置不生效缓存未清除执行php flarum cache:clearPHP 扩展缺失镜像未安装对应扩展修改 Dockerfile 重新构建6. 后期维护与扩展的几个实用建议6.1 备份策略数据库与代码分开处理数据库的备份可以用mysqldump命令在数据库容器里执行docker compose exec db mysqldump -u flarum -p flarum backup.sql这个命令会把数据库导出到宿主机的当前目录。建议设置一个定时任务每天凌晨自动备份一次并且保留最近 7 天的备份文件。代码的备份更简单直接打包app目录就行。但要注意app目录里可能包含vendor目录这个目录很大而且可以通过 Composer 重新生成备份的时候可以排除掉。6.2 升级 Flarum 版本的正确姿势升级 Flarum 不能直接覆盖文件需要按照官方文档的步骤来。大致流程是先备份数据库和代码然后在 PHP 容器里执行composer update最后执行数据库迁移命令php flarum migrate。升级之前一定要在测试环境先跑一遍确认没有兼容性问题再在正式环境操作。Flarum 的某些扩展可能不兼容新版本升级后会导致论坛无法访问。6.3 安装扩展的注意事项Flarum 的扩展生态比较丰富但安装扩展时要注意几点。第一扩展对 Flarum 版本有要求装之前先看扩展的说明。第二安装扩展用 Composer命令是composer require 扩展包名。第三安装完成后要执行php flarum migrate和php flarum cache:clear。如果安装扩展后论坛白屏大概率是扩展不兼容。解决办法是进入 PHP 容器用composer remove 扩展包名卸载扩展然后清除缓存。6.4 性能优化的几个入手点Flarum 的性能瓶颈通常在数据库查询和 PHP 执行上。开启 OPcache 可以显著提升 PHP 执行速度在 PHP 容器里安装 OPcache 扩展即可。数据库方面可以调整innodb_buffer_pool_size参数根据服务器内存大小设置合适的值。另外Nginx 开启 gzip 压缩和 HTTP/2 也能提升页面加载速度。如果论坛访问量比较大可以考虑在前面加一层缓存比如用 Nginx 的 fastcgi_cache 或者独立的缓存服务。我在实际使用中发现Flarum 在默认配置下性能已经不错对于小规模论坛日活几百人完全够用。真正需要优化的时候再动手不要一开始就过度设计。