Documentation

شروع به کار

Mon, 01 Jan 0001 00:00:00 +0000

شروع به کار - توسعه‌دهندگان (Getting Started)#

این راهنما نحوه آماده‌سازی محیط توسعه، کامپایل و اجرای محلی bgscan را برای مقاصد توسعه و برنامه‌نویسی توضیح می‌دهد.

ابتدا بخوانید: راهنمای مشارکت — سیستم برانچ‌بندی، قوانین ثبت کامیت و فرآیند ثبت درخواست‌های Pull Request (PR).

پیش‌نیازها (Prerequisites)#

زبان برنامه‌نویسی Go نسخه 1.26.3 به بالا (نسخه دقیق را در فایل go.mod بررسی کنید)
سیستم کنترل نسخه Git
برای کامپایل نسخه اندروید: ابزار Android NDK

۱. کلون کردن مخزن (Repository)#

git clone [https://github.com/MohsenBg/bgscan.git](https://github.com/MohsenBg/bgscan.git)
cd bgscan

۲. ایجاد یک شاخه یا برانچ (Branch)#

git checkout -b feature/my-change

برای آشنایی با استانداردهای نام‌گذاری شاخه‌ها، بخش راهنمای مشارکت را مطالعه کنید.

منبع اسکن

Mon, 01 Jan 0001 00:00:00 +0000

منبع اسکن (Scan Source)#

قبل از پیکربندی اسکن، bgscan از شما می‌خواهد مشخص کنید که آی‌پی‌های هدف از کجا تأمین شوند. به مسیر Main Menu → Scan بروید تا پنجره انتخاب منبع باز شود. در این بخش دو گزینه پیش روی شماست:

کلید	گزینه	توضیحات
`i`	IP List	انتخاب از میان فایل‌های لیست آی‌پی وارد شده
`r`	Result List	انتخاب از میان فایل‌های نتایج اسکن‌های قبلی

لیست آی‌پی (IP List)#

با انتخاب IP List، مرورگر فایل‌های آی‌پی شما باز می‌شود. می‌توانید هر فایلی را از پوشه ips/ انتخاب کنید تا bgscan از آیتم‌های فعال آن به عنوان هدف اسکن استفاده کند.

نمای کلی تنظیمات

Mon, 01 Jan 0001 00:00:00 +0000

نمای کلی تنظیمات (Settings Overview)#

ابزار bgscan تمام پیکربندی‌های خود را در قالب فایل‌های متنی ساده TOML در پوشه settings/ نگهداری می‌کند. برنامه همچنین همین گزینه‌ها را از طریق بخش داخلی مدیریت تنظیمات (Settings inspector) در محیط برنامه نیز در اختیارتان می‌گذارد که تغییرات را به صورت خودکار روی دیسک ذخیره می‌کند.

فایل‌های تنظیمات#

فایل	کاربرد
`settings/general_settings.toml`	مدیریت سراسری اسکن و حالت فرآیند چندمرحله‌ای
`settings/writer_settings.toml`	بافر کردن نتایج و ذخیره‌سازی آن‌ها روی دیسک
`settings/icmp_settings.toml`	تنظیمات دقیق پروب (بررسی) ICMP
`settings/tcp_settings.toml`	تنظیمات دقیق اتصال TCP
`settings/http_settings.toml`	تنظیمات دقیق پروب‌های HTTP/HTTPS/HTTP3
`settings/xray_settings.toml`	تنظیمات دقیق تست Xray
`settings/dns_settings.toml`	تنظیمات دقیق ریزالور DNS، ابزارهای DNSTT و SlipStream

دو روش برای ویرایش تنظیمات#

فایل‌های TOML — هر کدام از فایل‌های موجود در مسیر settings/*.toml را در یک ادیتور متنی باز کنید، مقادیر را تغییر دهید، ذخیره کنید و bgscan را مجدداً راه‌اندازی کنید. این روش صریح‌ترین رویکرد است و برای سیستم‌های کنترل نسخه (مثل Git) عالی عمل می‌کند.
بخش داخلی مدیریت تنظیمات — برنامه bgscan را باز کنید، از منوی اصلی به بخش Settings بروید، دسته‌بندی مورد نظر را انتخاب کرده و روی هر فیلد کلید Enter را بزنید تا ویرایش شود. تغییرات بلافاصله روی دیسک ذخیره می‌شوند.

برخی از فیلدها پویا (Dynamic) هستند. به عنوان مثال، گزینه‌های مربوط به TLS تنها زمانی نشان داده می‌شوند که پروتکل HTTPS انتخاب شده باشد، و فیلدهای مربوط به DNSTT/Slipstream نیز تنها در صورت فعال بودن پروب‌های مربوطه به نمایش در می‌آیند.

انواع اسکن

Mon, 01 Jan 0001 00:00:00 +0000

انواع اسکن (Scan Types)#

ابزار bgscan از ۵ نوع اسکن اصلی پشتیبانی می‌کند که از طریق منوی اصلی و با کلیدهای میانبر کیبورد قابل دسترسی هستند:

کلید	نوع اسکن	توضیحات	کاربرد اصلی	فایل پیکربندی
`i`	اسکن ICMP	ارسال درخواست‌های ICMP echo (پینگ) برای بررسی در دسترس بودن هاست	کشف هاست‌های فعال، نقشه‌برداری شبکه	`icmp_settings.toml`
`t`	اسکن TCP	تلاش برای برقراری اتصال TCP به پورت‌های مشخص شده	اسکن پورت‌ها، شناسایی سرویس‌ها	`tcp_settings.toml`
`h`	اسکن HTTP	ارسال درخواست‌های HTTP/HTTPS به وب‌سرورها	تست وب‌سرویس‌ها، کشف اندپوینت‌های API	`http_settings.toml`
`d`	اسکن DNS	پرس‌وجو از سرورهای DNS برای بررسی قابلیت‌های رزولوشن و تانلینگ	تست ریزالورهای DNS، شناسایی قابلیت تانلینگ	`dns_settings.toml`
`x`	اسکن Xray	تست اتصال خروجی (Outbound) و سنجش پهنای باند به سرورهای مقصد	تست خروجی شبکه، اندازه‌گیری پهنای باند	`xray_settings.toml`

💡 نکته: گزینه اسکن DNS) d) در صورت فعال بودن در تنظیمات، خودش شامل سه نوع زیرمجموعه اسکن می‌شود:

مدیریت تنظیمات در برنامه

Mon, 01 Jan 0001 00:00:00 +0000

مدیریت تنظیمات در برنامه (Settings Inspector)#

هنگامی که هر یک از بخش‌های تنظیمات را از منوی Settings داخل برنامه باز می‌کنید، پنجره مدیریت تنظیمات را مشاهده خواهید کرد. این پنجره شامل لیستی از فیلدهای تب‌بندی‌شده (برتبه‌بندی‌شده) همراه با عناوین، مقادیر فعلی و امکانات ویرایش است.

فیلدها را انتخاب کرده و کلید Enter را فشار دهید تا مقادیر آن‌ها تغییر کند.
کلید d را فشار دهید تا توضیحات یا متن راهنمای مربوط به فیلد انتخاب‌شده نمایش داده شود.
مقادیر بله/خیر (Booleans) به صورت دکمه‌های سوئیچ (Toggle) نمایش داده می‌شوند.
برخی از پروتکل‌ها، فیلدهای اضافی را تنها زمانی باز می‌کنند که حالت (Mode) مربوط به آن‌ها انتخاب شده باشد.

تغییرات بلافاصله روی دیسک ذخیره می‌شوند و نیازی به راه‌اندازی مجدد اسکنر نیست.

معماری

Mon, 01 Jan 0001 00:00:00 +0000

معماری (Architecture)#

برنامه bgscan ساختاری لایه‌بندی‌شده دارد. یک نقطه ورود (Entry Point) سبک، بررسی‌های سلامت اولیه (Health Checks) را هنگام راه‌اندازی سیستم اجرا می‌کند و سپس کنترل برنامه را به رابط کاربری متنی BubbleTea TUI می‌سپارد. این رابط کاربری متنی، یک موتور اسکنر چندمرحله‌ای را هدایت می‌کند که پروب‌ها (Probes) و سیستم ورودی/خروجی (I/O) آن به صورت ماژولار و قابل تعویض (Pluggable) طراحی شده‌اند.

ساختار دایرکتوری‌ها (Directory Layout)#

.
├── assets
│ └── xray
│ └── outbounds
├── cmd
│ └── bgscan
│ └── main.go
├── docs
├── go.mod
├── internal
│ ├── core
│ │ ├── config
│ │ ├── dns
│ │ ├── fileutil
│ │ ├── ip
│ │ ├── iplist
│ │ ├── process
│ │ ├── result
│ │ ├── scanner
│ │ └── xray
│ ├── logger
│ ├── startup
│ └── ui
│ ├── components
│ ├── main
│ ├── shared
│ └── theme
├── ips
├── scripts
└── settings

نمای کلی لایه‌ها (Layer Overview)#

┌─────────────────────────────────────────────┐
│ cmd/bgscan │
│ (نقطه ورود برنامه) │
├─────────────────────────────────────────────┤
│ internal/startup │
│ (بررسی سلامت، مقداردهی تنظیمات) │
├─────────────────────────────────────────────┤
│ internal/ui │
│ ┌─────────────────────────────────────┐ │
│ │ main (مدل ریشه، چیدمان، دیالوگ‌ها) │ │
│ │ components (منوها، جدول‌ها، فرم‌ها) │ │
│ │ shared (زیرساخت چیدمان، محیط، دیالوگ)│ │
│ │ theme (تم‌ها) │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────────┤
│ internal/core │
│ ┌──────────────┐ ┌──────────┐ ┌─────────┐ │
│ │ scanner │ │ config │ │ result │ │
│ │ (موتور، پروب) │ │ (TOML) │ │(نویسنده)│ │
│ └──────────────┘ └──────────┘ └─────────┘ │
│ ┌──────────┐ ┌─────────┐ ┌──────────────┐ │
│ │ iplist │ │ dns │ │ xray/process │ │
│ └──────────┘ └─────────┘ └──────────────┘ │
├─────────────────────────────────────────────┤
│ internal/logger │
├─────────────────────────────────────────────┤
│ assets/ ips/ settings/ │
│ (فایل‌های داده) │
└─────────────────────────────────────────────┘

راهنمای دایرکتوری‌ها (Directory Reference)#

مسیر	توضیحات
`cmd/bgscan`	نقطه ورود اصلی برنامه (`main.go`). مدل ریشه TUI را ایجاد و آن را اجرا می‌کند.
`internal/core`	منطق و هسته اصلی: تنظیمات، دی‌ان‌اس، ابزارهای کمکی فایل، مدیریت آی‌پي‌ها، مدیریت پروسس‌ها، نتایج، اسکنر و یکپارچه‌سازی Xray.
`internal/core/config`	پکیج سینگلتون (Singleton) تنظیمات مبتنی بر TOML با قابلیت دسترسی ایمن در محیط‌های چندنخی (Thread-safe).
`internal/core/scanner`	هماهنگ‌کننده اسکنر، موتور (خط‌لوله)، اینترفیس پروب‌ها، مدیریت پورت‌ها و ابزارهای کمکی شبکه.
`internal/core/result`	نویسنده ناهمگام نتایج (Asynchronous Writer)، ادغام/مرتب‌سازی فایل‌های CSV، رجیستری و بارگذاری‌کننده فایل نتایج.
`internal/core/iplist`	بارگذاری‌کننده فایل‌های CSV لیست آی‌پي، پارسر، رجیستری و برهم‌زننده تصادفی (Shuffle) لیست‌ها.
`internal/core/dns`	ابزارهای کمکی برای کوئری‌های DNS، ابزارهای DNSTT، SlipStream و SOCKS5.
`internal/core/xray`	اجراکننده دستورات Xray، مدیریت اینباندها/آوتباندها (Inbound/Outbound) و تست سرعت.
`internal/core/process`	مدیریت چرخه حیات پروسس‌ها به صورت چندسکویی (ایجاد، خاتمه و ارسال سیگنال).
`internal/core/fileutil`	ابزارهای کمکی برای کار با فایل‌های CSV، JSON، TOML، متن، فایل‌های موقت و مدیریت مسیرها.
`internal/core/ip`	پارس کردن آدرس‌های آی‌پي و باز کردن رنج‌های CIDR.
`internal/logger`	ثبت لاگ‌های سطح‌بندی‌شده با قابلیت جابه‌جایی و چرخش خودکار فایل‌ها (Lumberjack Rotation). شامل سه جریان: هسته، رابط کاربری و دباگ.
`internal/startup`	بررسی‌های ترتیبی سلامت سیستم در زمان راه‌اندازی: لاگر، تم، تنظیمات، باینری Xray، باینری DNSTT و Slipstream.
`internal/ui/main`	مدل ریشه BubbleTea — مدیریت چیدمان هدر/بدنه/فوتر و مدیریت دیالوگ‌های لایه‌رویی (Overlay Dialogs).
`internal/ui/components`	اجزای قابل استفاده مجدد رابط کاربری: ویجت‌های پایه، فرم‌های بازرس، منوها، جدول‌ها و نمای اسکنر.
`internal/ui/shared`	زیرساخت مشترک UI: هندسه و ابعاد چیدمان، سیستم دیالوگ، کلیدها/محیط، اینترفیس کامپوننت‌ها و اعتبارسنجی ورودی‌ها.
`internal/ui/theme`	پالت‌های رنگی تاریک، روشن و خودکار (بر پایه استایل Catppuccin).
`assets/xray/outbounds`	فایل‌های پیکربندی آوتباند Xray که به همراه برنامه توزیع می‌شوند.
`assets/dnstt-client`, `assets/slipstream-client`	باینری‌های مربوط به تونل‌زنی دی‌ان‌اس.
`ips`	لیست پیش‌فرض رنج‌های آی‌پي به تفکیک ارائه‌دهندگان (Cloudflare، AWS، Azure و غیره) در قالب فایل‌های CSV.
`settings`	فایل‌های تنظیمات پیش‌فرض با فرمت `.toml`. فایل‌های با پسوند `.default` به عنوان قالب‌های زاپاس و پشتیبان عمل می‌کنند.
`scripts`	اسکریپت‌های کمکی برای نصب، کامپایل و ریلیز پروژه.
`docs`	وب‌سایت مستندات پروژه که با Hugo Book ساخته شده است.

گردش کار برنامه (Application Flow)#

()main
 │
 ├─ ()startup.RunHealthChecks
 │ ├─ مقداردهی اولیه لاگر (logger init)
 │ ├─ مقداردهی اولیه تم (theme init)
 │ ├─ بارگذاری و اعتبارسنجی تنظیمات (config load + validate)
 │ ├─ بررسی وجود باینری xray
 │ ├─ بررسی وجود باینری dnstt
 │ └─ بررسی وجود باینری slipstream
 │
 ├─ ()tea.NewProgram(app.New()).Run
 │ │
 │ ├─ هدر (نوار عنوان بالای صفحه)
 │ ├─ بدنه (پشته کامپوننت‌ها: منوی اصلی ← اسکن/تنظیمات/لاگ‌ها/...)
 │ └─ فوتر (نوار وضعیت پایین صفحه، کلیدهای راهنما)
 │
 └─ هنگامی که کاربر گزینه شروع اسکن را انتخاب می‌کند:
 ├─ ()scanner.NewScanner(ctx, inputPath)
 ├─ (scanner.AddStage(BuildICMPStage
 ├─ (scanner.AddStage(BuildTCPStage
 ├─ ...
 ├─ ()scanner.Run
 │ ├─ اسکن تک‌مرحله‌ای ← engine.RunScan
 │ └─ اسکن چندمرحله‌ای ← engine.RunScanWithChain
 │ ├─ به صورت ترتیبی (sequential)
 │ ├─ به صورت جریانی (streaming)
 │ └─ به صورت دسته‌ای (batch)
 │
 └─ نتایج از طریق ثبت‌کننده نتایج روی دیسک ذخیره می‌شوند: result.Writer ← ادغام فایل‌های CSV ← ذخیره نهایی

اصول کلیدی طراحی (Key Design Principles)#

عدم وابستگی به ابزارهای خارجی برای اسکن‌های پایه: پروب‌های ICMP، TCP و HTTP کاملاً از کتابخانه‌های استاندارد خود زبان Go (go stdlib) استفاده می‌کنند. ابزارهای Xray، DNSTT و Slipstream باینری‌های اختیاری هستند که وجود و سلامت آن‌ها در زمان راه‌اندازی (Startup) اعتبارسنجی می‌شود.
تنظیمات فایل‌محور: تمام تنظیمات و پیکربندی‌ها در مسیر settings/*.toml زندگی می‌کنند. بخش بازرس (Inspector) درون برنامه نیز دقیقاً همین فایل‌ها را خوانده و بازنویسی می‌کند.
پروب‌های ماژولار و قابل تعویض: تنها قرارداد موجود برای افزودن اسکنر جدید، اینترفیس probe.Probe است. برای افزودن یک نوع اسکن جدید، کافی است متدهای Init/Run/Close را پیاده‌سازی کرده و سازنده مرحله (Stage Builder) آن را ثبت کنید.
موتور مستقل از نوع خط‌لوله (Pipeline-agnostic): موتور اصلی اسکنر اطلاعی از ماهیت و کارکرد پروب‌ها ندارد — وظیفه آن صرفاً تزریق آی‌پي‌ها، جمع‌آوری نتایج و تخلیه آن‌ها روی دیسک است. حالت خط‌لوله (ترتیبی/جریانی/دسته‌ای) بر اساس ترجیحات فایل تنظیمات تعیین می‌شود.
رابط کاربری درختی از کامپوننت‌ها: هر صفحه در برنامه یک ui.Component مجزا است که از متدهای Init/Update/View/OnClose/Mode پیروی می‌کند. لایه‌های رویی (دیالوگ‌ها، انتخاب‌گرها) روی لایه‌های قبلی پشته می‌شوند و بالاترین لایه، تمامی ورودی‌های کاربر را به خود اختصاص می‌دهد.

صفحات مرتبط#

هسته اصلی (Core) — جزئیات موتور اسکنر، اینترفیس پروب‌ها، سیستم پیکربندی و خط‌لوله نتایج
رابط کاربری (UI) — معماری TUI، مدل کامپوننت‌ها، چیدمان و سیستم تم‌ها
شروع به کار (Getting Started) — دستورالعمل‌های کامپایل و اجرای پروژه

تنظیمات عمومی

Mon, 01 Jan 0001 00:00:00 +0000

تنظیمات عمومی (General Settings)#

💡 نکته: شما می‌توانید این تنظیمات را به جای ویرایش دستی فایل TOML، مستقیماً درون خود برنامه bgscan تغییر دهید.

برای پیکربندی تعاملی این گزینه‌ها با استفاده از بخش مدیریت تنظیمات (TUI inspector)، از منوی اصلی به مسیر Settings ← General Settings بروید.

فایل پیکربندی: settings/general_settings.toml

این فایل رفتار هسته اصلی اسکنر bgscan، از جمله محدودیت‌های اسکن، حالت‌های اجرا و بهینه‌سازی عملکرد سیستم را کنترل می‌کند.

فرآیند چندمرحله‌ای اسکن

Mon, 01 Jan 0001 00:00:00 +0000

فرآیند چندمرحله‌ای اسکن (Scan Pipeline)#

ابزار bgscan از اسکن چندمرحله‌ای پشتیبانی می‌کند؛ به طوری که خروجی یک مرحله از اسکن، به عنوان ورودی برای شروع مرحله بعدی استفاده می‌شود. این ویژگی از طریق تنظیمات عمومی (General Settings) زیر بخش “Pipeline Execution Mode” پیکربندی می‌شود.

حالت‌های فرآیند پردازش (Pipeline Modes)#

برنامه bgscan سه حالت مختلف برای اجرای فرآیند پردازش ارائه می‌دهد تا بتوانید تعادلی میان عملکرد، میزان مصرف حافظه (RAM) و انعطاف‌پذیری سیستم ایجاد کنید:

نصب و راه‌اندازی

Mon, 01 Jan 0001 00:00:00 +0000

نصب و راه‌اندازی#

ابزار bgscan روی سیستم‌عامل‌های لینوکس، مک، ویندوز و اندروید (ترموکس) اجرا می‌شود. روشی را که با محیط کاربری‌تان سازگارتر است انتخاب کنید.

نصب سریع#

لینوکس / مک

curl -fsSL https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.sh | bash

ویندوز (PowerShell)

irm https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.ps1 | iex

اندروید (Termux)

pkg update -y && pkg install bash curl unzip -y && curl -fsSL https://raw.githubusercontent.com/MohsenBg/bgscan/refs/heads/main/scripts/install.sh | bash

اسکریپت نصب‌کننده، آخرین نسخه منتشر شده را دانلود کرده، آن را در پوشه bgscan/ استخراج می‌کند و فایل باینری را به حالت قابل اجرا (executable) در می‌آورد. اگر نسخه‌ای از قبل نصب شده باشد، از شما می‌پرسد که آیا تمایل به حذف آن دارید یا می‌خواهید یک نسخه پشتیبان از آن با نام bgscan_old بسازید.

هسته اصلی

Mon, 01 Jan 0001 00:00:00 +0000

هسته اصلی (Core)#

پکیج internal/core حاوی تمام منطق‌های غیر UI برنامه است: پیکربندی و تنظیمات، موتور اصلی اسکنر، پیاده‌سازی پروب‌ها، مدیریت لیست‌های آی‌پی، ثبت نتایج، دی‌ان‌اس، یکپارچه‌سازی Xray و مدیریت پروسس‌ها.

نقشه پکیج‌ها (Package Map)#

پکیج	وظیفه و مسئولیت
`config`	پکیج سینگلتون و ایمن در برابر چندنخی که تمام تنظیمات TOML را نگه می‌دارد؛ همراه با ابزارهای کمکی بارگذاری/ذخیره و نقاط ورود اعتبارسنجی.
`config/validate`	اعتبارسنج‌های اختصاصی هر پروتکل (ICMP، TCP، HTTP، DNS، Xray، نویسنده نتایج، تنظیمات عمومی).
`scanner`	هماهنگ‌کننده ساختار `Scanner` و سازنده‌های مراحل اسکن (Stage Builders).
`scanner/engine`	اجرای چرخه پردازش اسکن: اسکن تک‌مرحله‌ای، زنجیره ترتیبی، خط‌لوله جریانی (Streaming) و خط‌لوله دسته‌ای (Batch).
`scanner/probe`	اینترفیس `Probe` و تمام پروب‌های واقعی (ICMP، TCP، HTTP، HTTP/3، DNS، DNSTT، SlipStream، Resolve، Xray).
`scanner/portmgr`	استخر پورت‌های زودگذر (Ephemeral Port Pool) برای پروب‌هایی که نیاز به بایند کردن پورت‌های محلی دارند (Xray، DNSTT، SlipStream).
`scanner/netutil`	ابزارهای کمکی مشترک شبکه.
`result`	ساختار `Writer` (ثبت ناهمگام دسته‌ای + ادغام)، فرمت فایل‌های CSV، بارگذاری‌کننده، رجیستری و مرتب‌سازی.
`iplist`	بارگذاری‌کننده فایل‌های CSV لیست آی‌پی، پارسر، رجیستری، برهم‌زننده تصادفی (Shuffle) و استریم داده‌ها.
`ip`	پارس کردن IPv4 و باز کردن رنج‌های CIDR.
`dns`	ابزارهای کمکی کوئری‌های DNS، پارس کردن لایه انتقال، کلاینت SOCKS5 ابزارهای DNSTT/SlipStream.
`xray`	اجراکننده باینری Xray، تنظیمات اینباند/آوتباند، پارس کردن لینک‌های اتصال و تست سرعت.
`process`	ایجاد/خاتمه پروسس‌ها به صورت چندسکویی (تفکیک مجزا برای سیستم‌عامل‌های ویندوز و یونیکس).
`fileutil`	ابزارهای کمکی برای فایل‌های CSV، JSON، TOML، متن، فایل‌های موقت و مسیرها.
`logger`	ثبت لاگ‌های سطح‌بندی‌شده (هسته، رابط کاربری، دباگ) همراه با قابلیت جابه‌جایی و چرخش خودکار فایل‌ها (Lumberjack).

اسکنر (Scanner)#

فایل internal/core/scanner/scanner.go ساختار Scanner را تعریف می‌کند — این بخش همان API عمومی است که رابط کاربری (UI) برای اجرای یک اسکن آن را فراخوانی می‌کند.

تنظیمات نویسنده نتایج

Mon, 01 Jan 0001 00:00:00 +0000

تنظیمات نویسنده نتایج (Result Writer Settings)#

💡 نکته: شما می‌توانید این تنظیمات را به جای ویرایش دستی فایل TOML، مستقیماً درون خود برنامه bgscan تغییر دهید.

برای پیکربندی تعاملی این گزینه‌ها با استفاده از بخش مدیریت تنظیمات (TUI inspector)، از منوی اصلی به مسیر Settings ← General Settings (تب دوم) بروید.

فایل پیکربندی: settings/writer_settings.toml

این فایل فرآیند بافر کردن (ذخیره موقت) و فواصل زمانی انتقال و ثبت نتایج روی دیسک را کنترل می‌کند.

رابط کاربری

Mon, 01 Jan 0001 00:00:00 +0000

رابط کاربری (UI)#

رابط کاربری پایانی (Terminal UI) ابزار bgscan بر پایه فریم‌ورک BubbleTea (نسخه فورک شده Elvish v2 در مسیر charm.land/bubbletea/v2) و ابزار استایل‌دهی [Lipgloss] توسعه یافته است. معماری این بخش به صورت یک درخت کامپوننت (Component Tree) همراه با یک سیستم دیالوگ لایه‌ای (Overlay) و یک مدیریت‌کننده چیدمان مرکزی (Layout Manager) طراحی شده است.

نقشه پکیج‌ها (Package Map)#

پکیج	وظیفه و مسئولیت
`ui/main/app`	مدل ریشه (Root) در BubbleTea. مدیریت چیدمان، هدر/بدنه/فوتر و پشته‌ی دیالوگ‌های لایه‌ای.
`ui/main/header`	نوار بالایی — شامل نام برنامه و برندینگ آن.
`ui/main/body`	بخش محتوای مرکزی — پشته‌ای از کامپوننت‌ها را نگه می‌دارد (منوی اصلی ← زیرصفحه‌ها).
`ui/main/footer`	نوار وضعیت پایین — نسخه برنامه، نام صفحه فعلی، تعداد گوروتین‌ها و میزان مصرف حافظه رم.
`ui/components/basic`	ویجت‌های قابل استفاده مجدد: تاییدیه، مدیریت داده (CRUD)، فیلد ورودی، بازرس (Inspector)، نمایش لاگ، منو، اعلان، انتخاب‌گر فایل، نوار پیشرفت، جدول و تب‌ها.
`ui/components/inspector`	فرم‌های تنظیمات اختصاصی هر پروتکل (DNS، عمومی، HTTP، ICMP، TCP، Xray).
`ui/components/menus`	منوهای سطح صفحه: ورودی اصلی (Entry)، لاگ‌ها، آوتباندها، نوع اسکن، تنظیمات، منبع هدف.
`ui/components/tables`	جدول‌های داده: لیست آی‌پی، نمایشگر آی‌پی، آوتباندها، لیست نتایج.
`ui/components/scanner`	نمای زنده اسکن — نوارهای پیشرفت تب‌بندی‌شده + جدول نتایج به ازای هر مرحله.
`ui/shared`	زیرساخت‌های مشترک: چیدمان هندسی، دیالوگ، محیط (کلیدها/حالت‌ها)، اینترفیس کامپوننت و اعتبارسنجی.
`ui/theme`	پالت‌های رنگی تاریک/روشن/خودکار + آداپتور تم برای فرم‌های کتابخانه huh.

اینترفیس کامپوننت (Component Interface)#

تمام صفحه‌ها، ویجت‌ها و دیالوگ‌ها اینترفیس ui.shared.ui.Component را پیاده‌سازی می‌کنند:

فایل‌های آی‌پی

Mon, 01 Jan 0001 00:00:00 +0000

فایل‌های آی‌پی (IP Files)#

اسکنرها آدرس‌های هدف را از روی فایل‌های لیست آی‌پی می‌خوانند. قبل از اینکه بتوانید از یک لیست برای اسکن استفاده کنید، باید آن را از طریق محیط TUI وارد (Import) کنید تا برنامه آن را اعتبارسنجی کرده و به فرمت داخلی bgscan تبدیل کند.

آماده‌سازی فایل برای وارد کردن#

فایلی که وارد می‌کنید باید یک فایل متنی ساده با پسوند .txt باشد که در هر خط آن فقط یک آیتم قرار گرفته باشد. در حال حاضر فقط از IPv4 پشتیبانی می‌شود؛ آدرس‌ها و پیشوندهای IPv6 قابل قبول نیستند و هنگام وارد کردن نادیده گرفته می‌شوند.

لاگ‌ها

Mon, 01 Jan 0001 00:00:00 +0000

لاگ‌ها (Logs)#

برنامه bgscan سه جریان مجزای لاگ‌گیری (Log Streams) را نگهداری می‌کند که هرکدام لایه متفاوتی از برنامه را پوشش می‌دهند. شما می‌توانید هر یک از آن‌ها را به صورت زنده از داخل محیط گرافیکی متنی (TUI) مشاهده کنید.

برای باز کردن منوی لاگ، از Main Menu ← Logs اقدام کنید.

دسته‌بندی لاگ‌ها#

کلید میانبر	دسته‌بندی	توضیحات
`c`	لاگ‌های هسته (Core Logs)	فعالیت‌های موتور اسکنر — از جمله بررسی آی‌پي‌ها، ورودی/خروجی فایل‌ها، ثبت نتایج و خطاهای داخلی هسته اسکنر.
`u`	لاگ‌های رابط کاربری (UI Logs)	رویدادهای مربوط به لایه کاربری — مانند چرخه حیات کامپوننت‌ها، عملیات‌های فایلی اجرا شده از داخل TUI و خطاهای سطح رابط کاربری.
`d`	لاگ‌های عیب‌یابی (Debug Logs)	خروجی‌های تشخیصی سطح پایین — وضعیت‌های دقیق داخلی، دامت‌های داده (Data Dumps) و ردپای دقیق خطاها (Verbose Traces) جهت رفع مشکل.

با فشردن کلید مربوطه، نمایش‌دهنده اختصاصی آن لاگ باز می‌شود.

نمای کلی

Mon, 01 Jan 0001 00:00:00 +0000

شروع کار با bgscan#

به bgscan خوش آمدید! این راهنما یک دید کلی و سریع از چیزهایی که بعد از نصب با آن‌ها روبه‌رو می‌شوید و نحوه اجرای اولین اسکن را به شما نشان می‌دهد.

اجرای bgscan#

به پوشه محل نصب برنامه بروید و آن را اجرا کنید:

ویندوز: روی فایل bgscan.exe دو بار کلیک کنید یا دستور .\bgscan.exe را در پاورشل اجرا کنید.
لینوکس/مک/ترموکس: دستور ./bgscan را در ترمینال خود بزنید.

آشنایی با منوی اصلی#

وقتی bgscan را اجرا می‌کنید، منوی اصلی با گزینه‌های زیر پیش روی شما قرار می‌گیرد:

تنظیمات ICMP

Mon, 01 Jan 0001 00:00:00 +0000

تنظیمات ICMP (ICMP Settings)#

💡 نکته: شما می‌توانید این تنظیمات را به جای ویرایش دستی فایل TOML، مستقیماً درون خود برنامه bgscan تغییر دهید.

برای پیکربندی تعاملی این گزینه‌ها با استفاده از بخش مدیریت تنظیمات (TUI inspector)، از منوی اصلی به مسیر Settings ← ICMP Settings بروید.

فایل پیکربندی: settings/icmp_settings.toml

این فایل پارامترهای مربوط به تنظیم دقیق پروب (بررسی) ICMP را کنترل می‌کند.

مرجع سریع (Quick Reference)#

تنظیمات	مقدار پیش‌فرض	توضیحات
`timeout`	`2000`	حداکثر زمان انتظار (به میلی‌ثانیه) برای دریافت پاسخ ICMP (پینگ). اهدافی که در این بازه پاسخ ندهند، غیرقابل دسترس در نظر گرفته می‌شوند.
`tries`	`1`	حداکثر تعداد دفعات تلاش مجدد برای هر هدف جهت کاهش اثر افت پکت (Packet Loss). مقادیر بالاتر دقت را بالا می‌برند اما زمان کل اسکن را افزایش می‌دهند.
`workers`	`400`	تعداد ورکرهای هم‌زمان (Concurrent) برای ارسال درخواست‌های پینگ. مقادیر بالاتر سرعت اسکن را افزایش می‌دهند، اما مصرف پردازنده و پهنای باند شبکه را بالا می‌برند.
`prefix_output`	`"icmp_"`	پیشوند نام فایل برای تمام خروجی‌های تولید شده توسط این ماژول. این گزینه برای تفکیک نتایج در زمان اجرای هم‌زمان چند اسکن کاربرد دارد.

مهلت زمانی (Timeout)#

timeout = 2000

حداکثر زمان انتظار (به میلی‌ثانیه) برای دریافت پاسخ ICMP echo reply. اهدافی که در این بازه پاسخ ندهند، غیرقابل دسترس در نظر گرفته می‌شوند.

فایل‌های نتایج

Mon, 01 Jan 0001 00:00:00 +0000

فایل‌های نتایج (Result Files)#

پس از اتمام هر اسکن، bgscan آی‌پ‌ی‌های کشف‌شده و معیارهای سنجش آن‌ها را در فایل‌های نتایج می‌نویسد. این فایل‌ها بر اساس زمان ساخت سازماندهی می‌شوند و می‌توانید از طریق محیط TUI آن‌ها را مرور، مشاهده، تغییر نام یا حذف کنید.

مشاهده فایل‌های نتایج#

برای باز کردن مرورگر فایل‌های نتایج، به مسیر Main Menu → Result Files بروید.

در جدول این صفحه، تمام فایل‌های نتایج مربوط به انواع اسکن‌ها به ترتیب از جدیدترین به قدیمی‌ترین مرتب شده‌اند و اطلاعات زیر را نشان می‌دهند:

اوت‌باندهای ایکس‌ری

Mon, 01 Jan 0001 00:00:00 +0000

اوت‌باندهای ایکس‌ری (Xray Outbounds)#

یک قالب اوت‌باند (Outbound Template) به bgscan می‌گوید که در طول اسکن Xray، ترافیک را چگونه از طریق پروکسی سرور شما هدایت (مسیریابی) کند. هر قالب در واقع یک فایل JSON ذخیره‌شده در مسیر assets/xray/outbounds/ است که پروتکل، لایه انتقال (Transport) و تنظیمات امنیتی یک کانفیگ پروکسی را توصیف می‌کند.

قبل از اجرای اسکن Xray، باید حداقل یک قالب اوت‌باند پبکربندی‌شده داشته باشید.

برای باز کردن مدیریت اوت‌باندها، به مسیر Main Menu → Xray Outbounds بروید.

تنظیمات TCP

Mon, 01 Jan 0001 00:00:00 +0000

تنظیمات TCP (TCP Settings)#

💡 نکته: شما می‌توانید این تنظیمات را به جای ویرایش دستی فایل TOML، مستقیماً درون خود برنامه bgscan تغییر دهید.

برای پیکربندی تعاملی این گزینه‌ها با استفاده از بخش مدیریت تنظیمات (TUI inspector)، از منوی اصلی به مسیر Settings ← TCP Settings بروید.

فایل پیکربندی: settings/tcp_settings.toml

این فایل پارامترهای مربوط به اسکن پورت TCP از جمله پورت هدف، مهلت زمانی (Timeout)، تعداد ورکرها، دفعات تلاش مجدد و پیشوند خروجی را کنترل می‌کند.

مشارکت در پروژه

Mon, 01 Jan 0001 00:00:00 +0000

راهنمای مشارکت (Contributing Guide)#

از اینکه علاقه‌مند به مشارکت در توسعه bgscan هستید، صمیمانه سپاسگزاریم! تک‌تک مشارکت‌های شما — چه در قالب رفع باگ، چه بهبود مستندات و چه پیاده‌سازی قابلیت‌های جدید — برای ما بسیار ارزشمند است.

قبل از شروع#

پیش از باز کردن یک ایشو (Issue) جدید، ابتدا لیست ایشوهای موجود را جستجو کنید تا از عدم وجود گزارش مشابه مطمئن شوید.
اگر قصد دارید قابلیت بزرگ یا تغییر عمده‌ای در پروژه ایجاد کنید، لطفاً ابتدا یک ایشو باز کنید تا درباره آن با هم گفتگو کنیم.
درخواست‌های ادغام (Pull Requests) خود را کوچک نگه دارید و تنها روی یک تغییر مشخص تمرکز کنید.

استراتژی شاخه‌ها (Branch Strategy)#

لطفاً به هیچ عنوان تغییرات خود را مستقیماً روی شاخه main کامیت نکنید.

تنظیمات HTTP

Mon, 01 Jan 0001 00:00:00 +0000

تنظیمات HTTP (HTTP Settings)#

💡 نکته: شما می‌توانید این تنظیمات را به جای ویرایش دستی فایل TOML، مستقیماً درون خود برنامه bgscan تغییر دهید.

برای پیکربندی تعاملی این گزینه‌ها با استفاده از بخش مدیریت تنظیمات (TUI inspector)، از منوی اصلی به مسیر Settings ← HTTP Settings بروید.

فایل پیکربندی: settings/http_settings.toml

این فایل تنظیمات دقیق پروب (بررسی) HTTP/HTTPS/HTTP3 از جمله هاست مقصد، پورت، پروتکل، تنظیمات TLS، نسخه HTTP، مهلت زمانی (Timeout) و استاتوس کدهای مجاز را کنترل می‌کند.

تنظیمات DNS

Mon, 01 Jan 0001 00:00:00 +0000

تنظیمات DNS (DNS Settings)#

💡 نکته: شما می‌توانید این تنظیمات را به جای ویرایش دستی فایل TOML، مستقیماً درون خود برنامه bgscan تغییر دهید.

برای پیکربندی تعاملی این گزینه‌ها با استفاده از بخش مدیریت تنظیمات (TUI inspector)، از منوی اصلی به مسیر Settings ← DNS Settings بروید.

فایل پیکربندی: settings/dns_settings.toml

این فایل ماژول‌های اسکن ریزالور DNS، ابزار DNSTT و SlipStream را کنترل می‌کند.

مرجع سریع (Quick Reference)#

تنظیمات	مقدار پیش‌فرض	توضیحات
`workers` (ریزالور)	`500`	تعداد ورکرهای هم‌زمان برای ارسال کوئری‌های DNS.
`protocol` (ریزالور)	`"udp"`	پروتکل لایه انتقال مورد استفاده برای کوئری‌های DNS.
`domain` (ریزالور)	`""`	نام دامنه هدف که به عنوان مقصد اصلی برای رزولوشن DNS استفاده می‌شود.
`port` (ریزالور)	`53`	پورت هدف برای کوئری‌های DNS (معمولاً 53).
`check_types` (ریزالور)	`["txt"]`	انواع رکورد DNS برای کوئری گرفتن (مانند A، AAAA، TXT، MX).
`timeout` (ریزالور)	`2000`	حداکثر زمان انتظار (به میلی‌ثانیه) برای دریافت پاسخ DNS.
`tries` (ریزالور)	`2`	حداکثر تعداد دفعات تلاش مجدد در شبکه برای هر هدف جهت کاهش اثر افت پکت.
`accepted_rcodes` (ریزالور)	`["noerror", "nxdomain"]`	کدهای وضعیت پاسخ DNS که به عنوان نتایج موفق (“فعال”) در نظر گرفته می‌شوند.
`check_dpi` (ریزالور)	`false`	فعال‌سازی پیش‌بررسی ضد دستکاری و سانسور (Anti-hijacking).
`dpi_timeout` (ریزالور)	`500`	حداکثر زمان انتظار (به میلی‌ثانیه) برای پاسخ پیش‌بررسی DPI.
`dpi_tries` (ریزالور)	`2`	حداکثر تعداد دفعات تلاش مجدد در شبکه برای پیش‌بررسی DPI.
`random_subdomain` (ریزالور)	`true`	تولید یک ساب‌دامین تصادفی برای هر کوئری جهت دور زدن کشِ ریزالورها.
`prefix_output` (ریزالور)	`"dns_"`	پیشوند اعمال‌شده روی نام تمامی فایل‌های خروجی تولید شده توسط این ماژول.
`enabled` (ابزار dnstt)	`false`	فعال یا غیرفعال کردن فاز پروب DNSTT.
`workers` (ابزار dnstt)	`20`	تعداد ورکرهای هم‌زمان برای انجام دست‌تکانی‌های (Handshakes) ابزار DNSTT.
`domain` (ابزار dnstt)	`""`	زون DNS مقتدر (Authoritative) که به سرور DNSTT شما واگذار (Delegate) شده است.
`timeout` (ابزار dnstt)	`10000`	حداکثر زمان انتظار (به میلی‌ثانیه) برای تکمیل دست‌تکانی DNSTT.
`prefix_output` (ابزار dnstt)	`"dnstt_"`	پیشوند اعمال‌شده روی نام تمامی فایل‌های خروجی تولید شده توسط ماژول DNSTT.
`enabled` (ابزار slip_stream)	`true`	فعال یا غیرفعال کردن فاز پروب SlipStream.
`workers` (ابزار slip_stream)	`20`	تعداد ورکرهای هم‌زمان برای انجام پروب‌های SlipStream.
`domain` (ابزار slip_stream)	`""`	زون DNS مقتدر (Authoritative) مورد استفاده توسط سرور SlipStream.
`timeout` (ابزار slip_stream)	`8000`	حداکثر زمان انتظار (به میلی‌ثانیه) برای تکمیل پروب SlipStream.
`prefix_output` (ابزار slip_stream)	`"slipstream_"`	پیشوند اعمال‌شده روی نام تمامی فایل‌های خروجی تولید شده توسط ماژول SlipStream.

تنظیمات ریزالور (Resolver Settings)#

این بخش، اسکنر انبوه ریزالورهای DNS را پیکربندی می‌کند که وظیفه تست ریزالورهای DNS عمومی را بر عهده دارد.

تنظیمات Xray

Mon, 01 Jan 0001 00:00:00 +0000

تنظیمات Xray (Xray Settings)#

💡 نکته: شما می‌توانید این تنظیمات را به جای ویرایش دستی فایل TOML، مستقیماً درون خود برنامه bgscan تغییر دهید.

برای پیکربندی تعاملی این گزینه‌ها با استفاده از بخش مدیریت تنظیمات (TUI inspector)، از منوی اصلی به مسیر Settings ← Xray Settings بروید.

فایل پیکربندی: settings/xray_settings.toml

این فایل ماژول اعتبارسنجی خروجی‌های Xray را کنترل می‌کند که وظیفه تست اتصال و پهنای باند سرورهای راه دور را بر عهده دارد.