آموزش نصب FreshRSS روی سرور مجازی Ubuntu

آنچه در حال ساخت آن هستید

یک RSS reader خود-میزبان (self-hosted)، ابزاری برای خواندن فیدها است که روی سروری متعلق به خودتان اجرا می‌شود؛ بنابراین هیچ‌کس نمی‌تواند آن را متوقف کند یا محتوایی که به شما نمایش داده می‌شود را تغییر دهد. این راهنما FreshRSS را روی یک VPS با سیستم‌عامل Ubuntu 24.04 نصب می‌کند: Apache در لایه جلو، PHP در لایه پشت، MariaDB برای ذخیره‌سازی، و یک cron job که مقالات جدید را دریافت می‌کند. RSS (مخفف Really Simple Syndication) فرمت فایلی است که یک وب‌سایت منتشر می‌کند تا نرم‌افزارها بتوانند مقالات آن را بخوانند. FreshRSS یک برنامه PHP است که این فایل‌ها را جمع‌آوری کرده، مقالات را نگهداری می‌کند و یک رابط کاربری وب به همراه یک API (رابط برنامه‌نویسی اپلیکیشن) که اپلیکیشن‌های موبایل با آن ارتباط برقرار می‌کنند، در اختیار شما قرار می‌دهد.

خودِ فرآیند نصب کوچک است: یک نسخه (release) را استخراج کنید، یک دیتابیس بسازید، یک virtual host بنویسید، نصب‌کننده خط فرمان را اجرا کنید و سپس حساب کاربری را با cli/create-user.php ایجاد نمایید. بخش عمده‌ای از کارهای زیر مربوط به مراحلی است که افراد معمولاً پس از نصب در آن دچار اشتباه می‌شوند؛ یعنی تنظیم job تازه‌سازی، اسلش‌های کدگذاری‌شده برای API موبایل و مالکیت فایل‌ها.

نسخه FreshRSS 1.30.4 که در تاریخ 21 اکتبر 2026 منتشر شده، نسخه فعلی تا تاریخ 29 اکتبر 2026 است و به PHP 8.1 یا جدیدتر نیاز دارد. سیستم‌عامل Ubuntu 24.04 به همراه PHP 8.3 عرضه می‌شود، بنابراین بسته‌های موجود در توزیع کافی هستند و نیازی به استفاده از مخازن PHP شخص ثالث ندارید.

شروع از یک LAMP stack فعال

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

sudo apt update
sudo apt install -y apache2 mariadb-server php libapache2-mod-php
sudo systemctl enable --now apache2 mariadb

دستور systemctl status apache2 باید خروجی active (running) را نمایش دهد. اگر Apache اجرا نمی‌شود، دلیل معمول آن است که پردازش دیگری پورت 80 را اشغال کرده است؛ دستور sudo ss -ltnp | grep :80 نام آن پردازش را مشخص می‌کند.

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

برنامه FreshRSS استفاده از libxml، cURL، JSON، PDO_MySQL، PCRE و ctype را الزامی می‌داند. همچنین این برنامه به mbstring، iconv، Zlib، ZipArchive و در سیستم‌های 32 بیتی به GMP نیاز دارد. در توزیع Ubuntu، این موارد در قالب بسته‌های توزیع ارائه می‌شوند:

sudo apt install -y php-curl php-mbstring php-xml php-zip php-mysql php-intl php-gmp
sudo systemctl restart apache2

با استفاده از دستور php -m بررسی کنید که کدام افزونه‌ها توسط PHP بارگذاری شده‌اند. نبود یک افزونه باعث توقف اجرای نصب‌کننده نمی‌شود. این مشکل در صفحه پیش‌نیازها با یک خط قرمز که نام افزونه را ذکر می‌کند نمایان می‌شود، که مکان مناسبی برای پی بردن به مشکل نیست؛ بنابراین همین حالا آن را تأیید کنید. راه‌اندازی مجدد Apache اهمیت دارد، زیرا libapache2-mod-php باعث می‌شود PHP درون فرآیند Apache باقی بماند؛ بنابراین افزونه‌ای که به‌تازگی نصب شده است تا زمانی که وب‌سرور را مجدداً راه‌اندازی نکنید، برای آن قابل مشاهده نخواهد بود.

دانلود نسخه منتشرشده

برنامه FreshRSS را خارج از مسیر پیش‌فرض وب (web root) نصب کنید و Apache را به آن ارجاع دهید. جدا نگه‌داشتن دایرکتوری برنامه از document root باعث می‌شود که تنها پوشه public از طریق HTTP در دسترس باشد.

