توسط Matt Connor 2026-08-21

آموزش نصب Flarum روی VPS با PHP و MariaDB

Q: چرا با وجود کارکرد صفحه اصلی، لینکهای گفتگو خطای 404 میدهند؟

بلاک سرور nginx شما فاقد include /srv/flarum/.nginx.conf; است. Flarum آدرسهایی مانند /d/1-hello-world را درون PHP مدیریت میکند و این مسیر یک فایل واقعی روی دیسک نیست. بدون قانون try_files $uri $uri/ /index.php?$query_string در آن قطعهکد، nginx به دنبال پوشهای به نام d میگردد، موفق نمیشود و بدون فراخوانی PHP، خطای 404 برمیگرداند. در Apache، همین مسیریابی از طریق public/.htaccess انجام میشود که اگر در بلاک مقدار AllowOverride All تنظیم نشده باشد، نادیده گرفته میشود.

Q: چرا پس از فعالسازی HTTPS، تمام استایلهای انجمن از بین رفته است؟

Flarum آدرس پایه (base URL) را در config.php ذخیره میکند که از آدرسی که هنگام نصب استفاده کردهاید گرفته شده است. اگر روی HTTP معمولی نصب کرده باشید، Flarum همچنان آدرسهای asset را با http:// تولید میکند و مرورگر آنها را به عنوان mixed content در یک صفحه HTTPS مسدود میکند که نتیجه آن نمایش متن بدون استایل است. کلید url را در /srv/flarum/config.php به آدرس https:// تغییر دهید و php flarum cache:clear را با کاربری که مالک فایلهاست اجرا کنید.

Q: چرا هیچکس ایمیل تأیید ثبتنام را دریافت نمیکند؟

ابتدا درایور ایمیل را بررسی کنید. درایور mail به یک باینری محلی sendmail نیاز دارد که در VPSهای تازه نصبشده Ubuntu وجود ندارد، و درایور log نیز فقط در storage/logs/ مینویسد و چیزی ارسال نمیکند. به smtp تغییر وضعیت دهید، از پورت 587 با رمزنگاری tls استفاده کنید (چون اکثر سرویسدهندگان پورت 25 خروجی را مسدود میکنند) و دکمه Send Test Mail را بزنید. اگر لاگ ارسال موفقیتآمیز را نشان میدهد اما ایمیل هرگز نمیرسد، مشکل از تحویلدهی (deliverability) است نه پیکربندی؛ بنابراین رکوردهای SPF و DKIM را برای دامنه فرستنده منتشر کنید.

راهنمای گام‌به‌گام نصب Flarum روی سرور مجازی با PHP و Composer. یاد بگیرید چگونه دایرکتوری public را با TLS سرو کنید و خطاهای رایج ایمیل و آپدیت افزونه‌ها را رفع کنید.

نصب Flarum روی یک VPS با استفاده از PHP و MariaDB

با نصب Flarum روی یک VPS، شما صاحب یک انجمن می‌شوید که بر پایه PHP و MariaDB اجرا می‌شود؛ بدون نیاز به Docker، Ruby یا هرگونه job runner مجزا. همین موضوع دلیل اصلی انتخاب آن است. نصب Discourse روی یک VPS به معنای استفاده از یک stack داکر شامل Ruby، PostgreSQL، Redis و یک background worker است و 2 گیگابایت رم، حداقل مقدار عملیاتی پیش از افزودن سرویس‌های پشتیبان‌گیری یا ایمیل محسوب می‌شود. Discourse این حجم از منابع را برای انجمن‌های شلوغ با هزاران پست در روز توجیه می‌کند. برای انجمنی با چند صد کاربر، این زیرساخت هزینه‌ای ماهانه است که هرگز از تمام ظرفیت آن استفاده نخواهید کرد. Flarum در دل یک stack مبتنی بر PHP که احتمالاً هم‌اکنون در حال اجرای آن هستید جای می‌گیرد، بنابراین یک VPS با 1 گیگابایت رم به همراه nginx و MariaDB می‌تواند آن را در کنار سایر سرویس‌های شما میزبانی کند. اگر هنوز در حال تصمیم‌گیری هستید، مقایسه جامع‌تر نرم‌افزارهای انجمن‌ساز self-hosted سایر گزینه‌های موجود را بررسی کرده است.

