رفع اشکال و بررسی لاگها (Troubleshooting)
هدف این صفحه
این صفحه شامل لیست کاملی از تمام خطاها و پیامهایی است که ممکن است در سمت سرور یا کلاینت مشاهده کنید. اگر برنامه شما کار نمیکند، ابتدا لاگها را بررسی کرده و پیام مربوطه را در لیست زیر جستجو کنید.
راهنمای خواندن لاگها
زمانی که برنامه را اجرا میکنید (چه در لینوکس، ویندوز یا مک)، پیامهایی در ترمینال چاپ میشود.
- INFO: پیامهای عادی که نشاندهنده عملکرد صحیح هستند.
- WARNING: هشدارهایی که برنامه را متوقف نمیکنند اما باید بررسی شوند (مثلاً امنیت پایین).
- FATAL / ERROR: خطاهای بحرانی که باعث بسته شدن برنامه یا قطع اتصال میشوند.
۱. خطاهای سمت کلاینت (Client Side)
در این بخش پیامهایی که در ترمینال کامپیوتر یا گوشی خود مشاهده میکنید بررسی شدهاند.
الف. خطاهای راهاندازی (Startup)
| پیام لاگ (Log Message) | علت احتمالی | راه حل |
|---|---|---|
Failed to load config: ... | فایل client.toml وجود ندارد یا فرمت آن اشتباه است. | مطمئن شوید فایل کانفیگ در کنار برنامه است و دستور را درست وارد کردهاید (-config). |
Failed to generate keys: ... | (هنگام استفاده از -gen-keys) برنامه دسترسی نوشتن روی دیسک ندارد. | برنامه را با دسترسی Administrator/Root اجرا کنید یا در پوشهای دیگر تست کنید. |
Creating SECURE transport (TLS) | خطا نیست. نشان میدهد حالت امن (mTLS/TLS) فعال شده است. | - |
Creating INSECURE transport (h2c) | خطا نیست. نشان میدهد حالت ناامن (Cleartext) فعال است. | اگر قصد امنیت دارید، فایل کانفیگ را چک کنید که کلیدها پر شده باشند. |
WARNING: server_public_key NOT SET... | شما private_key دارید اما server_public_key را خالی گذاشتهاید. | برای جلوگیری از حملات MITM، حتماً کلید عمومی سرور را در client.toml وارد کنید. |
Failed to load private key: ... | فایل کلید خصوصی (مثلاً client.private.key) پیدا نشد. | مسیر فایل را در client.toml چک کنید. آیا فایل وجود دارد؟ |
[Transport] TLS Fingerprint Spoofing: chrome | خطا نیست. نشان میدهد کلاینت با موفقیت اثرانگشت مرورگر را تقلید میکند. | وضعیت عادی است. |
[Transport] Security Mode: INSECURE TLS | خطا نیست. نشان میدهد شما از حالت Insecure TLS استفاده میکنید و سرتیفیکت سرور بررسی نمیشود. | اگر سرور شما CDN ندارد این حالت پیشنهاد میشود. برای امنیت بیشتر One-Way TLS را ببینید. |
[Token] Security Mode: Token Auth ENABLED | خطا نیست. نشانگر آن است که کلاینت توکن auth_token را بارگذاری کرده است. | - |
ب. خطاهای اتصال و شبکه (Runtime)
| پیام لاگ (Log Message) | علت احتمالی | راه حل |
|---|---|---|
Failed to dial server: connection refused | سرور خاموش است یا پورت اشتباه وارد شده. | سرور را چک کنید که روشن باشد (./phoenix-server). پورت remote_addr را در کلاینت چک کنید. |
Failed to dial server: i/o timeout | فایروال سرور یا شبکه ایران پورت را بسته است. | پورت سرور را عوض کنید. فایروال سرور (ufw) را چک کنید. |
server key verification failed. Expected X, Got Y | خیلی مهم: سرور شما جعلی است یا کلید در کانفیگ اشتباه است. | کلید عمومی سرور (public key) را در client.toml چک کنید. اگر کلید درست است، احتمالاً تحت حمله MITM هستید! |
Failed to listen on 127.0.0.1:1080... | پورت ۱۰۸۰ توسط برنامه دیگری (مثلاً یک VPN دیگر) اشغال شده است. | در client.toml مقدار local_addr را به پورتی دیگر (مثلاً 1085) تغییر دهید. |
SOCKS5 Handler Error: ... | مرورگر یا تلگرام ارتباط را قطع کرد یا خطا داد. | اگر این خطا زیاد تکرار میشود، یعنی ارتباط با اینترنت ناپایدار است. |
Error: Shadowsocks inbound found but 'auth' is empty | (هنگام -get-ss) پسورد شادوساکس در کانفیگ خالی است. | برای اینباند شادوساکس، فیلد auth را با فرمت method:password پر کنید. |
tls: peer doesn't support any of the certificate's signature algorithms | ناسازگاری utls (مثل Chrome) با سرتیفیکت سرور (Ed25519). | وقتی fingerprint روشن است، سرور نمیتواند برای سرتیفیکت TLS کلید Ed25519 استفاده کند. (به بخش معماری قسمت ۶ مراجعه کنید). |
stream error: stream ID 1; HTTP_1_1_REQUIRED | کلاینت انتظار HTTP/2 دارد اما سرور/فیلترینگ HTTP/1.1 جواب میدهد. | معمولاً سیستم فیلترینگ یا پروکسی بین راه (CDN نامناسب) در حال تغییر ترافیک به HTTP/1.1 است. |
Token mismatch | توکن تنظیم شده در کلاینت با توکن سرور همخوانی ندارد. | فایل auth_token را در هر دو سمت (سرور و کلاینت) بررسی کنید. |
۲. خطاهای سمت سرور (Server Side)
این پیامها را در ترمینال VPS مشاهده میکنید.
الف. خطاهای عمومی
| پیام لاگ (Log Message) | علت احتمالی | راه حل |
|---|---|---|
Failed to load config: ... | فایل server.toml پیدا نشد یا خراب است. | فایل کانفیگ را چک کنید. |
Starting Phoenix Server on :443 | خطا نیست. سرور با موفقیت روی پورت ۴۴۳ روشن شد. | - |
Server failed: listen tcp :443: bind: access denied | سرور اجازه دسترسی به پورتهای زیر ۱۰۲۴ را ندارد. | سرور را با sudo اجرا کنید یا پورت را بالای ۱۰۲۴ (مثلاً 8443) بگذارید. |
Server failed: listen tcp :443: bind: address already in use | برنامه دیگری (مثل Nginx یا Apache) روی این پورت فعال است. | آن برنامه را متوقف کنید یا پورت ققنوس را تغییر دهید. |
ب. خطاهای امنیتی (Security)
| پیام لاگ (Log Message) | علت احتمالی | راه حل |
|---|---|---|
Client authentication failed | (در حالت mTLS) کلاینت کلید خصوصی معتبر ندارد. | کلید عمومی کلاینت را در authorized_clients سرور اضافه کنید. |
Handshake error: remote error: bad certificate | کلاینت گواهی نامعتبر فرستاده یا کلیدها همخوانی ندارند. | مطمئن شوید جفت کلیدهای کلاینت و سرور با هم ست هستند (Ed25519). |
http2: server: error reading preface from client | کلاینت دارد با پروتکل غیر HTTP/2 (مثلاً مرورگر عادی یا اسکنر) وصل میشود. | این معمولاً نشاندهنده Probing توسط فیلترچی است و سرور به درستی ارتباط را قطع کرده است. |
request rejected: invalid auth token | توکن کلاینت ارسال شده صحیح نیست یا خالی است. | مطمئن شوید auth_token کلاینت دقیقاً با سرور یکی باشد. کلاینت متخلف مسدود شد. |
۳. سناریوهای معمول و راهکارها
سناریو ۱: برنامه وصل میشود اما سایتهایی مانند یوتیوب باز نمیشوند
- علت: احتمالاً
enable_udpدر سرور خاموش است ولی کلاینت سعی دارد UDP بفرستد، یا DNS مشکل دارد. - راه حل: در مرورگر چک کنید آیا سایتهای HTTP باز میشوند؟ اگر فقط تلگرام باز میشود،
enable_udpرا چک کنید.
سناریو ۲: سرعت صفر است یا ارتباط قطع و وصل میشود
- علت: پکت لاس شدید در شبکه یا مسدود شدن پورت.
- راه حل: پورت سرور را تغییر دهید. از حالت mTLS استفاده کنید تا شناسایی نشوید.
سناریو ۳: ارور bad certificate دریافت میکنم
- علت: کلیدهای کلاینت و سرور با هم مچ نیستند.
- راه حل: یکبار دیگر با
-gen-keysکلید بسازید و دقیقاً طبق راهنما کپیپیست کنید. دقت کنید که کلید عمومی سرور باید در کلاینت باشد و برعکس (برای mTLS).
سناریو ۴: ارور tls: peer doesn't support signature algorithms در کروم Fingerprint
- علت: شما
fingerprint = "chrome"را روشن کردهاید اما سرور از سرتیفیکت Ed25519 استفاده میکند. (Chrome از Ed25519 برای سرتیفیکت TLS سرور پشتیبانی نمیکند). - راه حل:
- یا
fingerprintرا خاموش کنید. - یا در سرور یک کلید ECDSA بسازید (درحالحاضر ققنوس از طریق سورسکد از آن پشتیبانی میکند ولی برای تولید دستی باید از openssl استفاده کنید). پیشنهاد سادهتر استفاده از
safariیاfirefoxیا خاموش کردن این گزینه است.
- یا
سناریو ۵: ترافیک من کلاً بعد از چند ثانیه قطع (Drop) میشود
- علت: سیستم DPI اپراتور شما متوجه غیرمعمول بودن ترافیک (اثرانگشت کتابخانه Go) شده و پکتها را دراپ میکند.
- راه حل: مطمئن شوید قابلیت
fingerprint = "chrome"فعال باشد وtls_modeرویinsecureتنظیم شده باشد (در صورتی که CDN ندارید). این باعث میشود ترافیک شما کاملاً شبیه یک مرورگر واقعی به نظر برسد.