# VS Code Remote-SSH 服务端离线安装包

适用场景: VS Code 通过 Remote-SSH 连接 Linux 服务器时, 卡在
`Installing VS Code Server` / `Downloading with wget`, 最后报
`Failed to parse remote port from server output` 或 `local-server-1> Timed out`。

思路: 把 VS Code 服务端(`.vscode-server`)提前在服务器上装好, 客户端连上来只需要启动
已有服务端, 不再触发下载, 也就不会撞上客户端的超时。

---

## 1. 目录内容

```
/root/install-各安装类目/vscode-server/
├── install.sh                            安装脚本
├── README.md                             本说明
├── commit.txt                            本包对应的 VS Code commit id
├── vscode-server-linux-x64.tar.gz        服务端安装包 (x86_64)
└── vscode-server-linux-x64.tar.gz.sha256 校验文件
```

当前包对应:

| 项 | 值 |
|---|---|
| VS Code 版本 | 1.144.1 (stable) |
| commit id | `261c84cb1eddf11235f9e2c921425e9663fbe556` |
| 架构 | linux-x64 |
| 包大小 | 223,604,566 字节 |
| 解压后占用 | 约 641 MB |

---

## 2. 用法

### 在本机安装

```bash
cd /root/install-各安装类目/vscode-server
./install.sh
```

### 复制到其它电脑安装

```bash
# 整个目录拷走 (223 MB)
scp -r /root/install-各安装类目/vscode-server 目标机:/root/install-各安装类目/

# 到目标机上执行
cd /root/install-各安装类目/vscode-server
./install.sh
```

脚本会自动识别目标机 CPU 架构。若目标机不是 x86_64 而包里只有 x64, 脚本会打印出该
架构的下载地址, 或直接加 `-d` 让脚本自己下载。

### 参数

| 参数 | 作用 |
|---|---|
| `-c, --commit <id>` | 指定 commit id, 默认读 `commit.txt` |
| `-a, --archive <file>` | 指定 tar 包, 默认按架构自动选 |
| `-d, --download` | 本地缺包时联网下载 |
| `-f, --force` | 已安装也强制重新解压 |
| `-x, --clean` | 清理残留锁文件和半截安装, 不安装 |
| `-l, --list` | 列出本目录所有 tar 包 |
| `--agent-dir <p>` | 自定义服务端目录, 默认 `~/.vscode-server` |

脚本可重复执行: 已装好会直接跳过。

---

## 3. 关键前提: commit id 必须和客户端 VS Code 版本一致

服务端目录是按 commit id 区分的:

```
~/.vscode-server/bin/<commit id>/
```

客户端 VS Code 升级后 commit id 会变, 旧包就不起作用了, 表现为又开始重新下载。
取客户端 commit id 的两种办法:

1. VS Code 菜单 `帮助` -> `关于`, 里面的 "Commit"。
2. `输出` 面板选 `Remote-SSH`, 找这一行:
   `Using commit id "xxxx" and quality "stable" for server`

拿到新 commit 后更新本包:

```bash
cd /root/install-各安装类目/vscode-server
echo "<新commit id>" > commit.txt
curl -fL -o vscode-server-linux-x64.tar.gz \
  "https://update.code.visualstudio.com/commit:<新commit id>/server-linux-x64/stable"
sha256sum vscode-server-linux-x64.tar.gz > vscode-server-linux-x64.tar.gz.sha256
./install.sh -f
```

架构对应关系: `x86_64` -> `server-linux-x64`, `aarch64` -> `server-linux-arm64`,
Alpine/musl -> `server-linux-x64-musl`。

---

## 4. 客户端侧建议配置(强烈建议一起改)

这次连不上的直接原因不是带宽。实测服务器下载速度约 17 MB/s, 223 MB 的包 13 秒就能下完。
真正的问题在客户端: 连接日志里出现

```
local-server-1> listen EINVAL: invalid argument .../vscode-ssh-askpass-xxxx.sock
Server delay-shutdown request failed: connect EINVAL ...
local-server-1> Timed out
```

Remote-SSH 会先起一个 local server 进程代理 ssh 连接, 它和扩展之间靠一个本机 unix socket
通信。这个 socket 建立失败(`listen EINVAL`), 扩展就没法给 local server 续期, local server
在 5 秒左右自行超时, 把还在安装的 ssh 连接掐掉。服务端于是留下半截安装和一个锁文件,
之后每次重试都是:

```
Installation already in progress...
exitCode==24==
```

在一台机器上试过 socket 路径长度不是原因(113 字符路径在 macOS 上可以正常 listen), 所以
不要按路径长度去排查。

绕开这个 local server 即可, 在 VS Code `settings.json` 里加:

```json
{
  "remote.SSH.useLocalServer": false,
  "remote.SSH.showLoginTerminal": true
}
```

`useLocalServer: false` 让 Remote-SSH 直接用 ssh 而不经过 local server, 上面的 socket
问题和 5 秒超时都不存在了。`showLoginTerminal: true` 能在终端里看到真实报错, 便于排错。

如果还想保留 local server, 也可以改用服务端不下载的方式:

```json
{ "remote.SSH.localServerDownload": "off" }
```

---

## 5. 验证是否装好

```bash
C=$(cat /root/install-各安装类目/vscode-server/commit.txt)
D="$HOME/.vscode-server/bin/$C"
ls "$D"/node "$D"/out/server-main.js "$D"/bin/remote-cli/code
"$D"/node --version
```

四个文件都在、`node` 能出版本号, 就说明服务端可用。

---

## 6. 排错清单

| 现象 | 处理 |
|---|---|
| `Installation already in progress` | `./install.sh -x` 清锁, 再 `./install.sh -f` |
| 又开始重新下载 | commit id 和客户端版本不匹配, 见第 3 节 |
| `exitCode==24==` | 同上, 锁被占或包不匹配 |
| 磁盘不足 | `df -h /`, 服务端解压约需 700 MB; 清旧版本 `rm -rf ~/.vscode-server/bin/<旧commit>` |
| 连上后终端/端口转发异常 | 试 `"remote.SSH.enableDynamicForwarding": false` |
| 目标机是 arm64 / Alpine | 用对应架构的包, 见第 3 节 |

---

## 7. Cursor 同理

Cursor 用的是另一套目录, 出问题时的处理完全一样:

```
~/.cursor-server/bin/linux-x64/<commit id>/
```

包地址换成 Cursor 官方对应版本即可。

---

## 8. 卸载

```bash
C=$(cat /root/install-各安装类目/vscode-server/commit.txt)
rm -rf "$HOME/.vscode-server/bin/$C"
```
