> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 VSCS 开发环境

> 在人工智能平台中创建、访问和管理 VSCS 开发环境，并配置浏览器 VS Code、SSH 连接和远程开发目录。

VSCS 指 VS Code Server，用于在云端运行 VS Code 开发环境。您可以通过浏览器打开 VS Code，也可以启用 SSH 后从本地终端、本地 VS Code、Cursor 等工具连接开发环境。

VSCS 适合需要多文件项目开发、本地 IDE 远程连接、长时间调试或复用编辑器插件配置的场景。如果只需要 Notebook 交互式分析，可以使用 JupyterLab 开发环境。

## 选择访问方式

* **浏览器 VS Code**：开发环境运行后，通过浏览器打开 VS Code 页面，适合免安装、轻量开发和临时调试。
* **SSH 连接**：通过本地 SSH 客户端或本地 IDE 远程连接开发环境，适合本地工具链、远程开发和多文件项目开发。

两种方式可以单独启用，也可以同时启用。启用后访问的是同一个开发环境，共享同一份文件、Volume 和挂载数据。如果需要 SSH 访问，请先准备 SSH 公钥，并保存对应私钥。

## 准备 SSH 公钥

如果只使用浏览器 VS Code，可以跳过本节。如果需要通过 SSH 或本地 IDE 连接 VSCS，请先准备 SSH 公钥。

如果还没有 SSH 密钥对，可以在本地生成：

```bash theme={null}
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""
cat ~/.ssh/id_rsa.pub
```

创建 VSCS 开发环境或管理 SSH 密钥时，请只填写 SSH 公钥，不要上传或粘贴私钥。

如需提前保存常用 SSH 公钥，进入 **开发环境 > VSCS**，打开 **SSH 密钥管理**。单击 **新建** 后，填写 SSH 公钥内容和便于识别的标题，例如设备或用途。

## 创建 VSCS 开发环境

### 1. 进入创建页

1. 进入 **开发环境 > VSCS**。
2. 单击 **新建**。

### 2. 填写配置信息

#### 基本信息

| 配置项     | 说明                                                                     |
| ------- | ---------------------------------------------------------------------- |
| 区域和集群   | 决定开发环境运行位置。选定后，资源规格、镜像、Volume、数据集和模型等可选项会随之变化。建议选择与数据、模型和算力资源相同或相近的集群。 |
| 名称      | 用于在列表和详情中识别开发环境。名称需符合平台校验规则；如果提交时提示名称冲突，请更换名称后重试。                      |
| 项目组     | 指定开发环境所属项目组。                                                           |
| 在项目组内公开 | 控制项目组内其他用户是否可以在列表中查看该开发环境。公开后，管理操作仍由创建者执行。                             |

#### 资源信息

| 配置项   | 说明                                                                                          |
| ----- | ------------------------------------------------------------------------------------------- |
| 资源类型  | 选择 **预留实例**、**按量实例** 或 **Spot**。不同资源类型会影响资源来源和计费方式。                                         |
| 实例    | 使用 **预留实例** 时，选择 **共享资源池** 或 **专属资源池**。                                                     |
| 实例类型  | 选择 **GPU** 或 **CPU**。代码编辑、依赖安装和轻量调试通常可选择 CPU；需要运行模型训练、推理验证或 GPU 加速任务时选择 GPU。                |
| 资源规格  | 在实例列表中选择规格，并配置单节点实例规格数。创建时可以查看实例详情、用户剩余配额和资源池可用量；提交时平台会校验资源配额，如果提示配额不足，可减少规格数、更换规格或联系管理员扩容。 |
| 资源优先级 | 选择多个实例规格时，按优先级从高到低排序。调度时优先使用排在前面的实例规格。                                                      |

#### 环境信息

