Windows 远程开发到 Linux 服务器（vs Code/cursor + Docker）极其详细通用笔记
适用场景与目标
-
场景：用 Windows 电脑，远程连接到一台 Linux 服务器（已安装 Docker），希望用 VS Code 或 Cursor 进行“像本地一样”的开发（编辑、调试、运行、端口转发等）。
-
目标：
-
用 SSH 安全连接远程主机；
-
在远端使用 Docker 容器进行开发；
-
在 VS Code/Cursor 中获得完整的 IDE 体验（扩展、终端、调试、端口转发、Git 等）；
-
全流程“极其详细”，每一步都不省略，且通用。
-
总览：两种推荐工作流（任选其一）
工作流 A（最推荐）：Remote-SSH → 在远端打开项目 → Dev Containers 重开到容器
-
优点：不要求本机装 Docker；VS Code Server 在远端运行，直接调用远端 Docker，性能最好。
工作流 B（备选）：本机装 Docker Desktop → 配置 Docker Context/SSH → Dev Containers 在远端构建/运行
-
优点：无需通过 Remote-SSH 打开远端文件；
-
缺点：配置更复杂，易踩坑。若非特殊需要，优先用 A。
下文按顺序完整讲解 前置准备 → 工作流 A（主线）→ 工作流 B（备选）→ 常见问题 → 最佳实践。
一、前置准备（Windows 端 & 服务器端）
1. Windows 端必备
-
安装 VS Code 或 Cursor（二选一，建议两者都能用）：
-
VS Code：Visual Studio Code - Code Editing. Redefined
-
Cursor：Cursor - The AI Code Editor
-
-
安装/启用 OpenSSH 客户端（Windows 10/11 通常已内置）：
-
打开 设置 → 应用 → 可选功能，确认“OpenSSH Client”已安装；如未安装，点“添加可选功能”安装。
-
-
安装 Git（可选但强烈建议）： Redirecting…
-
安装后在 PowerShell 里确认：
git --version ssh -V
-
-
（可选）安装 Windows Terminal：提升终端体验：Windows Terminal
2. 生成 SSH 密钥（Windows 端）
推荐 ed25519 算法，短小安全。
-
打开 PowerShell（非管理员即可）。
-
生成密钥：
ssh-keygen -t ed25519 -C "your_email@example.com"-
按提示选择保存路径（默认
C:Users<你的用户名>.sshid_ed25519），设置强密码（passphrase）。
-
-
启动并配置 ssh-agent（用于自动解锁密钥）：
# 启动一次性服务（当前会话） Start-Service ssh-agent # 将私钥加入 agent（输入你刚设置的密钥口令） ssh-add $env:USERPROFILE.sshid_ed25519 # 查看已加载密钥 ssh-add -l
3. 将公钥部署到远程服务器
目标：把
id_ed25519.pub的内容，追加到远端~/.ssh/authorized_keys。
方法 A（有 ssh-copy-id 环境）：
# 如果你在 WSL 或 Git Bash 中，可能有 ssh-copy-id 可用
ssh-copy-id -i $HOME/.ssh/id_ed25519.pub user@server_ip
方法 B（通用，纯 PowerShell）：
-
显示公钥：
Get-Content $env:USERPROFILE.sshid_ed25519.pub复制整行。
-
首次用密码登录服务器：
ssh user@server_ip -
在服务器上执行：
mkdir -p ~/.ssh && chmod 700 ~/.ssh echo "<粘贴你的公钥整行>" >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys -
退出：
exit
务必确认远端
~/.ssh权限为700、authorized_keys为600，否则 SSH 可能拒绝使用密钥。
4. 服务器端检查项（必须逐条确认）
-
Linux 用户与权限：
-
有一个非 root 用户（例如
dev）。 -
该用户在
sudoers里（能sudo）。
-
-
OpenSSH Server 已运行：
sudo systemctl status sshd # Debian/Ubuntu 可能是 ssh -
** Docker 已安装且可用**：
docker --version sudo docker info -
将你的非 root 用户加入 docker 组（避免每次都用 sudo）：
sudo usermod -aG docker $USER # 重新登录会话后生效，或临时： newgrp docker docker ps -
（可选）防火墙：开放 SSH 端口（默认 22），禁止对外暴露 Docker 守护进程的 TCP 端口（除非你明确要这么做，并配 TLS）。
-
（可选）SSH 安全加固：在
/etc/ssh/sshd_config中设置：-
PasswordAuthentication no（使用密钥登录）； -
PermitRootLogin no（禁止 root 直登）。
修改后：sudo systemctl reload sshd。
-
5. 测试纯 SSH 连接（Windows 端）
-
新建/编辑 SSH 配置文件：
C:Users<你>.sshconfigHost myserver HostName <服务器IP或域名> User <你的用户名> IdentityFile C:/Users/<你>/.ssh/id_ed25519 Port 22 ServerAliveInterval 30 ServerAliveCountMax 3 # 如需代理跳板： # ProxyJump bastion # 如有跳板机： Host bastion HostName <跳板机IP> UserIdentityFile C:/Users/<你>/.ssh/id_ed25519 -
连接测试：
ssh myserver第一次会提示保存主机指纹（known_hosts），输入
yes，能登录即通过。
二、VS Code 必装扩展（Cursor 同理）
-
Remote - SSH（ms-vscode-remote.remote-ssh）
-
Dev Containers（ms-vscode-remote.remote-containers）
-
Docker（ms-azuretools.vscode-docker）
-
语言相关扩展（Python、ESLint、Go、Java 等，按项目需要）
Cursor 基于 VS Code，扩展安装路径、用法几乎一致（在 Cursor 的扩展页搜索安装同名扩展）。
三、工作流 A（推荐）：Remote-SSH + Dev Containers
步骤 A1：通过 Remote-SSH 连接服务器
-
打开 VS Code，安装好 Remote - SSH 扩展。
-
左侧活动栏点击 远程资源管理器（或按
F1→ 输入Remote-SSH: Connect to Host...）。 -
选择 Add New SSH Host...，输入：
ssh myserver并选择要写入的
~/.ssh/config文件（选当前用户的）。 -
在主界面右下角的绿色远程图标（><）中选择 Connect to Host...，选
myserver。 -
首次连接会弹出 选择远端平台，选 Linux。
-
VS Code 会在远端安装 VS Code Server，等待完成（需要网络通畅）。
-
连接成功后，左下角会显示
SSH: myserver，说明已在远程环境。
步骤 A2：在远端打开项目目录
-
F1→Remote-SSH: Open Folder...，选择远端路径（例如：/home/dev/project）。 -
如果项目还不在服务器：
-
方案 1：在远端
git clone：cd /home/dev git cloneproject -
方案 2：用
scp/rsync从本地上传：# 例：把本地 D:codemyapp 上传到 /home/dev/project scp -r D:codemyapp myserver:/home/dev/project
-
步骤 A3：验证远端 Docker 正常
在 VS Code 集成终端（此时已是远端终端）执行：
docker info
docker ps
能看到正常输出即通过。如提示权限问题，回到前置准备第 4 步修复（加入 docker 组并重新登录）。
步骤 A4：使用 Dev Containers 在容器中开发
两种典型方式：
方式 1：项目内置
.devcontainer→ “在容器中重新打开”。**方式 2：附着到一个已运行的容器”。
方式 1：创建 .devcontainer 并“在容器中重新打开”
-
在项目根新建目录
.devcontainer/。 -
新建
devcontainer.json（最小可用示例 - 基于镜像）：{ "name": "myapp-dev", "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": {}, "remoteUser": "vscode", "customizations": { "vscode": { "extensions": [ "ms-azuretools.vscode-docker", "ms-python.python", "esbenp.prettier-vscode" ] } }, "postCreateCommand": "bash .devcontainer/postCreate.sh || true", "forwardPorts": [3000, 8000], "mounts": [ "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,consistency=cached" ] } -
（可选）同目录新建
Dockerfile（如果需要自定义依赖）：FROM mcr.microsoft.com/devcontainers/base:ubuntu # 安装系统依赖示例 RUN apt-get update && apt-get install -y curl ca-certificates build-essential git && rm -rf /var/lib/apt/lists/*并把
devcontainer.json改为：{ "name": "myapp-dev", "build": { "dockerfile": "Dockerfile" }, "remoteUser": "vscode" } -
（可选）
docker-compose方案（有多服务时）：-
新建
docker-compose.yml，并在devcontainer.json使用：{ "name": "myapp-dev", "dockerComposeFile": "../docker-compose.yml", "service": "app", "workspaceFolder": "/workspace", "remoteUser": "vscode", "forwardPorts": [3000] }
-
-
（可选）新建
.devcontainer/postCreate.sh用于一键装依赖：#!/usr/bin/env bash set -e if [ -f requirements.txt ]; then pip3 install -r requirements.txt fi if [ -f package.json ]; then npm install fi赋可执行：
chmod +x .devcontainer/postCreate.sh。 -
在 VS Code 命令面板执行：
Dev Containers: Reopen in Container（在容器中重新打开）。 -
等待构建/拉取镜像并启动容器。完成后，左下角会显示
Dev Container: myapp-dev，此时你的工作区已在容器内。
说明：由于你是“先 Remote-SSH 到服务器”，Dev Containers 会直接调用远端服务器上的 Docker，不需要本机 Docker。
方式 2：附着到已运行的容器
-
确保容器已在远端运行：
docker ps。 -
VS Code 左侧 Docker 面板 → 右键目标容器 → Attach Visual Studio Code（如果没有这个选项，有个小窍门，可以在vscode的欢迎界面点击连接到容器即可）。
-
VS Code 会在该容器中打开一个新的工作区窗口，直接开发/调试。
步骤 A5：端口转发（访问容器/远端服务）
-
在 VS Code 底部“端口”面板（Forwarded Ports）：
-
点击 Add Port，输入远端端口（如
3000）。 -
得到一个本地转发口（如
127.0.0.1:3000）。
-
-
命令行等价：
# 把远端 3000 转发到本地 3000 ssh -L 3000:localhost:3000 myserver -
若使用
docker-compose，确保服务监听0.0.0.0或对容器内部端口映射正确。
步骤 A6：远程调试（示例）
-
Node.js：在容器内启动：
node --inspect=0.0.0.0:9229 app.js；端口转发 9229；在 VS Code 新建launch.json：{ "version": "0.2.0", "configurations": [ { "type": "pwa-node", "request": "attach", "name": "Attach to Node", "address": "localhost", "port": 9229 } ] } -
Python（debugpy）：
python -m pip install debugpy python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py转发 5678，然后用 VS Code Python Debug 的“Attach”。
步骤 A7：Git 与凭据
-
首选：在远端配置你的 Git 身份：
git config --global user.name "Your Name" git config --global user.email "you@example.com" -
拉取/推送凭据：推荐在远端用 SSH Key 或 访问令牌（PAT）。
-
（可选）Agent 转发：在
~/.ssh/config为myserver增加ForwardAgent yes，并在本地确保ssh-agent已加载密钥。注意安全，仅在可信主机使用。 -
Windows 换行符：推荐设置
git config --global core.autocrlf input
四、Cursor 的用法（与 VS Code 基本一致）
-
打开 Cursor，安装与 VS Code 相同扩展：Remote-SSH、Dev Containers、Docker、语言扩展。
-
用 Remote-SSH 连接
myserver并打开远端项目目录。 -
按 工作流 A 的 A3~A6 步骤在容器内开发、调试、端口转发。
-
Cursor 的 AI 辅助功能可直接在远端/容器内使用（确保网络策略允许）。
五、工作流 B（备选）：本机 Docker Desktop + 远端 Docker 主机
仅“本机编辑，本机 VS Code，但构建/运行在远端 Docker 上”时使用。
步骤 B1：安装 Docker Desktop（Windows）
-
Docker Desktop: The #1 Containerization Tool for Developers | Docker
-
安装完成后，在 PowerShell 验证：
docker version
步骤 B2：通过 SSH 配置 Docker Context（指向远端）
# 创建一个指向远端的上下文（用 SSH）
docker context create myserver --docker "host=ssh://user@server_ip"
# 切换到该上下文
docker context use myserver
# 验证
docker info
要求你已能
ssh user@server_ip无密码登录（见“前置准备”）。
步骤 B3：让 VS Code 在该远端 Docker 上运行 Dev Containers
-
VS Code 设置里搜索 Docker: Host，填入：
ssh://user@server_ip或者设置环境变量
DOCKER_HOST=ssh://user@server_ip。 -
打开本地项目文件夹，使用命令：
Dev Containers: Open Folder in Container...。 -
Dev Containers 将在 远端 Docker 上构建/运行容器，但你的源码仍在本地。
-
注意：此模式的文件同步、性能与网络转发更易出问题；遇到卡顿或路径映射异常，优先切回 工作流 A。
六、常见问题与排错清单
-
SSH 提示
Permission denied (publickey)：-
确认私钥路径与权限；
-
确认远端
~/.ssh/authorized_keys已写入公钥，且权限600； -
ssh -v myserver查看详细日志定位是找不到密钥、口令错误还是权限问题。
-
-
docker: Got permission denied while trying to connect to the Docker daemon socket：-
把用户加入
docker组：sudo usermod -aG docker $USER； -
重新登录 /
newgrp docker； -
再试
docker ps。
-
-
Remote-SSH 安装 VS Code Server 失败/卡死：
-
检查服务器能否访问微软下载源（可能需代理）；
-
清理远端
~/.vscode-server目录后重连：rm -rf ~/.vscode-server
-
-
端口转发后仍无法访问：
-
确认服务监听
0.0.0.0（容器内）或localhost与转发设置一致； -
检查容器网络与
docker-compose端口映射； -
检查本地浏览器/防火墙拦截。
-
-
构建镜像缓慢：
-
就近配置镜像源；
-
使用多阶段构建、缓存依赖、减少层数；
-
频繁变动的文件放到 Dockerfile 尾部。
-
-
容器内时间/时区不对：
-
在 Dockerfile 配置
TZ或挂载宿主/etc/localtime； -
统一用 UTC 并在应用层处理时区。
-
-
GPU 无法在容器内使用（需要时）：
-
安装
nvidia-container-toolkit并--gpus all运行（与宿主 GPU 驱动匹配）。
-
七、安全性
-
禁用密码登录与 root 直登，只允许密钥登录。
-
定期更新系统与容器镜像，及时打补丁。
-
不要裸露 Docker TCP 守护端口（
/var/run/docker.sock仅本机使用）。 -
最小权限：只给需要的用户与服务必要权限；容器内尽量非 root 运行。
-
机密管理：
-
使用环境变量/
docker secret/外部密钥管理； -
不要把密钥、令牌写进镜像或代码库。
-
-
资源与清理：
# 清理无用镜像/容器/网络/缓存 docker system prune -af -
日志与监控：为服务配置日志输出；需要时采用
docker logs、docker stats、Prometheus/Grafana 等。
八、示例（可直接CV）
1）~/.ssh/config 示例（含跳板）
Host myserver
HostName 203.0.113.10
User dev
IdentityFile C:/Users/you/.ssh/id_ed25519
Port 22
ServerAliveInterval 30
ServerAliveCountMax 3
# ForwardAgent yes # 如需本地代理转发
Host bastion
HostName 198.51.100.5
User bastion
IdentityFile C:/Users/you/.ssh/id_ed25519
# 使用跳板：
Host myserver-via-bastion
HostName 10.0.0.10
User dev
ProxyJump bastion
IdentityFile C:/Users/you/.ssh/id_ed25519
2）最小 devcontainer.json（基于镜像）
{
"name": "myapp-dev",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"remoteUser": "vscode",
"forwardPorts": [3000]
}
3）docker-compose.yml + devcontainer.json（多服务）
docker-compose.yml
version: "3.8"
services:
app:
build: .
volumes:
- .:/workspace
ports:
- "3000:3000"
depends_on:
- db
db:
image: postgres:16
environment:
POSTGRES_USER: dev
POSTGRES_PASSWORD: dev
POSTGRES_DB: app
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:
.devcontainer/devcontainer.json
{
"name": "myapp-dev",
"dockerComposeFile": ["../docker-compose.yml"],
"service": "app",
"workspaceFolder": "/workspace",
"remoteUser": "root",
"forwardPorts": [3000]
}
九、完成度自检（逐条打勾）
-
Windows 端：VS Code/Cursor、OpenSSH、Git 安装妥当；
-
生成 ed25519 密钥并加入 ssh-agent；
-
公钥已写入远端
authorized_keys，权限正确； -
远端用户加入 docker 组，
docker ps正常； -
~/.ssh/config已配置myserver并可一键ssh myserver； -
VS Code 已装 Remote-SSH、Dev Containers、Docker 扩展；
-
Remote-SSH 成功连接，能打开远端项目；
-
Dev Containers 能“在容器中重新打开”并顺利构建；
-
端口转发可从本地访问远端服务；
-
调试（Node/Python 等）能正常 Attach；
-
Git 身份与凭据在远端配置完成；
-
安全基线与清理策略已落实。
至此，Windows → Linux（Docker）远程开发环境已经搭建完毕。
