我们遇到的就是这类问题。用户可以在 Sandbox 里安装软件，而实例回收、重新创建以后，安装过的东西没有跟着回来。

上一篇文章讨论了如何把源码留在 NAS，把依赖安装和构建放到本地盘。这次要继续看工作区之外的内容：软件到底装在哪里，怎样让这些安装结果跨实例保存，以及三种持久化方案各自需要解决什么问题。

1. 文件还在，软件为什么没了

1.1. 先分清“重启”做了什么

先用一个简化场景说明。假设基础镜像没有 Graphviz，用户在 Debian 系的 Sandbox 中执行 apt-get install graphviz，随后用它的 dot 命令把项目里的关系图导出为图片。

这时有两份新内容：工作区里生成的图片，以及系统里新增的 Graphviz。两者虽然都能从同一个终端访问，实际可能写在完全不同的存储上。

容器启动时，根据基础镜像准备文件系统。镜像提供初始的系统文件，运行中新增和修改的内容进入这个实例的可写层。与此同时，平台把 NAS 上的项目目录挂进容器，作为工作区。这里把工作区简写为 /workspace。

如果只重启 Agent 进程，文件系统没有换掉，已经安装的文件通常还在。如果停止容器后继续启动原容器，能否保留文件，要看平台是否保留它的可写层。

我们遇到的另一条路径是：旧实例被销毁，再从基础镜像创建新实例。 新实例重新挂载原来的 NAS，所以代码和图片还在；它的系统文件重新来自基础镜像，后来安装的 Graphviz 就没有了。Docker 文档也明确区分了容器可写层和独立 Volume：删除容器会删除可写层，Volume 则有独立的生命周期。Docker Volume

因此，排查时需要看实际发生的是进程重启、原实例恢复，还是销毁后重建。业务层沿用同一个 Sandbox ID，也不能证明底下仍然是同一份文件系统。

1.2. 一次安装会修改哪些地方

apt、apk 是系统包管理器，分别常见于 Debian 系和 Alpine 系发行版。它们安装软件时，不会把所有内容都放进当前工程目录。

下面列的是系统安装可能涉及的位置，不是 Graphviz 某个版本的完整文件清单。

例如，只复制一个可执行文件，可能因为缺共享库而无法运行；只保存包管理器的数据库，则可能出现“记录显示已经安装，文件却不存在”的情况。Debian 的安装流程还会执行包中的维护脚本，处理配置等工作，安装结果不只是一组解压出来的文件。Debian 包安装过程

这里需要保存的是一套相互匹配的文件与元数据。后面提到的根文件系统（RootFS），指的就是 Sandbox 从 / 开始看到的系统文件体系。独立挂载进去的 NAS、临时内存文件系统等，需要按各自的存储规则处理，不能默认算进一份 RootFS 备份里。

我们当时讨论的三条路，也就对应三个不同的保存范围：保留指定目录、保留原来的运行磁盘、把某一时刻的系统环境保存成快照。

2. 方案一：把需要的目录挂到持久卷

2.1. 新实例重新挂载原目录

这是最容易从现有工作区方案继续扩展的一条路。

平台为项目准备一份独立存储，在每个新实例中挂到固定路径。写入这个目录的内容留在存储里，实例删除后，下一个实例再挂载同一份数据。NAS 可以承载这种目录；自建容器平台也可以通过 Volume 或 Kubernetes PVC 声明需要的存储。

但 Volume、PVC 说明的是挂载与管理方式，具体数据存在哪里，仍要看后端。Docker 的本地 Volume 默认在宿主机上；需要换节点恢复时，还必须有相应的共享存储、磁盘迁移或数据恢复能力。Docker Volume 的存储与共享

平台至少需要记录项目对应的卷标识或远端目录、挂载路径、访问身份。创建新实例时，先完成挂载，再启动依赖这些目录的工具。挂错项目目录、改变安装路径，或者恢复后使用不同的用户权限，都可能让文件还在，却无法正常使用。

2.2. 适合能控制安装位置的工具

例如，一个工具允许把自身及依赖安装到 /home/user/tools，我们可以把这个目录持久保存，启动时再配置好 PATH。对于能明确管理目录的用户级工具，这样做简单，也不需要备份整个系统。

语言依赖需要再看一层。保存 Python 虚拟环境的目录，并不保证换一个基础镜像后仍能运行：它可能依赖原来的解释器路径、系统库或本地编译扩展。恢复时应保持兼容的基础环境，或者根据依赖声明重新安装。

上一篇文章中的 node_modules 就采用了后者：保存源码、包声明和锁文件，在新的本地盘上重新准备依赖。这里主动保留的是重建输入，本地依赖目录可以丢弃。这有助于兼顾持久性和小文件访问性能。

2.3. 系统包为什么不能照搬

对于任意 apt install 或 apk add，平台无法事先假定所有修改都落在一个用户目录。多挂一个 /home，仍然覆盖不到 /usr、/etc 和系统包数据库。

