适用场景与目标

  • 场景：用 Windows 电脑，远程连接到一台 Linux 服务器（已安装 Docker），希望用 VS Code 或 Cursor 进行“像本地一样”的开发（编辑、调试、运行、端口转发等）。

  • 目标：

    1. 用 SSH 安全连接远程主机；

    2. 在远端使用 Docker 容器进行开发；

    3. 在 VS Code/Cursor 中获得完整的 IDE 体验（扩展、终端、调试、端口转发、Git 等）；

    4. 全流程“极其详细”，每一步都不省略，且通用。

总览：两种推荐工作流（任选其一）

工作流 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 端必备

  1. 安装 VS Code 或 Cursor（二选一，建议两者都能用）：

  2. 安装/启用 OpenSSH 客户端（Windows 10/11 通常已内置）：

    • 打开 设置 → 应用 → 可选功能，确认“OpenSSH Client”已安装；如未安装，点“添加可选功能”安装。

  3. 安装 Git（可选但强烈建议）： Redirecting…

    • 安装后在 PowerShell 里确认：

      git --version
ssh -V

  4. （可选）安装 Windows Terminal：提升终端体验：Windows Terminal

2. 生成 SSH 密钥（Windows 端）

推荐 ed25519 算法，短小安全。

  1. 打开 PowerShell（非管理员即可）。

  2. 生成密钥：

    ssh-keygen -t ed25519 -C "your_email@example.com"

    • 按提示选择保存路径（默认 C:\Users\<你的用户名>\.ssh\id_ed25519），设置强密码（passphrase）。

  3. 启动并配置 ssh-agent（用于自动解锁密钥）：

    # 启动一次性服务（当前会话）
Start-Service ssh-agent
# 将私钥加入 agent（输入你刚设置的密钥口令）
ssh-add $env:USERPROFILE\.ssh\id_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）：

  1. 显示公钥：

    Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

    复制整行。

  2. 首次用密码登录服务器：

    ssh user@server_ip

  3. 在服务器上执行：

    mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "<粘贴你的公钥整行>" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

  4. 退出：exit

务必确认远端 ~/.ssh 权限为 700、authorized_keys 为 600，否则 SSH 可能拒绝使用密钥。

4. 服务器端检查项（必须逐条确认）

  1. Linux 用户与权限：

    • 有一个非 root 用户（例如 dev）。

    • 该用户在 sudoers 里（能 sudo）。

  2. OpenSSH Server 已运行：

    sudo systemctl status sshd    # Debian/Ubuntu 可能是 ssh

  3. ** Docker 已安装且可用**：

    docker --version
sudo docker info

  4. 将你的非 root 用户加入 docker 组（避免每次都用 sudo）：

    sudo usermod -aG docker $USER
# 重新登录会话后生效，或临时：
newgrp docker
docker ps

  5. （可选）防火墙：开放 SSH 端口（默认 22），禁止对外暴露 Docker 守护进程的 TCP 端口（除非你明确要这么做，并配 TLS）。

  6. （可选）SSH 安全加固：在 /etc/ssh/sshd_config 中设置：

    • PasswordAuthentication no（使用密钥登录）；

    • PermitRootLogin no（禁止 root 直登）。
      修改后：sudo systemctl reload sshd。

5. 测试纯 SSH 连接（Windows 端）

  1. 新建/编辑 SSH 配置文件：C:\Users\<你>\.ssh\config

    Host myserver
  HostName <服务器IP或域名>
  User <你的用户名>
  IdentityFile C:/Users/<你>/.ssh/id_ed25519
  Port 22
  ServerAliveInterval 30
  ServerAliveCountMax 3
  # 如需代理跳板：
  # ProxyJump bastion

# 如有跳板机：
Host bastion
  HostName <跳板机IP>
  User <bastion用户>
  IdentityFile C:/Users/<你>/.ssh/id_ed25519

  2. 连接测试：

    ssh myserver

    第一次会提示保存主机指纹（known_hosts），输入 yes，能登录即通过。

二、VS Code 必装扩展（Cursor 同理）

  1. Remote - SSH（ms-vscode-remote.remote-ssh）

  2. Dev Containers（ms-vscode-remote.remote-containers）

  3. Docker（ms-azuretools.vscode-docker）

  4. 语言相关扩展（Python、ESLint、Go、Java 等，按项目需要）