| 配置项   | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 访问方式  | 选择 **VSCS**、**SSH**，或同时启用两种方式。启用 SSH 时，请配置 SSH 公钥。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 工作区目录 | 配置打开 VSCS 后默认进入的工作目录。建议指向已挂载的 Volume 路径，否则重启后文件可能丢失。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 镜像    | 选择 **内置**、**自定义** 或 **镜像地址**，决定开发环境内的系统环境、依赖库和开发工具。使用自定义镜像或镜像地址时，请根据访问方式确认镜像组件。请确保镜像包含以下组件：<ul><li><code>bash</code>：平台启动脚本依赖 <code>bash</code>，缺失可能导致开发环境无法拉起。</li><li><code>code-server</code>：启用浏览器 VS Code 访问时需要。建议在镜像中预装，缩短启动时间并提升稳定性。</li><li><code>openssh-server</code> 或 <code>sshd</code>：启用 SSH 访问时需要。建议按所选访问方式在镜像中预装对应组件。</li><li><code>wget</code> 或 <code>curl</code>：使用本地 VS Code、Cursor 等通过 Remote-SSH 首次连接时，远程 IDE 可能需要下载 server 组件，镜像内建议具备 <code>wget</code> 或 <code>curl</code>。</li></ul>如果镜像缺少 <code>code-server</code> 或 SSH 相关组件，平台可能会在启动时尝试注入。为了缩短启动时间并提升稳定性，建议在镜像中预装所需组件。 |
| 存储    | 选择需要挂载的 Volume，并填写 Pod 中挂载路径。Volume 和挂载路径需成对配置，可添加多条存储挂载。挂载时关注：<ul><li>挂载路径建议使用 `/volume`、`/mnt` 等开头的目录。</li><li>避免覆盖根目录、`/opt`、`/workspace`、`/usr` 等镜像默认目录。</li><li>需要保留代码、编辑器设置、插件、Python 依赖或输出结果时，请挂载 Volume，并将工作区目录、用户配置目录和插件安装目录设置到 Volume 路径下。</li><li>容器本地盘容量有限，开发环境重启或迁移后，写入本地盘的数据可能被清空。</li></ul>                                                                                                                                                                                                                                                                                         |
| 数据集   | 选择需要挂载的数据集，可按需挂载子目录。数据集通常作为只读输入使用。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 模型    | 选择需要挂载的模型，可按需挂载子目录。模型通常作为只读输入使用。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 命令    | 输入 shell 命令，在 coder-server 启动前执行，适合设置环境变量、准备目录或启动轻量后台服务。如果命令无效或执行失败，可能导致 VSCS 无法启动。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

#### 高级配置

| 配置项    | 说明                                                        |
| ------ | --------------------------------------------------------- |
| 环境变量   | 以键值对形式添加环境变量，供启动命令或开发环境内程序读取，常用于配置项、路径或凭据。敏感信息需谨慎使用。      |
| 时区     | 配置开发环境时区，默认 `Asia/Shanghai`，会影响日志时间戳、定时启停时间和程序本地时间。       |
| 用户配置目录 | 配置 VSCS 用户设置和历史记录保存路径。建议指向已挂载的 Volume 路径，便于重启或重建后复用编辑器设置。 |
| 插件安装目录 | 配置 VSCS 插件安装路径。建议指向已挂载的 Volume 路径，避免重启或重建后重复安装插件。         |

### 3. 提交创建

单击 **新建** 提交。开发环境会异步创建，您可以在列表中查看状态变化。

## 打开 VSCS

### 打开浏览器 VS Code

1. 进入 **开发环境 > VSCS**。
2. 在列表中找到目标开发环境。
3. 确认开发环境处于运行中状态，且已启用浏览器 VS Code 访问。
4. 单击 **打开**。
5. 进入浏览器 VS Code 后，确认工作区目录、用户配置目录和插件安装目录符合预期。

浏览器 VS Code 打开后，会进入创建或更新时配置的工作区目录。VSCS 不使用 JupyterLab 的默认目录；打开后的默认位置由工作区目录决定。

<img src="https://mintcdn.com/siflow/avekptrv6O-LsLPz/ai-platform/development/media/open-vscode-server-development-environment.png?fit=max&auto=format&n=avekptrv6O-LsLPz&q=85&s=07858750010ed99d8212cea0d2bd9fc4" alt="在浏览器中打开 VSCS 开发环境" width="1440" height="900" data-path="ai-platform/development/media/open-vscode-server-development-environment.png" />

### 通过 SSH 连接 VSCS

