Ray Lab（数据实验室）支持通过本地 IDE 远程连接：您可以在本地使用 VS Code、Cursor、CodeBuddy 等熟悉的编辑器，直接编辑云端 Ray Lab 工作目录中的代码，代码的执行、调试与算力均运行在云端 Ray Lab 实例中。
与浏览器 WebIDE 的对比
对比项 | 浏览器 WebIDE | 本地 IDE 连接 |
编辑体验 | 在浏览器内编辑 | 本地完整 IDE，支持自定义快捷键、插件与主题 |
AI 辅助编程 | 受限 | 可直接使用 Cursor、CodeBuddy、Codex 等 AI 编程能力 |
文件管理 | 在浏览器内管理 | 直接在本地编辑云端目录，无需手动上传下载 |
断点调试 | 受限 | 使用本地 IDE 原生调试能力 |
运行环境 | 云端 | 云端 |
前提条件
条件 | 说明 |
账号权限 | 您的腾讯云账号（CAM）拥有目标 Ray Lab 的资源访问权限，且具备本地 IDE 连接相关的操作权限 |
已开启访问认证 | |
实例运行中 | 非运行中状态的实例无法建立连接，请在 Ray Lab 列表或详情页确认状态为“运行中” |
本地 Python 环境 | 本地已安装 Python 3.x 与 pip，用于安装连接工具 |
本地 IDE | 已安装 VS Code、Cursor 或 CodeBuddy（支持一键打开）；或任意支持 SSH 远程开发的工具 |
网络连通性 | 本地可访问公网 443 端口 |
使用限制
仅连接 Head 节点：本地 IDE 连接的是 Ray Lab 容器（等价于 Ray 集群的 Head 节点），不支持直接登录 Worker 节点。您提交的 Ray 任务由 Head 节点通过 Ray 内部机制分发到各 Worker 节点执行，无需也无法单独访问 Worker。
登录身份为普通用户：连接后的登录身份为
ray 用户，不提供 root 权限。一键打开范围：控制台支持一键打开 VS Code、Cursor、CodeBuddy；其他支持 SSH 远程开发的 IDE 与终端工具也可连接，需手动完成配置。
配置有效期：连接码生成后 5 分钟内有效；完成配置后，本地连接配置的有效期为 30 天，到期需重新配置，详见 管理访问凭证与连接有效期 一节。
存量实例需重启一次：2026年11月2日前创建的 Ray Lab，首次使用本地 IDE 连接前请在控制台重启一次实例。未重启直接连接时，可能出现连接码校验通过但终端报错的情况，重启实例后重新执行步骤4即可。
步骤1：创建 Ray Lab 并开启访问认证
1. 进入 Ray Lab 创建页，完成基本配置。
2. 在「基本信息」的「访问认证」处勾选开启访问认证。使用本地 IDE 或第三方工具连接时必须开启该项。
3. 建议同时在「基本信息」的「持久化配置」中开启启用代码文件持久化，避免本地 IDE 中产生的代码在实例重启后丢失，详见 文件与持久化说明 一节。
警告：
访问认证只能在新建 Ray Lab 时开启，存量 Ray Lab 无法直接开启。如需对存量 Ray Lab 使用本地 IDE 连接，请克隆该 Ray Lab，并在克隆时勾选开启访问认证。
步骤2：进入本地 IDE 连接页面
1. 单击进入运行中的 Ray Lab 详情页。
2. 单击右上角 IDE 连接，选择本地 IDE 连接，进入连接指引弹窗。
步骤3：安装连接工具
首次使用需在本地终端安装 DLC 提供的连接工具（仅需安装一次）：
1. 在弹窗的「安装连接工具」中，复制安装命令。
2. 在本地终端中执行该命令完成安装。
说明：
安装命令以控制台弹窗中提供的为准。安装完成后，后续连接其他 Ray Lab 时可直接从步骤4开始。
步骤4：在终端完成连接配置
1. 在本地终端执行连接命令。命令中的 Ray Lab ID 可在弹窗中复制：
tcdlc connect raylab-xxxxxxxxxxxx
2. 终端会提示粘贴连接码：
Paste the connect code copied from the console page (starts with dlc1., valid for 5 minutes):
3. 回到控制台弹窗，单击生成连接码并复制。
4. 将连接码粘贴到终端并回车。
5. 终端显示
Connection verified 即表示配置成功，并提示可通过 ssh raylab-xxxxxxxxxxxx 连接：Connection verified. Return to the console to open your IDE.Try it: ssh raylab-xxxxxxxxxxxx
注意：
1. 连接码中包含 Ray Lab 的访问凭证，请妥善保管，不要分享给他人。连接码仅 5 分钟内有效，过期后请重新生成。
2. 若在控制台单击生成连接码并复制时提示操作失败，或终端出现
SSH could not be started 等 SSH 相关报错，请先确认本地 OpenSSH 客户端可用（终端执行 ssh -V 能输出版本号）；若 Ray Lab 创建于 2026年11月2日前，请重启实例后重新生成连接码并完成配置，详见常见问题。步骤5：打开本地 IDE
1. 回到控制台弹窗，勾选我已在终端完成配置。
2. 单击 VS Code、Cursor 或 CodeBuddy，本地 IDE 将自动拉起并连接云端 Ray Lab。
3. 首次连接时，本地 IDE 可能提示安装 Remote-SSH 等远程开发扩展，按提示安装后重试即可。
4. 连接成功后，打开 Ray Lab 工作目录即可开始开发。
说明：
首次连接需要等待几分钟：首次建立连接时，需要在 Ray Lab 容器中安装远程开发所需的依赖，请耐心等待。只要 Ray Lab 未重启，后续再次打开本地 IDE 无需重复等待。
使用 AI 编程功能需开通公网访问：AI 编程功能需要 Ray Lab 能够访问公网。请在创建 Ray Lab 时，于「网络配置」中选择已配置公网访问的网络连接，配置方法参见 网络连接配置。
用其他工具连接
若您使用其他支持 SSH 远程开发的 IDE 或终端工具（如 JetBrains 系列、Trae 等），可单击弹窗底部的用其他工具连接展开指引，按提示获取连接信息并完成配置。
步骤6：验证连接
连接成功后，在本地 IDE 的终端中执行以下命令，确认使用的是云端 Ray 环境：
python -c "import ray; print(ray.__version__)"
您也可以在 Ray Lab 详情页的 Dashboard 页签查看 Ray 集群状态，确认任务运行在云端算力上。
使用 SSH 相关能力（可选）
完成步骤4后，本地即具备标准 SSH 能力，主机别名为 Ray Lab ID（例如
raylab-xxxxxxxxxxxx），可按需使用：能力 | 使用方式 |
命令行登录 | ssh raylab-xxxxxxxxxxxx |
文件复制 | scp ./local_file.py raylab-xxxxxxxxxxxx:/workspace/ |
端口转发 | ssh -L 8265:localhost:8265 raylab-xxxxxxxxxxxx，之后在本地浏览器访问 localhost:8265 即可打开 Ray Dashboard |
IDE 端口面板 | 在 VS Code 的「端口」面板中转发远端端口后本地访问 |
管理访问凭证与连接有效期
项目 | 有效期 / 说明 |
连接码 | 生成后5分钟内有效，过期需重新生成 |
本地连接配置 | 完成步骤4后30天内有效，到期需重新执行步骤4 |
访问凭证（Token）重置 | 重置后原有连接配置立即失效，需重新执行步骤4 |
访问凭证相当于 Ray Lab 的访问凭证，请妥善保管，避免泄露造成安全风险。
警告：
请勿将访问凭证与连接码硬编码到代码、脚本，或提交到代码仓库中。
文件与持久化说明
场景 | 代码文件是否保留 |
已开启代码文件持久化 | 实例重启、重建后保留，可用于集群恢复与重新挂载 |
未开启代码文件持久化 | 工作目录文件为临时属性，实例重启、重建等操作后丢失 |
常见问题
连接失败或超时，如何排查？
请按以下顺序排查：
1. Ray Lab 实例是否处于运行中状态。
2. 创建时是否已开启访问认证，且访问凭证未被重置。
3. 若 Ray Lab 创建于 2026年11月2日前，是否已重启过一次实例。
4. 连接码是否在 5 分钟内使用，本地连接配置是否仍在 30 天有效期内。
5. 本地网络是否可访问公网 443 端口。若您在企业网络或代理环境下，请确认代理放行了 HTTPS 与 WebSocket 连接。
6. 连接工具是否安装成功。
7. 单击弹窗底部的**连接失败?**查看更多排查建议。
单击生成连接码提示操作失败，或终端提示
SSH could not be started，怎么办？以上报错均可能由存量实例未重启导致，请按以下顺序处理：
1. 重启 Ray Lab 实例，回到详情页重新进入本地 IDE 连接，重新生成连接码并执行步骤4。2026年11月2日前创建的 Ray Lab 未重启时较易出现此类报错：控制台侧表现为单击生成连接码并复制时提示操作失败（如
Lab SSH secret not found），终端侧表现为 SSH could not be started 等 SSH 相关报错。2. 若报错出现在终端侧，确认本地 OpenSSH 客户端可用：在终端执行
ssh -V，能正常输出版本号即为可用。3. Windows 环境如未安装 OpenSSH，请在「设置 - 应用 - 可选功能」中添加 OpenSSH 客户端，或安装 Git for Windows 后重试。
4. 若仍失败，请按**连接失败或超时，如何排查？**中的顺序逐项检查；仍未解决请提交工单联系技术支持。
企业网络或代理环境下无法连接？
本地 IDE 连接通过 443 端口的 HTTPS 加密通道传输。若企业网络启用了 TLS 检查或代理，可能拦截 WebSocket 连接，请联系网络管理员放行相关域名与 WebSocket 协议升级请求。
是否需要为 Ray Lab 配置公网 IP 或放通 22 端口？
不需要。本地 IDE 连接本身不使用 SSH 22 端口，无需为 Ray Lab 配置公网 IP 或安全组入方向规则。
我的 Ray Lab 是之前创建的，没有开启访问认证，怎么办？
访问认证只能在新建时开启，存量 Ray Lab 无法直接开启。请克隆该 Ray Lab，并在克隆时勾选开启访问认证，再使用克隆后的 Ray Lab 进行本地 IDE 连接。
提示连接已失效或连接码已过期怎么办？
连接码仅 5 分钟内有效，本地连接配置有效期为 30 天，访问凭证重置后原有配置也会失效。以上任一情况，请回到详情页重新进入本地 IDE 连接，重新执行步骤4完成配置，再重新打开本地 IDE。
连接后能使用 root 权限吗？能登录 Worker 节点吗？
不能。连接后的登录身份为
ray 用户，不提供 root 权限。本地 IDE 连接的是 Ray Lab 容器（等价于 Head 节点），不支持直接登录 Worker 节点。您提交的 Ray 任务由 Head 节点通过 Ray 内部机制分发到各 Worker 节点执行。断开本地 IDE 后，实例是否仍在运行与计费？
是。断开本地 IDE 不会停止 Ray Lab 实例，实例将在运行期间持续计费。如不再使用，请在控制台对实例执行停止操作。
重启 Ray Lab 实例后，需要重新配置吗？代码还在吗？
能否多人同时连接同一个 Ray Lab？
可以。只要成员的腾讯云账号（CAM）具备该 Ray Lab 的资源访问权限，并拥有本地 IDE 连接的相关操作权限，即可各自在本地完成配置并同时连接。请由主账号或管理员在访问管理中为成员授权。
提示无权限，或看不到「本地 IDE 连接」入口？
请确认您的腾讯云账号（CAM）具备该 Ray Lab 的资源访问权限与本地 IDE 连接相关的操作权限，且实例已开启访问认证并处于运行中状态。权限问题请联系主账号或管理员在访问管理中为您授权。
