عیب‌یابی FreeGuard CLI

آیا با FreeGuard CLI مشکل دارید؟ این راهنما رایج‌ترین مشکلات و راه‌حل‌های آن‌ها را پوشش می‌دهد. برای هر مشکلی، ابتدا freeguard doctor را اجرا کنید — این ابزار به‌طور خودکار بیشتر مشکلات پیکربندی و محیطی را شناسایی می‌کند.

مشکلات نصب

عدم دسترسی هنگام نصب

علامت: اسکریپت نصب با خطای Permission denied یا EACCES ناموفق می‌شود.

راه‌حل: در macOS/Linux، نصب‌کننده به دسترسی نوشتن در /usr/local/bin نیاز دارد. با سطح دسترسی بالا اجرا کنید:

curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sudo sh

در Windows، مطمئن شوید که PowerShell را به‌عنوان مدیر (Administrator) باز کرده‌اید قبل از اجرای دستور نصب.

دستور پس از نصب یافت نشد

علامت: اجرای freeguard خطای command not found یا not recognized برمی‌گرداند.

خروجی Doctor:

✗ CLI binary:     Not in PATH

راه‌حل: فایل باینری ممکن است در PATH شِل شما نباشد. آن را به‌صورت دستی اضافه کنید:

# macOS/Linux — add to your shell profile (~/.bashrc, ~/.zshrc)
export PATH="$HOME/.freeguard/bin:$PATH"

# Then reload your shell
source ~/.zshrc  # or ~/.bashrc

در Windows، مسیر %USERPROFILE%\.freeguard\bin را به متغیر محیطی PATH سیستم اضافه کنید و ترمینال را مجدداً راه‌اندازی کنید.

خطای curl یا اتمام زمان دانلود

علامت: اسکریپت نصب نمی‌تواند فایل باینری را دانلود کند.

راه‌حل: اگر پشت فایروال شرکتی هستید یا در شبکه‌ای محدود قرار دارید، فایل باینری را به‌صورت دستی از صفحه انتشارات GitHub دانلود کرده و در ~/.freeguard/bin/ قرار دهید. سپس آن را قابل اجرا کنید:

chmod +x ~/.freeguard/bin/freeguard

مشکلات ورود

کد تأیید دریافت نشد

علامت: پس از اجرای freeguard login --email [email protected] --send-code، هیچ ایمیلی نمی‌رسد.

راه‌حل:

پوشه هرزنامه/اسپم خود را بررسی کنید — ایمیل‌های تأیید گاهی فیلتر می‌شوند.
۲ دقیقه قبل از درخواست مجدد صبر کنید. محدودیت نرخ ارسال کد وجود دارد.
مطمئن شوید که آدرس ایمیل صحیح است:

freeguard login --email [email protected] --send-code

اگر مشکل ادامه داشت، یک ارائه‌دهنده ایمیل دیگر امتحان کنید.

توکن منقضی شده

علامت: دستورات با خطای Authentication expired یا Token invalid ناموفق می‌شوند.

خروجی Doctor:

✗ Credentials:     Token expired (last refresh: 2026-03-01)

راه‌حل: دوباره وارد شوید تا اعتبارنامه‌های خود را بازنشانی کنید:

freeguard logout
freeguard login --email [email protected] --send-code

ایمیل اشتباه — اشتراکی یافت نشد

علامت: ورود موفقیت‌آمیز است اما freeguard connect پیام No active subscription می‌دهد.

خروجی Doctor:

✓ Credentials:     Logged in (email: u***@example.com)
✗ Subscription:    No active subscription found

راه‌حل: مطمئن شوید که با همان ایمیلی وارد می‌شوید که برای خرید اشتراک استفاده کرده‌اید. اگر از ایمیل دیگری استفاده کرده‌اید:

freeguard logout
freeguard login --email [email protected] --send-code

مشکلات اتصال

اتمام زمان اتصال

علامت: freeguard connect متوقف می‌شود یا Connection timed out برمی‌گرداند.

خروجی Doctor:

✗ Network:         Internet not reachable

راه‌حل:

اتصال اینترنت پایه خود را بررسی کنید (ابتدا VPN را قطع کنید):

freeguard disconnect
ping 8.8.8.8

یک نود یا کشور دیگر امتحان کنید:

freeguard connect --country SG

یک پروتکل دیگر امتحان کنید که ممکن است در شبکه شما بهتر کار کند:

freeguard connect --protocol hysteria2

پورت 7890 در حال استفاده است

علامت: freeguard connect با خطای Port 7890 is already in use ناموفق می‌شود.

خروجی Doctor:

✗ Port 7890:       In use by another process (PID: 12345)

راه‌حل: یک برنامه proxy دیگر از پورت پیش‌فرض استفاده می‌کند. یا برنامه دیگر را متوقف کنید، یا پورت proxy FreeGuard را تغییر دهید:

freeguard config set proxy.port 8080
freeguard connect

نشت DNS شناسایی شد

علامت: درخواست‌های DNS از تونل VPN عبور نمی‌کنند.

راه‌حل: به پیکربندی DNS امن تغییر دهید:

freeguard config set dns.provider secure
freeguard disconnect
freeguard connect

می‌توانید تأیید کنید که DNS از طریق VPN مسیریابی می‌شود:

freeguard doctor

در خروجی به بررسی DNS نگاه کنید تا مطمئن شوید به‌درستی کار می‌کند.

مشکلات دسترسی

حالت TUN نیاز به sudo دارد

علامت: freeguard connect --tun با خطای Permission denied: TUN device ناموفق می‌شود.

خروجی Doctor:

✗ TUN permission:  Not available (run with sudo for TUN mode)

راه‌حل: حالت TUN یک رابط شبکه مجازی ایجاد می‌کند که نیاز به سطح دسترسی بالا دارد:

# macOS/Linux
sudo freeguard connect --tun

# Windows — run PowerShell as Administrator
freeguard connect --tun

اگر به پوشش VPN در سطح سیستم نیاز ندارید، از حالت proxy سیستم پیش‌فرض استفاده کنید (نیازی به sudo نیست):

freeguard connect

پورت زیر 1024 نیاز به سطح دسترسی بالا دارد

علامت: تنظیم پورت proxy زیر 1024 با خطای Permission denied ناموفق می‌شود.

راه‌حل: پورت‌های زیر 1024 در اکثر سیستم‌عامل‌ها محدود هستند. از پورت بالای 1024 استفاده کنید:

freeguard config set proxy.port 7890

یا اگر به‌طور خاص به پورت پایین نیاز دارید، با سطح دسترسی بالا اجرا کنید:

sudo freeguard connect

هنوز مشکل دارید؟

اگر freeguard doctor و راه‌حل‌های بالا مشکل شما را حل نکرد، اجازه دهید هوش مصنوعی آن را به‌طور خودکار تشخیص دهد.

از صفحه FreeGuard CLI Agent دیدن کنید و مشکل خود را توضیح دهید. عامل هوشمند می‌تواند خروجی freeguard doctor --json شما را بخواند و قدم به قدم شما را راهنمایی کند.

همچنین می‌توانید ویزارد عیب‌یابی تعاملی را اجرا کنید:

freeguard doctor --json | pbcopy
# Then paste the output into the CLI Agent chat

سؤالات متداول

چرا FreeGuard CLI پیام “connection refused” می‌دهد؟

این معمولاً به این معنی است که سرور VPN موقتاً در دسترس نیست. برای انتخاب خودکار بهترین سرور موجود freeguard connect --server auto را امتحان کنید، یا تنظیمات فایروال خود را بررسی کنید.

چگونه بررسی کنم که اتصال VPN من کار می‌کند؟

freeguard status را اجرا کنید تا وضعیت اتصال، سرور فعلی و پروتکل را ببینید. همچنین می‌توانید curl ifconfig.me را اجرا کنید تا تأیید کنید آدرس IP شما تغییر کرده است.

FreeGuard CLI پس از به‌روزرسانی سیستم شروع نمی‌شود. چه باید بکنم؟

freeguard update را اجرا کنید تا آخرین نسخه را دریافت کنید. اگر ناموفق بود، با اسکریپت نصب مجدداً نصب کنید: curl -fsSL https://downloadcli.freeguardvpn.com/cli/install.sh | sh.

چگونه یک باگ گزارش دهم یا کمک بگیرم؟

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

آخرین به‌روزرسانی: مارس ۲۰۲۶