این راهنما نصب را بر اساس Flarum 1.x، که در حال حاضر سری 1.8 است، تنظیم می‌کند. تا آگوست 2026، نسخه Flarum 2.0 همچنان در مرحله release candidate قرار دارد، بنابراین 1.8 نسخه‌ای است که باید برای انجمنی که کاربران به آن وابسته‌اند، اجرا کنید. در اینجا اهمیت افزونه‌ها (extensions) بیش از نسخه هسته است و اکثر توسعه‌دهندگان افزونه هنوز به نسخه 2.0 مهاجرت نکرده‌اند.

پیش‌نیازهای Flarum 1.8 روی سرور

نیازمندی‌های مستندشده برای Flarum شامل PHP 7.3 یا جدیدتر، MySQL 5.6 به بالا یا MariaDB 10.0.5 به بالا، و یکی از وب‌سرورهای nginx یا Apache با mod_rewrite است. توزیع Ubuntu 24.04 به‌صورت پیش‌فرض PHP 8.3 و MariaDB 10.11 را ارائه می‌دهد، بنابراین بسته‌های موجود در مخازن رسمی توزیع، تمامی این نیازمندی‌ها را بدون نیاز به مخازن شخص ثالث برآورده می‌کنند. افزونه‌های PHP مورد نیاز Flarum عبارتند از curl، dom، fileinfo، gd، json، mbstring، openssl، pdo_mysql، tokenizer و zip. شما همچنین به دسترسی shell نیاز دارید، زیرا استفاده از Composer در اینجا اختیاری نیست: هر افزونه Flarum یک بسته Composer محسوب می‌شود و هیچ راهی برای افزودن افزونه بدون اجرای Composer وجود ندارد.

Flarum یک برنامه PHP معمولی است. اگر در حال حاضر یک LAMP stack روی Ubuntu 24.04 اجرا می‌کنید، بیشتر موارد دو بخش بعدی از قبل نصب شده‌اند و می‌توانید سریعاً از آن‌ها عبور کرده و به بخش پایگاه داده بروید.

نصب PHP و افزونه‌های مورد نیاز Flarum

sudo apt update
sudo apt install -y nginx mariadb-server composer
sudo apt install -y php8.3-fpm php8.3-cli php8.3-curl php8.3-gd php8.3-mbstring php8.3-mysql php8.3-xml php8.3-zip
php -m | grep -E 'curl|dom|gd|mbstring|pdo_mysql|zip'
composer --version

نام بسته‌ها دقیقاً با لیست Flarum مطابقت ندارد. افزونه dom درون php8.3-xml قرار دارد و fileinfo، json، openssl و tokenizer در نسخه PHP 8.3 روی Ubuntu کامپایل شده‌اند، بنابراین نیازی به نصب بسته جداگانه برای آن‌ها نیست. دستور grep باید شش خط خروجی داشته باشد و composer --version باید نسخه 2.x را گزارش کند. بهتر است نبود هر افزونه‌ای را همین حالا برطرف کنید، زیرا Composer بدون آن‌ها از نصب Flarum خودداری می‌کند و در پیام خطا، نام افزونه مورد نیاز را ذکر می‌کند:

  Problem 1
    - flarum/core[v1.8.0, ..., v1.8.17] require ext-gd * -> it is missing from your system.
      Install or enable PHP's gd extension.

بررسی کنید که نسخه PHP خط فرمان و مدیر پردازش FastCGI (یعنی PHP-FPM) یکسان باشند. Composer با استفاده از باینری خط فرمان اجرا می‌شود، در حالی که انجمن شما تحت FPM کار می‌کند؛ بنابراین php -v و sudo php-fpm8.3 -v باید با هم مطابقت داشته باشند. این نسخه‌ها در سروری که چندین نسخه PHP از مخازن شخص ثالث در آن جمع شده است، ممکن است از هم فاصله بگیرند؛ در این صورت، افزونه‌ای که برای یک نسخه نصب کرده‌اید برای نسخه دیگر قابل مشاهده نخواهد بود.

ایجاد پایگاه داده و یک کاربر اختصاصی برای آن

sudo mariadb-secure-installation
sudo mariadb

CREATE DATABASE flarum CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'flarum'@'localhost' IDENTIFIED BY 'use-a-long-random-password';
GRANT ALL PRIVILEGES ON flarum.* TO 'flarum'@'localhost';
FLUSH PRIVILEGES;
EXIT;

