یک ربات آرشیو موسیقی برای پیام‌رسان بله، نوشته‌شده با زبان Go و بدون هیچ وابستگی خارجی. کاربران آهنگ‌ها را برای ربات فوروارد می‌کنند؛ ربات آن‌ها را در یک کانال آرشیو ذخیره و ایندکس می‌کند و هر کسی می‌تواند با جستجوی متنی، آهنگ مورد نظرش را پیدا و دریافت کند.
این پروژه در دوره‌ی قطعی‌های گسترده اینترنت (از اواسط بهمن ۱۴۰۴ تا اواخر اسفند ۱۴۰۴) و به‌عنوان راهکاری کوچک برای یک مشکل واقعی ساخته شد: وقتی سرویس‌های پخش آنلاین در دسترس نیستند، پیدا کردن و به‌اشتراک‌گذاشتن موسیقی سخت می‌شود. ایده ساده بود — یک آرشیو مشارکتی که خود کاربران با فوروارد کردن آهنگ‌هایشان پرش می‌کنند و جستجو در آن برای همه آزاد است.
توسعه‌ی پروژه به‌کمک ابزارهای هوش مصنوعی و مطالعه و یادگیری شخصی انجام شد و در همان مدت کوتاه مخاطب جذب کرد؛ پیک مصرف آن به حدود ۱۲۰۰ کاربر فعال ماهانه رسید.
توسعه‌ی کد از اواسط بهمن ۱۴۰۴ آغاز شد، اما پروژه عملاً از ۲۸ اسفند ۱۴۰۴ (مارس ۲۰۲۶) وارد گیت شد و سابقه‌ی قبل از آن تاریخ در این مخزن ثبت نشده است. کامیت‌های اولیه‌ی مخزن، بازسازیِ تاریخ‌چه بر اساس تاریخ فایل‌هاست و به دقتِ زمانیِ روزهای اول نباید اتکا کرد. علاوه بر این، بخش‌هایی از تاریخ‌چه در جابه‌جایی بین سیستم‌ها دچار دست‌کاری تاریخ فایل‌ها شده و ساختار کامیت‌ها بازسازی‌شده است، نه ثبت لحظه‌ای.
- آرشیو با فوروارد (Bulk): هر فایل صوتی که در حالت عادی برای ربات فوروارد شود، به‌صورت خودکار استخراج متادیتا می‌شود، از تکراری بودن بررسی می‌شود و در کانال آرشیو منتشر و ایندکس می‌گردد.
- جستجو با کیبورد شیشه‌ای: دستور
/findعبارت را می‌گیرد و نتایج را با کیبورد این‌لاین و صفحه‌بندی (دکمه‌های قبلی/بعدی) نمایش می‌دهد. - جستجوی متنی ساده: دستور
/azaنتایج را مستقیم و به‌صورت رگباری فوروارد می‌کند (با محدودیت نرخ ارسال برای جلوگیری از بن شدن). - لیست هنرمندان:
/artistsفهرست هنرمندان را به‌ترتیب الفبا و با صفحه‌بندی نشان می‌دهد. - استانداردسازی نام هنرمند: یک دیتابیس نام‌مستعار، املاهای مختلف (فارسی/عربی/انگلیسی، فاصله، خط تیره و ...) را به یک نام استاندارد نگاشت می‌کند تا نتایج جستجو از دست نروند.
- شنونده‌ی ساکت گروه‌ها: ربات در گروه‌ها هیچ پیامی نمی‌فرستد و به‌صورت بی‌صدا هر فایل mp3 ارسال‌شده را آرشیو می‌کند؛ آمار گروه‌ها و اعضا نیز ثبت می‌شود.
- ثبت دستی:
/sendیک فلوی چندمرحله‌ای (فایل، نام خواننده، نام آهنگ) برای ثبت دقیق آهنگ است. - پنل مدیریت: بیش از بیست دستور ادمین برای آمارگیری، پاک‌سازی، ارسال گروهی، بررسی لاگ‌ها و مدیریت دیتابیس.
- لاگ چرخشی: لاگر داخلی رویدادها را به تفکیک سیستم/کاربر/گروه در فایل‌های چرخشی (به‌صورت خودکار برش خورده) می‌نویسد.
ربات هیچ وابستگی خارجی ندارد و فقط از کتابخانه استاندارد Go استفاده می‌کند:
- Long Polling روی
getUpdatesبله؛ هر update در یک goroutine پردازش می‌شود. - دیتابیس فایل‌محور JSON با ایندکس درون‌حافظه‌ای و قفل خواندن/نوشتن (
sync.RWMutex): موزیک‌ها، کاربران، گروه‌ها، اعضای گروه و هنرمندان. - مدیریت وضعیت (Session) برای فلوی چندمرحله‌ای ثبت دستی، به‌ازای هر chat.
- استخراج متادیتا از نام فایل/تگ‌های صوتی و نرمال‌سازی کلید جستجو (یکسان‌سازی «ي/ی»، «ك/ک» و حذف علائم).
جزئیات کامل معماری در docs/ARCHITECTURE.md آمده است.
پیش‌نیاز: Go 1.25 یا جدیدتر.
git clone https://github.com/AliGhanizade/ArchivBot.git
cd ArchivBot
go build -o archivbot .سپس فایل config.example.json را با نام config.json کپی کنید و مقادیر خود را جایگزین کنید:
{
"bot_token": "توکن ربات شما از @BotFather بله",
"channel_id": 123456789,
"admin_ids": [123456789],
"db": { "musics": "./data/musics.json", "users": "./data/users.json", "artists": "./data/artists.json", "groups": "./data/group.json", "group_users": "./data/groupUser.json" },
"logs": { "system": "./logs/system/s_log", "user": "./logs/user/u_log", "group": "./logs/group/g_log" }
}نکات مهم:
- مسیر فایل کانفیگ را می‌توانید با متغیر محیطی
ARCHIVBOT_CONFIGتغییر دهید. - توکن را می‌توانید به‌جای فایل، از متغیر محیطی
ARCHIVBOT_BOT_TOKENبدهید؛ این مقدار بر فایل کانفیگ اولویت دارد. - توکن را هرگز در سورس یا در مخزن کامیت نکنید. فایل
config.jsonدر.gitignoreقرار دارد. - پوشه‌های
data/وlogs/در اولین اجرا به‌صورت خودکار ساخته می‌شوند و محتوای آن‌ها (شامل اطلاعات خصوصی کاربران) هرگز نباید منتشر شود.
اجرای ربات مهاجرت‌کننده‌ی داده‌ها (برای بازسازی کلیدهای جستجو) به‌صورت دستی و کامنت‌شده در main.go موجود است.
| دستور | توضیح |
|---|---|
/start |
پیام خوش‌آمدگویی و معرفی |
/help |
راهنمای کامل استفاده |
/find |
جستجو با کیبورد این‌لاین و صفحه‌بندی |
/aza |
جستجوی متنی ساده با ارسال مستقیم نتایج |
/artists |
فهرست هنرمندان به‌ترتیب الفبا |
/send |
ثبت دستی آهنگ (فایل، خواننده، عنوان) |
/cancel |
لغو عملیات جاری و بازگشت به منو |
فوروارد هر فایل صوتی در چت خصوصی نیز بدون هیچ دستوری، آن را آرشیو می‌کند.
/ping، /stats، /statsys (آمار کلی و سیستم)، /cleanup و /clearcache (نگهداری)، /toall (ارسال گروهی)، /users، /topusers، /userinfo (آمار کاربران)، /groups، /topgroups، /groupinfo، /groupusers (آمار گروه‌ها)، /log-sys، /log-user، /log-group (دریافت فایل لاگ)، /getid (شناسه‌ی چت).
ArchivBot/
├── main.go # نقطه ورود: لاگر، کلاینت، دیتابیس‌ها، حلقه Long Polling
├── config/ # بارگذاری تنظیمات از config.json
├── api/ # کلاینت HTTP برای API ربات بله + مدل‌ها
├── router/ # مسیریابی updateها به هندلر مناسب
├── bot/ # هندلرها: جستجو، آرشیو، گروه‌ها، ادمین، کیبوردها، sessionها
├── database/ # دیتابیس‌های فایل‌محور JSON + مهاجرت داده
├── pkg/log/ # لاگر چرخشی رنگی
├── pkg/utils/ # استخراج متادیتا و ابزارهای کمکی
├── docs/ # مستندات معماری
├── config.example.json # نمونه فایل کانفیگ
└── LICENSE # لایسنس MIT
| نسخه | تاریخ | خلاصه |
|---|---|---|
| v1.0.0 | فروردین ۱۴۰۵ | اولین نسخه کارکردی: آرشیو با فوروارد، جستجوی /find، ذخیره‌سازی JSON |
| v1.1.0 | فروردین ۱۴۰۵ | جستجوی کیبوردی با صفحه‌بندی، استانداردسازی هنرمندان، پنل ادمین |
| v1.2.0 | فروردین ۱۴۰۵ | بهبود پایداری، مدیریت خطاهای API و نرخ ارسال |
| v1.3.0 | شهریور ۱۴۰۵ | انتقال تنظیمات به config.json، بهداشت مخزن و مستندات |
این مخزن عمداً شامل هیچ داده‌ی اجرایی نیست: فایل‌های data/ (لیست موزیک‌ها، کاربران، گروه‌ها) و logs/ حاوی اطلاعات خصوصی کاربران ربات هستند و در .gitignore قرار دارند. هر کسی که ربات را self-host می‌کند، مسئولیت داده‌های کاربران خودش را دارد.
این پروژه تحت لایسنس MIT منتشر شده است.