把这些系统目录逐个挂出去，还会引出新的问题。挂载到已有目录上的外部文件系统，会遮住那个位置原有的内容；它不会自动把旧系统与新镜像正确合并。基础镜像升级后，外部目录里的旧库、旧配置和新系统之间，也需要处理兼容关系。Docker 挂载覆盖行为

我们的 FC 环境还有平台限制：NAS 挂载文档要求使用适合的数据目录，不能把通用系统目录及其子目录作为挂载点，例如 /bin、/opt、/var、/dev。FC 配置 NAS

所以，这个方案适合保存边界明确的目录。要支持用户自由安装系统软件，就需要把保存范围扩大到整套系统环境。

3. 方案二：停止计算，保留运行磁盘

3.1. 把磁盘的生命周期单独管理

第二种方案直接保留已经安装好的那份文件系统。

对于虚拟机，可以是保留系统盘；对于容器，可以由运行平台保留根文件系统的可写部分，并继续使用匹配的基础镜像。用户安装软件后，文件和包管理器记录都在这份环境里。停止计算时保留它，恢复时继续使用它。

这样，前面的 Graphviz 无须重新安装。恢复时取得原来的磁盘，软件文件、配置和包记录就一起回来了。进程则通常要重新启动，磁盘持久化本身不包含进程内存。

Daytona 的普通 Container Sandbox 提供了这类使用语义：stop/start 保留文件与安装包，停止时清除内存；删除 Sandbox 则是另一种操作。具体选型仍需核对 Sandbox 类型和自动删除配置，不能只看一个“支持持久化”的介绍。Daytona 持久化说明

3.2. 平台需要记录什么

业务层不能只保存“项目正在使用哪个实例”。还需要保存项目的环境磁盘标识、匹配的基础镜像版本，以及当前由哪个实例使用。

正常停止时，平台应让安装和写入结束，再按存储系统的要求完成落盘，最后停止计算、保留磁盘。恢复时找到这份磁盘，确认旧实例已经停止写入，再交给新的运行实例。删除项目时，才根据保留策略删除它。

这里有一个容易忽略的情况：旧实例网络断开，平台认为它失联，于是又启动了一个新实例。旧实例其实还活着，两个实例就可能同时修改包数据库。管理服务中的一把锁还不够，平台需要通过磁盘挂载约束或存储侧的写入控制，阻止已经失去所有权的旧实例继续写。

3.3. 磁盘保留在哪，决定了能恢复到哪里

如果只是让容器停在原机器上，并保留那台机器的本地可写层，原地启动确实方便。但宿主机永久故障以后，能否恢复就取决于有没有其他持久副本。

要允许换节点恢复，需要磁盘本身能脱离原计算节点，例如使用可重新挂载的持久块存储，并满足可用区、文件系统和运行时的约束。异常断电后还可能面对文件系统恢复、包安装中断等状态，保存磁盘不会自动把安装过程变成一个事务。

这条路的主要成本是长期保留每个项目的环境空间，以及磁盘挂载、迁移和故障处理。计算停止后，存储仍然占用资源。它适合经常回来继续工作的开发环境；若有大量长期不活跃的项目，还需要归档和回收机制。

4. 方案三：把环境保存成文件系统快照

4.1. 新实例从保存的环境启动

第三种方案允许原实例彻底退出。退出之前，先把某个时刻的根文件系统保存为一个可恢复版本；下次根据这个版本创建新实例。

快照可以是完整磁盘副本，也可以只记录相对基础镜像的变化。后者能够复用公共镜像，项目只保存自己新增、修改和删除的内容。这里讨论的是文件系统快照；要继续执行原来的进程，还涉及另外的内存与设备状态恢复。

例如，Modal 的文件系统快照记录 RootFS 相对基础镜像的差异，生成的 Image 可以创建新 Sandbox。它的文档也明确说明，挂载的 Volume 不包含在这份快照里；快照还需要配置保留期限。Modal 文件系统快照

恢复 Graphviz 时，平台不再重新执行安装命令，而是从快照取得已经安装好的文件与状态。快照生成以后，即使原实例被删除，只要快照及其依赖仍在，便可以据此准备另一个实例。

保存差异时，删除操作也必须被记录。假设用户删除了基础镜像中的一个配置文件，只备份“当前新增的文件”，恢复后那个旧配置又会出现。以 OverlayFS 为例，它会用 whiteout 等元数据表达对下层文件的删除；这类信息不能在复制过程中丢失。Linux OverlayFS

4.2. 在什么时刻保存

最直接的做法是正常关闭前保存一次。但节点故障、强制回收等情况，不保证有机会执行关闭脚本。要减少丢失，就要在环境修改后建立保存点。

用户安装 Graphviz 后，当前实例里已经有新软件，但持久存储中还是上一次保存的环境。只有新快照生成、上传并确认可恢复之后，才能把它设为项目下次启动时使用的环境。

