Cursor 远程开发实战：通过 SSH 连接 Linux（自建 + 云服务器通用篇）

Cursor Remote-SSH 是什么

Cursor 的远程开发能力建立在 VS Code Remote - SSH 协议之上：本地只跑轻量客户端 UI，语言服务器、文件系统、终端进程全部在远端 Linux 机器上运行，体验上几乎与本地开发无异。

前置准备

检查 SSH 客户端

ssh -V
# macOS/Linux 通常已内置；Windows 10 1809+ 内置 OpenSSH

生成 SSH Key（ed25519，当前推荐）

ssh-keygen -t ed25519 -C "[email protected]"
# 路径直接回车使用默认 ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
# 复制整行，后续写入远端 authorized_keys

不再推荐 -t rsa -b 2048：ed25519 在安全性和性能两个维度均优于 RSA 2048，且密钥文件更短。

known_hosts 说明

首次连接新主机会弹出指纹确认。输入 yes 后指纹写入 ~/.ssh/known_hosts；Cursor Remote-SSH 在后台建立连接时同样触发此流程。

自建 Linux 配置（树莓派 / 本地虚拟机 / LXC）

树莓派

# 方式一：raspi-config
sudo raspi-config  # → Interface Options → SSH → Enable

# 方式二：boot 分区放空文件（无头安装）
touch /boot/ssh

# 确认 SSH 监听
sudo systemctl status ssh
sudo ss -tlnp | grep :22

建议在路由器设置 DHCP 静态绑定，把树莓派 MAC 地址绑定到固定 IP，避免重启后 IP 变化。

本地虚拟机网卡模式

LXC 容器（Proxmox / 软路由）

pct exec <容器ID> -- apt install openssh-server -y
pct exec <容器ID> -- systemctl enable --now ssh

云服务器配置（阿里云、腾讯云、AWS 通用）

安全组开放 22 端口

上传公钥到远端

# 方式 A — ssh-copy-id
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@your-server-ip

# 方式 B — 手动复制（通过 web shell）
mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "粘贴你的公钥内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

关闭密码登录（可选但推荐）

sudo nano /etc/ssh/sshd_config
# PasswordAuthentication no
# PubkeyAuthentication yes
sudo systemctl restart sshd

SSH Key 免密登录

本地 SSH Config 配置（关键）

在 ~/.ssh/config 里为每台服务器建立别名，Cursor Remote-SSH 会自动读取：

Host my-rpi
  HostName 192.168.1.88
  User pi
  IdentityFile ~/.ssh/id_ed25519
  Port 22

Host my-cloud
  HostName your-server-ip
  User ubuntu
  IdentityFile ~/.ssh/id_ed25519
  Port 22
  ServerAliveInterval 60
  ServerAliveCountMax 3

ServerAliveInterval / ServerAliveCountMax 保活设置，防止长时间编辑后连接断开。

跳板机（Bastion / Jump Host）场景

Host bastion
  HostName public-bastion-ip
  User ec2-user
  IdentityFile ~/.ssh/id_ed25519

Host private-server
  HostName 10.0.1.100
  User ubuntu
  ProxyJump bastion
  IdentityFile ~/.ssh/id_ed25519

Cursor Remote-SSH 会自动走 ProxyJump 透明建立连接，使用体验与直连无异。

Cursor 中添加 Remote 主机

1. 按 Ctrl+Shift+P（macOS：Cmd+Shift+P），搜索选择 Remote-SSH: Connect to Host…
2. 或点击左下角状态栏 >< 图标 → Connect to Host
3. 列表显示 ~/.ssh/config 中已配置的别名（如 my-rpi）
4. 选中后 Cursor 在后台安装远端服务组件（~/.cursor-server/），首次约 1-3 分钟，此后缓存秒开

验证连接状态

左下角状态栏显示 SSH: my-cloud 即表示当前工作在远端。终端执行：

hostname && uname -a

看到服务器名称确认无误。

远程项目目录与终端

推荐目录约定

~/projects/
  my-api/      # Git 项目
  my-scripts/  # 独立运维脚本
  tmp/         # 临时实验，不提交

打开远端目录后，所有文件操作（创建、编辑、保存）直接发生在远端，无需手动同步。

终端常用操作

tail -f /var/log/nginx/access.log
sudo systemctl restart my-app
git pull && npm run build

实测建议：在远端启动 tmux / screen 跑长任务（编译、测试），即使 Cursor 断开连接任务仍在后台运行。

文件权限陷阱

# 检查权限
ls -la ~/projects/my-api
# 修正（谨慎在生产使用）
sudo chown -R $USER:$USER ~/projects/my-api

Cursor 里保存文件时弹出"没有权限"，通常是文件由 root 创建而当前用户无写权限。

远程跑 Composer Agent（注意：远程机需要外网才能调模型 API）

可复用的 Composer 提示词（远端场景）

目标：帮我在这台远端 Linux 机器上写一个部署脚本 deploy.sh，
      完成「拉取最新代码 → 安装依赖 → 构建 → 重启服务」全流程。

约束：
1. #!/bin/bash，出错立即退出（set -e）
2. 目标项目在 ~/projects/my-api，构建命令 npm run build
3. 服务管理使用 systemd，单元名 my-api.service
4. 脚本末尾输出"Deploy done at $(date)"
5. 不要硬编码任何密码或 token

验收：bash deploy.sh 可执行；systemctl status my-api 显示 active (running)

Chat + @引用远端文件排障

@nginx.conf 帮我检查这份 Nginx 配置有没有可能导致 502 的写法

Cursor 会读取远端文件内容后再给出回答，不需要把文件复制到本地。

常见报错速查

Q1：Permission denied (publickey)

根因：服务器没有你的公钥，或公钥路径 / 权限有问题。

# 1. 确认私钥可用
ssh-add -l
# 若无输出：ssh-add ~/.ssh/id_ed25519

# 2. 检查远端 authorized_keys 权限（关键）
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

# 3. 开启详细日志
ssh -vvv user@host 2>&1 | grep -i "key\|auth"

Q2：Connection refused

根因：SSH 服务未启动，或端口不对，或安全组未放行。

# 在远端（通过 web shell）
sudo systemctl status sshd
sudo systemctl enable --now sshd
sudo ss -tlnp | grep sshd

# 若有 ufw
sudo ufw allow 22/tcp

云服务器还需在控制台安全组入方向规则确认 22 端口已开放。

Q3：Host key verification failed

根因：服务器重装系统或 IP 被复用，known_hosts 指纹与当前不匹配。

# 删除旧指纹
ssh-keygen -R your-server-ip

# 重新连接，输入 yes 接受新指纹
ssh user@your-server-ip

相关教程

• Cursor 国内使用完整教程（注册 / 充值 / 模型 / 功能 / 故障排查）
• Cursor + GitHub + Cloudflare 静态站实战
• 机场订阅与节点选型
• 代理访问异常通用排查