启用 SSH 访问后，开发环境详情页会展示 SSH 连接地址，格式如下：

```bash theme={null}
ssh root@<公网IP> -p <端口>
```

使用本地终端连接时，将 `<公网IP>` 和 `<端口>` 替换为详情页显示的值，并确保本地私钥与开发环境所配置的 SSH 公钥匹配。

如果使用本地 VS Code、Cursor 等 IDE 的 Remote-SSH 功能，请将详情页中的 SSH 地址配置到本地 IDE 中。首次连接时，远程 IDE 可能需要在开发环境内下载 server 组件，因此自定义镜像中建议包含 `wget` 或 `curl`。

启用 SSH 访问的开发环境会通过集群节点的 NodePort 暴露 SSH 服务。每个集群可用的 NodePort 数量有限；如果启用 SSH 的开发环境过多，新建时可能因无法分配端口而失败。SSH 端口在开发环境生命周期内保持稳定，原地重启或重调度重启后通常不需要修改本地连接配置。

## 保存代码、插件和依赖

VSCS 的工作内容由代码工作区、编辑器设置、插件和运行依赖组成。建议将需要长期保留的内容放到 Volume 挂载路径下。

### 保存工作区和编辑器配置

* **工作区目录**：打开 VSCS 后默认进入的工作目录。建议设置为项目目录或 Volume 挂载路径，避免重启后文件丢失。
* **用户配置目录**：保存 VSCS 用户设置和历史记录。建议使用 Volume 路径，便于复用编辑器设置。
* **插件安装目录**：保存 VSCS 插件。建议使用 Volume 路径，避免重启或重建后重复安装插件。

挂载 Volume、数据集和模型时，建议提前约定路径命名。例如将项目代码、插件缓存、Python 依赖和输出结果放在 Volume 路径下，将数据集和模型作为只读输入路径使用。这样本地 IDE、终端命令和脚本可以复用固定路径。

### 持久化 Python 依赖

如果需要持久化 Python 依赖，可以将安装目录指向 Volume 路径，并配置 `PYTHONPATH`。例如：

```bash theme={null}
pip config set global.target /volume/test/pkg
export PYTHONPATH=/volume/test/pkg:$PYTHONPATH
```

## 查看和管理开发环境

### 查看配置、事件和监控

详情页用于确认开发环境配置、访问方式、生命周期事件和资源用量。开发环境创建、启动、停止、重启或访问异常时，建议先进入详情页查看状态、事件和停止原因。

* **基本配置**：查看资源规格、区域、集群、所有者、创建时间、更新时间、项目组和可见性等信息。
* **资源信息**：查看资源池、用户选择的实例规格、实际使用规格和所在节点。
* **环境信息**：查看时区、镜像、镜像地址、挂载的存储、数据集、模型、环境变量、启动命令、访问方式和 VSCS 目录配置。
* **事件**：查看开发环境调度、启动、异常和生命周期变化，适合排查创建失败、启动失败、卷挂载失败等问题。
* **监控**：查看开发环境的 CPU、内存、GPU 等资源用量曲线，用于判断资源是否够用或是否长期闲置。

如果开发环境未进入运行中状态，先查看事件和停止原因，再根据提示检查资源配额、镜像组件、访问方式、卷挂载路径、启动命令或环境变量。

### 管理生命周期

创建后，您可以在列表或详情页对 VSCS 开发环境执行生命周期管理操作。

* **更新**：修改镜像、资源规格、Volume 挂载、数据集或模型挂载、启动命令、环境变量、访问方式或 VSCS 目录配置。部分变更需要重启后才能生效。
* **启动**：将已停止的开发环境重新拉起。启动时会重新申请算力并进行调度。
* **停止**：关闭运行中的开发环境并释放算力。开发环境配置和已写入 Volume 的数据会保留。
* **重启**：重启会中断开发环境内正在运行的程序、终端进程或远程 IDE 会话。原地重启通常用于重置运行进程；重调度重启会重新校验资源并重新调度，可能被分配到其他节点。
* **保存为镜像**：将运行中的开发环境保存为自定义镜像，便于后续复用已安装的依赖和工具。保存期间开发环境会暂时不可用，建议在无交互操作时执行。
* **调整可见性**：将开发环境设置为私有或项目组内公开。调整可见性不影响运行状态。
* **删除**：移除开发环境记录并释放占用资源。删除前，请确认需要保留的数据已保存到 Volume。

