توسعه‌دهنده on 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

معماری (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

هسته اصلی (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

رابط کاربری (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

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

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

قبل از شروع#

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

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

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