15 KiB
راهنمای جامع پیادهسازی و تست سیستم انتشار خودکار پادکست (RSS Distribution & Import)
این مستند یک نقشه راه عملیاتی از صفر تا صد است تا بدون وابستگی به اکانتهای کارفرما، بتوانیم کل چرخه تولید فید RSS در بکاند، ایمپورت از RSS خارجی و انتشار خودکار روی پلتفرمهای پادکست (Castbox، Spotify، Apple Podcasts و Mave) را با اکانتهای تستی خودمان پیادهسازی و آزمایش کنیم.
۱. معماری کلی سیستم چگونه کار میکند؟
در اکوسیستم جهانی پادکست، پلتفرمهای شنیدن پادکست فایل صوتی را از شما دریافت (Push) نمیکنند، بلکه از طریق یک لینک استاندارد XML (RSS 2.0 + iTunes Tags) که سرور شما تولید میکند، اپیزودها را میخوانند (Pull).
sequenceDiagram
autonumber
participant Admin as "پنل ریاکت (ادمین)"
participant Backend as "بکاند جنگو (Dovoodi)"
participant RSS as "اندپوینت RSS (/api/podcast/rss.xml)"
participant Platforms as "پلتفرمها (Castbox / Apple / Spotify)"
Admin->>Backend: آپلود اپیزود جدید (MP3 + کاور + عنوان + توضیحات)
Backend->>Backend: ذخیره در جدول Podcast و محاسبه زمان (audio_time)
Platforms->>RSS: درخواست دورهای (Polling) برای بررسی اپیزودهای جدید
RSS->>Backend: خواندن لیست اپیزودهای فعال از دیتابیس
RSS-->>Platforms: برگرداندن XML استاندارد با تگهای <item> و <enclosure>
Platforms->>Platforms: انتشار خودکار اپیزود جدید در اپلیکیشنها
۲. پیشنیازهای فنی برای اینکه پلتفرمها فید ما را قبول کنند
پلتفرمهای پادکست (مخصوصاً Apple Podcasts و Castbox) قبل از تایید لینک RSS شما، چند قانون فنی را اعتبارسنجی (Validate) میکنند:
[!IMPORTANT] الزامات اجباری فید RSS استاندارد پادکست:
- پشتیبانی از HTTPS و Byte-Range: لینک فید RSS، لینک عکس کاور و لینک فایلهای صوتی
.mp3حتماً باید رویhttps://باشند و سرور وب (Nginx) باید هدرAccept-Ranges: bytesرا روی فایلهای صوتی برگرداند (که Nginx بهصورت پیشفرض روی فایلهای استاتیک/مدیا پشتیبانی میکند).- ابعاد تصویر کاور کانال (
<itunes:image>): تصویر کاور اصلی پادکست باید مربع (1:1) و حداقل1400x1400پیکسل و حداکثر3000x3000پیکسل (فرمت JPG یا PNG با رنگ RGB) باشد.- وجود حداقل ۱ اپیزود منتشرشده: فید RSS بدون تگ
<item>(اپیزود) توسط پلتفرمها تایید نمیشود؛ پس قبل از ثبت لینک در پلتفرمها باید حداقل ۱ اپیزود تستی در پنل ساخته باشیم.- تگ
<itunes:owner>معتبر: داخل فید باید یک تگ<itunes:email>وجود داشته باشد که به آن ایمیل دسترسی داشته باشید، چون پلتفرمهایی مثل Castbox و Spotify کد تایید مالکیت (OTP) را به همان ایمیل داخل فید میفرستند!
۳. پیادهسازی در کد پروژه (بکاند و پنل ریاکت)
بخش الف: تغییرات بکاند جنگو (dovoodi/backend)
۱. مدل تنظیمات کانال پادکست (PodcastChannelSettings یا فیلدهای تکمیلی در PodcastPlaylist)
در فایل apps/podcast/models.py یک مدل Singleton (یا سطح پلیلیست) برای نگهداری متادیتای کلی فید RSS تعریف میکنیم:
title: نام کانال پادکست (مثلاًПро ислам)description: توضیحات کانالauthor: نام گوینده/نویسنده (<itunes:author>)owner_nameوowner_email: نام و ایمیل مالک برای تایید مالکیت در پلتفرمها (<itunes:owner>)language: کد زبان (مثلاًruیاen)categoryوsubcategory: دستهبندی استاندارد اپل (مثلاًReligion & Spirituality->Islam)copyright: متن کپیرایتcover_image: تصویر کاور اصلی کانال (۱۴۰۰×۱۴۰۰)explicit: بولین (false)source_rss_url: لینک RSS خارجی جهت ایمپورت/سینک (مثلاًhttps://cloud.mave.digital/34205)
همچنین در مدل Podcast:
- افزودن فیلد اختیاری
external_guid = models.CharField(max_length=255, null=True, blank=True, unique=True)تا هنگام ایمپورت از RSS خارجی، از ساخت اپیزود تکراری جلوگیری شود و شناسه<guid>هر اپیزود ثابت بماند. - افزودن فیلدهای اختیاری
episode_numberوseason_number.
۲. ساخت اندپوینت خروجی RSS XML در apps/podcast/views.py و apps/podcast/urls.py
ایجاد یک View عمومی (بدون نیاز به توکن لاگین، چون سرورهای Apple و Castbox باید بتوانند آن را بخوانند) در مسیر:
/api/podcast/rss.xml(فید سراسری پادکستها)/api/podcast/playlists/<slug>/rss.xml(فید اختصاصی هر پلیلیست)
این View هدر Content-Type: application/rss+xml; charset=utf-8 برمیگرداند و ساختار زیر را تولید میکند:
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:content="http://purl.org/rss/1.0/modules/content/"
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd">
<channel>
<title><![CDATA[عنوان کانال]]></title>
<description><![CDATA[توضیحات کانال]]></description>
<link>https://yourdomain.com</link>
<language>ru</language>
<itunes:type>episodic</itunes:type>
<itunes:explicit>false</itunes:explicit>
<itunes:author>نام نویسنده</itunes:author>
<itunes:owner>
<itunes:name>نام مالک</itunes:name>
<itunes:email>your-test-email@gmail.com</itunes:email>
</itunes:owner>
<itunes:image href="https://api.yourdomain.com/media/podcast/channel_cover.jpg"/>
<itunes:category text="Religion & Spirituality">
<itunes:category text="Islam"/>
</itunes:category>
<!-- تکرار برای هر اپیزود فعال در جدول Podcast -->
<item>
<title><![CDATA[عنوان اپیزود]]></title>
<description><![CDATA[توضیحات اپیزود]]></description>
<guid isPermaLink="false">podcast-uuid-or-id</guid>
<pubDate>Thu, 23 Apr 2026 03:00:00 GMT</pubDate>
<enclosure url="https://api.yourdomain.com/media/podcast/audio/episode1.mp3"
length="48752533"
type="audio/mpeg"/>
<itunes:duration>3037</itunes:duration>
<itunes:image href="https://api.yourdomain.com/media/podcast_thumbnails/ep1.png"/>
<itunes:explicit>false</itunes:explicit>
<itunes:episodeType>full</itunes:episodeType>
</item>
</channel>
</rss>
۳. ساخت سرویس و اندپوینت Import از RSS خارجی (/api/podcast/admin/import-rss/)
- دریافت آدرس فید (مثلاً
https://cloud.mave.digital/34205) یا فایل XML. - پارس کردن تگ
<channel>و تمام تگهای<item>باxml.etree.ElementTree. - بررسی
guidهر آیتم؛ اگر قبلاً در جدولPodcastوجود نداشت:- دانلود تصویر
<itunes:image>و فایل صوتی<enclosure url="..."> - تبدیل
<itunes:duration>(ثانیه) بهdatetime.timeبرای فیلدaudio_time - ذخیره اپیزود در دیتابیس.
- دانلود تصویر
بخش ب: تغییرات پنل ریاکت (dovodi-panel/dashboard)
در بخش پادکستهای پنل (src/pages/Podcasts.tsx / src/components/archive/ArchiveSectionPage.tsx):
- کارت / مودال «RSS & Distribution Settings»:
- نمایش لینک RSS سایت ما همراه با دکمه Copy RSS URL و دکمه Preview XML.
- فرم ویرایش مشخصات فید کانال (
Channel Title،Author،Owner Emailبرای دریافت کد تایید پلتفرمها،Cover 1400x1400،Language،Category).
- مودال «Import from RSS Feed»:
- ورودی لینک RSS (یا آپلود فایل XML فید) + انتخاب پلیلیست مقصد.
- نمایش پیشنمایش تعداد اپیزودهای پیداشده در فید و شروع ایمپورت در پسزمینه.
۴. مراحل تست عملی توسط خودمان (با اکانتهای تستی رایگان)
برای اینکه بدون نیاز به کارفرما، کل فرآیند را خودمان تست کنیم، مراحل زیر را به ترتیب انجام میدهیم:
flowchart LR
A["۱. آمادهسازی لینک عمومی\n(سرور تست یا Cloudflare Tunnel)"] --> B["۲. ساخت ۱ اپیزود تستی در پنل\nو تنظیم ایمیل خودمان در Owner Email"]
B --> C["۳. تست اعتبارسنجی فید در\nCastFeedValidator / Podba.se"]
C --> D["۴. ثبت فید در Castbox و Spotify\nو دریافت کد تایید روی ایمیل"]
D --> E["۵. آپلود اپیزود دوم در پنل\nو مشاهده انتشار خودکار"]
گام ۱: قابل دسترس کردن بکاند روی اینترنت (اگر روی لوکال تست میکنید)
چون سرورهای Castbox و Spotify باید بتوانند لینک RSS و فایل MP3 شما را دانلود کنند، نمیتوانید آدرس http://127.0.0.1:8000 را به آنها بدهید.
- اگر روی سرور استیجینگ/پروداکشن هستید: از همان دامنه
https://...سرور استفاده کنید. - اگر روی سیستم لوکال خودتان تست میکنید: با یک دستور رایگان Cloudflare Tunnel یا ngrok یک لینک HTTPS عمومی بگیرید:
npx cloudflared tunnel --url http://127.0.0.1:8000این دستور یک آدرس مثل
https://random-name.trycloudflare.comبه شما میدهد که لینک فید شما میشود:https://random-name.trycloudflare.com/api/podcast/rss.xml
گام ۲: تنظیم ایمیل خودتان در فید و ساخت اپیزود تستی اول
- در تنظیمات RSS پنل، فیلد Owner Email را روی ایمیل شخصی خودتان (مثلاً جیمیل خودتان) بگذارید.
- یک تصویر مربع حداقل
1400x1400پیکسل برای کاور کانال انتخاب کنید. - در پنل ریاکت یک پادکست تستی با یک فایل
.mp3کوتاه آپلود و ذخیره کنید.
گام ۳: تست سلامت فید در ابزارهای Validator رایگان (قبل از ثبت در پلتفرمها)
قبل از اینکه سراغ ساخت اکانت در پلتفرمها بروید، لینک rss.xml خودتان را در یکی از این دو سایت رایگان تست کنید تا مطمئن شوید ۱۰۰٪ استاندارد است:
- Cast Feed Validator: https://www.castfeedvalidator.com
- Podbase Validator: https://podba.se/validate
[!TIP] اگر هر دو سایت تیک سبز دادند (کاور ۱۴۰۰×۱۴۰۰، تگهای iTunes و پشتیبانی از Byte-Range روی فایل MP3)، فید شما آماده اتصال به تمام پلتفرمهای دنیاست.
گام ۴: ثبت رایگان در پلتفرمها با اکانت تستی خودتان
۱. تست در Castbox (کاملاً رایگان و سریعترین برای تست - حدود ۵ دقیقه)
- وارد سایت Castbox Creator Studio شوید: https://castbox.fm/creator (با جیمیل خودتان ثبتنام کنید).
- از منوی بالا یا داشبورد روی Claim Ownership / Submit Podcast کلیک کنید.
- لینک RSS سایت خودمان (
https://.../api/podcast/rss.xml) را وارد کنید. - کستباکس ایمیل داخل تگ
<itunes:email>فید را میخواند و یک کد تایید به جیمیل شما میفرستد. - کد را وارد کنید؛ پادکست بلافاصله در Castbox ساخته میشود!
۲. تست در Spotify for Creators (Podcasters) (کاملاً رایگان - حدود ۵ تا ۱۰ دقیقه)
- وارد https://creators.spotify.com شوید و با یک اکانت رایگان Spotify لاگین کنید.
- گزینه I already have a podcast را بزنید و لینک RSS سایت خودمان را وارد کنید.
- اسپاتیفای یک کد ۸ رقمی به ایمیل داخل
<itunes:email>فید میفرستد. - کد را وارد کنید و Submit را بزنید؛ پادکست شما روی Spotify قرار میگیرد.
۳. تست در Mave (mave.digital) (برای تست ایمپورت و فید Mave)
- وارد https://app.mave.digital شوید و با ایمیل خودتان یک اکانت رایگان بسازید.
- گزینه Создать подкаст (Create Podcast) -> Импортировать (Import via RSS) را بزنید.
- لینک RSS سرور خودمان را بدهید تا ببینید چطور Mave اپیزودهای پنل ما را میخواند، یا برعکس لینک RSS تستی Mave را در پنل خودمان ایمپورت کنید.
۴. تست در Apple Podcasts Connect
[!NOTE] برخلاف Castbox و Spotify که کاملاً رایگان هستند، ثبت پادکست جدید در https://podcastsconnect.apple.com نیازمند داشتن یک Apple Account با روش پرداخت معتبر (یا اکانت توسعهدهنده اپل) است و بررسی اولیه آن توسط تیم اپل ۲۴ تا ۷۲ ساعت طول میکشد. بنابراین برای تست فنی خودمان، Castbox و Spotify بهترین و سریعترین گزینهها هستند و از دقیقاً همان استاندارد XML اپل استفاده میکنند.
گام ۵: تست انتشار خودکار اپیزود دوم
- حالا که فید را در Castbox یا Spotify ثبت کردید، دیگر وارد سایت آنها نشوید.
- فقط وارد پنل ریاکت خودمان شوید و اپیزود تستی شماره ۲ را آپلود کنید.
- لینک
/api/podcast/rss.xmlرا رفرش کنید تا ببینید اپیزود ۲ به بالای XML اضافه شده است. - پس از سینک دورهای پلتفرم، اپیزود ۲ بهصورت خودکار در Castbox و Spotify ظاهر میشود!