一种可采用的保存流程是：

1. 暂停同一环境上的其他修改，确认安装进程及其后续配置已经完成。
2. 按快照实现的要求，完成写入刷新，并取得一致的文件系统视图。
3. 生成新快照，保存其数据与元信息，检查它已经能够被恢复。
4. 把新版本标记为可用，再原子地切换项目的当前版本。

单独调用一次 sync 不会阻止其他进程继续写，也不保证跨多个存储的一致性。如果软件还在修改文件，需要先让相关写入停下来，或使用平台提供的协调机制。快照内部完成的原子性范围，也应由具体实现说明。

如果第三步失败，下次启动仍使用上一次保存成功的环境。这样不会把半份快照交给下一次启动，但尚未保存的新安装也不能保证回来。因此，产品需要区分“本次安装可用了”和“环境已保存，可以重建恢复”。如果承诺每次安装成功后都能恢复，就必须把保存完成纳入这次操作的成功条件；允许任意终端命令时，则还需要明确的环境保存点或受控修改入口。

4.3. 快照记录不能只有一个文件地址

管理服务需要在实例之外保存项目与环境版本的关系。可以在数据库中记录当前使用哪一版环境，每个版本关联以下信息。

并发保存时，还需要检查当前版本和写入所有权。保存任务开始时记下项目使用的环境版本，更新时确认它没有被其他任务替换，且自己仍持有有效写入权，再切换到新快照。检查与切换需要原子完成，避免超时后继续执行的旧任务覆盖已经发布的新环境。

NAS 工作区不随 RootFS 快照一起回退。如果还希望把代码与环境一起回到过去，就要额外保存代码提交或工作区版本，并协调两者的对应关系。只记录工作区标识，找到的仍然是同一个目录，并不代表这个目录在历史时刻的内容。

5. 三种方案放在一起看

三种方案都能保存文件，区别在于保存范围和恢复方式。

手机上可左右滑动查看完整对比。

表里的“可以覆盖”有前提：保存的文件范围完整，元数据正确，并使用兼容的恢复环境。外部服务状态、进程内存、单独挂载的数据卷，不会因为保留 RootFS 就全部跟着保存。

性能也需要按用户真正等待的路径来测。目录方案要看挂载后访问文件的成本；保留磁盘要看重新挂载与启动的时间；快照方案则要看生成、传输、恢复，以及恢复后第一次真正使用软件的时间。延迟加载可以把一部分恢复工作推迟到首次读文件，单看“实例启动完成”容易漏掉这部分等待。

这次回顾没有三种方案在同一负载下的耗时和费用实测，因此不能给出谁快多少的排名。更适合先按需求缩小范围：固定工具链与可控目录优先考虑持久卷；需要频繁继续使用同一套环境，可以评估保留磁盘；需要释放原实例、回滚或从同一环境分出多个副本，快照提供的版本能力更直接。

三者也可以组合。例如，活跃项目保留磁盘，长期不活跃时归档为快照；源码继续放 NAS，构建缓存留在可丢弃的本地盘。

6. 放回我们的 FC 架构，怎样接入

6.1. 现有实现保存到了哪一层

现有实现把 NAS 挂到项目工作区；恢复时，根据保存的记录选择镜像和运行配置，再创建实例。部分配置变化还会触发旧实例删除与重新创建。

这条创建、恢复链路没有携带每项目的 RootFS 快照或持久系统盘标识。基础镜像预装的工具会随镜像重新出现，用户在旧实例中临时安装的软件则没有相应的恢复步骤。FC 文档也说明，自定义容器的可写层随容器销毁而删除。FC 自定义容器

目前能从代码中确认的，是公共工具预装、NAS 工作区，以及本地项目依赖的重新准备。项目级环境磁盘、RootFS 快照和下面的派生镜像流程，仍属于这里讨论的设计，不能据此声称已经上线。

6.2. 继续使用 FC，可以先约束可保存的安装

如果暂时继续使用当前的 FC 运行方式，又无法取得和恢复容器的完整可写层，可以把可持久化的安装收敛为声明式配置：记录项目需要哪些系统包、版本和来源，再构建一份项目专用镜像。

例如，用户通过受控入口增加 Graphviz，平台记录基础镜像 digest、发行版与软件源、包名和版本。构建任务在隔离环境中生成派生镜像，验证后推送到镜像仓库，再把项目的环境镜像指针切换过去。下次重建时，创建逻辑使用这个 digest。

软件源也要纳入设计。只记一个包版本，如果上游已经不再提供对应包，仍可能构建失败。长期重建需要可保留的包来源、仓库快照或构建产物。已经构建成功的镜像可以复用，不必在每次启动时重新下载和安装。

这种方式保存的是明确声明并成功构建的环境。用户随手修改 /etc，或者运行一个会改动多个位置的安装脚本，不能仅靠记录命令就完整恢复。允许的包管理入口、额外配置文件和安装脚本范围，需要作为产品能力明确下来。

