- PHP 85.9%
- CSS 12.1%
- Shell 2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- Added `import-worker.php` script to manage background import workers. - Introduced `start-workers.sh` and `stop-workers.sh` scripts for starting and stopping workers. - Created `RateLimiter` class to manage rate limiting for import operations. - Implemented `RuntimeLog` class for structured logging of method calls and responses. - Added SQL migration to include `lease_until` column in `import_job_items` table. - Enhanced `run.php` test suite to validate new logging and rate limiting features. - Created `searchmuti.php` and `searchsingle.php` scripts for testing contact searches with logging. - Updated `start-termux.sh` and `stop-termux.sh` scripts to integrate worker management. |
||
| app | ||
| config | ||
| database | ||
| public | ||
| samples | ||
| scripts | ||
| tests | ||
| var | ||
| .env.example | ||
| .gitignore | ||
| composer.json | ||
| composer.lock | ||
| README.md | ||
| searchmuti.php | ||
| searchsingle.php | ||
مدیر مخاطبان بله
یک برنامه شخصی PHP برای نگهداری و بررسی مخاطبان حساب بله. برنامه فقط از قابلیتهای موجود در بسته نصبشده aiobale/aiobale-php استفاده میکند: ورود با شماره/کد/رمز دومرحلهای، SearchContact برای جستوجوی مجاز، LoadUsers و LoadFullUsers برای اطلاعات پروفایل قابلدسترسی، و LoadAvatars بههمراه GetFileUrl برای تصویرهای قابلدسترسی. تصویرها پس از دریافت در حافظه خصوصی برنامه ذخیره میشوند؛ نشانیهای موقت بله نگهداری نمیشوند. شمارهها به دفترچه مخاطبان بله افزوده نمیشوند. این بسته ابزار رسمی بله نیست؛ استفاده از حساب شخصی و رعایت محدودیتهای سرویس بر عهده کاربر است.
نیازمندیها
- PHP 8.2 یا جدیدتر با افزونههای
PDO,pdo_mysql,json,mbstring,fileinfo - Composer
- MySQL یا MariaDB
- Apache با
mod_rewriteو PHP Apache
نصب در Termux
در ریشه پروژه:
chmod +x scripts/*.sh
./scripts/install-termux.sh
نصبکننده بستههای PHP، PHP-Apache، MariaDB و Composer را با pkg نصب میکند؛ Docker و systemd لازم نیست. سپس:
-
در
.envمقادیرDB_*و مسیر امنAPP_STORAGE_PATHرا تنظیم کنید. پوشهvar/باید خارج از DocumentRoot وب باشد و برای کاربر Apache قابلنوشتن بماند. مقدار پیشفرضvarدر ریشه پروژه است. -
سرویسها را اجرا کنید تا MariaDB برای نخستین بار مقداردهی شود:
./scripts/start-termux.shstart-termux.shدر نبود دیتادایرکتوری اولیه،mariadb-install-dbرا اجرا میکند. اگر قبلاً دیتادایرکتوری دارید، از حذف یا مقداردهی دوباره آن خودداری کنید. پس از شروع MariaDB، رمز قوی تعیین کنید و پایگاهداده را آماده کنید:mariadb -u root -pپایگاهداده را بسازید:
CREATE DATABASE bale_finder CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'bale_finder_app'@'127.0.0.1' IDENTIFIED BY 'یک-رمز-قوی'; GRANT ALL PRIVILEGES ON bale_finder.* TO 'bale_finder_app'@'127.0.0.1'; FLUSH PRIVILEGES;سپس با کاربر مدیریتی، اسکیما را وارد کنید:
./scripts/init-db.shاسکریپت اسکیما از شما رمز root میخواهد. دسترسی برنامه را با همان کاربر مدیریت نکنید؛ یک کاربر محدود به پایگاهداده
bale_finderبسازید و مقادیر اتصال را در.envوارد کنید. اگر پایگاهداده از نسخهای استفاده میکند که قبلاً اسکیما داشته، مهاجرت ورود محلی را یکبار اجرا کنید:mariadb -u bale_finder_app -p bale_finder < database/migrations/001_local_app_login.sqlبرای پایگاهدادهای که قبلاً ساخته شده، مهاجرت lease پردازش موازی را هم اجرا کنید:
mariadb -u bale_finder_app -p bale_finder < database/migrations/002_import_worker_leases.sql -
فایل
config/apache-vhost.conf.exampleرا با مسیر واقعی پروژه تطبیق دهید و آن را در تنظیمات Apache بارگذاری کنید. اگرListen 8080یا بارگذاری PHP/rewrite از قبل درhttpd.confوجود دارد، از اضافهکردن دوباره آنها خودداری کنید. مسیر DocumentRoot حتماً باید بهpublic/ختم شود. -
مطمئن شوید
php-apacheوmod_rewriteفعالاند؛ همچنین محدودیتهایupload_max_filesizeوpost_max_sizeدر تنظیمات PHP باUPLOAD_MAX_BYTESهماهنگ باشند. -
اگر نصب Apache یا تنظیمات آن را تغییر دادهاید، تنظیمات را بارگذاری مجدد کنید:
apachectl restartاین اسکریپت علاوه بر MariaDB و Apache، پردازشگرهای واردسازی را هم در پسزمینه اجرا میکند. سپس
http://127.0.0.1:8080را در مرورگر باز کنید. برای توقف:./scripts/stop-termux.sh
start-termux.sh از mysqld_safe و apachectl استفاده میکند و سرویسها را با ابزارهای خود Termux اجرا میکند. پردازشگرهای واردسازی PHP CLI هستند و مستقل از صفحه مرورگر کار میکنند؛ در اندروید ممکن است برای ادامه کار پسزمینه لازم باشد Termux را از بهینهسازی باتری خارج کنید.
پیکربندی
فایل .env.example را به .env کپی کنید. فایل .env در ریشه پروژه است و بهعلت DocumentRoot محدودشده به public/ از وب قابلدسترسی نیست. نمونه:
APP_ENV=production
APP_TIMEZONE=Asia/Tehran
APP_STORAGE_PATH=var
SESSION_NAME=bale_finder
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=bale_finder
DB_USERNAME=bale_finder_app
DB_PASSWORD=یک-رمز-قوی
UPLOAD_MAX_BYTES=5242880
IMPORT_MAX_ROWS=10000
IMPORT_BATCH_SIZE=10
IMPORT_DELAY_MS=700
IMPORT_WORKERS=1
IMPORT_WORKERS تعداد پردازشهای PHP CLI همزمان را بین ۱ تا ۶ تعیین میکند (پیشفرض ۱). این پردازشگرها با scripts/start-workers.sh شروع میشوند و با scripts/stop-workers.sh متوقف میشوند؛ در نصب Termux، اسکریپتهای شروع/توقف سرویس این کار را خودکار انجام میدهند. بعد از تغییر .env، پردازشگرها را restart کنید. مکث تنظیمشده برای هر کار، بین تمام workerها بهصورت سراسری و از طریق قفل فایل مشترک اعمال میشود؛ تعداد workerها نرخ مجاز کلی را چندبرابر نمیکند. با بستهشدن مرورگر، پردازش ادامه دارد؛ فقط خود PHP worker و MariaDB باید روشن بمانند.
نشست کتابخانه در APP_STORAGE_PATH/sessions/bale-session.json و تصویرهای دریافتشده در APP_STORAGE_PATH/avatars/ قرار میگیرند؛ هر دو خارج از DocumentRoot و با مجوز محدود فایل/پوشه نگهداری میشوند. از قرار دادن APP_STORAGE_PATH داخل public/ خودداری کنید. نشست PHP نیز با کوکی HttpOnly و SameSite=Strict نگهداری میشود. HTTPS برای هر دسترسی از شبکه ضروری است؛ در نصب محلی، برنامه را فقط روی loopback در دسترس قرار دهید.
استفاده
- در ورود نخست، شماره حساب شخصی را وارد کنید و کد بله را تأیید کنید. اگر رمز دومرحلهای بله خواسته شود، فقط برای همان مرحله استفاده میشود و ذخیره نمیشود.
- پس از تأیید بله، نام کاربری برنامه و رمز عبور محلی (حداقل ۱۲ نویسه و حداکثر ۷۲ بایت) بسازید. رمز فقط به شکل hash ذخیره میشود. در مراجعات بعدی با همین مشخصات وارد شوید؛ نشست بله خارج از پوشه عمومی باقی میماند.
- برای تغییر نام کاربری یا رمز، وارد «تنظیمات ← ورود به برنامه» شوید. تغییر عادی رمز، رمز فعلی را میخواهد؛ اگر رمز محلی را فراموش کردید، «ورود یا بازیابی با حساب بله» را انتخاب و دوباره با کد بله تأیید کنید.
- «قفل برنامه» فقط نشست محلی را میبندد و نشست بله را نگه میدارد. برای لغو نشست ذخیرهشده بله، در تنظیمات «قطع اتصال حساب بله» را انتخاب کنید؛ ورود بعدی نیاز به تأیید دوباره بله دارد.
- فایل TXT یا CSV با حداکثر ۵ مگابایت بارگذاری کنید. شماره باید در ستون اول یا ابتدای هر خط باشد. ابتدا پیشنمایش تعداد ردیفها، شمارههای معتبر، نامعتبر و تکراری را ببینید؛ سپس پردازش را جداگانه تأیید کنید. پیشوندهای بینالمللی و قالبهای رایج ایرانی، از جمله ارقام فارسی، به E.164 تبدیل میشوند. فقط شمارههای صریح و مجاز پذیرفته میشوند؛ الگوهایی مانند
+98938155****به شمارههای احتمالی گسترش داده نمیشوند و نامعتبر شمرده خواهند شد. - برنامه شمارههای موجود را از کارهای جدید حذف میکند. worker سمت سرور بهطور خودکار کارهای جدید را اجرا میکند؛ بستن یا refresh کردن مرورگر آن را متوقف نمیکند. کارهای ناتمام از داشبورد قابل مکث و ادامهاند. اندازه دسته (۱ تا ۱۰۰۰) و مکث درخواست (۰ تا ۱۰۰۰ میلیثانیه) از صفحه تنظیمات قابل تغییر است؛ تعداد worker همزمان از
IMPORT_WORKERSدر.envتنظیم میشود و مکث درخواست بین آنها مشترک است. - جدول مخاطبان قابلیت جستوجو، فیلتر، مرتبسازی، صفحهبندی، مشاهده جزئیات، حذف تکی/گروهی و خروجی CSV/JSON دارد.
فیلدهای خالی در API بهصورت NULL میمانند تا «در دسترس نبودن» با داده واقعی اشتباه نشود. اطلاعات جداگانه نام و نام خانوادگی در مدلهای بررسیشده وجود ندارد؛ بنابراین ساخته یا حدس زده نمیشوند. تصویر پروفایل در صورت دسترسی، هنگام نمایش تنبل در جدول از LoadAvatars دریافت و خارج از DocumentRoot ذخیره میشود. FullUser.contact_info در نسخه نصبشده فقط یک مقدار عددی و عنوان عمومی دارد و نوع این مقدار را مشخص نمیکند؛ برنامه آن را بهعنوان شماره تلفن ذخیره نمیکند و profile_phone تا زمان ارائه داده صریح و قابلتأیید خالی میماند.
گزارش فعالیتها
درخواستهای API کاربران واردشده در جدول activity_logs با نوع رویداد api_call، روش HTTP و مسیر ثبت میشوند. مسیرهای دارای شناسه به شکل عمومی ذخیره میشوند؛ افزودن و حذف مخاطب نیز با تعداد رکوردها رویداد جداگانه دارند. رویدادهای ورود، ایجاد/پردازش واردسازی و تغییر تنظیمات هم ثبت میشوند. برای حفظ حریم خصوصی، بدنهٔ درخواستها، شماره تلفنها، رمزها و نشست بله در گزارش فعالیت قرار نمیگیرند.
برای دیدن اجرای زندهٔ متدهای بله از ریشه پروژه اجرا کنید:
tail -F var/logs/runtime.jsonl
همین گزارش در پنل وب، از گزینهٔ «لاگ زنده» در منوی کناری، با بهروزرسانی خودکار هر ۲٫۵ ثانیه قابل مشاهده است. بهروزرسانی را میتوان موقتاً متوقف کرد یا دستی تازهسازی کرد. این API فقط پس از ورود به برنامه قابل دسترسی است و درخواستهای دورهای آن در گزارش فعالیت دیتابیس ثبت نمیشوند.
این فایل فقط رویدادهای فراخوانی متدهای بله، نام و نوع پارامترها، نوع پاسخ، ساختار ثابت مدل پاسخ، مدت اجرا و نوع/کد خطاهای بله را ثبت میکند. شمارهای که به Bale.SearchContact فرستاده میشود در لاگ میآید؛ شمارهٔ ورود به بله و مقادیر حساس دیگر مانند کد ورود، رمز، شناسه و توکن بهصورت [redacted] نمایش داده میشوند. مقادیر واقعی پاسخ، نتیجهٔ تطبیق و اطلاعات پروفایل ثبت نمیشوند. درخواستها و پاسخهای داخلی API برنامه در این فایل نوشته نمیشوند. فایل با دسترسی خصوصی ساخته میشود و پس از ۵ مگابایت چرخش مییابد. گزارشهای حسابرسی عملیات برنامه در جدول activity_logs جدا باقی میمانند.
برای تست زندهٔ یک شمارهٔ مجاز، در ریشهٔ پروژه اجرا کنید:
php searchsingle.php
برای تست آرایهای با دو شمارهٔ مجاز، اجرا کنید:
php searchmuti.php
هر دو اسکریپت شمارهها را از ورودی میگیرند و RPC واقعی میفرستند؛ فقط وجود فیلد user یا group را گزارش میکنند و اطلاعات پروفایل را چاپ نمیکنند. هیچکدام چیزی به دیتابیس محلی اضافه نمیکنند. شمارههای تست در فایل لاگ خصوصی ثبت میشوند. اسکریپت آرایهای پیش از ارسال دو RPC (ترتیب اصلی و وارونه) تأیید میگیرد؛ تفاوت نتیجهها نشانهای است که کل آرایه جستوجو نمیشود، اما یکسان بودن نتیجهها هم پشتیبانی دستهای را ثابت نمیکند. schema نصبشده همچنان request را یک رشته تعریف میکند.
برای مشاهده رویدادهای اخیر یک کاربر از MySQL/MariaDB استفاده کنید:
SELECT event_type, detail_json, created_at
FROM activity_logs
WHERE user_id = ?
ORDER BY id DESC
LIMIT 100;
فایلهای نمونه
samples/contacts.csvsamples/contacts.txt
این نمونهها از شمارههای ساختگی/رزروشده برای مثال استفاده میکنند.
آزمون
composer test
آزمونها مستقل از شبکه و حساب بله هستند و نرمالسازی شماره، تجزیه فایل، اعتبارسنجی/هش رمز برنامه و ذخیره امن تصویر را پوشش میدهند. برای بررسی اتصال واقعی، از یک حساب شخصی در رابط برنامه استفاده کنید؛ اجرای خودکار آزمونها هیچ درخواست ورود یا جستوجویی به بله نمیفرستد.
ساختار
app/: تنظیمات، PDO، API، اعتبارسنجی ورودی و درگاه کتابخانه بلهpublic/: DocumentRoot، رابط RTL و داراییهای وبdatabase/schema.sql: اسکیما و ایندکسهای MySQL/MariaDBdatabase/migrations/: مهاجرتهای افزایشی برای پایگاهدادههای موجودscripts/: نصب، مقداردهی پایگاهداده و شروع/توقف Termuxvar/: نشستهای حساس؛ خارج از DocumentRoot و در Git نادیده گرفته میشود
نکته امنیتی و محدودیت
این برنامه فقط از جستوجوی مخاطب و پروفایلهایی که خود کتابخانه در اختیار حساب قرار میدهد استفاده میکند؛ تلاش برای دور زدن حریم خصوصی یا یافتن اطلاعات پنهان انجام نمیدهد. برای استقرار عمومی، HTTPS، محدودسازی دسترسی شبکه و تهیه نسخه پشتیبان رمزگذاریشده از پایگاهداده را فعال کنید. فایل نشست Bale را مانند رمز عبور حساب محافظت کنید.