cd /tmp
curl -fsSLO https://github.com/FreshRSS/FreshRSS/archive/refs/tags/1.30.4.tar.gz
tar xzf 1.30.4.tar.gz
sudo mv FreshRSS-1.30.4 /srv/freshrss

اکنون نوبت مجوزهاست؛ مستندات FreshRSS در این مورد بسیار سخت‌گیرانه عمل می‌کنند: کاربر وب‌سرور باید مالک کل ساختار درختی باشد، گروه باید اجازه خواندن تمام فایل‌ها را داشته باشد و گروه باید بتواند در ./data/ بنویسد.

sudo chown -R www-data:www-data /srv/freshrss
sudo chmod -R g+r /srv/freshrss
sudo chmod -R g+w /srv/freshrss/data

اگر این مرحله را نادیده بگیرید، نصب‌کننده هنگام نوشتن فایل پیکربندی با خطا مواجه می‌شود؛ زیرا PHP با کاربر www-data اجرا می‌شود و www-data نمی‌تواند در دایرکتوری که مالک آن root است، فایلی بنویسد.

ایجاد پایگاه داده

نرم‌افزار FreshRSS از SQLite، MariaDB، MySQL و PostgreSQL پشتیبانی می‌کند. SQLite به افزونه php-sqlite3 نیاز دارد اما نیازی به راه‌اندازی سرور پایگاه داده ندارد و داده‌های هر کاربر را در یک فایل data/users/_user_/db.sqlite مجزا ذخیره می‌کند. افزودن کاربران باعث نمی‌شود نوشته‌های آن‌ها در یک فایل SQLite مشترک قرار گیرد؛ این راهنما از MariaDB به عنوان بخشی از پشته LAMP استفاده می‌کند.

sudo mariadb -e "CREATE DATABASE freshrss CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mariadb -e "CREATE USER 'freshrss'@'localhost' IDENTIFIED BY 'ReplaceThisPassword';"
sudo mariadb -e "GRANT ALL PRIVILEGES ON freshrss.* TO 'freshrss'@'localhost';"
sudo mariadb -e "FLUSH PRIVILEGES;"

از utf8mb4 استفاده کنید و نه utf8. فیدها حاوی ایموجی و نویسه‌های غیر لاتین هستند و کدگذاری سه بایتی قدیمی utf8 نمی‌تواند نویسه‌های چهار بایتی را ذخیره کند. نویسه‌های پشتیبانی‌نشده در حالت strict پیش‌فرض MariaDB باعث بروز خطا می‌شوند؛ کوتاه شدن (truncation) داده‌ها به حالت SQL و گزینه‌های دستور مانند IGNORE بستگی دارد.

میزبان مجازی Apache

دایرکتوری عمومی p/ است، نه بالاترین سطح درخت فایل‌ها. سایر موارد، از جمله فایل پیکربندی که رمز عبور پایگاه داده شما در آن قرار دارد، در سطحی بالاتر از document root قرار می‌گیرند تا Apache هرگز آن‌ها را سرو نکند.

<VirtualHost *:80>
	ServerName rss.example.com
	DocumentRoot /srv/freshrss/p/

	<Directory /srv/freshrss/p>
		AllowOverride AuthConfig FileInfo Indexes Limit
		Require all granted
	</Directory>

	ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log
	CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined

	AllowEncodedSlashes On
</VirtualHost>

آن را با نام /etc/apache2/sites-available/freshrss.conf ذخیره کرده و فعال کنید:

sudo a2enmod rewrite
sudo a2ensite freshrss
sudo a2dissite 000-default
sudo apache2ctl configtest
sudo systemctl reload apache2

configtest باید Syntax OK را چاپ کند. AllowEncodedSlashes On اختیاری به نظر می‌رسد اما چنین نیست: Google Reader API شناسه‌های فیدی ارسال می‌کند که حاوی %2F هستند و بدون این دستور، Apache آن‌ها را رد می‌کند؛ در نتیجه، برنامه‌های موبایل همگام‌سازی نمی‌شوند، در حالی که رابط وب به درستی کار می‌کند.

پیش از ورود به سیستم، HTTPS را فعال کنید