它是现有平台约束下的一条接入路径，与前面的 RootFS 快照有不同的保存语义。构建失败时也不能先更新项目镜像；应该保留上一版可用环境，并说明这次修改尚未持久保存。

6.3. 完整环境持久化需要运行平台配合

如果产品要让用户自由安装系统软件，并在实例重建后继续使用，就应选择能保存完整环境的运行平台，或者自行提供磁盘与快照能力。这已经涉及 Sandbox 创建和回收的接口，工作区里的脚本无法单独完成。

创建接口需要接受环境版本，保存接口需要返回可恢复的磁盘或快照标识，删除接口则要区分“释放这次计算”和“删除项目环境”。恢复完成后，确认软件真正可用，再让 Agent 继续执行任务。

对应的回收也要分开：本地缓存可以随实例删除；项目当前环境不能被普通实例清理顺手删掉；旧快照只有在不再被项目、恢复任务和派生版本引用时，才能回收。还要设置容量配额，并在写入时返回明确错误，避免用户安装了很大的软件以后，环境迟迟无法保存。

环境快照也不宜包含运行时注入的临时凭证。凭证应放在独立的临时挂载或注入机制中，恢复时重新取得，而不是把一个可能过期的访问令牌随环境版本长期保存。

7. 怎样确认软件确实保住了

验收不能只看“Sandbox 又启动了”。对于开头的例子，应在新实例中执行 dot，实际生成一张图，同时检查包管理器记录、安装配置和工作区文件。

下面是选型时应执行的验证场景，并非本次已经完成的测试结果。

性能测试则应固定基础镜像、软件集合和修改量，分别记录保存耗时、保存大小、冷恢复时间，以及第一个真实命令的完成时间。只有这些数据齐全，才能把方案能力、用户等待和存储费用放在同一张表里比较。

8. 环境留下来了，基础镜像怎样升级

持久化解决了安装结果丢失，也带来了下一个问题：公共基础镜像升级以后，用户保存的旧环境要怎样跟上。

一个项目可能在原基础镜像上安装了很多包。直接换成新版基础镜像，再覆盖旧环境的差异，可能混入两版系统库，甚至把已经修复的旧文件重新盖回去。因此，环境版本需要绑定基础镜像，升级应当是一次可验证的迁移。

声明式环境可以尝试在新镜像上重新构建；保存了任意文件修改的环境，则需要更谨慎地迁移和验证。可以先创建一份新环境，运行项目的真实任务，成功后再切换，并保留旧版本作为回退点。

到了这一步，平台管理的已经不只是一个会启动和销毁的 Sandbox，还包括用户逐渐积累起来的开发环境。它需要明确的保存点、版本和升级过程。这也是持久化方案选定以后，下一步要继续解决的事情。

文中实现状态截至 2026 年 10 月 13 日；项目级环境持久化流程为方案设计。

2026 年 4 月 6 日，测试环境两次新项目准备的平均耗时是 6.66 秒，负责推送的 push_remote 步骤平均用了 2.90 秒，占约 43.6%。沿着这次推送继续看，Gitea 服务端的仓库目录挂在 NAS 上，文件存储由此进入了排查范围。

后面我们又测了不同文件系统上的依赖安装和构建，遇到了“包已经缓存，安装仍然很慢”的问题。这篇文章从 Git push 开始，沿着这些测量与实现，讲到 NAS 选型，以及本地盘上的依赖和编译。

1. 先从一次 Git push 看起

1.1. 新项目为什么先要推送代码

当时的新项目初始化流程，会先把模板解压到 Sandbox，创建本地 Git 仓库并提交初始代码，再推送到 Gitea。Gitea 是保存项目 Git 仓库的服务，后续可以从这里取得已经提交的版本。只有这套准备流程完成，项目才能继续使用。

我们在预热流程，也就是 warmup 中记录了各步骤耗时。下面两条是 2026 年 4 月 6 日测试环境的成功样本，均为新项目的模板初始化路径，时间单位为秒。

占比按未四舍五入的原始时间计算，平均行使用两次推送耗时之和除以两次总耗时之和。这是两个现场样本，不代表长期平均延迟。

init_git 包含建仓、配置提交身份、git add 和 git commit，这两次只花了约 50 毫秒和 47 毫秒。随后的 push_remote 则用了约 2.9 秒，等待主要集中在后一步。

这两个步骤都从沙箱代理服务发起远程执行开始计时，直到脚本返回。push_remote 执行初始代码推送，包含远程执行开销、Git 客户端处理、网络和服务端等待；前一步的本地提交不算在里面。因此，不能把它直接当作纯网络上传时间，也不能拿新项目首次提交的结果代表任意大小仓库的提交与推送。

1.2. 推送在等待什么

Git push 会向远端发送它尚未拥有的对象，并请求更新分支引用。服务端需要接收相关对象，检查这次更新是否允许，再让目标分支指向新的提交。Git push、服务端 receive-pack

