اتصال VS Code Remote SSH به سرور؛ رفع خطای دانلود

خطای «Downloading VS Code Server» که روی سرور ایران تمام نمی‌شود، تقصیر VS Code Remote SSH نیست؛ افزونه فقط نمی‌تواند بسته سمت سرور را دانلود کند. مستندات رسمی دو مسیر برای همین حالت دارد: دانلود بسته روی سیستم خودتان و انتقال آن با SSH، یا گذاشتن دستی همان بسته با commit id هم‌نسخه در پوشه مورد انتظار.

پرسش	پاسخ کوتاه
سرور چه چیزی را اجرا می‌کند؟	بسته‌ای به نام VS Code Server که افزونه خودش روی سیستم‌عامل سرور نصب می‌کند.
ریشه خطای دانلود کجاست؟	نصب این بسته به دسترسی HTTPS روی پورت 443 به update.code.visualstudio.com و vscode.download.prss.microsoft.com نیاز دارد.
راه‌حل مستندشده اول	تنظیم remote.SSH.localServerDownload تا بسته روی سیستم شما دانلود و با SSH منتقل شود.
راه‌حل مستندشده دوم	گذاشتن بسته هم‌نسخه در ~/.vscode-server/bin/COMMIT روی خود سرور.
حداقل منابع سرور	یک گیگابایت رم، با bash و tar و curl یا wget.

بیشتر راهنماهای این موضوع از نصب افزونه شروع می‌کنند و همان‌جا هم تمام می‌شوند، چون روی یک لپ‌تاپ با اینترنت باز همه‌چیز در چند ثانیه کار می‌کند. شروع ما جای دیگری است: همان لحظه‌ای که نوار پیشرفت دانلود روی سرور تهران می‌ایستد. اول معماری، بعد کلید و فایل config، و در پایان سه راه مستندشده برای رد کردن مرحله دانلود.

معماری VS Code Remote SSH و پیش‌نیازهای سرور

افزونه، بسته‌ای به نام VS Code Server را روی سیستم‌عامل سرور نصب می‌کند و مستندات تصریح می‌کند این بسته از هر نصب دیگری از ویرایشگر روی آن ماشین مستقل است. فایل‌ها، ترمینال و افزونه‌های زبانی روی سرور اجرا می‌شوند و لپ‌تاپ فقط رابط کاربری را نشان می‌دهد.

چه چیزی روی سرور اجرا می‌شود و چه چیزی روی لپ‌تاپ

این تفکیک علت خطای دانلود را هم توضیح می‌دهد:

• روی سرور: بسته سرور، ترمینال، ایندکس پروژه و افزونه‌هایی که مستندات آن‌ها را workspace می‌نامد.
• روی لپ‌تاپ: پنجره ویرایشگر، تم‌ها و افزونه‌های رابط کاربری (ui).
• روی مرحله نصب: دانلود بسته سرور، که اول روی خود سرور و بعد روی سیستم محلی امتحان می‌شود.

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

پیش‌نیازهای سیستمی سرور لینوکسی

مستندات رسمی حداقل‌ها را دقیق نوشته و همین جدول بیشتر خطاهای «اتصال برقرار نشد» را قبل از وقوع حل می‌کند. اعداد ستون دوم از همان مستندات است.

مورد	حداقل اعلام‌شده	توضیح
رم	1 گیگابایت	پیشنهاد مستندات: دو گیگابایت و دو هسته.
ابزارهای پایه	ابزار bash و tar و curl یا wget	مسیر /bin/bash باید وجود داشته باشد.
کرنل و کتابخانه‌ها	کرنل 4.18، glibc 2.28، libstdc++ 3.4.25	برای 1.99.x و جدیدتر binutils 2.29 هم لازم است.
توزیع	توزیع‌های مبتنی بر glibc	توزیع Alpine Linux پشتیبانی نمی‌شود.
معماری	معماری x86_64 یا ARM64	ARM سی‌ودو بیتی تا نسخه 1.122.
سرویس SSH	سرویس sshd فعال	پورت عمومی دیگری لازم نیست.

