Cursor远程开发：Remote – SSH报错Failed to install server within the timeout 的解决方案-171主机测评

Cursor ：远程服务器开发时Remote – SSH：报错Failed to install server within the timeout 的解决方案

一、问题原因分析
二、解决方案
- 服务器磁盘空间不足
- 权限问题
- 外网网络下载速度慢
- - 方法1：Remote.SSH: Local Server Download 改成 alwys 即可：
  - 方法2：插件平替，使用 Open Remote – SSH 替换 Remote – SSH
  - 方法3：手动下载Cursor Server（旧版cursor）
  - - 1.获取本地 Cursor 版本信息
    - 2. 手动下载 cursor server 文件
    - 3.用其他SSH工具连接服务器，执行下面命令
    - 4.将刚刚下载的两个文件上传到服务器中的~/.cursor-server文件夹中
    - 5.解压重命名文件（主要替换参数）
  - 方法4：手动下载Cursor Server（新版cursor）
  - - 1.本地电脑使用 cursor –version 命令查看版本（与旧版一样）
    - 2.手动下载 cursor server 文件
    - 2.在服务器创建目录
    - 3.上传文件到服务器
    - 4.解压重命名
参考文献

在使用 Cursor 远程连接 Linux 服务器开发时，很多开发者会遇到 “Failed to install server within the timeout” 报错。明明手动 SSH 能正常登录，但 Cursor 始终卡在远程组件安装阶段，最终超时失败。本文将从问题根源出发，提供可落地的解决方案，并梳理完整的 Remote – SSH 使用流程。

一、问题原因分析

当Cursor通过Remote-SSH连接远程服务器时，它会在服务器上自动安装一个服务端程序（cursor-server，类似 VS Code 的 server 组件），这是实现远程开发功能的核心组件。

出现"Failed to install server within the timeout"错误的主要原因包括：

服务器磁盘空间不足：这是最常见的原因之一。如果远程服务器的磁盘已满，Cursor无法在远程主机上安装所需的服务端程序。

权限问题：1.当前用户对安装目录没有写入权限，导致无法创建必要的文件和目录（若服务器端已存在 .cursor-server目录，可以考虑先删除然后重新SSH），2.服务器防火墙等原因无法访问。

外网网络下载速度慢：cursor-server文件托管在外网服务（https://cursor.blob.core.windows.net），服务器需要从外网下载cursor-server文件。由于国内网络访问外网存在延迟，即使 cursor-server 文件仅几十 MB，也可能需要十几分钟甚至半小时才能下载完成，远超 Cursor 默认的 30 秒超时时间。

二、解决方案

服务器磁盘空间不足

由于使用Remote – SSH需要在远程主机上安装所需的服务端程序cursor-server，若磁盘空间不足，则无法安装。

# 登录服务器，查看磁盘空间使用情况
df –h

方法1：如果磁盘使用率接近100%，需要清理服务器磁盘空间。可以删除不必要的文件、日志或缓存：

方法2：修改服务器安装路径，可以将Cursor服务端程序安装到其他有足够空间的磁盘分区；在Cursor中修改配置：

打开Cursor，按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（Mac）
输入"Preferences: Open User Settings (JSON)"并选择，以打开 settings.json 文件。
在settings.json文件中添加以下配置

"remote.SSH.serverInstallPath": {
"your-server-ip": "/path/to/alternative/directory/.cursor-server"
}

将your-server-ip替换为您的服务器IP，/path/to/alternative/directory/替换为有足够空间的目录路径。

确保目标目录存在并具有写权限：

# 登录服务器，创建目录
mkdir –p /path/to/alternative/directory/.cursor–server

# 确保当前用户有读写权限
chmod 755 /path/to/alternative/directory

权限问题

见问题分析2，根据相应内容逐步排查解决即可

可参考的相关操作指令

1.检查服务器已安装SSH服务

# 检查SSH服务状态
sudo systemctl status ssh

# 如果未安装，执行安装
sudo apt update && sudo apt install openssh–server # Debian/Ubuntu
sudo yum install openssh–server # CentOS/RHEL

# 启动SSH服务
sudo systemctl start ssh
sudo systemctl enable ssh