因此，客户端在等待推送结果时，等待的内容还包括服务端对仓库的处理。如果仓库保存在网络文件系统上，这条路径就涉及服务端的文件操作。

当时检查 Gitea 部署配置，确认 /data 挂载了 NAS，其中保存 Gitea 的仓库数据。这条线索把存储纳入了排查，但还不能把那 2.90 秒全部归因于 NAS：我们没有在这两个样本中继续测出网络、客户端和服务端 I/O 各占多少。

接下来需要区分两个存储位置：Gitea 保存已经提交的 Git 版本，Sandbox 工作区保存当前正在修改的工程文件。 它们都可以使用 NAS，但访问发生在不同位置，优化其中一处，不会自动改变另一处。

1.3. 工程工作区也需要持久保存

Agent 在 Sandbox 中修改代码、安装依赖，再执行构建。Sandbox 是承载这些操作的隔离执行环境，里面有项目目录、Node.js 和构建工具。用户下一次回来继续修改时，执行任务的容器可能已经换了一个。

源码需要跨实例保存。例如，Agent 给游戏增加了暂停菜单，修改了 src/menu.ts，还增加了一个依赖。容器回收以后，这次修改和对应的依赖版本都需要保留下来。

后来的 NAS 工作区方案，把网络文件存储通过 NFS 协议挂载到 Sandbox 中。挂载以后，程序仍然通过普通目录访问它。新容器挂载同一个项目目录，就可以继续处理原来的工程，包括尚未提交到 Git 的修改。

这个布局很直接：源码、package.json、锁文件、node_modules 和 dist 都在同一个工程目录里，现有工具基本不用调整。持久化的问题解决了，安装和构建也随之使用了网络文件系统。

读取一个依赖文件，可能先要查找目录项、确认权限、读取文件属性，然后才是内容。客户端会缓存一部分信息；缓存未命中或需要向服务端确认时，这些操作就要经过网络。对于包含大量小文件的 node_modules，文件总量不大，也可能有很多次访问。

1.4. 第一个方案：换一种文件系统

既然安装和构建都在 NAS 上，首先可以尝试改善这条存储路径。这样不需要调整工程目录，也不用让包管理器适应新的布局。

阿里云的 NAS 有多种规格。按目前的产品划分，通用型包含容量型、高级型和性能型，极速型又分标准型与高级型。各类产品提供的容量、时延、吞吐和 IOPS 规格不同，选型需要结合项目的实际操作。通用型 NAS、极速型 NAS

CPFS 也进入过我们的测试范围。不过，文件系统的性能只是选型的一部分，还要看 Sandbox 能否接入。当时 Sandbox 使用函数计算 FC，可以配置 NAS 挂载；CPFS 实验则需要先创建协议服务与导出目录，再在 ECS 上安装 CPFS-NFS 客户端并挂载导出的路径。接通 ECS，并不等于可以直接把 FC 的 NAS 地址换成 CPFS。FC 存储选型、CPFS-NFS 挂载说明

接下来需要回答的，就是换存储到底能改善多少。连续读写大文件的吞吐，不能直接换算成安装几万个依赖文件需要的时间，因此我们拿已有的前端模板执行安装和构建。

2. 换了文件系统，构建快了多少

2026 年 6 月 12 日，我们用四种前端模板做了两轮测试，表中分别记为 2D、3D、Empty3D（空的 3D 工程）、Canvas。以下时间均为秒。

这一轮测的是工程目录中的 npm install 和 npm run build，与前面的初始 Git 推送是不同负载。现有记录没有 Git push 在各文件系统上的同口径对照，下面的数据只用于比较安装和构建。命令也保留当时的 npm 口径，不改写成后来的 pnpm 生产流程。

2.1. 第一轮：容量型反而安装得更快

NAS 测试使用新加坡区域的 ecs.c9i.xlarge，4 核 8 GiB，Node.js 22.16.0、npm 10.9.2。每个项目先安装依赖，再连续构建三次。CPFS 随后补跑，也使用 Node.js 22.16.0、npm 10.9.2。

下面是第一轮记录。这轮 NAS 测试共用了 ECS 本地的 npm 缓存，性能型先跑，容量型后跑，安装条件并不完全一致。

2D 的结果最明显：容量型安装用了 16.911 秒，性能型用了 29.924 秒。检查测试过程后，发现 npm 缓存保存在 ECS 的 /root/.npm，后测的一组能够复用前面下载过的内容。

因此，这两行数字不能直接证明容量型更快。缓存是已经确认的干扰因素，但没有单独控制它做实验，也无法判断这约 13 秒的差异有多少由缓存造成。CPFS 的补跑同样没有满足后来要求的完整隔离条件。