شما قصد دارید رمز عبور خود را در این سایت وارد کنید، بنابراین ابتدا یک گواهی دریافت کنید. یک رکورد A به سمت سرور تنظیم کنید، سپس راهنمای راه‌اندازی Certbot برای Apache روی Ubuntu را دنبال کرده و دستور sudo certbot --apache -d rss.example.com را اجرا کنید. Certbot فایل virtual host مربوط به پورت 443 را بازنویسی کرده و تغییر مسیر (redirect) را اضافه می‌کند. با استفاده از curl -I https://rss.example.com/ صحت عملکرد را بررسی کنید؛ این دستور باید یک 200 یا یک تغییر مسیر به صفحه ورود را بازگرداند.

اجرای نصب‌کننده از طریق خط فرمان

نرم‌افزار FreshRSS دارای یک نصب‌کننده تحت مرورگر است، اما نسخه خط فرمان آن قابلیت تکرارپذیری دارد و سوابق دقیقی از انتخاب‌های شما ثبت می‌کند.

sudo -u www-data php /srv/freshrss/cli/do-install.php \
  --default-user admin --auth-type form --environment production \
  --base-url https://rss.example.com --language en --api-enabled \
  --db-type mysql --db-host localhost --db-user freshrss \
  --db-password 'ReplaceThisPassword' --db-base freshrss
sudo -u www-data php /srv/freshrss/cli/create-user.php \
  --user admin --password 'a-long-passphrase' --api-password 'a-different-passphrase'

هر دو دستور را به عنوان کاربر www-data اجرا کنید. اجرای آن‌ها با دسترسی root باعث می‌شود فایل‌های پیکربندی با مالکیت root ایجاد شوند و در نتیجه رابط کاربری وب بعداً در ذخیره هرگونه تنظیمات دچار خطا شود. تنظیم --environment production نیز حائز اهمیت است، زیرا حالت development باعث می‌شود اعلان‌های PHP در صفحه نمایش داده شوند.

فایل https://rss.example.com/ را بارگذاری کرده و با نام کاربری admin وارد شوید.

چرا فیدها به‌طور خودکار به‌روزرسانی نمی‌شوند

تا زمانی که به سیستم دستور ندهید، هیچ‌کس فیدهای شما را بررسی (poll) نمی‌کند. باز کردن FreshRSS باعث زمان‌بندی برای دریافت فیدها نمی‌شود؛ بدون یک زمان‌بند (scheduler)، باید از لینک به‌روزرسانی در منوی ناوبری برای دریافت دستی مقالات استفاده کنید. راه‌حل این مشکل، استفاده از اسکریپتی است که پروژه برای این منظور ارائه کرده است، یعنی app/actualize_script.php، که باید توسط cron اجرا شود.

sudo crontab -u www-data -e

یک خط زیر را اضافه کنید:

*/20 * * * * php /srv/freshrss/app/actualize_script.php > /tmp/FreshRSS.log 2>&1

بازه زمانی 20 دقیقه یک زمان‌بندی معقول است، اما همچنان بازهٔ به‌روزرسانی هر فید اعمال می‌شود: مقدار پیش‌فرض یک ساعت است و فیدهای تکی از بازه‌های زمانی تا حداقل 15 دقیقه پشتیبانی می‌کنند. ابتدا آن را یک‌بار به‌صورت دستی اجرا کنید:

sudo -u www-data php /srv/freshrss/app/actualize_script.php

خروجی سالم، اجرای عملیات به‌روزرسانی را گزارش می‌دهد و بدون خطای PHP پایان می‌یابد؛ نام فیدها زمانی ظاهر می‌شود که مقالات جدید اضافه یا به‌روزرسانی شده باشند. اگر هیچ خروجی‌ای چاپ نشد، خروجی خطای PHP و لاگ‌های FreshRSS را بررسی کنید؛ سکوتِ محض به تنهایی مشخص نمی‌کند که آیا کاربرِ cron عامل مشکل است یا خیر. خطای مجوز در data/ نشان‌دهنده نیاز به بررسی مالکیت (ownership) و مجوزهای نوشتن (write permissions) است.

افزودن اولین فیدها

از دکمه مثبت در سمت چپ بالای رابط کاربری استفاده کنید، آدرس سایت را وارد کنید تا FreshRSS لینک فید را برای شما پیدا کند. اکثر سایت‌ها حتی زمانی که آن را تبلیغ نمی‌کنند، همچنان یک فید منتشر می‌کنند که معمولاً در /feed، /rss یا /atom.xml قرار دارد. دسته‌بندی‌ها همان پوشه‌ها هستند و جابه‌جایی فید بین آن‌ها با کشیدن و رها کردن انجام می‌شود.