نصب افزونه، ساخت کلید SSH و فایل config

مسیر مستندشده سه قدم دارد: نصب افزونه Remote – SSH، تست دستی دسترسی با دستور ssh در ترمینالی معمولی، و بعد اجرای فرمان «Remote-SSH: Connect to Host». ورود با کلید اجباری نیست، اما رمز ذخیره نمی‌شود؛ پس برای کار روزمره کلید بسازید.

نصب افزونه و اولین اتصال

1. افزونه Remote – SSH را نصب کنید؛ روی سیستم شما یک کلاینت سازگار با OpenSSH هم لازم است.
2. در ترمینال معمولی دستور ssh user@host را اجرا کنید و مطمئن شوید ورود جواب می‌دهد.
3. فرمان «Remote-SSH: Connect to Host» را اجرا کنید و میزبان را انتخاب کنید.
4. اگر سیستم‌عامل سرور تشخیص داده نشد، پلتفرم را دستی انتخاب کنید؛ انتخابتان در remote.SSH.remotePlatform ذخیره می‌شود.
5. پیشرفت کار را در کانال خروجی Remote – SSH ببینید.

تنظیم‌های اتصال در VS Code Remote SSH از همان فایل config استاندارد SSH خوانده می‌شود و با remote.SSH.configFile می‌توانید فایل دیگری بدهید. اگر پیش‌تر پورت SSH سرورتان را عوض کرده‌اید، همان پورت را در ورودی Host بنویسید؛ تغییر پورت SSH سرور مجازی جزئیات سمت سرور را دارد.

ساخت کلید ed25519 و درست کردن مجوز فایل‌ها

اول ببینید کلید دارید یا نه (معمولاً ~/.ssh/id_ed25519.pub). مستندات پیشنهاد می‌کند برای ماشین‌های توسعه یک کلید جدا بسازید تا لو رفتن یک کلید همه میزبان‌ها را باز نکند:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519-remote-ssh
chmod 400 ~/.ssh/id_ed25519-remote-ssh
ssh-copy-id -i ~/.ssh/id_ed25519-remote-ssh.pub deploy@203.0.113.10

سمت سرور مجوزها اهمیت دارد: پوشه ~/.ssh با 700 و ~/.ssh/authorized_keys با 600. روی سیستم خودتان ~/.ssh با 700 و فایل config و کلیدها با 600. هشدار UNPROTECTED PRIVATE KEY FILE دقیقاً از باز بودن همین مجوزها می‌آید. اگر با مفاهیم پایه تازه آشنا می‌شوید، آموزش اتصال به سرور با SSH قدم اول خوبی است.

ورودی Host در فایل config و نقش ssh-agent

با فرمان «Remote-SSH: Open SSH Configuration File…» فایل config را باز کنید و میزبان را یک بار بنویسید (مقدار Port در نمونه زیر فقط یک مثال است):

Host dev-tehran
  HostName 203.0.113.10
  User deploy
  Port 2222
  IdentityFile ~/.ssh/id_ed25519-remote-ssh
  LocalForward 127.0.0.1:3000 127.0.0.1:3000

اگر کلیدتان عبارت عبور دارد، ssh-agent را روی سیستم خودتان بالا نگه دارید: در لینوکس با eval “$(ssh-agent -s)” و در ویندوز با سرویس ssh-agent روی حالت خودکار؛ فهرست کلیدها را با ssh-add -l ببینید. ForwardAgent yes همان agent را روی سرور در دسترس می‌گذارد، ولی فقط برای میزبانی بگذاریدش که به ادمینش اعتماد دارید.

رفع خطای دانلود VS Code Server روی سرور داخلی