2.检查SSH配置，确保允许远程连接

sudo vim /etc/ssh/sshd_config

#确保包含以下配置：
PermitRootLogin yes
PubkeyAuthentication yes
PasswordAuthentication yes

3.修改后重启SSH服务：

sudo systemctl restart sshd

4.检查并配置防火墙，确保服务器防火墙允许SSH连接（默认端口22）：

# 检查防火墙状态
sudo ufw status # Ubuntu

# 如果防火墙开启，确保SSH端口开放
sudo ufw allow 22
sudo ufw reload

外网网络下载速度慢

方法1：Remote.SSH: Local Server Download 改成 alwys 即可：

cursor-server 的默认下载逻辑是（auto 模式）：优先在远程直接下载，如果远程服务器连接不到 https://cursor.blob.core.windows.net，就会转为本地下载，然后 scp 复制到远程。

具体操作步骤如下：

打开Cursor设置：在Cursor中，使用快捷键 Ctrl + ,(Windows/Linux) 或 Cmd + ,(Mac) 打开设置界面。

搜索并修改设置：在顶部的搜索框中输入 Local Server Download。找到名为 “Remote.SSH: Local Server Download” 的设置项。

将其默认值 auto修改为 always 。这个选项的意义是： auto：Cursor自动判断，如果服务器下载失败则尝试本地下载。 always：始终使用本地网络下载服务端程序，然后通过SSH连接上传到远程服务器。这正是你需要的模式。

重新连接：完成设置后，关闭所有Cursor窗口，重新打开Curso。

方法2：插件平替，使用 Open Remote – SSH 替换 Remote – SSH

Remote SSH 的替代品 Open Remote – SSH，使用它替换掉 Remote – SSH 插件之后，Cursor 就可以正常进行远程开发了。不过这个插件没有上架插件商店，只能使用 vsix 安装。

Open Remote – SSH 的.vsix 文件下载：https://github.com/jeanp413/open-remote-ssh/releases

下载.vsix文件后，将 vsix 文件拖入至 cursor 扩展中心{ctrl+shift+x}即可完成安装。

在这里插入图片描述

方法3：手动下载Cursor Server（旧版cursor）

由于网络问题（尤其是在国内）或服务器本身不联网，Cursor 在通过 Remote-SSH 连接服务器时，无法自动下载和安装其服务端组件（Cursor Server），导致连接失败或长时间卡在下载界面。

可以考虑手动下载 Cursor Server 的两个关键组件压缩包，通过 SCP 或者SSH服务器工具等方式传输到服务器上，并解压到指定的目录结构中，以绕过自动安装过程。

1.获取本地 Cursor 版本信息

在本地计算机上执行 cursor –version命令，获取三个关键信息：

# 示例输出，分别表示 CURSOR_VERSION CURSOR_COMMIT LOCAL_ARCH
C:\\Users\\ZHUANG>cursor ––version
0.48.9
b9e5948c1ad20443a5cecba6b84a3c9b99d62580
x64

# CURSOR_VERSION：例如 0.48.9
# CURSOR_COMMIT：例如 b9e5948c1ad20443a5cecba6b84a3c9b99d62580
# LOCAL_ARCH：例如 x64

这些信息将用于构造正确的下载链接。

2. 手动下载 cursor server 文件

https://cursor.blob.core.windows.net/remote–releases/${CURSOR_COMMIT}/cli–alpine–${REMOTE_ARCH}.tar.gz

https://cursor.blob.core.windows.net/remote–releases/${CURSOR_VERSION}–${CURSOR_COMMIT}/vscode–reh–${REMOTE_OS}–${REMOTE_ARCH}.tar.gz
# REMOTE_OS为服务器的操作系统例如linux

以步骤1获取的信息为例：

https://cursor.blob.core.windows.net/remote–releases/b9e5948c1ad20443a5cecba6b84a3c9b99d62580/cli–alpine–x64.tar.gz

https://cursor.blob.core.windows.net/remote–releases/0.48.9–b9e5948c1ad20443a5cecba6b84a3c9b99d62580/vscode–reh–linux–x64.tar.gz

3.用其他SSH工具连接服务器，执行下面命令

