راه اندازی سرور ntfy شخصی با Docker Compose
آموزش گام به گام میزبانی ntfy روی VPS با تنظیمات TLS و Docker Compose. یاد بگیرید چگونه با استفاده از ACL و احراز هویت، اعلانهای cron و systemd را به صورت امن ارسال کنید.
عملکرد یک سرور ntfy خودمیزبان
یک سرور ntfy خودمیزبان، درخواستهای HTTP POST را به اعلانهای push روی تلفن همراه شما تبدیل میکند. شما با استفاده از curl پیام را منتشر میکنید و پیام در اپلیکیشن Android، اپلیکیشن iOS، تب مرورگر یا هر ابزار دیگری که بتواند یک اتصال HTTP را باز نگه دارد، دریافت میشود. هیچ کتابخانه کلاینتی برای نصب و هیچ message broker برای اجرا وجود ندارد.
ntfy پیامها را بر اساس topic آدرسدهی میکند. یک topic نامی در مسیر URL است، مانند https://ntfy.example.com/alerts، و به محض اینکه کسی پیامی در آن منتشر کند، ایجاد میشود. در یک نصب پیشفرض، هر کسی که آن نام را بداند میتواند topic را بخواند یا در آن بنویسد؛ به همین دلیل است که مستندات خود پروژه، نام topic را به یک رمز عبور تشبیه میکند. این مدل برای سرویس عمومی ntfy.sh مناسب است، اما برای سروری که گزارشهای خطای پشتیبانگیری شما را حمل میکند مناسب نیست؛ بنابراین این راهنما پیش از ارسال اولین پیام، احراز هویت را فعال میکند.
پیشنیازهای شروع کار
شما به یک VPS با سیستمعامل Ubuntu 24.04 یا Debian 13، به همراه Docker Engine و پلاگین Compose، یک نام دامنه و مقدار بسیار کمی رم نیاز دارید. یک رکورد A در DNS (سامانه نام دامنه) ایجاد کنید که ntfy.example.com را به آدرس IP عمومی سرور اشاره دهد، سپس پیش از انجام هر کار دیگری، از صحت resolve شدن آن اطمینان حاصل کنید.
dig +short ntfy.example.com
sudo ufw allow 80,443/tcp
sudo ufw statusdig باید IP سرور شما را نمایش دهد. صدور گواهی نیازمند آن است که نام میزبان (hostname) بهصورت عمومی از طریق یک رکورد A یا AAAA به سرور resolve شود. پورت 80 باید باز بماند، زیرا ACME (محیط مدیریت خودکار گواهی)، پروتکل پشت Let's Encrypt، از آن برای چالش HTTP استفاده میکند. خود کانتینر ntfy هرگز پورت عمومی دریافت نمیکند.
نوشتن فایل پیکربندی ntfy
ایمیج Docker شامل فایل پیکربندی نیست، بنابراین باید یکی ایجاد کنید. تمام دستورات بعدی در این راهنما از این فایل استفاده میکنند. ابتدا شناسه کاربری (UID) و شناسه گروه (GID) که کانتینر با آن اجرا میشود را پیدا کنید.
id -u
id -g
sudo install -d -o "$(id -u)" -g "$(id -g)" /etc/ntfy /var/cache/ntfy /var/lib/ntfy
sudo nano /etc/ntfy/server.ymlbase-url: "https://ntfy.example.com"
listen-http: ":2586"
behind-proxy: true
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
enable-login: true
enable-signup: falseچهار مورد از این خطوط اهمیت ویژهای دارند. base-url باید دقیقاً آدرس HTTPS عمومی باشد، زیرا ntfy از آن برای تولید لینکهای پیوست و نوتیفیکیشنهای push در iOS (در حالت self-hosted) استفاده میکند. listen-http: ":2586" به تمام اینترفیسهای داخل کانتینر متصل میشود؛ این کار ممکن است ناامن به نظر برسد اما صحیح است: کانتینر فضای نام شبکه (network namespace) اختصاصی خود را دارد، بنابراین اتصال به 127.0.0.1 در آنجا باعث میشود پورت از سمت میزبان غیرقابل دسترس باشد و پورت منتشر شده توسط Docker هرگز متصل نشود. auth-default-access: "deny-all" کل وضعیت امنیتی را تعیین میکند، زیرا خواندن و نوشتن را برای هر کسی که دسترسی صریح نداشته باشد، رد میکند. behind-proxy: true به ntfy میگوید که آدرس کلاینت را از هدر X-Forwarded-For بخواند تا محدودیتهای نرخ (rate limits) به جای شمارش reverse proxy به عنوان یک کلاینت بسیار پرمشغله، بازدیدکنندگان واقعی را محاسبه کنند.
enable-login: true به کاربران اجازه میدهد از طریق اپلیکیشن وب یا API وارد سیستم شوند. enable-signup روی false باقی میماند، زیرا ایجاد حساب کاربری توسط خود کاربر در یک سرور خصوصی، مانند باز گذاشتن در با مراحل اضافی است.
sudo chown "$(id -u):$(id -g)" /etc/ntfy/server.yml
sudo chmod 600 /etc/ntfy/server.ymlاجرای ntfy با Docker Compose
این محتوا را در /opt/ntfy/compose.yaml قرار دهید و 1000:1000 را با دو عدد id -u و id -g که در بالا چاپ شدهاند، جایگزین کنید.
services:
ntfy:
image: binwiederhier/ntfy:v2.36.0
container_name: ntfy
command: serve
user: "1000:1000"
environment:
- TZ=UTC
volumes:
- /etc/ntfy:/etc/ntfy
- /var/cache/ntfy:/var/cache/ntfy
- /var/lib/ntfy:/var/lib/ntfy
ports:
- "127.0.0.1:2586:2586"
restart: unless-stoppedcd /opt/ntfy
sudo docker compose up -d
sudo docker compose logs ntfy
curl -s http://127.0.0.1:2586/v1/healthیک سرور سالم به {"healthy":true,"role":"active"} پاسخ میدهد. دو جزئیات در آن فایل compose عمدی هستند. ایمیج به v2.36.0 پین شده است، که نسخه پایدار فعلی تا تاریخ 1 نوامبر 2026 است، به جای latest؛ زیرا با latest دستور docker compose pull بعدی ایمیج فعلی را دانلود میکند و یک docker compose up -d متعاقب آن، کانتینر را با آن بازسازی میکند؛ صرفِ pull کردن، نسخه سرور در حال اجرا را تغییر نمیدهد. پین کردن همچنان نیاز به بهروزرسانی دارد. اکتبر 2026 بهتنهایی ده نسخه داشت: v2.29.0 در 7 اکتبر، v2.30.0 در 12 اکتبر، v2.31.0 و v2.31.1 در 16 اکتبر، v2.32.0 در 18 اکتبر، v2.33.0 و v2.33.1 در 23 اکتبر، v2.34.0 در 24 اکتبر، v2.35.0 در 30 اکتبر و v2.36.0 در 31 اکتبر. نسخه v2.31.0 پیامهایی را اصلاح کرد که هنگام اتصال مجدد کلاینت پیش از رسیدن به کش پیام، از دست میرفتند، اما اتصالهای مجدد آن با since=<message ID> تمام پیامهای موجود در topic را از دیتابیس میخواند و ntfy.sh آن را بازگرداند (rollback کرد). نسخه v2.31.1 آن بار کاری را با یک ایندکس جدید اصلاح میکند و v2.34.0 کاربرانی را که لغو اشتراک شده یا حذف شدهاند اما همچنان برخی اشتراکها را نگه داشتهاند، اصلاح میکند. نسخه v2.35.0 درخواستهای همزمانی را که اعتبارنامههای معتبر را به عنوان ناشناس تلقی میکردند و همچنین یک دور زدن مجوز در Matrix push gateway روی SQLite را اصلاح میکند، بنابراین پینهای قدیمیتر را به v2.36.0 منتقل کنید. پورت به صورت 127.0.0.1:2586:2586 منتشر میشود، بنابراین کانتینر فقط از آدرس loopback میزبان قابل دسترسی است. اگر به جای آن 2586:2586 بنویسید، داکر قوانین فایروال خود را پیش از قوانین شما قرار میدهد، که به این معنی است که پورت از اینترنت پاسخ میدهد، حتی اگر ufw status بگوید پورت بسته است. هر دو عادت به کانتینر بعدی که اضافه میکنید منتقل میشوند: یک relay خودمیزبان RustDesk تگ ایمیج خود را به همان روش پین میکند، اما نمیتواند پشت loopback پنهان شود، زیرا پورتهای سیگنال و relay آن باید از اینترنت پاسخگو باشند.
اگر curl عبارت Connection refused را چاپ کرد، لاگ کانتینر را بخوانید. خطای مجوز در /var/lib/ntfy/user.db به این معنی است که خط user: با مالک آن دایرکتوریها مطابقت ندارد، بنابراین پردازش نمیتواند دیتابیس خود را ایجاد کند و خارج میشود. راهنمای اصول Docker Compose برای یک VPS مالکیت volume و سیاستهای راهاندازی مجدد را با جزئیات بیشتری پوشش میدهد.
قرار دادن TLS در مقابل با Caddy
Caddy گواهی را بهطور خودکار درخواست و تمدید میکند که کوتاهترین مسیر برای دستیابی به TLS (امنیت لایه انتقال) است.
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddyمحتوای /etc/caddy/Caddyfile را با سه خط زیر جایگزین کنید.
ntfy.example.com {
reverse_proxy 127.0.0.1:2586
}sudo systemctl reload caddy
curl -s https://ntfy.example.com/v1/healthهمان {"healthy":true,"role":"active"} روی HTTPS به این معنی است که کل مسیر بهدرستی کار میکند. یک 502 از طرف Caddy معمولاً به این معنی است که ntfy در حال گوش دادن نیست: با استفاده از sudo ss -lntp | grep 2586 بررسی کنید. اگر ntfy در حال گوش دادن است و 502 همچنان باقی است، Caddy خطای upstream دریافتی، مانند reset connection را لاگ میکند. خطای گواهی معمولاً به این معنی است که رکورد DNS اشتباه است یا اعتبارسنجی گواهی نمیتواند به سرور روی پورت 80 یا 443 دسترسی پیدا کند؛ برای مشاهده خطای اعتبارسنجی، sudo journalctl -u caddy -n 50 را بررسی کنید. افزودن سرویس دیگر در آینده، تنها به یک بلوک hostname بیشتر در همان Caddyfile نیاز دارد؛ این همان روشی است که چیزی مانند Halcyon، یک رابط کاربری ویدیو کلوپ دهه 90 برای کتابخانه Jellyfin شما روی زیردامنه دوم همان سرور قرار میگیرد.
اگر از قبل nginx را اجرا میکنید، تنظیمات پروکسی مستند شده توسط ntfy را کپی کنید: proxy_http_version 1.1، proxy_buffering off، proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for، و زمانهای read و send timeout را حداقل روی سه دقیقه تنظیم کنید. یک مشترک (subscriber) تا زمانی که در حال گوش دادن است، یک اتصال HTTP را باز نگه میدارد. مقدار پیشفرض proxy_read_timeout در nginx که 60 ثانیه است، فقط زمان بین دو خواندن را محاسبه میکند و ntfy بهطور پیشفرض هر 45 ثانیه یک پیام keepalive ارسال میکند (keepalive-interval) تا واسطهها اتصال را به دلیل عدم فعالیت نبندند. بنابراین یک مشترک آرام حتی پشت nginx پیشفرض هم متصل میماند و timeoutهای طولانیتر، صرفاً فضای اطمینان هستند، نه عاملی که اتصال را زنده نگه میدارد. اگر keepalive-interval را افزایش دادید، آن را کمتر از read timeout پروکسی خود نگه دارید.
ایجاد کاربران و محدودسازی دسترسی به موضوعات
احراز هویت فعال است و در حال حاضر هیچکس به هیچچیز دسترسی ندارد؛ این دقیقاً همان هدفی است که دنبال میکردیم. یک حساب کاربری مدیریتی برای خودتان و یک حساب ماشینی برای اسکریپتها ایجاد کنید. این دستورات /etc/ntfy/server.yml را از داخل کانتینر میخوانند، به همین دلیل فایل پیکربندی به صورت یک volume mount متصل شده است.
sudo docker compose exec ntfy ntfy user add --role=admin admin
sudo docker compose exec ntfy ntfy user add robot
sudo docker compose exec ntfy ntfy user listهر دستور user add برای دریافت رمز عبور از شما درخواست میکند. مدیر (admin) لیست دسترسی را نادیده میگیرد و میتواند تمام موضوعات (topics) را بخواند و بنویسد، بنابراین این حساب را برای خودتان و اپلیکیشن موبایل نگه دارید. robot یک کاربر عادی است که تا زمانی که دسترسی خاصی به او ندهید، هیچ دسترسیای نخواهد داشت.
sudo docker compose exec ntfy ntfy access robot alerts write
sudo docker compose exec ntfy ntfy access robot "alerts_*" write
sudo docker compose exec ntfy ntfy accessیک ورودی ACL (لیست کنترل دسترسی) شامل یک کاربر، یک موضوع و یک سطح دسترسی است. موضوع میتواند یک نام مشخص یا یک الگو باشد که در آن * با هر چیزی مطابقت دارد؛ بنابراین alerts_* شامل alerts_backup و alerts_db میشود و نیازی نیست برای هر میزبان یک دستور جداگانه وارد کنید. سطح دسترسی write به معنای فقط انتشار (publish) است، بنابراین اگر توکن یک cron job به سرقت برود، مهاجم نمیتواند مشترک (subscribe) شود و دادههای ارسالی را بخواند. نام کاربری ویژه everyone تعیین میکند که بازدیدکنندگان احراز هویتنشده چه کاری میتوانند انجام دهند. با تنظیم deny-all به عنوان پیشفرض، معمولاً از آن برای باز کردن دسترسی به بخشهای عمومی مانند ntfy access everyone status read استفاده میکنید؛ همچنین این بخش از deny پشتیبانی میکند، زمانی که میخواهید قانونی صریح برای جلوگیری از دسترسی بازدیدکنندگان ناشناس به یک موضوع خاص وضع کنید.
اسکریپتها باید از توکن استفاده کنند، نه رمز عبور شما.
sudo docker compose exec ntfy ntfy token add robotاین دستور توکنی را چاپ میکند که با tk_ شروع میشود. یک توکن دقیقاً همان دسترسیهای کاربری را به ارث میبرد که به آن تعلق دارد، بنابراین این توکن فقط میتواند در موضوعات alerts منتشر کند و هیچ کار دیگری انجام ندهد. دستور ntfy token list موارد موجود را نمایش میدهد و ntfy token remove یکی از آنها را بدون تغییر در رمز عبور کاربر، باطل میکند.
ارسال اولین پیام و اطمینان از عملکرد قفل
ابتدا بررسی کنید که در بسته است.
curl -s -o /dev/null -w '%{http_code}\n' -d "hello" https://ntfy.example.com/alertsاین دستور 403 را چاپ میکند و 403 پاسخ صحیح است: auth-default-access: "deny-all" انتشار ناشناس را نمیپذیرد. اکنون یک پیام واقعی ارسال کنید.
curl -H "Authorization: Bearer tk_REPLACE_WITH_YOUR_TOKEN" \
-H "Title: Nightly backup finished" \
-H "Priority: default" \
-H "Tags: white_check_mark" \
-d "42 GB copied in 11 minutes" \
https://ntfy.example.com/alertsسرور با پیام ذخیرهشده در قالب JSON پاسخ میدهد؛ این نشان میدهد که پیام پذیرفته شده و نادیده گرفته نشده است. Title خط اول پررنگ است. Priority از 1 تا 5 یا با نام از min تا urgent مقدار میگیرد و تعیین میکند که آیا گوشی صدا پخش کند یا خیر. Tags در صورتی که نام با یک کد کوتاه ایموجی شناختهشده مطابقت داشته باشد، به ایموجی در اعلان تبدیل میشوند و در غیر این صورت به صورت متن ساده باقی میمانند.
برای نظارت بر یک موضوع از طریق ترمینال، آن را stream کنید:
curl -s -u admin https://ntfy.example.com/alerts/rawدستور curl رمز عبور را درخواست میکند. هر پیام به صورت یک خط دریافت میشود و خطوط خالی که گاهی ظاهر میشوند، keepalive هستند. باز کردن https://ntfy.example.com در مرورگر و ورود با همان حساب کاربری، نسخه وب همان stream را در اختیار شما قرار میدهد.
تنظیم محدودیت نرخ برای جلوگیری از سیل درخواست توسط یک اسکریپت
بهطور پیشفرض، هر بازدیدکننده یک سطل با 60 درخواست دریافت میکند که هر 5 ثانیه یک درخواست به آن اضافه میشود. این برای یک سرور خصوصی سخاوتمندانه است و اسکریپتی که در حلقه تلاش مجدد گیر کرده باشد، تمام آن را مصرف میکند. محدودیتها را به server.yml اضافه کنید.
visitor-request-limit-burst: 30
visitor-request-limit-replenish: "10s"
visitor-message-daily-limit: 500sudo docker compose restart ntfyبازدیدکنندهای که از حد مجاز فراتر رود، به جای پیام تحویلدادهشده، HTTP 429 دریافت میکند. محدودیت بر اساس آدرس بازدیدکننده محاسبه میشود، که دلیل اهمیت زیاد behind-proxy: true است: بدون آن، ntfy فقط آدرس Caddy را میبیند، هر کلاینت به عنوان همان بازدیدکننده شمارش میشود و یک اسکریپت پرسر و صدا، سطلی را که گوشی شما و سایر سرورهایتان به اشتراک میگذارند، خالی میکند. از نسخه v2.36.0، شمارشهای روزانه پس از راهاندازی مجدد در دیتابیس کاربر باقی میمانند و سهمیه هر بازدیدکننده به جای نیمهشب UTC، در چرخه 24 ساعته مخصوص به خود بازنشانی میشود.
هشدار در صورت شکست یک cron job
توکن را در خط فرمان قرار ندهید. ps aux خط فرمان کامل هر پردازش در حال اجرا را به تمام کاربران سیستم نشان میدهد، بنابراین توکنی که با -H ارسال شود، تا زمانی که curl در حال اجراست برای هر حساب کاربری محلی قابل خواندن خواهد بود. استفاده از یک فایل پیکربندی curl از این مشکل جلوگیری میکند.
sudo install -d -m 700 /etc/ntfy-alert
printf 'header = "Authorization: Bearer tk_REPLACE_WITH_YOUR_TOKEN"\n' | sudo tee /etc/ntfy-alert/curlrc
sudo chmod 600 /etc/ntfy-alert/curlrcحالا job را بستهبندی کنید. این فایل را با نام /usr/local/bin/backup-with-alert.sh ذخیره کرده و آن را chmod 750 کنید.
#!/bin/bash
out=$(/usr/local/bin/backup.sh 2>&1)
code=$?
if [ "$code" -ne 0 ]; then
printf '%s' "$out" | tail -c 1000 | curl -K /etc/ntfy-alert/curlrc \
-H "Title: backup.sh failed with exit $code" \
-H "Priority: high" \
-H "Tags: warning" \
--data-binary @- \
https://ntfy.example.com/alerts
fi
exit "$code"17 3 * * * /usr/local/bin/backup-with-alert.sh >> /var/log/backup-alert.log 2>&1$? بلافاصله پس از دستور ثبت میشود، زیرا دستور بعدی که اجرا شود آن را بازنویسی میکند. خروجی از طریق tail -c 1000 فیلتر میشود، زیرا ntfy محدودیت حداکثر اندازه پیام دارد و اعلان (notification) جایگزین نمایشگر لاگ نیست. دستور exit "$code" در انتها، وضعیت اصلی (exit status) را حفظ میکند تا هر ابزار دیگری که این job را نظارت میکند، همچنان شکست آن را تشخیص دهد. کل فرآیند را با تغییر مسیر اسکریپت به /bin/false برای یک بار اجرا تست کنید.
شاخه شکست (failure branch) که هرگز اجرا نمیشود، از نبود هشدار بدتر است، زیرا این تصور را ایجاد میکند که سکوت به معنای موفقیت است. Cron محیطی تقریباً خالی و PATH بسیار کوتاهتری نسبت به shell ورود شما در اختیار job قرار میدهد، بنابراین اسکریپتی که هنگام اجرای دستی کار میکند، ممکن است پیش از رسیدن به خط curl متوقف شود. راهنمای دلایل اجرا نشدن یک cron job این تلههای محیطی را پوشش میدهد. در همه جا از مسیرهای مطلق (absolute paths) استفاده کنید و پس از اولین اجرای زمانبندیشده، به جای فرض کردن موفقیت، فایل لاگ را مطالعه کنید.
هشدار هنگام شکست یک unit در systemd
Cron برای کارهای زمانبندیشده مناسب است. سرویسهای طولانیمدت به OnFailure= نیاز دارند که systemd هر زمان که یک unit وارد وضعیت failed شود، آن را اجرا میکند. یک template unit بسازید و برای تمام سرویسهای روی سیستم از آن استفاده کنید. این فایل را با نام /etc/systemd/system/ntfy-unit-failed@.service ذخیره کنید.
[Unit]
Description=Send an ntfy alert because %i failed
[Service]
Type=oneshot
ExecStart=/usr/local/bin/ntfy-unit-failed %iسپس /usr/local/bin/ntfy-unit-failed را با دسترسی 750 ایجاد کنید:
#!/bin/bash
unit="$1"
journalctl -u "$unit" -n 15 --no-pager -o cat | tail -c 1000 | curl -K /etc/ntfy-alert/curlrc \
-H "Title: $unit failed on $(hostname -s)" \
-H "Priority: urgent" \
-H "Tags: rotating_light" \
--data-binary @- \
https://ntfy.example.com/alertsآن را با استفاده از یک drop-in به سرویس مورد نظر متصل کنید تا ارتقای بستهها، تغییرات شما را بازنویسی نکند.
sudo systemctl edit myapp.service[Unit]
OnFailure=ntfy-unit-failed@%n.service%n به نام کامل unit بسط مییابد، بنابراین unit نمونهسازیشده به ntfy-unit-failed@myapp.service.service تبدیل میشود و %i در داخل template، مقدار myapp.service را به عنوان اولین آرگومان به اسکریپت میفرستد. این همان چیزی است که اجازه میدهد یک template برای همه unitها استفاده شود. عملکرد آن را با یک unit که عمداً شکست میخورد و با نام /etc/systemd/system/ntfy-selftest.service ذخیره شده است، تست کنید.
[Unit]
Description=Deliberately failing unit
OnFailure=ntfy-unit-failed@%n.service
[Service]
Type=oneshot
ExecStart=/bin/falsesudo systemctl daemon-reload
sudo systemctl start ntfy-selftest.serviceدستور start با کد خروجی غیر صفر خارج میشود و Job for ntfy-selftest.service failed because the control process exited with error code را چاپ میکند؛ گوشی شما باید حدود یک ثانیه بعد هشدار دریافت کند. پس از تست، unit آزمایشی را حذف کنید.
یک نکته مهم وجود دارد. OnFailure= فقط زمانی اجرا میشود که یک unit به وضعیت failed برسد و RestartMode=direct در طول راهاندازی مجدد خودکار از این وضعیت عبور میکند، بنابراین handler شکست نیز اجرا نمیشود. با تنظیمات پیشفرض RestartMode=normal، راهاندازیهای مجدد خودکار از وضعیت failed عبور میکنند. StartLimitBurst و StartLimitIntervalSec کنترل میکنند که چه زمانی راهاندازیهای مکرر متوقف شود؛ آنها را طوری تنظیم کنید که crash loop در نهایت متوقف شود. Timers جایگزین تمیزتری برای الگوی cron در بالا هستند، زیرا سرویسِ یک timer از همان drop-in یعنی OnFailure= پشتیبانی میکند و راهنمای سرویسها و تایمرهای systemd روی یک VPS مراحل تبدیل آن را توضیح میدهد.
اتصال یک مانیتور آپتایم به همان تاپیک
Uptime Kuma، مانیتور وضعیت self-hosted، از نوع اعلان ntfy پشتیبانی میکند. به بخش Settings، سپس Notifications و بعد Setup Notification بروید، گزینه Ntfy را انتخاب کنید، آدرس سرور را روی https://ntfy.example.com و تاپیک را روی alerts تنظیم کنید، یک اولویت (priority) انتخاب کرده و توکن دسترسی robot را وارد کنید. پیش از ذخیره، یک اعلان تست ارسال کنید، زیرا نام تاپیک اشتباه باعث بروز خطا در دسترسی write میشود که آن تاپیک را پوشش نمیدهد.
محدودیت منطقی این چیدمان: مانیتوری که روی همان VPS اجرا میشود نمیتواند از کار افتادن خودِ آن VPS را به شما اطلاع دهد و ntfy نیز نمیتواند خبر از کار افتادن سرویس ntfy را ارسال کند. مانیتور را روی یک ماشین دیگر اجرا کنید و برای مانیتوری که خودِ ntfy را پایش میکند، یک کانال اعلان دوم مانند ایمیل در نظر بگیرید. نوع مانیتور Push در Uptime Kuma نقطه کور دیگر را پوشش میدهد: کرونجاب (cron job) شما پس از اجرای موفقیتآمیز، یک URL از نوع push را فراخوانی میکند و Kuma زمانی که این فراخوانیها متوقف شوند، هشدار میدهد. شاخه خطا (failure branch) فقط زمانی فعال میشود که جاب اجرا شده باشد، بنابراین در مورد جابی که هرگز شروع نشده است، هیچ هشداری صادر نمیکند.
آیا ntfy خودمیزبان (self-hosted) روی Android و iPhone کار میکند؟
در Android، بله، بدون هیچ قید و شرطی. برنامه را از Google Play یا F-Droid نصب کنید، تنظیمات را باز کنید، سرور پیشفرض را روی https://ntfy.example.com تنظیم کنید، حساب خود را در صفحه مدیریت کاربر اضافه کنید و سپس در alerts مشترک شوید. تحویل فوری (Instant delivery) یک سرویس پیشزمینه را فعال نگه میدارد تا پیامها حتی در حالت doze گوشی نیز دریافت شوند؛ اعلان دائمی که همراه آن نمایش داده میشود، الزام سیستمعامل Android برای سرویسهای پیشزمینه است و نه یک باگ. نسخه F-Droid هیچ کدی از Firebase ندارد، بنابراین تمام اشتراکها از تحویل فوری استفاده میکنند. ntfy همچنین میتواند به عنوان یک توزیعکننده UnifiedPush عمل کند که جایگزینی متنباز برای سرویس push گوگل است، بنابراین سایر برنامههایی که از UnifiedPush پشتیبانی میکنند نیز میتوانند از طریق سرور شما پیام ارسال کنند.
در برنامه رسمی iOS، این کار با یک وابستگی که نمیتوانید آن را حذف کنید انجام میشود. سیستمعامل iOS برنامههایی که در پسزمینه هستند را معلق میکند و حالتهای پسزمینهای که Apple اجازه میدهد (مانند پخش صدا، دریافت بهروزرسانیهای موقعیت مکانی، یا پردازش وظایف زمانبندیشده) به برنامه اجازه نمیدهد منتظر پیام از سرور شما بماند. بنابراین، بیدار شدن سریع برنامه باید از طریق APNs (سرویس اعلان push اپل) انجام شود. فقط ارائهدهندهای که اعتبارنامه مجاز برای برنامه را دارد میتواند به آن پیام ارسال کند، بنابراین سرور شما راهی برای دسترسی مستقیم به برنامه رسمی ندارد. ntfy این مشکل را با یک relay حل میکند: سرور شما یک poll_request حاوی شناسه پیام را به ntfy.sh میفرستد، که آن را از طریق Firebase و APNs برای بیدار کردن برنامه ارسال میکند و سپس برنامه، بدنه پیام را از سرور شما دریافت میکند.
upstream-base-url: "https://ntfy.sh"در مورد هزینههای این کار شفاف باشید. محتوای پیام روی سرور شما باقی میماند، اما این واقعیت که پیامی دریافت شده است و شناسه آن، از زیرساختی عبور میکند که شما آن را مدیریت نمیکنید. بدون این تنظیم، اعلانها در iPhone از یک سرور خودمیزبان در نهایت دریافت میشوند، اما مستندات ntfy هشدار میدهند که تأخیر ممکن است به چند ساعت برسد، زیرا هیچ چیزی برنامه را به سرعت بیدار نمیکند. برای استفاده از برنامه بومی iOS بدون relay مربوط به ntfy.sh، باید برنامه را خودتان با حساب توسعهدهنده Apple و کلیدهای APNs خودتان build و منتشر کنید که به معنای پرداخت هزینه سالانه و build مجدد برای هر بهروزرسانی است. راه دیگر، استفاده از PWA مربوط به ntfy در iOS 16.4 یا بالاتر است: آن را به صفحه اصلی (home screen) اضافه کنید و Web Push را روی سرور خود پیکربندی کنید. این کار از relay مربوط به ntfy.sh جلوگیری میکند، اما همچنان از زیرساخت push مرورگر استفاده میکند. اگر استفاده از relay برای شما قابل قبول نیست، هشدارها را روی Android یا برنامه وب دسکتاپ نگه دارید.
بکآپ، ارتقا و پین کردن ایمیج
دو مسیر قابل بازسازی نیستند: /etc/ntfy/server.yml و /var/lib/ntfy/user.db. دومی شامل تمام کاربران، هش رمز عبور، ورودی ACL و توکن است، بنابراین با آن مانند یک کلید خصوصی رفتار کنید.
sudo tar czf ntfy-backup.tgz -C / etc/ntfy var/lib/ntfy
sudo chmod 600 ntfy-backup.tgzآن فایل را از سرور کپی کنید. cache.db پیامهای اخیر را نگه میدارد، 12 ساعت از آنها با cache-duration در بالا، بهعلاوه هر پیامی که برای تحویل در آینده زمانبندی شده است، که تا 12 ساعت پس از تحویل باقی میماند. مگر اینکه پیامها را از قبل زمانبندی کنید، از دست دادن آن هزینه محافظتکردنی ندارد. ارتقا به معنای ویرایش تگ در فایل compose، pull کردن ایمیج و بازسازی کانتینر است.
sudo docker compose pull
sudo docker compose up -d
curl -s https://ntfy.example.com/v1/healthابتدا یادداشتهای انتشار را بخوانید. دیتابیسهای SQLite هنگام شروع مهاجرت میکنند، بنابراین بازگشت به یک تگ قدیمیتر پس از تغییر طرحواره (schema) ایمن نیست. برای مثال، v2.31.1 کش پیام را به نسخه طرحواره 17 منتقل کرد و یادداشتهای ارتقای آن میگوید که دانگرید به v2.31.0 یا قدیمیتر نیاز دارد که آن نسخه بهصورت دستی به 16 برگردانده شود. ارتقا به v2.36.0 شمارشهای روزانه موجود همه را یک بار بازنشانی میکند. بکآپی را که گرفتید تا زمانی که نسخه جدید یک روز اجرا شود، نگه دارید. یادداشتها همچنین تغییرات رفتاری را علامتگذاری میکنند. از v2.31.0 به بعد، کلاینتی که با since=<message ID> دوباره متصل میشود، پیامهای منتشرشده در همان ثانیه را نیز دریافت میکند، بنابراین ممکن است یک نسخه تکراری ببیند. برنامههای ntfy و برنامه وب، موارد تکراری را بر اساس شناسه پیام حذف میکنند، اما اسکریپت شخصی شما که یک topic را دوباره پخش میکند، باید همین کار را انجام دهد. هر سرویس روی سرور لیست کوتاه مخصوص به خود از مسیرهایی را دارد که قابل بازسازی نیستند و مقایسه PhotoPrism و Immich آن لیست و دستورات بکآپ مربوط به آن را برای یک کتابخانه عکس روی همان نوع VPS بررسی میکند.
Gotify و Apprise
Gotify گزینه سبکتری است: یک فایل اجرایی واحد با رابط کاربری وب و یک اپلیکیشن اندروید که پیامها را بر اساس اپلیکیشن دستهبندی میکند؛ این ویژگی برای سرورهای شخصی که تنها مقصد آنها اندروید است، مناسب میباشد. Apprise یک کتابخانه پایتون و ابزار خط فرمان است که یک سرور API مجزا نیز برای آن در دسترس است. این ابزار یک پیام واحد را به بیش از صد سرویس مختلف از جمله ntfy ارسال میکند و برای اسکریپتهایی که باید همزمان به چندین مقصد اطلاعرسانی کنند، مناسب است. ntfy سرویسی است که سرور، HTTP API و اپلیکیشنهایی برای هر دو پلتفرم موبایل ارائه میدهد؛ به همین دلیل، این ابزار معمولاً بهترین پاسخ برای ارسال هشدار از یک سرور اجارهای است.
FAQ
چرا انتشار پیام در سرور ntfy من با خطای 403 مواجه میشود؟
با تنظیم auth-default-access: "deny-all" در server.yml، انتشار ناشناس رد میشود و این رفتار مورد انتظار است. اعتبارنامهها را با -u user:pass یا -H "Authorization: Bearer tk_..." ارسال کنید. اگر در حال حاضر توکن ارسال میکنید و همچنان 403 دریافت میکنید، بررسی کنید که آیا کاربر آن دارای ورودی ACL برای اجازه نوشتن در آن موضوع (topic) هست یا خیر: در صورت نبود ورودی منطبق، read-only یا deny انتشار را رد میکند. در نسخه v2.34.0، درخواستهای همزمان از یک IP واحد ممکن بود باعث شود اعتبارنامههای معتبر به عنوان ناشناس تلقی شوند؛ نسخه v2.35.0 این باگ را برطرف کرده است، بنابراین پیش از آنکه یک 403 مقطعی را نشانه مشکل ACL بدانید، به نسخه جدیدتر ارتقا دهید. دستور ntfy access را اجرا کنید تا لیست کامل را چاپ کنید. به یاد داشته باشید که مجوز write اجازه اشتراک (subscribe) را نمیدهد، بنابراین حسابی که به درستی منتشر میکند، هنگام تلاش برای خواندن همان موضوع همچنان با رد دسترسی مواجه خواهد شد.
آیا اعلانها در آیفون با سرور ntfy شخصیسازیشده (self-hosted) کار میکنند؟
هنگامی که از اپلیکیشن رسمی iOS استفاده میکنید، اعلانها از طریق یک رله (relay) کار میکنند. بیدار شدن سریع اپلیکیشن معلق در آیفون باید از طریق APNs (سرویس اعلان اپل) انجام شود و ارسال به اپلیکیشن رسمی نیازمند اعتبارنامههای push ناشر آن است، بنابراین ntfy یک poll_request حاوی شناسه پیام را به ntfy.sh ارسال میکند که آن را به دستگاه رله میکند. مقدار upstream-base-url: "https://ntfy.sh" را در server.yml تنظیم کرده و کانتینر را ریاستارت کنید. بدنه اصلی پیام همچنان از سرور شما دریافت میشود. بدون این تنظیم، اعلانهای iOS در نهایت میرسند، اما مستندات ntfy هشدار میدهند که تأخیر ممکن است به چند ساعت برسد. PWA در iOS 16.4 یا نسخههای بالاتر، زمانی که Web Push روی سرور شما پیکربندی شده باشد، مسیر دیگری را ارائه میدهد.
چرا هشدار ntfy مربوط به cron job من هرگز نرسید؟
ابتدا خط دستور curl را به تنهایی اجرا کنید تا صحت توکن و موضوع (topic) ثابت شود. اگر به صورت دستی کار میکند اما در cron خیر، شکست در بالادست هشدار رخ داده است: cron کارها را با محیطی حداقلی و یک PATH کوتاه اجرا میکند، بنابراین اسکریپتی که دستوری را با نام ساده فراخوانی میکند ممکن است پیش از رسیدن به خط curl متوقف شود. از مسیرهای مطلق (absolute paths) استفاده کنید، خروجی کار را به یک فایل لاگ هدایت کنید و پس از اجرای بعدی، آن فایل را بخوانید. پاسخ 429 به جای تحویل پیام، به این معنی است که یک محدودیت درخواست را رد کرده است. معمولاً اسکریپت خیلی سریع در حال تلاش مجدد است، اما کاربری که سهمیه روزانه خود را تمام کرده است، مانند محدودیت پیام تعیینشده در بالا، حتی در یک درخواست واحد نیز با همین خطا مواجه میشود.
آیا باید ntfy را در اینترنت عمومی قرار دهم؟
اپلیکیشنهای موبایل باید از طریق شبکههای تلفن همراه به آن دسترسی داشته باشند، بنابراین یک نقطه پایانی HTTPS عمومی با auth-default-access: "deny-all" و ACLهای مخصوص هر موضوع، پیکربندی استاندارد است و تا زمانی که هیچ موضوعی برای everyone قابل خواندن نباشد، امن است. یک نمونه (instance) فقط در VPN زمانی منطقی است که هر مشترک، ماشینی باشد که شما کنترل میکنید. این روش برای گوشیها مناسب نیست، زیرا اپلیکیشن فقط زمانی پیام دریافت میکند که تونل برقرار باشد، بنابراین هشدارها تا زمان اتصال مجدد گوشی در صف باقی میمانند.