به‌جای استفاده از root، یک کاربر اختصاصی برای Flarum ایجاد کنید. دسترسی‌های اعطا شده فقط محدود به flarum.* است؛ بنابراین اگر یک افزونه که توسط شما نوشته نشده دارای آسیب‌پذیری SQL injection باشد، مهاجم نمی‌تواند سایر پایگاه‌های داده شما را بخواند. انتخاب مجموعه کاراکتر (character set) نیز اهمیت دارد: utf8mb4 ایموجی‌ها و خطوط غیرلاتین را به‌درستی ذخیره می‌کند، در حالی که utf8 در MySQL یک انکودینگ سه بایتی است که باعث می‌شود متن پست‌ها در اولین کاراکتر چهار بایتی قطع شود. پیش از ادامه، از صحت عملکرد کاربر اطمینان حاصل کنید.

mariadb -u flarum -p flarum -e 'SELECT DATABASE();'

این دستور باید flarum را چاپ کند. خطای ERROR 1045 (28000): Access denied for user 'flarum'@'localhost' به این معناست که رمز عبور مطابقت ندارد یا کاربر برای هاستی متفاوت از localhost ایجاد شده است.

نصب Flarum روی یک VPS با استفاده از Composer و محدود کردن نسخه به 1.8

ابتدا یک کاربر سیستمی ایجاد کنید که مالکیت کدها را بر عهده داشته باشد. اجرای Composer با root باعث می‌شود فایل‌ها با مالکیت root در vendor/ و storage/ ایجاد شوند؛ در نتیجه PHP نمی‌تواند بعداً در کش خود بنویسد و انجمن به تمام درخواست‌ها خطای 500 پاسخ می‌دهد.

sudo useradd --system --home-dir /srv/flarum --shell /bin/bash flarum
sudo install -d -o flarum -g flarum -m 755 /srv/flarum
sudo -iu flarum

دستور آخر شما را به یک shell با دسترسی کاربر flarum در مسیر /srv/flarum منتقل می‌کند. تمام دستورات از اینجا تا پایان راهنما باید با همین کاربر اجرا شوند، مگر آنکه با sudo شروع شده باشند.

composer create-project flarum/flarum:^1.8.0 .

محدودیت ^1.8.0 برای ثابت نگه‌داشتن نسخه است. این دستور نسخه‌های اصلاحی 1.8.x را می‌پذیرد و از نصب نسخه 2.0 جلوگیری می‌کند؛ این همان چیزی است که تا زمان انتشار نسخه نهایی 2.0 به آن نیاز دارید. Composer اسکلت‌بندی پروژه را دانلود کرده، flarum/core و وابستگی‌های آن را حل می‌کند و در نهایت public/، storage/، vendor/، composer.json و یک اسکریپت خط فرمان flarum را در اختیار شما قرار می‌دهد.

در یک VPS کوچک، این مرحله جایی است که فرآیند ممکن است با شکست مواجه شود و دو نوع خطای متفاوت، ظاهری مشابه دارند. PHP Fatal error: Allowed memory size of 134217728 bytes exhausted مربوط به تنظیمات memory_limit خودِ PHP است و قرار دادن COMPOSER_MEMORY_LIMIT=-1 پیش از دستور، این محدودیت را برای یک بار اجرا حذف می‌کند. اگر دستور Killed به تنهایی و بدون هیچ خطای PHP متوقف شد، به معنای مداخله kernel و بستن فرآیند به دلیل کمبود حافظه (OOM Killer) است که می‌توانید آن را با dmesg | tail تأیید کنید. در این حالت، دستگاه واقعاً با کمبود RAM مواجه است؛ بنابراین باید swap اضافه کنید. افزایش محدودیت حافظه PHP در این شرایط وضعیت را بدتر می‌کند، زیرا PHP پیش از آنکه kernel مداخله کند، درخواست حافظه بیشتری خواهد کرد.

چرا فقط دایرکتوری /public باید در دسترس وب باشد

ریشه پروژه شامل config.php است که رمز عبور دیتابیس شما را به صورت متن ساده در خود دارد، همچنین vendor/ که تمام وابستگی‌ها را در بر می‌گیرد و storage/ که شامل لاگ‌ها و نشست‌های کش‌شده است. هیچ‌کدام از این موارد نباید در اینترنت عمومی در دسترس باشند. Flarum همه چیزهایی که باید در وب قابل دسترسی باشند را در یک زیردایرکتوری به نام public/ نگه می‌دارد که حاوی index.php، یک پوشه assets/ و موارد اندک دیگری است. ریشه وب‌سرور را روی /srv/flarum/public تنظیم کنید؛ با این کار، بقیه ساختار درختی فایل‌ها از طریق HTTP غیرقابل دسترس می‌شود. این یک ویژگی ساختاری است و نیازی نیست قانونی را به خاطر بسپارید.