# 新好 .cursor-server 相关文件夹
mkdir –p ${HOME}/.cursor–server
mkdir –p ${HOME}/.cursor–server/cli/servers/Stable–$CURSOR_COMMIT/server/

4.将刚刚下载的两个文件上传到服务器中的~/.cursor-server文件夹中

可以使用两种方式下载好压缩包到服务器上

方法1：使用浏览器/其他下载工具粘贴下载链接，在本地下载好，通过 scp 传输到服务器上或者用如XTerminal这类SSH工具上传
方法2：在服务器上通过 wget 或 curl 下载

示例1：scp 传输到服务器，本地执行

# 1. 将本地的 cli-alpine-x64.tar.gz 文件上传到远程服务器的 .cursor-server 目录，并命名为 cursor-cli.tar.gz
scp –P $REMOTE_PORT cli–alpine–x64.tar.gz $REMOTE_USER@$REMOTE_HOST:.cursor–server/cursor–cli.tar.gz
# 变量说明：
# $REMOTE_PORT：远程服务器的 SSH 端口号（默认 SSH 端口为 22，若服务器修改过端口则需替换为实际端口，如 2222）
# $REMOTE_USER：远程服务器的登录用户名（例如你之前使用的 "znx"，即登录服务器时输入的用户名）
# $REMOTE_HOST：远程服务器的地址（可以是 IP 地址，如 "10.51.6.215"，也可以是服务器的域名或自定义主机名，如 "xutnian-test-gpu-002"）
# .cursor-server/cursor-cli.tar.gz：远程服务器上的目标路径和文件名，".cursor-server" 表示服务器当前登录用户的家目录（~）下的 cursor-server 文件夹，"cursor-cli.tar.gz" 是上传后文件的重命名（可根据需求修改）

# 2. 将本地的 vscode-reh-linux-x64.tar.gz 文件上传到远程服务器的 .cursor-server 目录，并命名为 cursor-vscode-server.tar.gz
scp –P $REMOTE_PORT vscode–reh–linux–x64.tar.gz $REMOTE_USER@$REMOTE_HOST:.cursor–server/cursor–vscode–server.tar.gz
# 变量说明（与上一条命令一致，仅本地源文件和远程目标文件名不同）：
# $REMOTE_PORT：远程服务器的 SSH 端口号（默认 22，非默认需替换实际值）
# $REMOTE_USER：远程服务器的登录用户名（如 "znx"）
# $REMOTE_HOST：远程服务器的地址（如 IP "10.51.6.215" 或主机名 "xutnian-test-gpu-002"）
# .cursor-server/cursor-vscode-server.tar.gz：远程服务器的目标路径，将本地的 vscode-reh-linux-x64.tar.gz 重命名为 cursor-vscode-server.tar.gz 并存入 ~/.cursor-server 目录

示例2：XTerminal这类SSH工具上传到服务器

在这里插入图片描述

# 查看上传后的目录，可以看到两个压缩包上传成功
(base) root@iZ2ze9myeakt079znibudrZ:~# cd /root/.cursor-server
(base) root@iZ2ze9myeakt079znibudrZ:~/.cursor–server# ls -l
total 71664
drwxr–xr–x 3 root root 4096 Oct 31 15:28 cli
–rw–r––r–– 1 root root 8636707 Oct 31 15:46 cli–alpine–x64.tar.gz
–rw–r––r–– 1 root root 64733248 Oct 31 15:47 vscode–reh–linux–x64.tar.gz
(base) root@iZ2ze9myeakt079znibudrZ:~/.cursor–server#

5.解压重命名文件（主要替换参数）

# 1.基础准备：文件重命名
mv cli-alpine-x64.tar.gz cursor-cli.tar.gz
mv vscode-reh-linux-x64.tar.gz cursor-vscode-server.tar.gz

# 2.解压 CLI 压缩包到目标目录
tar -xzf cursor-cli.tar.gz -C ~/.cursor-server

# 3.重命名解压后的文件夹，添加版本 Commit 标识
mv ~/.cursor-server/cursor ~/.cursor-server/cursor-$CURSOR_COMMIT
# 替换 $CURSOR_COMMIT 后的实际命令（示例）
mv ~/.cursor-server/cursor ~/.cursor-server/cursor-b9e5948c1ad20443a5cecba6b84a3c9b99d62580

