> ## 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 SSH 连接失败的问题。

本页用于排查工作负载运行环境和文件访问问题。先确认问题发生在镜像准备、存储挂载、持久化配置还是 SSH 连接阶段。

## 镜像拉取或构建失败

先确认问题发生在工作负载拉取镜像，还是自定义镜像构建。

**镜像拉取失败**

1. 查看工作负载 **事件** 中的具体报错。
2. 检查镜像地址和版本、目标集群可用的镜像 URL，以及仓库访问权限。

**自定义镜像构建失败**

1. 构建任务长时间排队时，检查构建资源、资源池可用量、个人配额和调度信息。
2. 构建失败时，先查看 **编译日志**，判断问题来自基础镜像、Dockerfile、依赖安装、文件路径还是命令执行。
3. `apt` 或 `pip` 安装失败时，核对包名称、固定版本、安装源、网络和基础环境兼容性。

修正已经确认的配置问题后再重新构建，不要只增加重试次数。完整操作请参考[构建自定义镜像](../images/build-custom-images)。

## 挂载后找不到文件，或只能读不能写

挂载问题通常来自源目录、容器内路径、目录权限或容量限制不一致。

1. 确认源目录确实包含目标文件。
2. 核对源目录与容器挂载路径的对应关系，代码应使用容器内路径访问文件。
3. 检查 Volume 或目录授权是只读还是读写，并确认目录级权限覆盖目标目录。
4. 可以读取但无法写入时，同时检查 Volume 剩余容量和用户目录限额。

数据集通常作为只读输入使用，训练输出、checkpoint、Notebook 和临时文件应写入独立的可写 Volume。

Volume 挂载请参考[创建和使用存储卷](../resources/create-and-use-storage-volumes)；数据集挂载请参考[在开发环境和训练任务中挂载数据集](../datasets/mount-datasets-in-workloads)。

## 重启后文件、插件或依赖丢失

容器本地文件和进程内存不会因重启自动保留。因此，开发环境中未写入持久化存储的文件和依赖，可能在重启、重调度或重新创建后丢失。请根据内容类型选择保存方式：

| 内容 | 建议保存方式 |
| - | - |
| 代码、Notebook、结果和 checkpoint | 写入已挂载的 Volume，必要时同步到代码仓库。 |
| 编辑器配置和插件 | 将对应目录配置到可写的持久路径，并在重启前验证配置确实写入该路径。 |
| 系统依赖、工具链和 Python 包 | 保存为自定义镜像，或保留 Dockerfile、依赖清单和安装脚本。 |

## VSCS SSH 无法连接或更新公钥后仍失败

先确认开发环境和连接信息，再检查本地密钥：

1. 确认 VSCS 开发环境已就绪，并且创建时启用了 **SSH** 访问方式。
2. 回到当前开发环境详情页，使用页面最新展示的地址、端口和用户名，不要沿用旧环境或旧会话中的连接信息。
3. 确认本地 SSH 客户端使用的私钥与平台保存的公钥匹配。
4. 出现 `publickey` 错误时，检查本地私钥路径、文件权限和 SSH 配置，不要上传私钥或关闭主机与密钥校验。
5. 修改公钥后等待约 `1` 分钟，再重新获取详情页连接信息；仍无法连接时，结合开发环境状态和 SSH 客户端错误继续定位。

密钥准备、创建配置和连接方式请参考[使用 VSCS 开发环境](../development/use-vscode-server-development-environment)。