اگر ریشه را به جای آن روی /srv/flarum تنظیم کنید، آسیب واقعی خواهد بود. درخواست /config.php نتیجه مفیدی برنمی‌گرداند، زیرا PHP فایل را اجرا کرده و فقط یک آرایه بازمی‌گرداند. اما /storage/logs/flarum.log ردپای پشته (stack traces) و خطاهای دیتابیس شما را به یک غریبه تقدیم می‌کند و /composer.lock نسخه دقیق تمام بسته‌هایی که اجرا می‌کنید را به آن‌ها می‌گوید؛ این لیست، فهرستی از آسیب‌پذیری‌های شناخته‌شده برای امتحان کردن است.

اختصاص یک pool مجزا به PHP-FPM

نرم‌افزار Flarum به دسترسی نوشتن در سه مسیر نیاز دارد: ریشه پروژه، تا نصب‌کننده بتواند config.php را ایجاد کند؛ storage/، برای لاگ‌ها و کش؛ و assets/، برای آواتارها و لوگوهای بارگذاری‌شده. مالکیت این فایل‌ها متعلق به کاربر flarum است، بنابراین راه‌حل اصولی، ایجاد یک pool اختصاصی در PHP-FPM است که با کاربر flarum اجرا شود. سرویس nginx همچنان با کاربر www-data اجرا شده و فقط عملیات خواندن را انجام می‌دهد.

فایل /etc/php/8.3/fpm/pool.d/flarum.conf را ایجاد کنید:

[flarum]
user = flarum
group = flarum
listen = /run/php/php8.3-fpm-flarum.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660
pm = ondemand
pm.max_children = 10
pm.process_idle_timeout = 30s
php_admin_value[memory_limit] = 256M
php_admin_value[upload_max_filesize] = 16M
php_admin_value[post_max_size] = 17M

sudo systemctl restart php8.3-fpm
ls -l /run/php/php8.3-fpm-flarum.sock

سوکت باید به صورت srw-rw---- 1 www-data www-data تعریف شود. پردازش اصلی (master process) با دسترسی root اجرا شده و سوکت را ایجاد می‌کند؛ به همین دلیل می‌تواند مالکیت آن را به www-data واگذار کند، در حالی که پردازش‌های worker با کاربر flarum اجرا می‌شوند. اگر سوکت وجود نداشته باشد، sudo journalctl -u php8.3-fpm -n 30 خطای FPM rejected را نمایش می‌دهد. pm = ondemand پردازش‌های worker را تنها زمانی آغاز می‌کند که درخواستی دریافت شود، بنابراین یک انجمن کم‌ترافیک در فواصل بین بازدیدها تقریباً هیچ حافظه‌ای مصرف نمی‌کند.

بلاک سرور nginx

پروژه Flarum یک قطعه کد (snippet) برای nginx در ریشه پروژه با نام .nginx.conf ارائه می‌دهد. این فایل شامل قوانین بازنویسی (rewrite)، هدرهای کش و تنظیمات فشرده‌سازی است. به‌جای کپی کردن محتوا، آن را در پیکربندی خود Include کنید تا در صورت به‌روزرسانی Flarum و تغییر این قطعه کد، تغییرات بدون نیاز به ویرایش دستی توسط شما، روی سرور اعمال شود.

server {
    listen 80;
    listen [::]:80;
    server_name forum.example.com;

    root /srv/flarum/public;
    index index.php;
    client_max_body_size 16M;

    include /srv/flarum/.nginx.conf;

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm-flarum.sock;
    }
}

آن را با نام /etc/nginx/sites-available/flarum ذخیره کرده و سپس فعال کنید.

sudo ln -s /etc/nginx/sites-available/flarum /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