نصب بسته سرور به دسترسی HTTPS روی پورت 443 به update.code.visualstudio.com و vscode.download.prss.microsoft.com نیاز دارد. افزونه اول آن را روی خود سرور امتحان می‌کند و اگر نشد، به دانلود روی سیستم محلی و انتقال با SSH برمی‌گردد.

در VS Code Remote SSH سه راه مستندشده برای همین حالت وجود دارد و ترتیبشان مهم است. اول لاگ را بخوانید تا بدانید کار کجا ایستاده؛ بعد محل دانلود را عوض کنید؛ بعد بسته را دستی سر جایش بگذارید؛ و اگر هیچ‌کدام جواب نداد، پوشه نیمه‌کاره را پاک کنید.

قدم صفر: خواندن لاگ افزونه و لاگ سمت سرور

فرمان «Remote-SSH: Show Log» کانال خروجی افزونه را باز می‌کند و خطاهایی را نشان می‌دهد که در رابط کاربری دیده نمی‌شوند. داخل همان لاگ عبارت Running ssh connection command را پیدا کنید؛ دستور بعدش همان چیزی است که افزونه اجرا کرده و می‌توانید عیناً در ترمینال امتحانش کنید. لاگ سمت سرور دو مسیر دارد و تنظیم remote.SSH.useExecServer تعیین می‌کند کدام فعال است. مقدار پیش‌فرض آن true است، پس مسیر فعال امروز ~/.vscode-server/cli/servers/*/log.txt است؛ با مقدار false، لاگ در فایلی به نام.<commit id>.log داخل ~/.vscode-server می‌نشیند. دنبال نام ثابت نگردید:

ls -1 ~/.vscode-server/cli/servers/*/log.txt 2>/dev/null
ls -1a ~/.vscode-server/.*.log 2>/dev/null

راه اول: دانلود روی سیستم خودتان به‌جای سرور

تنظیم remote.SSH.localServerDownload دقیقاً برای همین کار است. مقدار پیش‌فرض auto اول سرور را امتحان می‌کند؛ با مقدار always دانلود را به سیستم خودتان می‌سپارید. این را در settings.json همان سیستمی بگذارید که ویرایشگر رویش باز است، نه روی سرور:

{
  "remote.SSH.localServerDownload": "always"
}

بعد از ذخیره، پنجره را Reload کنید یا فرمان «Remote-SSH: Kill VS Code Server on Host» را بزنید تا تنظیم روی اتصال بعدی اثر کند. شرط کار کردن این مسیر آن است که لپ‌تاپ شما به دو دامنه بالا دسترسی داشته باشد؛ اگر ندارد، سراغ راه دوم بروید.

راه دوم: گذاشتن بسته هم‌نسخه در پوشه مورد انتظار

صفحه FAQ مستندات صریح می‌گوید بسته سرور را خود ویرایشگر مدیریت و به‌روز می‌کند و نصب جداگانه را توصیه نمی‌کند. پس این راه دوم است و با هر به‌روزرسانی ویرایشگر باید تکرار شود. بسته هر نسخه با commit id همان نسخه شناخته می‌شود.

1. شناسه commit نسخه خودتان را از لاگ Remote-SSH بردارید؛ مسیر پوشه سرور در لاگ همین رشته را در خود دارد.
2. فایل vscode-server-linux-x64.tar.gz همان commit را دانلود کنید (برای ARM64 نام معماری را عوض کنید).
3. دستورهای زیر را روی خود سرور اجرا کنید، نه روی لپ‌تاپ.
4. اتصال را دوباره بگیرید؛ افزونه بسته آماده را پیدا و مرحله دانلود را رد می‌کند.

نشانی دانلود الگوی ثابتی دارد. هنگام نگارش این راهنما (آبان ۱۴۰۵) همین نشانی برای کانال stable به بسته نسخه 1.143.1 با commit برابر e646868227c3e3a9e3f24277c8c7220be42c0be7 می‌رسید:

# COMMIT را با commit نسخه ویرایشگر خودتان عوض کنید
COMMIT=e646868227c3e3a9e3f24277c8c7220be42c0be7
mkdir -p ~/.vscode-server/bin/$COMMIT
curl -fL "https://update.code.visualstudio.com/commit:$COMMIT/server-linux-x64/stable" -o /tmp/vscode-server.tar.gz
sha256sum /tmp/vscode-server.tar.gz
tar -xzf /tmp/vscode-server.tar.gz -C ~/.vscode-server/bin/$COMMIT --strip-components 1
ls ~/.vscode-server/bin/$COMMIT/bin

فلگ -f در curl لازم است؛ بدون آن پاسخ خطا هم به شکل فایل ذخیره می‌شود و tar با پیامی گمراه‌کننده می‌شکند. خروجی sha256sum را با هدر x-sha256 همان نشانی مقایسه کنید.

راه سوم: پاک‌کردن پوشه نیمه‌کاره سرور

یک دانلود نصفه‌کاره پوشه‌ای به جا می‌گذارد که دفعه بعد هم خراب می‌ماند. دو فرمان یک کار نمی‌کنند: «Remote-SSH: Kill VS Code Server on Host» سرور را برمی‌دارد، اما فرمانی که مستندات برای حذف پوشه نصب معرفی کرده «Remote-SSH: Uninstall VS Code Server from Host…» است. معادل دستی دومی:

kill -9 $(ps aux | grep vscode-server | grep $USER | grep -v grep | awk '{print $2}')
rm -rf $HOME/.vscode-server

دو نکته که ندانستنشان وقت زیادی می‌گیرد. اگر پارتیشن /tmp با گزینه noexec سوار شده باشد نصب شکست می‌خورد، چون اسکریپت نصب در پوشه موقت سیستم نوشته و از همان‌جا اجرا می‌شود. و اگر.bash_profile شما شل دیگری را اجرا کند، راه درست عوض کردن شل با chsh است.

یک خطای دیگر هم شکل عجیبی دارد: پیام open failed: administratively prohibited در لاگ. مستندات می‌گوید AllowTcpForwarding yes را در /etc/ssh/sshd_config بگذارید و sshd را ری‌استارت کنید.

تنظیم یا فرمان	کاری که می‌کند	کِی سراغش بروید
remote.SSH.localServerDownload	محل دانلود بسته را بین سرور و سیستم محلی جابه‌جا می‌کند (auto، always، off).	سرور به منبع دانلود نمی‌رسد ولی لپ‌تاپ می‌رسد.
remote.SSH.useExecServer	تعیین می‌کند لاگ سمت سرور کدام مسیر را بگیرد؛ پیش‌فرضش true است.	دنبال فایل لاگ سرور می‌گردید.
remote.SSH.showLoginTerminal	ترمینال را هنگام اجرای دستورهای ssh نشان می‌دهد.	باید رمز یا توکن یا عبارت عبور وارد کنید.
remote.SSH.useLocalServer	حالت اتصال را بین Local Server و Terminal عوض می‌کند.	اتصال معلق می‌ماند یا میزبان ویندوزی غلط تشخیص داده شده است.
Remote-SSH: Uninstall VS Code Server from Host…	پروسه‌ها را می‌کشد و پوشه نصب را حذف می‌کند.	نصب قبلی نصفه مانده است.

اجرای پروژه، ارسال پورت و محدودیت‌های واقعی

بعد از اتصال، ترمینال یکپارچه ویرایشگر روی سرور باز می‌شود و همان دستورهای همیشگی را همان‌جا اجرا می‌کنید. برای دیدن خروجی پروژه در مرورگر لپ‌تاپ، فرمان Forward a Port یا پنل Ports را به کار ببرید.

ارسال پورت برای دیدن پروژه در مرورگر محلی

سرویس توسعه را روی سرور بالا می‌آورید، مثلاً روی پورت 3000. بعد با فرمان Forward a Port همان پورت را به سیستم خودتان می‌آورید. اگر پورت محلی اشغال باشد، با گزینه Change Local Address Port عوضش می‌کنید. با خط LocalForward 127.0.0.1:3000 127.0.0.1:3000 در فایل config هم می‌شود دائمی‌اش کرد.

