架构决策记录
ADR 0034: 模型文件属于存储,共享存储上的模型文件只记一行
本文目录
日期:2026-10-02 · 状态:已接受
依据:存储抽象与 NFS 计划。修改 ADR 0018 的获取候选:在"本地已存在 / 节点间同步 / 公网下载"之外增加"存储"这一维。
背景
模型文件原来是"节点的东西":model_files 每 (模型, 节点) 一行,Path 是该节点上的目录,模型根目录是节点属性,
"存储"只是一个内建的下载开关。要让多个节点读同一份 NFS 上的模型,只能每个节点各登记一行;N 行指向同一份文件、互不知情,
删一行会删掉大家共用的目录,两个节点往同一目录下载会互相写坏,千节点下状态同步要逐台校验同一批共享目录。
决策
- 存储是一等对象,有类型。
local(各节点上的一个目录)、nfs(agent 挂载的 NFS 导出,所有节点共用一份)、nfs_cache(NFS 导出加每个节点的本地缓存,启动读缓存)、shared_dir(节点上已挂好的共享目录,行为同nfs)。 节点不信任"目录能读":已有挂载的nfs/nfs_cache必须在 mountinfo 里是 nfs 挂载点,shared_dir必须是挂载点或位于网络文件系统上, 否则报failed/not_mounted——掉挂后留下的空目录在根盘上,不能当共享存储写。 类型是"权威文件在哪"与"节点怎么拿到本地路径"两件事的组合;以后加 S3 加本地缓存只需新增一种后端,缓存层只依赖"列文件、读文件"。 本地存储不再内建:新装时自动添加一个普通的默认本地存储,升级时把原内建行迁成它,节点原来的模型根目录变成它的节点覆盖。 - 模型文件按 (模型, 存储, 节点) 唯一。 本地存储每节点一行;共享存储的权威文件是节点为 0 的一行,
path是存储内相对路径;nfs_cache的节点缓存是同一存储下带节点的行。节点能不能读共享模型文件由storage_node_states(节点上报、只在变化时写)推导, 不落每节点一行;节点为 0 的行不随期望状态下发,agent 不校验共享目录。 - 一个位置查询入口。 "模型 M 在节点 N 上从存储 S 读哪个宿主机路径"只由
store.ModelLocation回答, 共享路径只在store.SharedHostPath里拼。启动、评估、模板解析、磁盘准入、评测读 tokenizer 都问它,不再直接读ModelFile.Path。 - 每台节点读它能读到的那份,部署不绑定存储。 建部署时的来源仍是用户显式选择、服务端只校验不替换(ADR 0018):
"本地已存在"推广为"某个存储上已有",节点间同步与公网下载多一个"保存到"。之后每台节点上读哪份由
store.ModelSourceOn一条规则决定,调度准入、controller、预览都只问它: 节点能直接读的就用(节点自己盘上的——本地存储、已缓存的nfs_cache——优先于直接读 NFS); NFS 加本地缓存里有的先填缓存;都没有才获取,保存到部署记下的存储(deployments.weight_storage_id, Go 里叫SaveToStorageID;只记请求里明确选的存储,没选为 0;它适用于这台节点时用它),否则默认存储,否则其他启用的本地存储。共享存储从不被自动写入:选了"保存到"某个共享存储而它里面没有该模型, 就拒绝并给出原因,不退而在各节点各下一份。要"只从某存储读",给部署加节点条件gpuworks.ai/storage(系统标签,值是存储 ID,节点带上所有适用于它的存储;挂载暂时不可用的节点仍是候选、准入时给出原因),平台从不自动加。 每个实例在创建时记下它读的模型文件行与宿主机路径(instance_model_files),"是否在用"(缓存淘汰、删除模型文件、 删除或移动存储、重启检查、存储页的部署数)都按这些记录判断。节点间同步只保存到本地存储;写入共享存储走下载或复制。 - 停用即只读。 停用的存储不再下载、复制进来或删除模型文件(部署触发的下载同样被挡),已有的仍可部署;
nfs_cache的节点缓存与心跳不受影响。镜像落在节点的容器运行时里,不归存储管,存储开关不再影响镜像同步。 - 写入共享存储由一个写入节点执行,先暂存再改名。 暂存在
<根>/.gpuworks/incoming/<控制面 ID>/下, 完成后 rename 到最终路径;目标已被别的写入方占用且是同一个模型就采用它,不同就失败、不覆盖。不用 NFS 文件锁。 - 多套 gpuworks 共用一个存储时写心跳,删除时提醒。 每套控制面在
<根>/.gpuworks/control-planes/<控制面 ID>.json写心跳,新鲜判断用 NFS 服务器的文件修改时间;删除共享模型文件时发现别的控制面在用,要求显式强制。心跳只是提醒,不是锁。 - agent 碰共享存储的调用都有时限。 挂死的 hard NFS 不能拖住状态上报:健康检查、状态快照、RPC 都经有时限的调用,
超时报
unresponsive;创建容器前对模型路径做有时限的stat,不存在就以MODEL_PATH_UNAVAILABLE失败, 避免 docker 把缺失的挂载源建成空目录。
后果
- 迁移 122–125 把内建存储、节点模型根目录、旧模型文件与部署迁进新结构,并删除
nodes.models_root、storages.builtin。 - 存储的目录不依赖 agent:本地存储必须有目录(新装默认
/opt/gpuworks/models),nfs_cache不填缓存目录时取/opt/gpuworks/cache/<名称>;某台节点用不了时给它单独设目录。在握手时报出自己实际模型目录的 agent(Hello.own_models_dir), 节点还没有单独目录时平台把它记成该节点的单独设置,一次性、可见、可改。2026-10-04 修订:上报者从"非 root agent"扩大为 "非 root agent + 状态目录不在/opt/gpuworks的 agent"——自定义--state的 root agent(云上装在数据盘、CI 容器)若不上报, 首帧期望状态会把模型目录静默搬到全局默认路径,正是本 ADR 要避免的"看不见也管不住",而且会落到本应避开的磁盘上; 标准 root 布局两条路径本就相同,上报与否无差别,维持原行为。迁移 126 把留空的存储改成明确目录,并把各节点之前 实际使用的目录记成它们的单独设置。理由:模型目录是用户的数据决策,而 agent 状态目录随安装方式变化 (/opt/gpuworks、自定义安装目录、非 root 时的用户配置目录),由它决定模型落在哪里既看不见也管不住。 - 协议:
DesiredState.storages(存储任务)、status.storage(节点的完整存储状态,变化时发送)、模型文件任务的 key 改为行 ID(f<id>,旧格式仍接受)并带存储、缓存、复制源与暂存目录;新增storage.probe/scan/peers/remove四个 RPC。 - 缓存淘汰是纯函数(
internal/server/modelcache),调度准入与 controller 淘汰共用,按最近使用从旧到新、只淘汰未被引用、 不在传输中、有共享副本兜底的缓存;单个模型超过缓存上限时拒绝,不改成直接读。 - 迁移 127 建
instance_model_files,并按现有实例期望状态里实际挂载的路径回填。早先的版本曾让部署绑定一个存储、运行时不替换, 结果节点本地已有的模型文件被忽略、这个限制又不出现在节点条件里;改为上面的规则,原因见 设计稿。 - 不做的:跨控制面的删除锁、周期扫描、内核 FS-Cache、docker 的 NFS volume driver、对象存储直读。
这篇文档有帮助吗?