构建数据也需要分开看。两个 NAS 的中位数比较接近，例如 3D 是 1.993 秒和 1.928 秒，Canvas 是 0.982 秒和 0.972 秒。每组只有三次连续执行，还不足以作稳定的性能排名；首次 build 紧接着安装，也不等于清空文件缓存后的冷读测试。

这轮先暴露出来的是测法的问题。要继续比较文件系统，得让每一组从独立环境开始。

2.2. 第二轮：隔离环境后再测

第二轮改成“文件系统类型 × 项目”各用一台新 ECS、一套新文件系统，避免共用 npm 缓存。规格也调整为更接近当时 Sandbox 的 2 核 4 GiB：ecs.c9i.large、Ubuntu 20.04、Node.js 22.22.3、npm 10.9.8，NAS 使用 NFSv3 挂载。

CPU 和软件版本与第一轮不同，所以这一轮内部比较，不能拿两轮数字计算升级收益。

有些组合没有跑完：Empty3D 在两种 NAS 上都遇到 npm install 的 ERESOLVE 依赖解析错误，项目本身声明使用 pnpm，直接以 npm 安装并不完全符合原来的依赖约束；CPFS 独立组合则停在资源与挂载准备阶段。它们没有有效构建时间，也不能用第一轮的 CPFS 数字补上。

极速型 NAS 没有参加这两轮测试。全部阶段记录，包括三次 build 和失败退出码，保留在测试数据 CSV 中。

2.3. 安装仍然占了大头

这六组成功结果，没有显示出换成性能型 NAS 后各个项目都明显变快。更值得继续追的是时间分布：2D 在容量型上的安装占“安装＋首次构建”的约 85%，3D 对应约 88%。

即使只看 2D，把 5.66 秒的编译继续压缩，前面的 31.93 秒安装仍然存在。要缩短用户等待的时间，需要继续拆解依赖准备。

安装依赖会下载包，因此一个直接的方案是预热包缓存，尽量离线安装。我们后来的镜像已经这样做了，但工作区中的 node_modules 仍在 NAS 上。接下来的问题变成了：包内容已经在本地，安装还需要做哪些文件操作？

3. 包已经缓存了，安装还在做什么

3.1. 缓存与依赖树是两个位置

安装大致包含读取包与锁文件、获取包内容、建立项目依赖树，以及执行安装脚本几个过程。缓存能够复用包内容，项目自己的依赖目录仍然需要准备。

以 pnpm 为例，需要区分三个位置：

• 内容存储 store：保存可以复用的包文件；
• 项目的 node_modules/.pnpm：项目使用的依赖文件和目录布局；
• node_modules 中的链接与入口：让程序按照依赖关系找到模块。

pnpm 使用内容存储和链接组织依赖。建立和读取项目依赖树时，仍然要操作项目目录；store 与项目分属不同文件系统时，也不能假定跨文件系统硬链接总能成立。pnpm 依赖目录结构

8 月检查构建链路时，镜像里的预热 store 已经在本地盘，安装器也支持优先离线安装。但 node_modules 和 .pnpm 还在 NAS。包可以不重新下载，目录创建、文件复制、链接与属性检查仍可能经过网络文件系统。

构建阶段也会反复查找模块、读取 package.json、解析源码，再生成临时文件和 dist。依赖留在 NAS 上时，读取依赖的成本会继续影响构建，只调整输出目录还不够。

3.2. 连查看目录也变慢了

2026 年 8 月 8 日的一次排查，进一步把范围指向了文件访问。工作区确认是 NFSv3 挂载，现场记录中，find 用了约 117 秒，git status 约 166 秒，部分目录扫描超过 60 秒。

这些命令不负责把源码编译成产物。它们也变慢，说明需要检查安装和编译之外共同使用的文件系统路径。

约 42 分钟的现场累计统计中，有下面这些 NFS 请求：

这些是多个操作累计的计数，不是一次安装的调用次数。不过，它们解释了为什么不能只看传输带宽：查目录、检查权限、创建文件，每一步都可能有等待。依赖文件多了，即使单个文件很小，这些步骤也要反复执行。

现场同时存在外部包下载慢的问题，手工执行的 pnpm 命令还曾把 store 建在 NAS 上。下载、缓存和项目目录需要分别检查，已有证据不足以把所有等待都算在 NAS 上。但对于已经确认留在 NAS 的依赖树，可以提出一个更具体的改法：把它移到本地。

4. 先把 node_modules 搬到本地

4.1. 哪些文件可以不持久保存

源码、素材和依赖约束需要保留；node_modules 则可以根据 package.json、锁文件和工具版本重新生成。它被频繁读写，却不一定需要和源码使用同一种存储。

因此，可以让 NAS 继续保存工程，把 node_modules 放到 Sandbox 本地盘。工作区里的 node_modules 变成软链接，工具访问这个路径时，实际读取本地目录。

本地盘的选择还取决于部署环境：有独立 SSD 时，可以把依赖目录放在 SSD 对应的挂载点；只有容器本地临时盘时，也可以验证同样的分工。两者的容量、性能和生命周期需要按实际环境确认，目录叫 /tmp 并不能说明底层一定是 SSD。