اگر از یک خبرخوان دیگر مهاجرت می‌کنید، یک فایل OPML از آنجا خروجی بگیرید و در صفحه مدیریت اشتراک‌ها وارد کنید. OPML (زبان نشانه‌گذاری پردازشگر طرح‌واره) فرمت استاندارد لیست فید است و هر خبرخوان قابل‌قبولی از آن پشتیبانی می‌کند. وارد کردن تعداد زیادی فید در اولین به‌روزرسانی کند است، زیرا هر فید یک‌بار فراخوانی می‌شود؛ بنابراین پیش از قضاوت درباره سرعت، به اولین اجرای cron زمان کافی بدهید.

مطالعه روی تلفن همراه

نرم‌افزار FreshRSS از Google Reader API پشتیبانی می‌کند که بسیاری از اپلیکیشن‌های RSS با آن سازگار هستند. دو شرط باید برقرار باشد. در تنظیمات احراز هویت، گزینه "Allow API access" باید فعال باشد که فلگ --api-enabled در بالا قبلاً آن را تنظیم کرده است. در بخش پروفایل، فیلد API password باید دارای مقدار باشد؛ این رمز عبور عمداً از رمز عبور ورود به سیستم جدا در نظر گرفته شده است، زیرا احتمال گم شدن تلفن همراه بیشتر است.

برای اجرای خودکار بررسی‌های پیکربندی سرور، به https://rss.example.com/api/ مراجعه کنید. یک تنظیمات صحیح، مقدار PASS را برمی‌گرداند. اگر بررسی با خطا مواجه شد، تنظیمات AllowEncodedSlashes On در virtual host و خطای گزارش‌شده را بررسی کنید. در اپلیکیشن، آدرس سرور را به صورت https://rss.example.com/api/greader.php، نام کاربری را همان نام کاربری FreshRSS خود و رمز عبور API را به عنوان رمز عبور وارد کنید.

جایگزین Docker

اگر ترجیح می‌دهید PHP و Apache را به‌صورت دستی مدیریت نکنید، این پروژه یک image رسمی freshrss/freshrss منتشر می‌کند و یک فایل compose، برنامه و دیتابیس آن را در کنار هم در اختیار شما قرار می‌دهد. این روش معامله‌ای معمول است: قطعات متحرک کمتر روی سیستم میزبان، اما یک لایه اضافه برای عیب‌یابی در صورت بروز مشکل؛ همچنین همچنان برای TLS (امنیت لایه انتقال) به یک reverse proxy نیاز خواهید داشت. اگر این روش برای شما مناسب‌تر است، اصول Docker Compose برای VPS فرمت فایل را توضیح داده است و خط cron به docker exec --user www-data freshrss php ./app/actualize_script.php تغییر می‌کند.

پشتیبان‌گیری و ارتقا

دو مورد وضعیت (state) شما را حفظ می‌کنند: پایگاه داده و /srv/freshrss/data/. اولی را با sudo mysqldump freshrss > freshrss.sql تخلیه (dump) کنید، از دومی کپی بگیرید و هر دو را در مکانی خارج از این سرور نگهداری کنید. لیست اشتراک‌های شما نیز ارزش آن را دارد که گهگاه به صورت OPML خروجی گرفته شود، زیرا این فایل لیست فیدهای شما را به سایر خواننده‌هایی که از OPML پشتیبانی می‌کنند، منتقل می‌کند. این کار تنظیمات اختصاصی FreshRSS مانند فرکانس به‌روزرسانی، اعتبارنامه‌ها، user agent یا قوانین XPath برای web scraping را حفظ نمی‌کند؛ برای حفظ آن‌ها از خروجی SQLite استفاده کنید.

