VS Code 远程连接 Linux 服务器 SSH 详细配置教程 从零开始解决连接超时与密钥认证问题

引言
Visual Studio Code (VS Code) 是一款功能强大的源代码编辑器,它通过 Remote – SSH 扩展提供了无缝的远程开发体验。这意味着你可以在本地计算机上使用 VS Code 的图形界面,而代码实际运行、文件存储、调试都在远程的 Linux 服务器上。这种模式极大地提高了开发效率,特别是对于需要特定环境或高性能计算资源的项目。
本教程将从零开始,详细指导你如何配置 VS Code 通过 SSH 连接到 Linux 服务器。我们将涵盖基础的 SSH 配置、密钥认证的设置,并重点解决常见的连接超时和认证失败问题。
1. 前置准备
在开始之前,请确保你满足以下条件:
本地计算机
:安装了最新版本的 VS Code。
Linux 服务器
:你拥有服务器的访问权限,包括 IP 地址、用户名和密码(或密钥)。
网络连接
:本地计算机可以访问到远程服务器的 SSH 端口(默认为 22)。
2. 安装 Remote – SSH 扩展
首先,我们需要在 VS Code 中安装 Remote – SSH 扩展。
打开 VS Code。
点击左侧活动栏中的
扩展
图标(或按
Ctrl+Shift+X
)。
在搜索框中输入
Remote – SSH
。
找到由 Microsoft 发布的 “Remote – SSH” 扩展,点击
安装
。
安装完成后,你会在左侧活动栏看到一个新的
远程资源管理器
图标(一个带有两个电脑屏幕的图标)。
3. 配置 SSH 连接
3.1. 生成 SSH 密钥对(推荐)
使用 SSH 密钥认证比密码认证更安全、更方便,因为它可以避免每次连接都输入密码,并且可以防止暴力破解。
在本地计算机上生成 SSH 密钥:
打开本地计算机的终端(Windows 用户可以使用 PowerShell 或 Git Bash)。
运行以下命令生成密钥对:
ssh-keygen -t rsa -b 4096 -C “your_email@example.com”
-t rsa
: 指定密钥类型为 RSA。
-b 4096
: 指定密钥长度为 4096 位,更安全。
-C
: 添加注释,通常是你的邮箱。
系统会提示你输入保存密钥的文件名和密码(可选,但推荐设置密码以增加安全性)。默认情况下,私钥保存在
~/.ssh/id_rsa
,公钥保存在
~/.ssh/id_rsa.pub
。
3.2. 将公钥复制到远程服务器
将本地生成的公钥添加到远程服务器的
~/.ssh/authorized_keys
文件中。
方法一:使用
ssh-copy-id
命令(如果本地是 Linux 或 macOS,或安装了 Git Bash)
ssh-copy-id -i ~/.ssh/id_rsa.pub username@remote_host
username
: 你的远程服务器用户名。
remote_host
: 远程服务器的 IP 地址或域名。
方法二:手动复制
在本地终端显示公钥内容:
cat ~/.ssh/id_rsa.pub
复制输出的所有内容。
登录到远程服务器(使用密码)。
在远程服务器上执行:
mkdir -p ~/.ssh
echo “粘贴你复制的公钥内容” >> ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
3.3. 配置 SSH Config 文件
VS Code 使用 OpenSSH 的配置文件来管理连接。我们需要编辑本地的 SSH 配置文件。
在 VS Code 中,按
F1
或
Ctrl+Shift+P
打开命令面板。
输入
Remote-SSH: Open SSH Configuration File…
并选择它。
通常会提示你选择
~/.ssh/config
文件。如果不存在,可以创建一个。
在打开的
config
文件中,添加以下内容:
Host my-remote-server
HostName 192.168.1.100
User your_username
IdentityFile ~/.ssh/id_rsa
Port 22
Host
: 一个别名,用于在 VS Code 中识别这个连接。
HostName
: 远程服务器的真实 IP 地址或域名。
User
: 用于登录的用户名。
IdentityFile
: 指向你本地的私钥文件路径。
Port
: SSH 服务的端口号,默认为 22。
4. 连接到远程服务器
点击 VS Code 左侧的
远程资源管理器
图标。
在 “SSH” 部分,你应该能看到我们刚刚配置的
my-remote-server
。
点击它旁边的
连接到主机
按钮(一个绿色的箭头)。
VS Code 会打开一个新的窗口,并尝试连接。首次连接时,可能会提示你确认远程主机的指纹,输入
yes
即可。
如果一切顺利,你会看到左下角显示绿色的 “SSH: my-remote-server”,并且可以打开远程服务器上的文件夹进行开发。
5. 解决常见问题
5.1. 连接超时 (Connection Timed Out)
症状
:连接过程中长时间无响应,最终报错 “Connection timed out”。
原因及解决方案
:
网络问题
:
检查 IP 和端口
:确保
config
文件中的
HostName
和
Port
正确无误。
Ping 测试
:在本地终端运行
ping your_server_ip
,看是否能通。
Telnet 测试端口
:运行
telnet your_server_ip 22
(或你的 SSH 端口),如果显示 “Connected” 说明端口是通的。如果卡住或拒绝连接,则是网络或防火墙问题。
服务器防火墙
:
检查远程服务器的防火墙设置,确保 SSH 端口(默认 22)是开放的。
对于 Ubuntu/Debian,可以使用
sudo ufw allow 22
。
对于 CentOS/RHEL,可以使用
sudo firewall-cmd –permanent –add-port=22/tcp
和
sudo firewall-cmd –reload
。
SSH 服务未运行
:
在远程服务器上运行
sudo systemctl status sshd
检查 SSH 服务状态。如果未运行,使用
sudo systemctl start sshd
启动它。
5.2. 密钥认证失败 (Permission Denied (publickey))
症状
:连接时提示 “Permission denied (publickey)“。
原因及解决方案
:
权限问题
:
本地私钥权限
:确保本地私钥文件权限正确。在本地终端运行:
chmod 600 ~/.ssh/id_rsa
远程
.ssh
目录和
authorized_keys
文件权限
:
# 在远程服务器上执行
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
公钥未正确添加
:
再次检查远程服务器上的
~/.ssh/authorized_keys
文件,确保公钥内容完整且没有多余的空格或换行。
SSH 配置文件错误
:
检查
~/.ssh/config
文件中的
IdentityFile
路径是否正确,文件名是否拼写错误。
服务器 SSH 配置限制
:
检查远程服务器的
/etc/ssh/sshd_config
文件:
确保
PubkeyAuthentication yes
。
确保
AuthorizedKeysFile .ssh/authorized_keys
没有被注释或修改。
如果修改了此文件,需要重启 SSH 服务:
sudo systemctl restart sshd
。
5.3. VS Code 无法解析主机名
症状
:报错 “Could not resolve hostname”。
原因及解决方案
:
DNS 问题
:如果
HostName
使用的是域名而不是 IP 地址,确保本地计算机可以正确解析该域名。
拼写错误
:仔细检查
config
文件中的
HostName
和
Host
别名是否有拼写错误。
6. 高级配置与技巧
6.1. 使用跳板机 (Bastion Host / Jump Host)
如果你的服务器位于内网,需要通过一台跳板机访问,可以在
config
文件中配置:
Host bastion
HostName bastion.example.com
User bastion_user
IdentityFile ~/.ssh/bastion_key

Host internal-server
HostName 10.0.0.5
User internal_user
IdentityFile ~/.ssh/internal_key
ProxyJump bastion
6.2. 保持 SSH 连接活跃
长时间不操作可能导致连接断开。可以在
config
文件中添加:
Host my-remote-server
# … 其他配置 …
ServerAliveInterval 60
ServerAliveCountMax 3
ServerAliveInterval 60
: 每 60 秒向服务器发送一个保持活跃的信号。
ServerAliveCountMax 3
: 如果服务器连续 3 次没有响应,则断开连接。
6.3. 在 VS Code 中管理多个服务器
你可以在
config
文件中添加多个
Host
块来管理多个远程服务器。VS Code 的远程资源管理器会列出所有配置的主机,方便你快速切换。
7. 总结
通过以上步骤,你应该能够成功配置 VS Code 通过 SSH 连接到 Linux 服务器,并解决了常见的连接超时和密钥认证问题。使用密钥认证和正确的权限设置是确保连接稳定和安全的关键。如果遇到问题,请仔细检查每一步的配置和网络状态。