Cursor 基于 VS Code，扩展安装路径、用法几乎一致（在 Cursor 的扩展页搜索安装同名扩展）。

三、工作流 A（推荐）：Remote-SSH + Dev Containers

步骤 A1：通过 Remote-SSH 连接服务器

  1. 打开 VS Code，安装好 Remote - SSH 扩展。

  2. 左侧活动栏点击 远程资源管理器（或按 F1 → 输入 Remote-SSH: Connect to Host...）。

  3. 选择 Add New SSH Host...，输入：

    ssh myserver

    并选择要写入的 ~/.ssh/config 文件（选当前用户的）。

  4. 在主界面右下角的绿色远程图标（><）中选择 Connect to Host...，选 myserver。

  5. 首次连接会弹出 选择远端平台，选 Linux。

  6. VS Code 会在远端安装 VS Code Server，等待完成（需要网络通畅）。

  7. 连接成功后，左下角会显示 SSH: myserver，说明已在远程环境。

步骤 A2：在远端打开项目目录

  1. F1 → Remote-SSH: Open Folder...，选择远端路径（例如：/home/dev/project）。

  2. 如果项目还不在服务器：

    • 方案 1：在远端 git clone：

      cd /home/dev
git clone <repo_url> project

    • 方案 2：用 scp/rsync 从本地上传：

      # 例：把本地 D:\code\myapp 上传到 /home/dev/project
scp -r D:\code\myapp myserver:/home/dev/project

步骤 A3：验证远端 Docker 正常

在 VS Code 集成终端（此时已是远端终端）执行：

docker info
docker ps

能看到正常输出即通过。如提示权限问题，回到前置准备第 4 步修复（加入 docker 组并重新登录）。

步骤 A4：使用 Dev Containers 在容器中开发

两种典型方式：

  • 方式 1：项目内置 .devcontainer → “在容器中重新打开”。

  • **方式 2：附着到一个已运行的容器”。

方式 1：创建 .devcontainer 并“在容器中重新打开”

  1. 在项目根新建目录 .devcontainer/。

  2. 新建 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"
  ]
}

  3. （可选）同目录新建 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"
}

  4. （可选）docker-compose 方案（有多服务时）：

    • 新建 docker-compose.yml，并在 devcontainer.json 使用：

      {
  "name": "myapp-dev",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "remoteUser": "vscode",
  "forwardPorts": [3000]
}

  5. （可选）新建 .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。

  6. 在 VS Code 命令面板执行：Dev Containers: Reopen in Container（在容器中重新打开）。

  7. 等待构建/拉取镜像并启动容器。完成后，左下角会显示 Dev Container: myapp-dev，此时你的工作区已在容器内。

说明：由于你是“先 Remote-SSH 到服务器”，Dev Containers 会直接调用远端服务器上的 Docker，不需要本机 Docker。

方式 2：附着到已运行的容器

  1. 确保容器已在远端运行：docker ps。

  2. VS Code 左侧 Docker 面板 → 右键目标容器 → Attach Visual Studio Code（如果没有这个选项，有个小窍门，可以在vscode的欢迎界面点击连接到容器即可）。

  3. VS Code 会在该容器中打开一个新的工作区窗口，直接开发/调试。

步骤 A5：端口转发（访问容器/远端服务）

  1. 在 VS Code 底部“端口”面板（Forwarded Ports）：

    • 点击 Add Port，输入远端端口（如 3000）。

    • 得到一个本地转发口（如 127.0.0.1:3000）。

  2. 命令行等价：

    # 把远端 3000 转发到本地 3000
ssh -L 3000:localhost:3000 myserver

  3. 若使用 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 与凭据

  1. 首选：在远端配置你的 Git 身份：

    git config --global user.name "Your Name"
git config --global user.email "you@example.com"

  2. 拉取/推送凭据：推荐在远端用 SSH Key 或 访问令牌（PAT）。

  3. （可选）Agent 转发：在 ~/.ssh/config 为 myserver 增加 ForwardAgent yes，并在本地确保 ssh-agent 已加载密钥。注意安全，仅在可信主机使用。

  4. Windows 换行符：推荐设置

    git config --global core.autocrlf input