nginx -t باید به syntax is ok و test is successful پاسخ دهد. خط include همان موردی است که کاربران اغلب فراموش می‌کنند؛ حذف آن یک نشانه بسیار مشخص دارد: صفحه اصلی به‌درستی بارگذاری می‌شود، اما تمام لینک‌های گفتگو خطای 404 از سمت nginx برمی‌گردانند. Flarum آدرس‌هایی مانند /d/1-hello-world را درون PHP مسیریابی می‌کند. این مسیر یک فایل فیزیکی روی دیسک نیست؛ بنابراین بدون قانون try_files $uri $uri/ /index.php?$query_string در این قطعه کد، nginx به دنبال دایرکتوری با نام d می‌گردد، آن را نمی‌یابد و پیش از آنکه درخواستی به PHP ارسال شود، خطای 404 می‌دهد. در Apache، همین مسیریابی از طریق فایل .htaccess که از قبل در public/ قرار دارد انجام می‌شود، که تنها در صورتی عمل می‌کند که بلاک <Directory> مربوطه، گزینه AllowOverride All را تنظیم کرده باشد.

پیش از اجرای نصب‌کننده، TLS را اضافه کنید

گواهی را همین حالا دریافت کنید، نه بعد از نصب. Flarum در حین نصب، آدرس پایه (base URL) را در config.php می‌نویسد و این آدرس را از URL موجود در مرورگر شما برمی‌دارد. اگر نصب را از طریق http:// انجام دهید، تمام URLهای دارایی‌ها (assets) که Flarum پس از آن تولید می‌کند با http:// شروع می‌شوند. بنابراین، به محض اینکه TLS (امنیت لایه انتقال) را اضافه کنید، مرورگر این درخواست‌ها را به دلیل محتوای ترکیبی (mixed content) مسدود می‌کند و انجمن به‌صورت متن بدون استایل و بدون JavaScript بارگذاری می‌شود. ابتدا مراحل راه‌اندازی certbot برای Let's Encrypt روی nginx را انجام دهید، مطمئن شوید که https://forum.example.com یک صفحه را نمایش می‌دهد، سپس به اینجا بازگردید.

اگر قبلاً نصب را از طریق HTTP ساده انجام داده‌اید، تعمیر آن تنها با یک خط دستور امکان‌پذیر است. فایل /srv/flarum/config.php را ویرایش کنید تا مقدار کلید url به 'url' => 'https://forum.example.com', تغییر یابد، سپس دستور php flarum cache:clear را با کاربر flarum اجرا کنید.

اجرای نصب‌کننده و محدودسازی دسترسی به config.php

آدرس https://forum.example.com را در مرورگر باز کنید. نصب‌کننده وب Flarum از شما نام پایگاه داده، نام کاربری و رمز عبور پایگاه داده‌ای که ایجاد کردید، عنوان انجمن و اطلاعات حساب کاربری مدیر را می‌خواهد. این نصب‌کننده فایل config.php را می‌نویسد و جداول را ایجاد می‌کند. پس از پایان عملیات، دسترسی فایلی که اکنون حاوی رمز عبور پایگاه داده شماست را محدود کنید.

sudo chmod 640 /srv/flarum/config.php

این فایل همچنان برای flarum، که کاربری است که FPM با آن اجرا می‌شود، قابل خواندن و نوشتن باقی می‌ماند و برای سایر حساب‌های کاربری روی سیستم غیرقابل خواندن خواهد بود. سپس نصب را از طریق shell بررسی کنید.

php flarum info

این دستور نسخه هسته، نسخه PHP، افزونه‌های فعال، درایور ایمیل و مسیرهای مورد استفاده را چاپ می‌کند. این اولین دستوری است که هنگام بروز مشکل باید اجرا کنید و اولین چیزی است که هر کسی که بخواهد به شما کمک کند، از شما درخواست خواهد کرد.

چرا ایمیل‌های ثبت‌نام و بازیابی رمز عبور بدون هیچ خطایی ارسال نمی‌شوند

این بخش تعیین می‌کند که آیا انجمن شما هفته اول فعالیت خود را پشت سر می‌گذارد یا خیر. دو ایمیل اولی که هر انجمن جدید ارسال می‌کند، تأییدیه ثبت‌نام و بازیابی رمز عبور است؛ هر دوی این ایمیل‌ها دقیقاً زمانی ارسال می‌شوند که یک کاربر غریبه در حال تصمیم‌گیری درباره واقعی بودن جامعه کاربری شماست. هر دو مورد ممکن است بدون هیچ هشداری با شکست مواجه شوند. کسی که ایمیل را دریافت نکرده است نمی‌تواند به شما اطلاع دهد و هیچ بخشی در پنل مدیریت شما نیز قرمز نمی‌شود.