ارتقا شامل استخراج یک نسخه جدیدتر روی همان دایرکتوری و اجرای مجدد دستورات مالکیت (ownership) است. مسیر ارتقای نسخه به نسخه پروژه را دنبال کنید و پس از هر مرحله، عملکرد FreshRSS را بررسی کنید. FreshRSS مهاجرت‌های پایگاه داده خود را در بارگذاری صفحه بعدی اعمال می‌کند. ابتدا پشتیبان بگیرید، زیرا مهاجرت ناموفق روی پایگاه داده‌ای که نمی‌توانید آن را بازیابی کنید، وضعیتی غیرقابل‌بازگشت ایجاد می‌کند. اگر از tarball قدیمی‌تری مانند 1.29.1 نصب کرده‌اید، به 1.30.4 بروید: نسخه‌های امنیتی 1.30.x شامل چرخش شناسه نشست (session ID) در تغییرات احراز هویت و محدودیت‌هایی برای واردات فایل‌های ZIP هستند، در حالی که 1.30.4 تصاویر جایگزین Alpine Docker را نیز برای آسیب‌پذیری‌های جدی PHP به‌روزرسانی می‌کند. یک RSS reader سرویسی با ریسک پایین برای اجراست و اگر در حال بررسی لیستی از سرویس‌های مناسب برای self-hosting هستید، گزینه اول خوبی برای شروع محسوب می‌شود.

FAQ

چرا فیدهای من فقط زمانی که FreshRSS را باز می‌کنم به‌روزرسانی می‌شوند؟

باز کردن صفحه، زمان‌بندی برای دریافت فیدها ایجاد نمی‌کند؛ بدون یک زمان‌بند (scheduler)، از لینک به‌روزرسانی برای رفرش دستی استفاده کنید. خط cron که app/actualize_script.php را فراخوانی می‌کند با کاربر www-data اضافه کنید، سپس اسکریپت را یک بار به‌صورت دستی اجرا کرده و خروجی آن را بخوانید. اگر خروجی خالی بود، خروجی خطای PHP و لاگ‌های FreshRSS را بررسی کنید، سپس مطمئن شوید که کاربر cron دسترسی نوشتن در data/ را دارد.

اپلیکیشن موبایل من نمی‌تواند متصل شود، اما وب‌سایت کار می‌کند. چرا؟

Google Reader API اسلش‌های کدگذاری‌شده (%2F) را در مسیرهای درخواست قرار می‌دهد و Apache به‌صورت پیش‌فرض آن‌ها را رد می‌کند. عبارت AllowEncodedSlashes On را داخل virtual host اضافه کرده و Apache را reload کنید. با باز کردن https://rss.example.com/api/ صحت این اصلاح را تأیید کنید؛ در آنجا بررسی خودکار پیکربندی باید PASS را گزارش دهد. همچنین بررسی کنید که رمز عبور API در پروفایل شما تنظیم شده باشد، زیرا این رمز از رمز عبور ورود شما جدا است.

آیا باید از SQLite استفاده کنم یا MariaDB؟

SQLite به افزونه php-sqlite3 نیاز دارد، اما نیازی به سرور دیتابیس یا مدیریت رمز عبور دیتابیس ندارد. هر کاربر یک فایل دیتابیس SQLite جداگانه دریافت می‌کند، بنابراین افزودن کاربر دوم باعث ایجاد تداخل در یک فایل مشترک نمی‌شود یا نیازی به MariaDB ندارد. اگر می‌خواهید از سرور دیتابیس در پشته LAMP خود استفاده کنید، MariaDB را انتخاب کنید. جابه‌جایی بین این دو در آینده از طریق دستورات export و import امکان‌پذیر است، بنابراین این یک تصمیم دائمی نیست.

نصب‌کننده هنگام نوشتن پیکربندی خود با خطا مواجه می‌شود. مشکل چیست؟

PHP تحت Apache با کاربر www-data اجرا می‌شود و آن کاربر نمی‌تواند در دایرکتوری که مالک آن root است بنویسد. دستورات sudo chown -R www-data:www-data /srv/freshrss و sudo chmod -R g+w /srv/freshrss/data را دوباره اجرا کنید، سپس نصب‌کننده را مجدداً شروع کنید. اگر قبلاً نصب‌کننده خط فرمان را به عنوان root اجرا کرده‌اید، پیش از تلاش مجدد، مالکیت فایل‌هایی که تحت data/ ایجاد شده‌اند را اصلاح کنید.

یک RSS reader خودمیزبان (self-hosted) به چه میزان سخت‌افزار نیاز دارد؟

بسیار کم. FreshRSS برای اجرا روی سخت‌افزارهای معمولی طراحی شده است، اما میزان مصرف منابع به فیدها، اندازه مقالات و تنظیمات نگهداری شما بستگی دارد. حجم دیسک با نگهداری مقالات افزایش می‌یابد، بنابراین به‌جای نگهداری همیشگی همه چیز، یک سیاست پاک‌سازی (purge) در تنظیمات آرشیو تعیین کنید.