Windows 远程 Ubuntu 开发环境搭建：SSH + VS Code + LoRA 微调实战

1. 为什么要在 Windows 笔记本上远程调试 Ubuntu 上的模型我平时主力机是一台 Windows 笔记本16 寸、32G 内存、带一块移动端显卡。日常写代码、查资料、开会议都在这台机器上习惯已经养成了不太想换。但只要一碰模型训练、微调这类活儿Windows 就有点力不从心CUDA 环境、各种 Python 依赖、文件权限、长任务稳定性随便哪一条都能让人折腾半天。所以我的常规做法是——本地 Windows 负责写代码、看日志、调界面真正的训练和推理跑在一台远程 Ubuntu 机器上。这个思路听起来简单但真正落地的时候坑是一层接一层。你得先能连上远程 Ubuntu然后得让 VS Code 在远程环境里跑起来接着要配好 Python 解释器、CUDA、各种依赖最后还要能跑通一个 LoRA 微调任务才算“能干活”。中间任何一环断了你都只能对着终端发呆。这篇内容就是把我自己从零搭这套环境的过程完整记录下来。目标很明确一台 Windows 笔记本通过 SSH 连到远程 Ubuntu用 VS Code 做远程开发最终能跑通一个 LoRA 微调任务。适合的人群也很清楚——手上有 Windows 机器、又需要远程跑模型训练或微调的开发者尤其是刚接触远程开发、对 Linux 环境还不算特别熟的朋友。我会把每一步的操作、参数、踩过的坑都写清楚尽量让你照着做就能复现。整个链路的核心关键词其实就几个Windows、Ubuntu、SSH、VS Code、LoRA。Windows 是本地操作端Ubuntu 是远程计算端SSH 是两者之间的通道VS Code 是开发界面LoRA 是最终要跑起来的目标任务。把这五个东西串起来这套环境就算通了。2. 远程连接前的整体设计与选型思路2.1 为什么选 SSH 而不是其他远程方案远程连接 Ubuntu 的方式其实不少图形界面有 VNC、RDP文件传输有 SFTP、SMB命令行有 SSH。我最终选 SSH 作为主通道原因有几个。第一SSH 是 Linux 服务器的标配几乎不需要在远程端额外装什么服务Ubuntu 装好之后默认就带 OpenSSH Server只要确认服务开着、端口通着就能连。第二SSH 是纯命令行通道带宽占用极低哪怕网络一般操作延迟也能接受不像图形远程那样卡成幻灯片。第三VS Code 的 Remote-SSH 插件就是基于 SSH 做的装好插件之后本地 VS Code 可以直接把远程目录当本地目录用编辑、终端、调试全都在远程环境里跑体验非常顺。VNC 和 RDP 我也试过图形界面确实直观但传输量大、延迟高而且很多训练任务根本不需要图形界面开了反而是浪费。SFTP 适合传文件但不适合做日常开发。所以主通道定 SSH文件传输用 VS Code 自带的拖拽或者 scp 命令辅助足够了。2.2 本地 Windows 端需要准备什么Windows 这边其实不需要太多东西。Win10 之后的系统自带 OpenSSH 客户端命令行里直接就能用 ssh 命令。如果你用的是比较老的系统或者想用更顺手的工具可以装一个终端工具比如 Windows Terminal界面比自带的 cmd 好看很多支持多标签、分屏、自定义配色日常用起来舒服。VS Code 是必须装的官网下载安装包一路下一步就行。装完之后需要在扩展市场里搜 Remote - SSH装上这个插件。这个插件是微软官方出的装完之后左侧活动栏会多一个远程资源管理器的图标后面连远程就靠它。另外建议装一个 Git因为后面拉代码、管理版本都用得上。Git 在 Windows 上安装也很简单官网下载安装包默认选项一路下一步即可。装完之后在命令行里执行git --version能看到版本号就说明成功了。2.3 远程 Ubuntu 端的前置条件远程 Ubuntu 这边首先要确认 SSH 服务是开着的。Ubuntu 桌面版默认可能没装 OpenSSH Server需要手动装一下sudo apt update sudo apt install openssh-server sudo systemctl enable ssh sudo systemctl start ssh装完之后用sudo systemctl status ssh看一下状态显示 active (running) 就说明服务起来了。然后确认防火墙没有挡住 22 端口如果开了 ufw需要放行sudo ufw allow ssh如果你改过 SSH 端口比如改成 2222那放行的时候要写对应的端口号。这一步很多人会忘结果本地怎么连都连不上排查半天才发现是防火墙的问题。另外远程 Ubuntu 上最好有一个专门的用户账号不要直接用 root 登录。用普通用户登录需要提权的时候再用 sudo这样更安全也更符合常规运维习惯。创建用户的命令是sudo adduser yourname sudo usermod -aG sudo yourname这样新用户就有了 sudo 权限后面装东西、改配置都方便。2.4 网络层面的考量网络这块核心就一件事本地能不能访问到远程的 22 端口。如果两台机器在同一个局域网里那直接填远程的内网 IP 就行。如果远程机器在公网那就填公网 IP。如果远程机器在 NAT 后面可能需要做端口映射这个就涉及到具体的网络环境了得根据实际情况来。我自己的场景是远程机器在同一个办公网络里所以直接用内网 IP 连接延迟很低体验很好。如果你是在家里连公司的机器那可能涉及到网络策略的问题这个需要和网络管理员确认我这里就不展开了。有一点要提醒不管网络怎么配SSH 的密钥认证一定要配好。密码认证虽然方便但安全性差而且每次连接都要输密码很烦。密钥认证配好之后连接是免密的既安全又省事。3. SSH 密钥配置与远程连接实操3.1 在 Windows 上生成 SSH 密钥对Windows 上生成密钥对很简单打开 PowerShell 或者 Windows Terminal执行ssh-keygen -t ed25519 -C your_emailexample.com这里我选的是 ed25519 算法而不是传统的 RSA。原因是 ed25519 更短、更快、安全性也更好现在主流平台都支持。执行之后会提示你输入保存路径直接回车用默认路径就行一般在C:\Users\你的用户名\.ssh\下面。然后会问你要不要设密码短语如果追求方便可以直接回车留空如果追求安全可以设一个但每次连接都要输看你自己的取舍。生成完之后目录下会有两个文件id_ed25519是私钥id_ed25519.pub是公钥。私钥绝对不能泄露公钥是要放到远程服务器上的。3.2 把公钥放到远程 Ubuntu 上这一步有两种做法。第一种是用ssh-copy-id命令但 Windows 上默认没有这个命令得用别的方式。第二种是手动把公钥内容追加到远程的~/.ssh/authorized_keys文件里。我一般用第二种操作也不复杂。先用密码方式登录一次远程ssh yournameremote_ip登录进去之后确认~/.ssh目录存在不存在就创建mkdir -p ~/.ssh chmod 700 ~/.ssh然后把本地公钥的内容粘贴到~/.ssh/authorized_keys里echo 你的公钥内容 ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys公钥内容就是本地id_ed25519.pub文件里的那一整行以ssh-ed25519开头。复制的时候注意不要漏字符也不要多换行。注意~/.ssh目录权限必须是 700authorized_keys文件权限必须是 600权限不对的话 SSH 会拒绝使用密钥认证这是很多人踩过的坑。3.3 配置 SSH config 简化连接每次连接都敲一长串ssh yournameremote_ip -p port很麻烦可以在本地C:\Users\你的用户名\.ssh\config文件里配置别名。没有这个文件就新建一个内容如下Host myserver HostName 192.168.1.100 User yourname Port 22 IdentityFile C:\Users\你的用户名\.ssh\id_ed25519配好之后直接ssh myserver就能连上非常方便。VS Code 的 Remote-SSH 也能直接读这个配置后面连远程的时候直接选 myserver 就行。3.4 首次连接与常见报错处理第一次连接的时候会提示你确认远程主机的指纹输入 yes 回车就行。如果之前连过同一台机器但指纹变了会报一个警告这时候需要把本地known_hosts文件里对应的旧记录删掉再重新连。常见的报错有这么几类。一是Connection refused说明远程 22 端口没开或者防火墙挡了回去检查 SSH 服务和防火墙。二是Permission denied (publickey)说明密钥认证没配好检查公钥内容、文件权限、config 配置。三是Connection timed out说明网络不通检查 IP、端口、网络策略。我自己的经验是大部分连接问题都能通过ssh -v myserver这个命令排查出来。加-v参数会打印详细的连接日志卡在哪一步一目了然。4. VS Code 远程开发环境搭建4.1 安装 Remote-SSH 插件并连接VS Code 装好之后打开扩展面板搜索 Remote - SSH安装。装完之后左侧会多一个远程资源管理器图标点进去把鼠标悬停在 SSH 那一栏会出现一个加号点加号输入ssh myserver回车选择配置文件一般选默认的那个就行。然后右键 myserver选择在当前窗口连接或者新窗口连接。VS Code 会开始连接远程第一次连接的时候会在远程自动安装 VS Code Server这个过程需要一点时间取决于网络速度。装完之后左下角会显示SSH: myserver说明已经连上了。连上之后打开远程的文件夹比如/home/yourname/projects就可以像操作本地文件一样编辑远程文件了。终端也是远程的执行命令直接在远程环境里跑非常方便。4.2 远程 Python 环境配置远程开发的核心之一就是 Python 环境。我一般用 conda 或者 venv 来管理环境避免污染系统 Python。conda 的安装这里不展开网上教程很多。假设你已经装好了 conda创建一个专门的环境conda create -n ml python3.10 conda activate ml然后装 PyTorch 和相关的库。PyTorch 的安装命令要根据你的 CUDA 版本选去官网查一下对应命令比如pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118装完之后验证一下 GPU 是否可用import torch print(torch.cuda.is_available()) print(torch.cuda.get_device_name(0))如果输出 True 和显卡型号说明环境没问题。在 VS Code 里按CtrlShiftP打开命令面板输入 Python: Select Interpreter选择刚才创建的 conda 环境。这样 VS Code 的终端、调试、代码补全都会用这个环境。4.3 远程终端与文件传输VS Code 连上远程之后按Ctrl打开终端这个终端就是远程的 shell直接在里面执行命令就行。文件传输也很方便直接把本地文件拖到 VS Code 的远程文件树里就会自动上传。反过来右键远程文件选择下载就能拉到本地。如果文件比较大或者要批量传输可以用 scp 命令scp -r local_folder myserver:/home/yourname/remote_folder这个命令在本地 Windows 的终端里执行把本地文件夹传到远程。反过来把远程文件拉到本地就是调换顺序scp -r myserver:/home/yourname/remote_folder local_folder4.4 端口转发与调试配置有时候远程跑了一个 Web 服务比如 TensorBoard 或者 Jupyter想在本地浏览器里看就需要端口转发。VS Code 的 Remote-SSH 会自动检测远程端口并转发你也可以手动加。在远程终端里跑tensorboard --logdir ./logs --port 6006VS Code 会提示检测到端口 6006点一下就能在本地浏览器打开http://localhost:6006。如果没有自动提示可以在端口面板里手动添加转发规则。调试配置方面VS Code 的 launch.json 需要配在远程工作区里路径、Python 解释器都指向远程环境。这样按 F5 调试的时候代码是在远程跑的断点、变量查看都在远程环境里生效。5. LoRA 微调任务跑通实录5.1 LoRA 微调的基本原理与参数选择LoRA 的核心思路是在预训练模型的部分权重旁边挂一个小型的低秩矩阵训练的时候只更新这个小矩阵不动原来的大模型权重。这样做的好处是显存占用大幅降低训练速度也快很多而且产出的 LoRA 权重文件很小方便保存和分享。关键参数有几个。r是低秩矩阵的秩一般取 8、16、32越大表达能力越强但显存占用也越高。lora_alpha是缩放系数一般取 r 的两倍。lora_dropout是 dropout 比例一般取 0.05 到 0.1。target_modules指定哪些层加 LoRA一般选 attention 的 q_proj、v_proj 这些。我自己的经验是第一次跑先用 r8、alpha16、dropout0.05 这组保守参数确认流程能跑通再根据效果调整。不要一上来就上大参数容易爆显存排查起来也麻烦。5.2 数据准备与格式整理LoRA 微调的数据一般是 json 或者 jsonl 格式每条数据包含 instruction、input、output 三个字段。比如{instruction: 把下面这句话翻译成英文, input: 今天天气很好, output: The weather is nice today.}数据量不用太大几百到几千条就能看到效果。关键是质量要高格式要统一不要有脏数据。我一般会写个小脚本检查一遍数据确认没有空字段、没有乱码、没有重复。数据准备好之后放到远程的一个目录里比如/home/yourname/data/train.json和/home/yourname/data/val.json。训练集和验证集的比例一般 9:1 或者 8:2。5.3 训练脚本配置与启动训练脚本我一般用 transformers peft 这套组合。核心配置大概是这样from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments from peft import LoraConfig, get_peft_model base_model your_base_model_path train_data ./data/train.json val_data ./data/val.json output_dir ./output/lora_model model AutoModelForCausalLM.from_pretrained(base_model, device_mapauto) tokenizer AutoTokenizer.from_pretrained(base_model) lora_config LoraConfig( r8, lora_alpha16, lora_dropout0.05, target_modules[q_proj, v_proj], biasnone, task_typeCAUSAL_LM ) model get_peft_model(model, lora_config) training_args TrainingArguments( output_diroutput_dir, num_train_epochs3, per_device_train_batch_size4, gradient_accumulation_steps4, learning_rate2e-4, logging_steps10, save_steps100, evaluation_strategysteps, eval_steps100, save_total_limit2, fp16True )这里per_device_train_batch_size设 4gradient_accumulation_steps设 4等效 batch size 就是 16。如果显存不够就把 batch size 降到 2 或者 1把 accumulation 提上去。fp16True开启半精度训练能省不少显存。启动训练直接在远程终端里跑python train.py如果任务比较长建议用 nohup 或者 tmux 挂后台避免 SSH 断开导致训练中断nohup python train.py train.log 21 或者用 tmuxtmux new -s train python train.py按CtrlB然后D脱离会话训练继续跑。下次连上之后tmux attach -t train就能回到会话看日志。5.4 训练过程监控与显存优化训练跑起来之后要盯着几个指标loss 是不是在下降、显存占用是不是稳定、有没有报错。日志里会打印每一步的 loss如果 loss 一直不降或者震荡很大可能是学习率太高或者数据有问题。显存优化有几个常用手段。一是开 gradient checkpointing用时间换空间model.gradient_checkpointing_enable()二是用 8bit 或者 4bit 量化加载模型from transformers import BitsAndBytesConfig bnb_config BitsAndBytesConfig(load_in_8bitTrue) model AutoModelForCausalLM.from_pretrained(base_model, quantization_configbnb_config, device_mapauto)三是减小 batch size、增大 gradient accumulation。这几个手段可以组合使用根据显存情况灵活调整。我自己的经验是先看nvidia-smi确认显存占用如果接近上限就赶紧降 batch size不要等 OOM 了再改。OOM 之后进程会挂掉前面的训练进度可能就丢了。6. 常见问题与排查技巧实录6.1 SSH 连接类问题速查问题现象可能原因排查方法Connection refusedSSH 服务没开或端口不对systemctl status ssh检查服务ss -tlnp检查端口Permission denied密钥没配好或权限不对检查 authorized_keys 内容和权限ssh -v看详细日志Connection timed out网络不通或防火墙挡了ping 远程 IP检查防火墙规则Host key verification failed远程指纹变了删除 known_hosts 里对应记录重新连6.2 VS Code 远程连接类问题VS Code 连不上远程最常见的原因是远程的 VS Code Server 装不上或者版本不匹配。可以在远程手动删掉~/.vscode-server目录然后重新连接让 VS Code 重新安装。如果网络不好导致下载慢可以配置代理或者手动下载 server 包放到对应目录。另一个常见问题是远程终端里 conda 环境不生效。这是因为 VS Code 的终端默认不加载 conda 的初始化脚本。可以在远程的~/.bashrc里加上 conda 的初始化或者在 VS Code 设置里指定 Python 解释器路径。6.3 LoRA 训练类问题训练过程中最常见的报错就是 CUDA out of memory。解决办法前面说了降 batch size、开 gradient checkpointing、用量化加载。还有一个容易忽略的点是 tokenizer 的 max_length 设太大导致单条数据占的显存过多。一般设 512 或者 1024 就够了不要一上来就设 2048。loss 不下降的话先检查数据格式对不对再看学习率是不是太高。我遇到过学习率设成 1e-3 导致 loss 直接飞掉的情况改成 2e-4 就正常了。另外base model 和 tokenizer 要匹配不要用 A 模型的 tokenizer 配 B 模型的权重。6.4 我踩过的几个坑第一个坑是远程 Ubuntu 的默认 Python 版本太老装某些库的时候编译失败。解决办法是装个新版本的 Python或者用 conda 创建独立环境。第二个坑是 SSH 连接一段时间不用就断训练任务也跟着挂。解决办法是配ServerAliveInterval在本地 config 里加上Host myserver ServerAliveInterval 60 ServerAliveCountMax 3这样每 60 秒发一次心跳保持连接。第三个坑是远程磁盘满了导致训练中断这个要提前用df -h检查磁盘空间训练输出目录不要放在系统盘。7. 一些实操心得与后续扩展方向整套环境搭下来最深的体会是远程开发的核心不是某一个工具而是整条链路的稳定性。SSH 要稳、VS Code 要稳、Python 环境要稳、训练任务要稳任何一环出问题都会影响效率。所以我在配置的时候会尽量把每个环节都做得规范一点比如用 SSH config 管理连接、用 conda 隔离环境、用 tmux 挂后台任务这些习惯能省掉很多麻烦。另外密钥认证和端口转发这两个东西建议一开始就配好不要等到需要的时候再折腾。密钥认证配好之后连接体验提升非常明显。端口转发配好之后远程的 TensorBoard、Jupyter 都能直接在本地看调试效率高很多。后续如果要扩展可以考虑几个方向。一是把训练脚本容器化用 Docker 管理环境这样换机器的时候迁移成本很低。二是加一些自动化脚本比如数据预处理、训练启动、结果收集一条龙减少手动操作。三是把 LoRA 权重合并回基础模型方便部署和推理。这些内容后面有机会再单独写。最后分享一个小技巧VS Code 的 Remote-SSH 支持多窗口连接同一台远程机器你可以开一个窗口写代码另一个窗口专门看训练日志互不干扰。这个在调试阶段特别有用不用来回切换终端。