نصب افزونه‌ها روی سرور

افزونه‌های زبانی باید سمت سرور نصب شوند و نصبشان به دسترسی به marketplace.visualstudio.com و *.gallerycdn.vsassets.io نیاز دارد. تنظیم remote.SSH.defaultExtensions فهرست شناسه افزونه‌ها را روی هر میزبان نصب می‌کند و فرمان «Extensions: Install from VSIX…» همان مسیر مستندشده نصب بدون اینترنت است.

محدودیت‌هایی که بهتر است از اول بدانید

محدودیت‌های VS Code Remote SSH را مستندات رسمی خودش شمرده و پنهان نکرده است:

• روی Alpine Linux و توزیع‌های غیر glibc کار نمی‌کند؛ هیچ تنظیمی این را حل نمی‌کند.
• روی میزبان با glibc پایین‌تر از 2.28 بسته‌های آماده اجرا نمی‌شوند؛ مستندات اتصال را فقط با فراهم بودن یک sysroot ممکن می‌داند و همان را سناریوی رسماً پشتیبانی‌شده نمی‌نامد.
• بعضی افزونه‌ها کد بومی x86 دارند و روی میزبان ARM اجرا نمی‌شوند.
• گزینه Remote Server Listen On Socket به OpenSSH 6.7 یا بالاتر در دو سر نیاز دارد و روی میزبان ویندوزی کار نمی‌کند.
• لایسنس بسته سرور تک‌کاربره است و میزبانی آن به شکل سرویس اجازه ندارد.

جایگزین‌ها؛ code-server و JetBrains Gateway

اگر این مسیر برای تیم شما جا نیفتاد، دو نام دیگر را هم بشناسید: code-server که ویرایشگر را در مرورگر اجرا می‌کند، و JetBrains Gateway. سنجیدنشان را به مستندات خودشان بسپارید؛ این مقاله درباره افزونه رسمی مایکروسافت است.

پرسش‌هایی که بیشتر تکرار می‌شوند:

جمع‌بندی؛ خطای دانلود مال افزونه نیست، مال یک فایل است کار VS Code Remote SSH در یک جمله خلاصه می‌شود: یک بسته باید از نشانی رسمی روی سرور بنشیند و بقیه ماجرا یک نشست SSH است. ترتیب عیب‌یابی هم همین را دنبال می‌کند. اول با یک ترمینال معمولی ثابت کنید اتصال SSH سالم است. بعد لاگ افزونه و لاگ سمت سرور را باز کنید؛ مسیر لاگ سرور را خود افزونه چاپ می‌کند و با تنظیم پیش‌فرض، زیر ~/.vscode-server/cli/servers است. اگر کار در مرحله دانلود ایستاده بود، محل دانلود را با remote.SSH.localServerDownload به سیستم خودتان بسپارید. اگر آن هم ممکن نبود، بسته هم‌نسخه را با commit درست در ~/.vscode-server/bin بگذارید و چک‌سامش را بسنجید. و هر وقت نصب نصفه ماند، با فرمان Uninstall پوشه را حذف کنید و از صفر بروید. دو چیز را عوض نکنید: منبع دانلود بسته، و مجوز فایل‌های کلید.

اگر سوالی داشتید، در بخش نظرات با ما در ارتباط باشید.

منابع

• مستندات رسمی VS Code، صفحه Remote Development using SSH
• مستندات رسمی VS Code، صفحه Remote Development Tips and Tricks
• مستندات رسمی VS Code، صفحه Remote Development FAQ
• مستندات رسمی VS Code، صفحه Network Connections in Visual Studio Code
• ویکی مخزن microsoft/vscode-remote-release، صفحه Remote SSH Troubleshooting (به دلیل سقف لینک بیرونی، بدون لینک)