四、Cursor 的用法（与 VS Code 基本一致）

  1. 打开 Cursor，安装与 VS Code 相同扩展：Remote-SSH、Dev Containers、Docker、语言扩展。

  2. 用 Remote-SSH 连接 myserver 并打开远端项目目录。

  3. 按 工作流 A 的 A3~A6 步骤在容器内开发、调试、端口转发。

  4. Cursor 的 AI 辅助功能可直接在远端/容器内使用（确保网络策略允许）。

五、工作流 B（备选）：本机 Docker Desktop + 远端 Docker 主机

仅“本机编辑，本机 VS Code，但构建/运行在远端 Docker 上”时使用。

步骤 B1：安装 Docker Desktop（Windows）

步骤 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

  1. VS Code 设置里搜索 Docker: Host，填入：

    ssh://user@server_ip

    或者设置环境变量 DOCKER_HOST=ssh://user@server_ip。

  2. 打开本地项目文件夹，使用命令：Dev Containers: Open Folder in Container...。

  3. Dev Containers 将在 远端 Docker 上构建/运行容器，但你的源码仍在本地。

  4. 注意：此模式的文件同步、性能与网络转发更易出问题；遇到卡顿或路径映射异常，优先切回 工作流 A。

六、常见问题与排错清单

  1. SSH 提示 Permission denied (publickey)：

    • 确认私钥路径与权限；

    • 确认远端 ~/.ssh/authorized_keys 已写入公钥，且权限 600；

    • ssh -v myserver 查看详细日志定位是找不到密钥、口令错误还是权限问题。

  2. docker: Got permission denied while trying to connect to the Docker daemon socket：

    • 把用户加入 docker 组：sudo usermod -aG docker $USER；

    • 重新登录 / newgrp docker；

    • 再试 docker ps。

  3. Remote-SSH 安装 VS Code Server 失败/卡死：

    • 检查服务器能否访问微软下载源（可能需代理）；

    • 清理远端 ~/.vscode-server 目录后重连：

      rm -rf ~/.vscode-server

  4. 端口转发后仍无法访问：

    • 确认服务监听 0.0.0.0（容器内）或 localhost 与转发设置一致；

    • 检查容器网络与 docker-compose 端口映射；

    • 检查本地浏览器/防火墙拦截。

  5. 构建镜像缓慢：

    • 就近配置镜像源；

    • 使用多阶段构建、缓存依赖、减少层数；

    • 频繁变动的文件放到 Dockerfile 尾部。

  6. 容器内时间/时区不对：

    • 在 Dockerfile 配置 TZ 或挂载宿主 /etc/localtime；

    • 统一用 UTC 并在应用层处理时区。

  7. GPU 无法在容器内使用（需要时）：

    • 安装 nvidia-container-toolkit 并 --gpus all 运行（与宿主 GPU 驱动匹配）。

七、安全性

  1. 禁用密码登录与 root 直登，只允许密钥登录。

  2. 定期更新系统与容器镜像，及时打补丁。

  3. 不要裸露 Docker TCP 守护端口（/var/run/docker.sock 仅本机使用）。

  4. 最小权限：只给需要的用户与服务必要权限；容器内尽量非 root 运行。

  5. 机密管理：

    • 使用环境变量/docker secret/外部密钥管理；

    • 不要把密钥、令牌写进镜像或代码库。

  6. 资源与清理：

    # 清理无用镜像/容器/网络/缓存
docker system prune -af

  7. 日志与监控：为服务配置日志输出；需要时采用 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）远程开发环境已经搭建完毕。

# 服务器 # windows # linux # docker # vscode
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

我用 Qwen3.8-Max 做了一个采购合同风险审查工具：从能分析，到能定位、复核和交付

avatar DeepSeek技术社区
cover

我用 Qwen3.8-MAX 搭了一个教研纪要 Agent，一次集体备课几秒出七段、分歧还不被和稀泥

avatar DeepSeek技术社区

我用 Qwen3.8-Max 做了缠论结构观察员，跑完了从开发到修复的全过程

Qwen3.8-Max 没有替我判断方向，也没有把缠论包装成预测工具。它在开发过程中支持多 Agent 并行，能够理解较长的产品约束和算法边界，拆分文档与实现任务；当子任务停滞后回到主上下文继续推进；再根据“笔断裂”“中枢过宽”这种图上的具体问题，定位到算法文件并补回归测试。复杂项目不能靠一次生成直接交付。Agent Team 会卡住，初版算法也会错。模型放进开发闭环里才有意义，最后还是要靠可检查

avatar DeepSeek技术社区