重启前请保存编辑器和终端中的未提交内容。删除或重建开发环境前，请确认代码、插件配置、Python 依赖和输出结果已写入 Volume；仅保存在容器本地盘中的文件可能无法恢复。

## 配置闲置回收

VSCS 开发环境长时间运行会持续占用算力。您可以按使用习惯配置定时启停或自动缩容，减少闲置资源占用。

### 定时启停

定时启停用于按周期性时间规则自动启动或停止开发环境，适合固定工作时间的开发场景。例如工作日前自动启动、夜间自动停止，让算力集中在实际使用时段。

配置定时启停时，请关注开发环境时区，避免计划触发时间与预期不一致。定时计划可以与手动启停并用；计划外需要使用时仍可手动启动，后续计划会在下一个触发点继续生效。

### 按 GPU 利用率自动缩容

按 GPU 利用率自动缩容用于回收长时间闲置的 GPU 算力。当 GPU 利用率在设定观测时长内持续低于阈值时，平台会自动停止开发环境并释放 GPU。

配置自动缩容时，需要关注观测时长、GPU 利用率阈值和策略类型。策略类型用于决定按观测期内的最大值或平均值判断是否闲置。自动缩容触发后不会自动重新启动开发环境；需要继续使用时，请手动启动，或配合定时启停计划启动。对需要长时间保留远程 IDE 会话的开发环境，请调高阈值或关闭自动缩容，避免误停正在进行的工作。

## 处理远程 IDE 组件下载失败

部分 GPU 节点无法联网。本地 VS Code、Cursor 等通过 Remote-SSH 首次连接时，可能需要在远端下载 server 组件或插件。如果目标 GPU 节点无法联网，连接可能卡在下载阶段。

可以先用可联网 CPU 开发环境完成预下载，再切换到目标 GPU 资源规格：

1. 创建启用 SSH 的 CPU 开发环境，挂载一个持久化 Volume。
2. 将用户配置目录和插件安装目录设置为该 Volume 中的路径。
3. 使用本地 VS Code 或 Cursor 通过 Remote-SSH 连接 CPU 开发环境，让远程 IDE 将 server 组件下载到 Volume。
4. 更新资源规格，切换为目标 GPU 资源规格，并保持同一个 Volume 和相同用户配置目录、插件安装目录。
5. 再次从本地 IDE 连接开发环境，此时可复用已经下载到 Volume 中的组件。

CPU 和 GPU 两个阶段需要挂载同一个 Volume，并保持用户配置目录和插件安装目录路径一致。

## 排查常见问题

<AccordionGroup>
  <Accordion title="开发环境长时间排队或创建失败怎么办？">
    查看事件和状态详情，确认所选资源规格、用户剩余配额和资源池可用量是否满足要求。配额不足时，可减少规格数、更换规格或联系管理员扩容。
  </Accordion>

  <Accordion title="浏览器 VS Code 打不开怎么办？">
    确认开发环境处于运行中状态，且已启用浏览器 VS Code 访问；如果反复重启，检查镜像是否包含 `code-server`，并查看启动命令和环境变量。
  </Accordion>

  <Accordion title="SSH 连接失败怎么办？">
    确认已启用 SSH 访问，本地私钥与平台配置的 SSH 公钥匹配，连接地址和端口来自开发环境详情页。
  </Accordion>

  <Accordion title="本地 IDE 首次连接卡在下载 server 组件怎么办？">
    确认开发环境所在节点是否可联网，或先使用可联网 CPU 开发环境完成离线预下载。
  </Accordion>

  <Accordion title="SSH 连接提示 remote host identification has changed 怎么办？">
    确认连接地址来自控制台详情页后，可以在本地清除旧记录再重连。

    ```bash theme={null}
    ssh-keygen -R "[<公网IP>]:<端口>"
    ```
  </Accordion>
</AccordionGroup>

## 相关文档

* [创建和使用存储卷](../resources/create-and-use-storage-volumes)