4.2. 实验结果：安装改善大，构建改善小

我们在 8 月评审过《低权限环境下 node_modules 本地快盘托管方案》，附录保留了一组 2026 年 6 月的实验。它先在本地目录安装依赖，再通过软链接让工作区使用这份 node_modules。

原实验中，/workspace 和 /scratch 是同一个 NFSv3 文件系统，/tmp 是约 9.9 GiB 的容器本地 overlay，没有独立本地 SSD。下面比较的是 NFS 路径与容器本地路径。

在 431 个依赖的记录里，安装从 166 秒降到 31 秒；Vite build 从 6.05 秒降到 4.29 秒。移动依赖目录影响了两部分，安装阶段的变化更大。构建还包含解析、转换、压缩等 CPU 工作，不能用安装的耗时比代表整个发布流程的收益。

这份附录没有保留完整的 CPU 规格、缓存控制和重复轮数，属于方案验证资料，也不是前面几个模板的同口径复测。它提供了继续实现本地依赖目录的依据，生产项目的具体收益还需要重新测量。原记录见方案文档的实机验证附录，revision 7。

4.3. 软链接又被安装器删掉了

有了这组结果，接下来的工作是把目录布局接入现有工具。最先遇到的限制，就在依赖安装本身。

假设目录是这样的：

/workspace/game/node_modules
    → /local/game/project/node_modules

软链接保存目标路径，但包管理器不一定保留它。补充实验中的 npm 11 在安装的 reify 阶段发现 node_modules 是软链接，会移除它，再在原位置创建目录。于是，看起来已经搬到本地的依赖，又写回了 NFS。npm ci 也明确包含先清理既有 node_modules 的行为。npm ci 的行为说明

要保留本地布局，安装命令应当直接在本地工程目录执行，成功以后再由平台建立工作区链接。处理已有依赖目录前，还需要确认它属于可重建数据，并停止正在使用它的进程。

构建工具有另一类限制：部分框架检查工程根目录与依赖的实际路径，外置依赖可能触发“超出文件系统根目录”的错误。只挪 node_modules，源码和依赖仍分处两个工程根，这套结构并不一定适合所有工具。

因此，下一步把源码副本也放进本地，让源码、依赖和构建命令位于同一个工程根。NAS 继续保留原工程，本地副本负责执行这一轮构建。

5. 在本地准备一个完整工程

5.1. 两份目录如何分工

本地工程副本需要源码，但不负责替代 NAS 保存用户修改。每次构建前，从 NAS 同步本轮输入；依赖安装、临时文件和编译都在本地完成；构建成功后，再把产物交回持久层。

同步时排除 NAS 上的旧 node_modules、旧 dist 和无关运行目录，避免把大量可重建文件复制回来。源码中的删除也要同步，否则已经从 NAS 删除的旧文件，可能继续留在本地参与编译。

如果一个 Sandbox 承载多个项目，本地目录还要按项目隔离，防止它们修改同一份依赖。整个本地副本的生命周期跟随当前实例，实例回收后可以重建。

5.2. 一个 npm 项目怎样执行

下面用 npm 展示最基本的过程。假设项目已有有效的 package-lock.json，构建期间没有并发修改，输出目录是 dist。本地目录每次新建，暂不考虑缓存复用。

workspace=/workspace/game
local_root=$(mktemp -d /tmp/game-build.XXXXXX)
local_project="$local_root/project"
mkdir -p "$local_project"

# 同步构建输入，跳过可以重新生成的内容。
rsync -a \
  --exclude='/.git' \
  --exclude='/node_modules' \
  --exclude='/dist' \
  --exclude='/.combos' \
  "$workspace/" "$local_project/"

# 安装和构建都从本地工程根开始。
(
  set -e
  cd "$local_project"
  npm ci --cache "$local_root/npm-cache"
  npm run build
)

产物出现在 $local_project/dist。平台检查命令退出状态与产物后，再把它交回持久层。这个示例说明目录关系，没有包含并发锁、缓存复用和发布过程。

已有项目使用 pnpm 时，应保留原来的锁文件与版本。采用本地目录，并不需要改用 npm 重新解析依赖。我们实际的主路径使用 sandbox-pnpm-install，先尝试离线安装，缺包时按策略联网补齐。

monorepo、本地 file: 依赖，以及会访问相邻目录的安装脚本，还要求同步完整的依赖范围。复制工程时需要保持这些相对关系，不能只带走一份 package.json。

5.3. 接入原来的构建入口

实现时，我们把本地 I/O 接入了依赖安装和构建两个统一入口，分别由 sandbox-pnpm-install 和 sandbox-build 负责，已有的持久工作区与后续发布流程继续使用。

依赖准备先检查本地目录是否可用、空间是否足够，再同步输入和安装。成功后，将工作区的 node_modules 链接到本地依赖目录。构建入口核对依赖状态，刷新源码，然后从本地工程根执行原来的 build.sh。