# 解压 cursor-vscode-server.tar.gz压缩包到目标目录
tar -xzf ~/.cursor-server/cursor-vscode-server.tar.gz -C ~/.cursor-server/cli/servers/Stable-$CURSOR_COMMIT/server/ –strip-components=1
# 替换 $CURSOR_COMMIT 后的实际命令（示例）
tar -xzf ~/.cursor-server/cursor-vscode-server.tar.gz -C ~/.cursor-server/cli/servers/Stable-b9e5948c1ad20443a5cecba6b84a3c9b99d62580/server/ –strip-components=1

删除压缩包（可选）

# 删除 cursor-cli.tar.gz 压缩包
rm -f ${HOME}/.cursor-server/cursor-cli.tar.gz

# 删除 cursor-vscode-server.tar.gz 压缩包
rm -f ${HOME}/.cursor-server/cursor-vscode-server.tar.gz

接着重启cursor即可ssh

方法4：手动下载Cursor Server（新版cursor）

1.本地电脑使用 cursor –version 命令查看版本（与旧版一样）

C:\\Users\\ZHUANG>cursor —version
# 示例输出，分别表示 CURSOR_VERSION CURSOR_COMMIT LOCAL_ARCH
1.7.46
b9e5948c1ad20443a5cecba6b84a3c9b99d62580
x64

2.手动下载 cursor server 文件

下载vscode-reh-linux-x64.tar.gz

https://cursor.blob.core.windows.net/remote-releases/${CURSOR_VERSION}-${CURSOR_COMMIT}/vscode-reh-${REMOTE_OS}-${REMOTE_ARCH}.tar.gz

# 替换 $CURSOR_COMMIT 等参数后的实际命令（示例）
https://cursor.blob.core.windows.net/remote-releases/1.7.46-b9e5948c1ad20443a5cecba6b84a3c9b99d62580/vscode-reh-linux-x64.tar.gz

2.在服务器创建目录

mkdir –p${HOME}/.cursor–server/bin/${CURSOR_COMMIT}

# 替换 $CURSOR_COMMIT 后的实际命令（示例）
mkdir –p ${HOME}/.cursor–server/bin/b9e5948c1ad20443a5cecba6b84a3c9b99d62580

3.上传文件到服务器

见方法3的3，上传文件

4.解压重命名

将步骤3上传的文件解压，（假设文件上传${HOME}/.cursor-server/目录）

tar –xzf ${HOME}/.cursor–server/vscode–reh–linux–x64.tar.gz –C ${HOME}/.cursor–server/bin/${CURSOR_COMMIT} —strip–components=1

# 替换 $CURSOR_COMMIT 后的实际命令（示例）
tar –xzf ${HOME}/.cursor–server/vscode–reh–linux–x64.tar.gz –C ${HOME}/.cursor–server/bin/b9e5948c1ad20443a5cecba6b84a3c9b99d62580/ —strip–components=1

然后重启cursor即可ssh

注意：若此前运行过cursor-server需要先把进程等清除掉

pkill –f cursor–server
rm –f ${HOME}/.cursor–server/.${CURSOR_COMMIT} .token
rm –f ${HOME}/.cursor–server/.${CURSOR_COMMIT} .pid
rm –f ${HOME}/.cursor–server/.${CURSOR_COMMIT} .log

参考文献

https://www.cnblogs.com/ziangshen/articles/17741402.html https://github.com/jeanp413/open-remote-ssh https://mark9804.github.io/blog/breves/fullstack/cursor-ssh https://www.cnblogs.com/coldchair/p/19101635 https://cursor.zone/faq/cursor-remote-ssh-connection.html https://zhuanlan.zhihu.com/p/1896951919022425607 https://blog.csdn.net/weixin_58303981/article/details/148471681 https://zhuanlan.zhihu.com/p/1907836616627722164

Cursor远程开发：Remote - SSH报错Failed to install server within the timeout 的解决方案

Cursor ：远程服务器开发时Remote – SSH：报错Failed to install server within the timeout 的解决方案

一、问题原因分析