Import documentation: README.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
2026-09-18 23:14:30 +03:30
parent 8fb79c6443
commit b26f899e91
1 changed files with 148 additions and 0 deletions
@@ -0,0 +1,148 @@
+# Coaxys Telegram to S3 Uploader
+
+ربات تلگرام برای دریافت فایل یا لینک مستقیم، آپلود سریع روی S3 با `rclone`، و تحویل لینک دانلود امضاشده با اعتبار ۱۶۸ ساعت.
+
+## قابلیت‌ها
+
+- دریافت فایل، ویدیو، عکس، صدا، استیکر و لینک مستقیم از تلگرام
+- دانلود فایل از تلگرام یا URL و قرار دادن در صف پردازش
+- آپلود روی bucket `coaxys` با `rclone copyto`
+- استفاده از تنظیمات پرسرعت rclone مثل multipart concurrency، chunk size، transfers و checkers
+- گزارش مرحله‌ای در تلگرام: دانلود، صف، آپلود، بررسی S3، ساخت لینک و خطا
+- ساخت لینک دانلود ۱۶۸ ساعته با `rclone link --expire 168h`
+- لغو یا حذف یک فایل با `/del <job_id>`
+- پاکسازی صف با `/delall`
+- نمایش وضعیت صف و پردازش با `/status`
+- Safe Mode برای ZIP رمزدار قبل از آپلود
+
+## ساختار پروژه
+
+```text
+main.py      اجرای همزمان worker تلگرام و worker آپلود
+telebot.py   دریافت پیام‌ها، دانلود فایل از تلگرام، مدیریت صف و پیام‌های ربات
+rub.py       worker آپلود S3 با rclone، بررسی فایل و ساخت لینک دانلود
+queue/       فایل‌های runtime صف و وضعیت
+downloads/   فایل‌های موقت دانلودشده
+bot.log      لاگ اجرای nohup
+```
+
+## پیش‌نیازها
+
+```bash
+sudo apt update
+sudo apt install python3 python3-venv python3-pip rclone -y
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+remote زیر باید در rclone تنظیم شده باشد:
+
+```text
+coaxys
+```
+
+تست دسترسی S3:
+
+```bash
+rclone ls coaxys:coaxys --s3-no-check-bucket
+```
+
+## تنظیمات
+
+فایل `.env` را در ریشه پروژه بسازید:
+
+```env
+API_ID=your_telegram_api_id
+API_HASH=your_telegram_api_hash
+BOT_TOKEN=your_bot_token
+```
+
+تنظیمات اختیاری:
+
+```env
+RCLONE_REMOTE=coaxys:coaxys
+RCLONE_PREFIX=
+RCLONE_TRANSFERS=8
+RCLONE_CHECKERS=16
+RCLONE_S3_UPLOAD_CONCURRENCY=8
+RCLONE_S3_CHUNK_SIZE=32M
+RCLONE_S3_UPLOAD_CUTOFF=16M
+RCLONE_MULTI_THREAD_STREAMS=8
+RCLONE_RETRIES=3
+RCLONE_LOW_LEVEL_RETRIES=20
+RCLONE_NO_OUTPUT_TIMEOUT=180
+RCLONE_COMMIT_TIMEOUT=90
+MAX_RETRIES=5
+UPLOAD_TIMEOUT=0
+DOWNLOAD_LINK_EXPIRE=168h
+```
+
+اگر `RCLONE_PREFIX` خالی باشد، فایل‌ها در root bucket آپلود می‌شوند. برای آپلود داخل پوشه، مثلا `uploads` قرار دهید.
+
+## اجرا
+
+اجرای معمولی:
+
+```bash
+python3 main.py
+```
+
+اجرای دائمی با nohup:
+
+```bash
+pkill -f python3
+setsid nohup python3 -u main.py > bot.log 2>&1 < /dev/null &
+echo $! > bot.pid
+```
+
+مشاهده لاگ:
+
+```bash
+tail -f bot.log
+```
+
+بررسی پردازش‌ها:
+
+```bash
+ps -eo pid,ppid,stat,cmd | grep -E 'python3 -u main.py|telebot.py|rub.py'
+```
+
+## دستورات ربات
+
+```text
+/start
+/status
+/del <job_id>
+/delall
+/safemode on
+/safemode off
+```
+
+## خروجی نهایی
+
+بعد از آپلود موفق، ربات پیام نهایی شامل نام فایل، حجم، مسیر ذخیره‌سازی و لینک دانلود می‌دهد. لینک با `rclone link --expire 168h` ساخته می‌شود و معمولا فرم زیر دارد:
+
+```text
+https://s3.ir-thr-at1.arvanstorage.ir/coaxys/file.ext?...&X-Amz-Expires=604800&...
+```
+
+## نکات عملیاتی
+
+- `queue/` و `downloads/` runtime هستند و نباید commit شوند.
+- اگر آپلود به ۱۰۰٪ رسید ولی پیام نهایی دیر آمد، worker تا حدود ۶۰ ثانیه منتظر visible شدن فایل در `rclone ls` می‌ماند.
+- برای بررسی دستی فایل‌ها:
+
+```bash
+rclone ls coaxys:coaxys --s3-no-check-bucket
+```
+
+- برای ساخت لینک دستی:
+
+```bash
+rclone link --expire 168h coaxys:coaxys/path/to/file.ext --s3-no-check-bucket
+```
+
+## امنیت
+
+`.env`، rclone config، فایل‌های دانلودشده، queue state و ZIPهای تولیدشده را منتشر نکنید. توکن ربات، Telegram API credentials و کلیدهای S3 محرمانه هستند.