نرم‌افزار Flarum چهار درایور ایمیل دارد که در بخش Administration و سپس Email تنظیم می‌شوند: smtp، mail، mailgun و log. گزینه smtp را انتخاب کرده و آن را به یک سرویس ایمیل معتبر که واقعاً پیام‌ها را تحویل می‌دهد، متصل کنید. درایور mail پیام را به یک باینری محلی sendmail می‌سپارد که در یک VPS تازه نصب‌شده با Ubuntu وجود ندارد؛ بنابراین پیام به هیچ مقصدی نمی‌رسد و هیچ خطایی نیز گزارش نمی‌شود. درایور log بدنه پیام را در storage/logs/ می‌نویسد و عملاً هیچ چیزی ارسال نمی‌کند، زیرا این درایور صرفاً برای محیط توسعه طراحی شده است.

تنظیمات را ذخیره کنید و سپس دکمه Send Test Mail را در همان صفحه فشار دهید. این دکمه تنها حلقه بازخورد شماست، بنابراین پیش از دعوت از هر کسی، از آن استفاده کنید. اگر پیام به دستتان نرسید، لاگ را بخوانید.

tail -n 50 /srv/flarum/storage/logs/flarum.log

اتصال ردشده، ورود ناموفق و شکست در مذاکره TLS، همگی در لاگ به همراه هاست و پورتی که برای اتصال تلاش شده است، ثبت می‌شوند. خطی که حاوی Connection could not be established with host smtp.example.com باشد به این معنی است که پورت مسدود شده یا اشتباه است؛ دلیل معمول این اتفاق آن است که ارائه‌دهنده سرویس، پورت خروجی 25 را به‌صورت پیش‌فرض مسدود کرده است. استفاده از پورت 587 با تنظیم فیلد رمزنگاری روی tls، ترکیبی است که با تقریباً تمام سرویس‌های ایمیل کار می‌کند.

هنگامی که سیستم ایمیل خراب باشد، کاربری که ثبت‌نام می‌کند با بنر خطای عمومی Flarum یعنی Oops! Something went wrong. Please reload the page and try again. مواجه می‌شود، زیرا درخواست در حین ارسال تأییدیه با خطا مواجه شده است. در هر صورت، آن شخص نمی‌تواند وارد شود و درباره این مشکل به شما پیامی نخواهد داد.

پذیرفته شدن ایمیل توسط مقصد، مسئله‌ای جدا از ارسال آن است. ایمیل‌های ارسالی از یک آدرس VPS که رکوردهای SPF یا DKIM برای دامنه آن‌ها منتشر نشده باشد، یا به پوشه اسپم می‌روند و یا بدون هیچ پیام بازگشتی (bounce) حذف می‌شوند؛ بنابراین لاگ شما ارسال موفقیت‌آمیز را نشان می‌دهد اما کاربر همچنان چیزی دریافت نمی‌کند. مقاله ارسال مطمئن ایمیل از برنامه‌های self-hosted توضیح می‌دهد که چه رکوردهای DNS باید منتشر شوند و استفاده از کدام سرویس‌های relay توصیه می‌شود.

افزونه‌ها بسته‌های Composer هستند، بنابراین ارتقای آن‌ها با دستور انجام می‌شود

در Flarum، هر افزونه یک بسته Composer است. دکمه‌ای برای آپلود وجود ندارد و هیچ فایل zip برای قرار دادن در پوشه در کار نیست. این یک تصمیم طراحی آگاهانه است: نسخه‌ها با یکدیگر تطبیق داده می‌شوند، مجموعه دقیق آن‌ها در composer.lock ثبت می‌شود و افزونه‌ای که به یک کتابخانه PHP وابسته است، آن کتابخانه را به‌درستی نصب می‌کند. هزینه این کار این است که افزودن یک افزونه به معنای اجرای سه دستور با کاربر flarum است.

composer require 'fof/upload:*'
php flarum migrate
php flarum cache:clear

سپس آن را در بخش Administration و سپس Extensions فعال کنید. هر دستور وظیفه مشخصی دارد. composer require کد را روی دیسک قرار می‌دهد. php flarum migrate هرگونه migration دیتابیس که افزونه به همراه دارد را اجرا می‌کند؛ این همان روشی است که افزونه جداول خود را ایجاد می‌کند. php flarum cache:clear بسته‌های کامپایل‌شده JavaScript و CSS که مرورگر بارگذاری می‌کند را بازسازی می‌نماید. نادیده گرفتن دستور آخر منجر به سردرگمی رایج می‌شود: افزونه در لیست دیده می‌شود، دکمه فعال است، اما هر چقدر هم صفحه را رفرش کنید، هیچ تغییری در مرورگر رخ نمی‌دهد.

