---
url: /zh/workspaces/file-keeper.md
description: |
  介绍云原生开发环境的代码备份与文件漫游策略，包括环境销毁时的工作区代码自动备份、恢复机制， 以及 VS Code 插件配置和漫游目录的持久化说明。
---
云原生开发采用按需使用、闲置自动销毁的策略。为防止环境销毁后丢失未提交代码和配置，系统会自动备份和漫游。

## 工作区代码备份

无需担心环境销毁导致工作区未提交代码丢失，系统提供两种备份方式确保代码安全。

:::tip
对于团队开发，建议创建个人分支开发。一个分支仅由一人开发，以减少恢复代码导致的冲突。
:::

### 开发环境销毁时备份

在当前工作区目录 `/workspace` 修改代码后，即使未及时提交，环境回收时也会自动备份。
重建开发环境后，代码会自动恢复到工作区。

#### 1. 备份和恢复方式

* **备份**：环境销毁时将未提交代码打包备份。每个分支仅保留一份备份，新备份会覆盖旧备份。
  如果同一分支同时启动了两个环境，后销毁的备份会覆盖先销毁的。
* **恢复**：环境重建时下载备份并原样恢复到工作区

:::tip
以下两种情况不会备份：

* 单个代码文件或单个 diff 文件内容大小超过 100MB，该文件会被过滤掉，仅打包不超过 100MB 的文件
* 总的备份文件大小超过 100MB，不会被备份

大文件建议用 `.gitignore` 忽略。
:::

#### 2. 备份内容

* 工作区的 stash
* 工作区未 push 的 commit
* 工作区未提交代码（工作区修改、暂存区修改、未追踪文件，不包括 `.gitignore` 忽略的文件）

#### 3. 备份代码删除时机

* 每个分支仅保留一份备份，新备份会覆盖旧备份
* 删除分支时，该分支下所有用户的备份将被自动删除且无法恢复

#### 4. 恢复策略说明

重建或新建环境时，会基于分支最新代码启动，并尝试恢复最新备份。
若在非云原生开发环境中提交过代码，可能会发生冲突，此时可丢弃恢复的代码。

:::tip
**工作区代码备份**在恢复成功后会自动删除远端备份，即每次备份仅可恢复一次。新环境销毁时会产生新备份。

**非工作区文件漫游**（如 `.gitconfig`、自定义漫游目录等）的远端备份不会被删除，会持续保留供后续环境复用。

以下内容不会备份：

* `.gitignore` 中声明的内容
* 子仓库中的修改
* 非工作区的修改

:::

### 定时备份策略

为提高备份可靠性，系统还采用定时备份策略，每 5 分钟自动将未提交代码打包备份。

* **下载**：在 `我的云原生开发` 列表页可下载备份代码压缩包。
* **删除**：删除开发环境历史记录时会删除该备份。

:::tip

* 单个文件超过 100MB，该文件不会备份。
* 备份代码压缩包超过 100MB 也不会被备份。

:::

## 非工作区文件漫游

云原生开发支持非工作区目录的文件漫游，环境销毁后再次创建时会自动恢复。

最大漫游容量：\_\_ENV\_\_VSCODE\_USER\_DATA\_SIZE MB，超出将报错且无法漫游。

### 默认漫游内容

以下文件或文件夹按用户维度漫游，对所有项目生效（`~` 为当前用户主目录，一般为 `/root`）：

* `~/.gitconfig`：Git 全局配置。若容器内已存在该文件（如自定义环境预置），
  则恢复和保存时均跳过。推荐自定义环境时修改 `/etc/gitconfig` 以避免冲突。
* `~/.local/share/code-server/User/settings.json`：WebIDE 配置文件
* `~/.local/share/code-server/User/snippets/*`：WebIDE 相关配置
* `~/.local/share/code-server/User/keybindings.json`：WebIDE 快捷键配置

用户可在 `~/.cnb` 目录下新增个人配置文件。例如新增 `.env.local` 存储个人环境变量，
再通过 [脚本任务](../build/grammar.md#脚本任务)将其复制或软链到工作目录，并在 `.gitignore` 中忽略该文件。

**示例：将漫游文件关联到工作目录**

修改漫游文件时需直接编辑 `/root/.cnb/.env.local`。以下示例将其关联到工作目录
（仓库根目录 `/workspace`），按需选择复制或软链方式：

#### 复制方式（cp）

```yaml title=".cnb.yml"
$: # 兜底匹配所有分支，不被 glob 匹配的分支
  vscode:
    - services:
        - vscode
      stages:
        - name: 关联 .env.local 到工作目录
          script: cp -f /root/.cnb/.env.local ./ 2>/dev/null || echo "文件不存在"
```

#### 软链方式（ln）

如使用软链（`ln -sf`），编辑工作目录文件时会自动同步回漫游文件：

```yaml title=".cnb.yml"
$: # 兜底匹配所有分支，不被 glob 匹配的分支
  vscode:
    - services:
        - vscode
      stages:
        - name: 关联 .env.local 到工作目录
          script: ln -sf /root/.cnb/.env.local ./.env.local
```

### 自定义漫游目录或文件

除了上述默认漫游内容外，用户还可以自定义需要漫游的目录或文件。

在 [个人设置 > 云原生开发](https://cnbprod.alpha.qq.com/profile/workspaces) 页面中，可配置自定义漫游目录或文件路径。
配置后，云原生开发环境销毁时会自动漫游保存这些目录或文件，新建或重建环境时将自动恢复。

**配置说明：**

* 需填写绝对路径，支持 Glob 格式
* 多个路径可换行分隔

**示例：**

```text
/root/.bashrc
/root/.config/
```

### 漫游原理和时机

**漫游时机**：修改可漫游文件后不会立即漫游，而是等到环境销毁时提取保存。

**恢复方式**：重建环境时自动恢复漫游文件。

**验证方法**：需在环境销毁后重新创建环境才能看到漫游效果。

:::tip
注意：

* 同时打开多个开发环境时，后销毁的漫游内容会覆盖先销毁的
* 通过 `kill 1` 关闭开发环境无法漫游成功
* 如果漫游的文件是软链，将漫游原始文件而非软链本身，避免原始文件丢失
* 若软链的原始文件不存在，则不进行漫游

:::