部分旧项目的 build.sh 会再次执行 npm ci 或 pnpm install。统一入口已经准备过依赖，如果脚本再来一遍，就会重复安装。因此，当时为这次构建进程加入命令包装，跳过约定中的重复安装命令；run build 等其他调用继续交给原来的包管理器。这项兼容处理限定在已有构建协议内。

编译成功后，先把本地 dist 复制到 NAS 的暂存目录。复制完成，再将它重命名为本次产物目录，后续上传、Git 提交和版本记录继续走原流程。

这里要分别处理编译失败和回写失败。编译失败，本轮没有可上传的结果；回写失败，即使本地编译已经完成，也还没有把产物交给发布流程。构建入口会清除旧输出，防止上传器在本轮失败后误用上一次的 dist。

暂存目录让消费者不会读到复制了一半的产物，但“编译、上传、版本发布”仍然是多个步骤，并没有组成一个文件系统事务。最终预览还要等后续发布完成。

5.4. 哪些修改需要写回

本地副本带来了一个新的边界：在本地改了文件，不代表用户的持久工程已经变化。

普通构建根据现有锁文件准备依赖。用户要求增加或删除依赖时，package.json 与锁文件的改动需要保存到 NAS，成为下次恢复的输入；只更新本地 node_modules，换一个实例就会丢失这次变化。

因此，修改依赖要作为单独的操作处理，检查并写回对应文件；写回前还应确认原文件没有被其他操作更新。构建脚本如果会生成需要长期保存的源码，也要约定这些文件的写回范围，不能将整个本地副本直接覆盖回 NAS。

到这里，安装和编译已经有了统一的本地执行路径，NAS 上保留的是持久输入与完成后的产物。但还有一个条件需要处理：本地目录只属于当前实例。用户下一次继续工作时，NAS 上的成功记录可能还在，本地文件却已经不在了。

6. 实例换了，依赖怎样恢复

6.1. 成功记录与真实目录

假设原实例已经完成依赖安装，NAS 保存了成功标记。原实例被回收后，新实例挂载同一份 NAS，可以看到旧记录，但没有原实例的本地依赖。

软链接也可能保存在 NAS 上。容器更换后，链接文件仍在，它指向的本地目录却不存在。只检查链接或“安装成功”状态，都会漏掉这个情况。

实际实现判断依赖是否就绪时，会一起核对记录是否属于当前实例、package.json 与锁文件的摘要、本地依赖目录、pnpm 布局标记，以及软链接是否指向当前目录。条件不满足，就重新建立本地副本、安装依赖、修复链接，再更新当前实例的记录。

Node.js 与包管理器版本也需要固定。如果以后把依赖缓存扩展到跨实例共享，还要考虑操作系统、CPU 架构、Node ABI 等兼容条件，尤其是包含原生扩展的包。当前实例内的一份成功记录，不能直接扩展成跨机器复用的依据。

6.2. 恢复过程还会并发执行

异步预热和用户触发的构建可能同时准备依赖。如果只给安装加锁，两个进程仍可能在前面的同步阶段相互干扰：一个正在准备本地布局，另一个同时删除或替换其中的文件。

为此，锁需要覆盖共享目录的准备过程，让源码同步、依赖安装和状态更新按照约定执行。

本地环境不可用时，还需要回到原来的 NAS 工作区。回退不能只切换工作目录：如果 node_modules 仍是指向已消失本地目录的链接，继续安装可能出现 ENOTDIR。因此，回退时还要处理失效链接，让依赖重新安装到可用的工作区目录中。

长时间保留实例时，还要限制缓存占用。检查容量也需要关注可用 inode：剩余字节足够，并不保证还能创建大量文件。

7. 下一步：重新测量完整构建

回看已有数据，可以确认两件事：当时测过的容量型与性能型 NAS 没有给所有模板带来一致的明显改善；补充实验把依赖放到本地后，安装耗时变化远大于构建耗时变化。沿着这个方向，我们把本地执行接入了统一安装、构建与恢复流程。

不过，现有测量还缺少最终生产链路在同一条件下的完整前后对照。前面 166 秒降到 31 秒的数字，不能直接作为这套完整方案的上线收益。

本地副本减少了安装与编译中的网络文件操作，也增加了源码同步和产物回写。因此，下一轮计时需要覆盖：等待执行、同步输入、依赖准备、实际编译、产物回写，以及后续上传和验证。否则，单看本地 build 变快，仍然无法判断用户少等了多久。

测试场景也要分开：新实例首次构建、同一实例重复构建、只修改源码、修改依赖，以及实例丢失后的恢复。每组固定代码、锁文件、工具版本和计算规格，记录缓存条件，核对最终发布的产物。

这样才能继续回答下一个问题：依赖和编译移到本地以后，整条链路中最长的等待又落在了哪里。