حذف یک افزونه مسیر معکوس را طی می‌کند. ابتدا آن را در پنل مدیریت غیرفعال کنید، سپس بسته را حذف نمایید. Flarum جداول افزونه را عمداً باقی می‌گذارد تا فعال‌سازی مجدد آن در آینده باعث از دست رفتن داده‌ها نشود. برای حذف کامل جداول، پیش از حذف کد، migrationهای آن را به عقب برگردانید (rollback کنید).

php flarum migrate:reset --extension fof-upload
composer remove fof/upload
php flarum cache:clear

شناسه افزونه در آن دستور، همان نام بسته است که اسلش آن با خط تیره جایگزین شده است. اگر ترجیح می‌دهید به جای تایپ کردن از کلیک استفاده کنید، composer require 'flarum/extension-manager:*' یک صفحه مدیریت رسمی اضافه می‌کند که رابطی برای Composer است. این صفحه همان عملیات کاربر وب را اجرا می‌کند، به همان میزان حافظه و همان دسترسی‌های نوشتن نیاز دارد و به همان دلایل ممکن است با خطا مواجه شود؛ بنابراین، خط فرمان همچنان مطمئن‌ترین مسیر در هنگام بروز مشکلات است.

چرا composer update از ارتقای Flarum خودداری می‌کند

ارتقای Flarum و تمامی افزونه‌ها شامل یک دستور Composer و به دنبال آن دو دستور Flarum است. ابتدا از پایگاه داده نسخه پشتیبان تهیه کنید.

composer update --prefer-dist --no-plugins --no-dev -a --with-all-dependencies
php flarum migrate
php flarum cache:clear

به جای فرض موفقیت‌آمیز بودن عملیات، خروجی را مطالعه کنید؛ چرا که حالت جالب زمانی است که Composer از انجام هرگونه تغییری سر باز می‌زند:

Your requirements could not be resolved to an installable set of packages.

این پیام بدین معناست که یکی از افزونه‌های نصب‌شده، یک محدودیت flarum/core اعلام کرده است که نسخه مورد نظر شما را مستثنی می‌کند. Composer این محدودیت را نقض نمی‌کند، بنابراین به جای ایجاد ترکیبی که نویسنده افزونه اعلام کرده کار نخواهد کرد، کل نصب را در نسخه قدیمی نگه می‌دارد. بسته مسئول این وضعیت را پیدا کنید.

composer why-not flarum/core 1.8.17

خروجی، تمام بسته‌هایی که مانع آن نسخه می‌شوند و محدودیتی که هر کدام اعلام کرده‌اند را فهرست می‌کند. از آنجا، گزینه‌ها شامل انتظار برای انتشار نسخه سازگار توسط نویسنده، یا حذف افزونه و ادامه کار بدون آن است. این بهای مدل Composer است و پیش از نصب پانزده افزونه روی انجمنی که دیگران به آن متکی هستند، ارزش درک کردن دارد. افزونه‌هایی را ترجیح دهید که اخیراً نسخه‌ای منتشر کرده‌اند و فهرست افزونه‌ها را به اندازه‌ای کوتاه نگه دارید که بتوانید آن را مطالعه کنید.

چه مواردی را پشتیبان‌گیری کنیم

از پایگاه داده و دایرکتوری پروژه پشتیبان تهیه کنید. سایر موارد قابل بازسازی هستند.

mariadb-dump -u flarum -p --single-transaction flarum > flarum-$(date +%F).sql
sudo tar czf flarum-files.tgz -C /srv flarum

در سیستم‌های قدیمی‌تر، mariadb-dump با نام mysqldump شناخته می‌شود؛ در Ubuntu 24.04 هر دو نام کار می‌کنند. پایگاه داده شامل تمامی پست‌ها، کاربران و تنظیمات است. دایرکتوری پروژه شامل config.php، composer.json (که رکورد اصلی افزونه‌های فعال شماست) و assets/ برای آواتارها و لوگوهای بارگذاری‌شده است. می‌توانید از vendor/ صرف‌نظر کنید، زیرا composer install آن را از روی composer.lock بازسازی می‌کند و storage/ نیز خودبه‌خود تولید می‌شود. هر دو فایل را از سرور خارج کنید، زیرا پشتیبانی که روی همان ماشینِ تحت حفاظت باقی بماند، پشتیبان محسوب نمی‌شود. بازیابی به معنای نصب یک Flarum تازه با همان نسخه، composer install، قرار دادن فایل‌های ذخیره‌شده در جای خود و بارگذاری فایل SQL است.

FAQ

آیا Flarum روی یک VPS با 1 GB رم اجرا می‌شود؟

بله، برای یک انجمن کوچک. Flarum در حالت عادی شامل PHP-FPM است که به درخواست‌ها پاسخ می‌دهد و همچنین MariaDB؛ با استفاده از pm = ondemand، پردازش‌های PHP فقط زمانی که کاربری در حال خواندن صفحه است فعال می‌شوند. اوج مصرف منابع در زمان نصب است: composer create-project کل نمودار وابستگی‌ها را در حافظه بارگذاری می‌کند و این مرحله‌ای است که بیشترین احتمال دارد توسط out-of-memory killer متوقف شود. پیش از نصب، یک swap file اضافه کنید یا Composer را یک‌بار روی دستگاهی با منابع بیشتر اجرا کرده و درخت فایل‌ها را منتقل کنید.

چرا با وجود کارکرد صفحه اصلی، لینک‌های گفتگو خطای 404 می‌دهند؟

بلاک سرور nginx شما فاقد include /srv/flarum/.nginx.conf; است. Flarum آدرس‌هایی مانند /d/1-hello-world را درون PHP مدیریت می‌کند و این مسیر یک فایل واقعی روی دیسک نیست. بدون قانون try_files $uri $uri/ /index.php?$query_string در آن قطعه‌کد، nginx به دنبال پوشه‌ای به نام d می‌گردد، موفق نمی‌شود و بدون فراخوانی PHP، خطای 404 برمی‌گرداند. در Apache، همین مسیریابی از طریق public/.htaccess انجام می‌شود که اگر در بلاک <Directory> مقدار AllowOverride All تنظیم نشده باشد، نادیده گرفته می‌شود.

چرا پس از فعال‌سازی HTTPS، تمام استایل‌های انجمن از بین رفته است؟

Flarum آدرس پایه (base URL) را در config.php ذخیره می‌کند که از آدرسی که هنگام نصب استفاده کرده‌اید گرفته شده است. اگر روی HTTP معمولی نصب کرده باشید، Flarum همچنان آدرس‌های asset را با http:// تولید می‌کند و مرورگر آن‌ها را به عنوان mixed content در یک صفحه HTTPS مسدود می‌کند که نتیجه آن نمایش متن بدون استایل است. کلید url را در /srv/flarum/config.php به آدرس https:// تغییر دهید و php flarum cache:clear را با کاربری که مالک فایل‌هاست اجرا کنید.

چرا هیچ‌کس ایمیل تأیید ثبت‌نام را دریافت نمی‌کند؟

ابتدا درایور ایمیل را بررسی کنید. درایور mail به یک باینری محلی sendmail نیاز دارد که در VPSهای تازه نصب‌شده Ubuntu وجود ندارد، و درایور log نیز فقط در storage/logs/ می‌نویسد و چیزی ارسال نمی‌کند. به smtp تغییر وضعیت دهید، از پورت 587 با رمزنگاری tls استفاده کنید (چون اکثر سرویس‌دهندگان پورت 25 خروجی را مسدود می‌کنند) و دکمه Send Test Mail را بزنید. اگر لاگ ارسال موفقیت‌آمیز را نشان می‌دهد اما ایمیل هرگز نمی‌رسد، مشکل از تحویل‌دهی (deliverability) است نه پیکربندی؛ بنابراین رکوردهای SPF و DKIM را برای دامنه فرستنده منتشر کنید.

آیا باید Flarum 1.8 را نصب کنم یا 2.0؟

1.8 را نصب کنید. تا اوت 2026، نسخه Flarum 2.0 یک release candidate است و مهم‌تر اینکه بسیاری از افزونه‌ها همچنان محدودیت flarum/core دارند که در نسخه 1.x متوقف می‌شود. نصب 2.0 در حال حاضر به معنای اجرای انجمنی است که افزونه‌های آن قابل به‌روزرسانی همزمان نیستند؛ این دقیقاً همان خطایی است که composer why-not برای تشخیص آن وجود دارد. با استفاده از flarum/flarum:^1.8.0 نسخه را ثابت نگه دارید و زمانی که افزونه‌های مورد نیاز شما نسخه 2.0 را منتشر کردند، دوباره بررسی کنید.

#flarum #forum #php #self-hosting #community