Agent 的工作目录:临时文件、配额与清理
说明:本文讨论的是 Agent 执行期间工作目录的隔离、配额与生命周期管理,属于 Agent 工程落地的资源治理话题,不涉及具体模型版本与价格。AI 领域版本迭代极快,凡涉及版本号、价格、可用性,请以你阅读时的官方页面为准。文中代码为结构示意,请按自己的技术栈调整后再上生产。
一、工作目录是 Agent 的第二个状态
一个 Agent 跑起来,系统里有两份状态。第一份是上下文:消息、工具调用记录、trace,坏了能重放重建。第二份是磁盘上那块可写空间:附件、解压结果、中间格式、最终报告。第二份不能重放,丢了就是丢了。
多数团队把第一份当基础设施做,把第二份当副作用:随手建个目录,跑完不管。两周后开始出事——磁盘告警、任务互相覆盖、续跑找不到中间件、清理脚本删错文件。
1.1 三类文件混在一个目录里
| 类型 | 谁产生 | 能否重建 | 合理保留 |
|---|---|---|---|
| 输入 | 用户上传、工具下载 | 多数不能,源头可能变了 | 跟任务同寿 |
| 中间件 | 解压、格式转换、切片 | 能,重跑该步骤即可 | 小时级 |
| 产物 | 报告、图表、打包结果 | 不能,生成了就是那一版 | 天级到月级 |
判断一个文件属于哪类,只用一条判据:能不能从上游重新算出来。 能重新导出的,是中间件;不能的,是输入或产物。
清理脚本认准「中间件可重建」,删错最多重跑一步;把输入产物当中间件删,就是事故。
反例很常见:任务目录里同时有 report.pdf(用户上传的原件)和 report.pdf(Agent 改写后的产物)。同名不同大小,清理脚本按修改时间删「旧的」,删掉的是用户原件。这类事故不报错,只会在三天后有人来问「我传的那份哪去了」。
1.2 为什么不直接用系统临时目录
/tmp 是第一个想到的落点,它恰好把四个问题凑齐。
共享。 多数系统上 /tmp 权限是 1777,谁都能写、都能读别人的文件。同一台机器跑两个租户,A 的中间件对 B 可读。
无配额。 一个任务解压 40GB 的包,写满的是整块盘,宿主机上其他进程跟着失败,包括本该负责清理的那个。
重启即丢。 容器重建、节点重启、systemd-tmpfiles 例行清理都会让内容消失。任务做到第 7 步,重启后第 1 步的文件没了。
被别人清。 systemd-tmpfiles 按文件年龄清理,tmpreaper 这类工具常驻。它们不知道任务还在跑。
还有一条容易忽略:容器里的 /tmp 常常是 tmpfs,写进去占的是内存,2GB 中间件落进去,OOM 杀掉的可能是别的服务。上线前看 df -hT /tmp,是 tmpfs 就别放超过几百 MB 的东西。
1.3 目录布局:三层各解决一个问题
层级不是审美问题,每层对应一类操作。
第一层按租户切,解决配额归属和可见性:配额按租户累计,一个租户的清理碰不到另一个。第二层按任务切,解决「取消一个任务」——有了这层,取消就是删一个目录,不用猜哪些文件属于它。第三层按步骤切,解决重跑:某一步输出有问题,只清这步目录,前面的结果不动。
路径形状:/data/agent/tenants/{tenant_id}/tasks/{task_id}/,下面分 in/、mid/{seq}-{step}/、out/。三个子目录不是分类习惯,是三种清理策略的挂载点。
task_id 用不透明 ID,ULID 或 UUID 都行。别用「用户名 + 时间戳 + 提示词摘要」拼——提示词里有换行、斜杠、emoji,拼出来的路径要么超长,要么截断后撞车。
二、隔离:一个任务一个根
隔离的实际含义是:任务 A 的任何一次文件操作,都读不到、写不进任务 B 的根。 这条要在代码层面成立,不能靠约定。
2.1 根目录由编排层给,不能由模型拼
模型不该知道绝对路径。它看到的是 input/a.pdf、out/report.md,绝对路径在工具调用时由执行器注入。
原因很直接:根路径一旦出现在模型可见的参数里,就有机会被改。改法不需要恶意,一次「帮我把文件整理到 /tmp 下」的合理请求就够了。
模型输出的路径一律当不可信输入,哪怕它刚列出来过,也可能在两轮之间编出一个很像的路径。
判据写死:入参里 / 开头或以 ~ 开头的路径直接拒绝,不做「清洗后放行」。 清洗规则越复杂,绕过方式越多;直接拒绝只有一种结果。
2.2 路径穿越与符号链接
三种越界方式要分开防:.. 穿越、绝对路径、符号链接。第三种最隐蔽——任务目录里有个 s 指向 /etc,模型读 s/passwd 就绕过了前两种检查。
硬链接和 bind mount 应用层挡不住,靠挂载策略兜,见 2.3 节。
校验顺序是:先拼、再解、再比。解要用 realpath 把 .. 和符号链接一起解掉,比要按路径段比较,不能用字符串 startswith。
startswith 出事的例子:根是 /data/t1,目标解析成 /data/t10/x,前缀匹配通过,实际是两棵不相干的树。os.path.commonpath 或 pathlib 的 is_relative_to 都能避开。
⚠️ 代码待验证
import os
from pathlib import Path
def resolve_under(root: str, user_path: str) -> Path:
"""把模型给的相对路径钉死在 root 之下"""
if user_path.startswith(("/", "~")) or "\x00" in user_path:
raise PermissionError("只接受相对路径")
root_real = os.path.realpath(root)
target = os.path.realpath(os.path.join(root_real, user_path))
# 按路径段比较,不能用 startswith:/data/t1 与 /data/t10 会误判
if os.path.commonpath([root_real, target]) != root_real:
raise PermissionError(f"越界: {user_path}")
# 逐段检查符号链接,只查最末一段挡不住目录本身是链接
probe = Path(root_real)
for part in Path(user_path).parts:
probe = probe / part
if probe.is_symlink():
raise PermissionError(f"不跟随符号链接: {part}")
return Path(target)
两个细节。realpath 对不存在的路径不报错,会按字面拼出来返回,所以「先校验后创建」要么先建父目录,要么用带 strict=True 的版本让它对缺失直接抛错。校验完到打开之间还有一个时间窗,链接可以被换掉,真正写入时用 os.open(..., os.O_NOFOLLOW | os.O_CREAT) 把这个窗口关掉。
2.3 跨任务读:只读挂载还是显式拷贝
任务之间需要共享公共数据集和上游结果,两种做法代价完全不同。
| 做法 | 空间 | 一致性 | 运维代价 | 适用 |
|---|---|---|---|---|
| 只读 bind mount | 零拷贝 | 实时,源变则读到的也变 | 需挂载权限,源删后挂载点悬空 | 大文件、多次读 |
| 显式拷贝 | 双份 | 快照,拷完即定版 | 无特权要求,可审计 | 一次性小文件 |
判据两条:单文件是否超过 200MB,同一份数据在任务内是否读三次以上。都满足就挂载,否则拷贝。
挂载的隐性成本在生命周期。源目录被清理后,挂载点变成空目录,读到的是「文件不存在」而不是报错,容易误判成任务逻辑问题。挂载由编排层建和解,业务代码不许自己 mount。
拷贝的隐性成本在一致性。拷一个正在写的源文件,拿到的是半截内容。源侧先写临时名再 rename 做原子替换,拷贝侧校验长度或哈希。
三、命名:三个月后还能找回来
目录结构决定「在哪」,文件名决定「是哪一个」。
3.1 文件名该带哪几段
路径里已经有任务和步骤,文件名不必重复,它要带来源和内容哈希。
来源指这份文件从哪来:原始附件名、URL 最后一段、上游工具名,负责让人看懂。内容哈希负责让机器认得出:同一份内容下载两次哈希相同,直接复用,不存两份。
不带三样:时间戳(同秒并发会撞名,时间信息路径里已有)、模型生成的标题(长度不可控、含标点、每次重跑都不一样)、自增序号(单机唯一,多副本部署就废)。
哈希还能挡静默截断:跨机拷贝、上传下载之后比一次,这类问题不抛异常,只在下游解析时炸。
⚠️ 代码待验证
import hashlib
import re
import unicodedata
UNSAFE = re.compile(r'[\s/\\:*?"<>|\x00-\x1f]')
def safe_name(raw: str, max_bytes: int = 80) -> str:
s = unicodedata.normalize("NFC", raw) # 先统一,再处理
s = UNSAFE.sub("_", s)
s = re.sub(r"_{2,}", "_", s).strip("._")
while len(s.encode("utf-8")) > max_bytes: # 按字节截,不按字符
s = s[:-1]
return s or "unnamed"
def artifact_name(source: str, content: bytes, ext: str) -> str:
digest = hashlib.sha256(content).hexdigest()[:12]
return f"{safe_name(source, max_bytes=60)}__{digest}{ext}"
截断按字节不按字符,因为 255 上限是字节:汉字 UTF-8 占 3 字节,80 个汉字 240 字节,字符数看着安全,字节数已贴边。哈希放最后,截断时不会被切掉。
3.2 中文、空格、超长、大小写与归一化
五样单独看不致命,叠在一起就是「文件明明在那儿,程序说找不到」。
中文与空格。 下游处处是坑:shell 没引号就断开、Makefile 里空格是分隔符、zip 打到 Windows 客户端乱码。统一规则是除字母数字和 . - _ 外全部替换。
超长。 单段 255 字节,全路径 4096 字节。路径超过 300 字节就该拆目录或截名字,别等 ENAMETOOLONG。
大小写。 Linux 区分,macOS 默认的 APFS 不区分。Report.pdf 和 report.pdf 在开发机上是一个文件,生产机上两个,测通上线后行为不同。规则是落盘前统一转小写,只在展示层保留原始大小写。
归一化。 macOS 上传的文件名常是 NFD(é 拆成 e 加组合音),Linux 侧多数工具产生 NFC。两者字节不同、肉眼相同,== 比较失败、字典去重失效。判据:任何进索引、缓存键、数据库的路径,先 unicodedata.normalize("NFC", name)。
反例:任务产出 300 个文件名是「关于华东区销售的分析报告(终版).pdf」。重跑一次多出 300 个带 (1) 的,第三次带 (2)。一个月后没人分得清哪版是最终,盘上躺着三份一样的 400MB。
3.3 产物与中间件用不同前缀
清理策略要能分开,前提是文件系统层面能分开。
| 子目录 | 写入者 | TTL 起点 | 清理动作 |
|---|---|---|---|
in/ | 任务入口 | 任务终态 | 跟任务一起删 |
mid/ | 各执行步骤 | 步骤结束 | 24 小时后删,可提前 |
out/ | 任务收尾 | 任务终态 | 30 天后归档或删 |
不用扩展名或大小来分,因为两者都不可靠。按 .tmp 后缀清,会误删名字里恰好带 .tmp 的产物;按大小清,会把正在写的大文件当垃圾。
按目录分还有个好处是权限:mid/ 在任务结束后设成不可写,out/ 保持只读,in/ 从一开始就只读。权限和策略对齐,误删概率小一个量级。
四、配额:先卡住最容易失控的三样
没有配额的共享盘,把所有租户的失败绑在一起。配额的作用不是省钱,是把一次失控限制在一个任务或一个租户内。
4.1 三层上限,超限该拒绝还是逐出
| 层级 | 口径 | 建议值(按盘调) | 超限动作 |
|---|---|---|---|
| 单文件 | 单个写入文件 | 256 MB | 写前拒绝,返回明确错误 |
| 单任务 | 任务根总占用 | 2 GB | 拒绝新写入,允许收尾 |
| 单租户 | 租户目录总占用 | 盘的 60% 除以租户数 | 逐出最老的终态任务 |
单文件超限必须写前拒绝,不能截断。截断产生的是一个损坏文件,下游解析时才炸,报错位置离真因很远。拒绝的话,Agent 能在同一轮换策略,比如分片写、改成流式。
单任务超限的正确动作是拒绝新写入、允许收尾。直接杀进程看着干脆,代价是 out/ 里留一个写了一半的文件,下游拿到的是语法不完整的 JSON 或缺页的 PDF。
单租户超限要逐出,顺序有讲究:先删 mid/(可重建),再删最老终态任务的 out/,in/ 最后动。逐出前给归属方一个明确通知,否则「我的产物自己消失了」比「配额满了」难排查十倍。
4.2 小文件与 inode
容量够但写不进去,第一种可能是 inode 用完,df -i 看 IUse%,df -h 看不出来。ext4 的 inode 数格式化时定死,默认约每 16KB 一个;XFS 动态分配。
真正先出问题的往往不是 inode 总量,是单目录文件数:十万个文件放一个目录,readdir 变慢,ls 卡住,rm -rf 跑几十分钟。单目录超过 5000 个文件就该按哈希前两位分桶,这个阈值不是拍脑袋,多数文件系统在几千到一万之间开始出现明显的目录项开销。
反例:抓网页每页存一个文件,一个任务四万个 4KB 小文件,占 160MB 看着无害,实际吃掉四万 inode,清理跑二十分钟。解法是写前聚合:按批次合成 NDJSON,几十个文件而不是几万个。
4.3 配额检查放在写前还是写后
先写再统计有两个问题:峰值已经打穿,可能写满整块盘;并发同时写会超卖,两个任务各看到「还有 1GB」,各写 800MB。
写前检查的问题是另一类:检查通过到写完之间,空间可能被别人占走。所以要预留。结论是写前预留、写后结算,预留是一次带条件的原子更新,条件不满足就说明会超。
⚠️ 代码待验证
class QuotaExceeded(Exception):
pass
def reserve(conn, task_id: str, nbytes: int, cap: int) -> None:
"""写前预占;条件不满足即拒绝,并发下不会超卖"""
cur = conn.execute(
"UPDATE task_usage SET reserved = reserved + ? "
"WHERE task_id = ? AND used + reserved + ? <= ?",
(nbytes, task_id, nbytes, cap),
)
if cur.rowcount != 1:
raise QuotaExceeded(task_id)
def settle(conn, task_id: str, reserved: int, actual: int) -> None:
"""写完结算:预占转实占,多余部分退回"""
conn.execute(
"UPDATE task_usage SET used = used + ?, reserved = reserved - ? "
"WHERE task_id = ?",
(actual, reserved, task_id),
)
预留和结算必须成对出现在 try/finally 里。只在成功路径结算,失败路径的 reserved 会一直挂着,配额看起来满了、盘是空的——这种「幽灵占用」不在 du 结果里,排查极费时间。
粒度按写入方式定:整文件按大小预留,流式按块预留、每块结算,别按 1.5 倍预留。
五、生命周期:TTL 与引用计数
配额管「能不能写」,生命周期管「什么时候该走」。
5.1 三种 TTL,起点各不相同
中间件短 TTL,24 小时量级;产物长 TTL,30 天,或者跟随会话生命周期;审计副本不参与自动清理,走归档(6.3 节)。
比数值更重要的是起点。TTL 从「任务进入终态」开始算,不从 mtime 算。
mtime 会被各种操作改写:cp -p 保留原时间、解压按包内时间戳还原、追加写会刷新。一个 2024 年的文件解压出来,mtime 显示 2024,按它清理会立刻删掉这个五分钟前刚解出来的文件。
统一起点还有个好处:排队、等审批的时间不计入 TTL,任务排队两小时再执行,中间件不会在执行前被清掉。
5.2 引用计数:一份文件被多个任务共用
一次任务下载 800MB 公共数据集,五个子任务都要读。各存一份是 4GB 浪费;共享一份,就要回答「谁最后一个用完」。
计数记在哪有讲究。扩展属性会被 cp 丢掉、被 rsync 默认忽略;硬链接数会被解压工具打散。可靠的位置是元数据库,键用内容哈希,值是计数和一组持有者。
规则三条:增计数和创建引用在同一事务里,不能先引用后计数;减计数在任务终态时做,不在启动清理时做;归零后等一个宽限期(1 小时量级)再真删,防止刚归零就被另一个任务引用。
反例:拿 atime 判断「有没有被读过」。多数挂载默认 relatime,一天才更新一次,读过的文件看着没读过。用它做引用判断,删错的概率比随机还高。
5.3 断点续跑与 TTL 的冲突
任务 23:50 因为等审批暂停,中间件 TTL 24 小时,第二天 10:00 恢复,文件还在;审批走两天,恢复时中间件没了,任务从第 7 步退回第 1 步。
三种处理,按代价排。
清单校验。 每步结束写一份 manifest,记文件名、大小、哈希,不记 mtime。续跑前逐条校验,缺哪步从哪步重跑。任何方案都要有它。
暂停即 pin。 任务进入暂停时在根目录放 .pinned 标记,清理任务跳过带标记的目录,恢复或放弃时解除。
TTL 延长。 暂停时把 TTL 延到 7 天,最省事,代价是忘了恢复的任务会慢慢吃盘。
推荐 pin 加清单校验,TTL 不动。清理必须显式检查 pin,且检查放在删除前而不是候选筛选时,否则标记可能是在筛选之后才写上的。
⚠️ 代码待验证
#!/usr/bin/env bash
set -uo pipefail
ROOT=/data/agent/tenants
LOG=/var/log/agent/cleanup.log
# 候选:mid 下的目录,超过 24 小时没动
find "$ROOT" -type d -path '*/mid/*' -mmin +1440 -print0 |
while IFS= read -r -d '' d; do
task_dir=${d%%/mid/*}
# 三个跳过条件,缺一个就会删掉正在用的东西
[ -e "$task_dir/.pinned" ] && continue # 暂停待续跑
[ -e "$task_dir/.running" ] && continue # 心跳未过期
[ -e "$d/.writing" ] && continue # 该目录当前有写入
if find "$d" -type f -delete 2>>"$LOG"; then
echo "ok $d" >>"$LOG"
else
echo "FAIL $d" >>"$LOG" # 失败不中断,交给下一轮
fi
done
两处容易写错。find ... -print0 和 read -d '' 必须配对,文件名带空格或换行才不会被切开;-delete 只能作用于单个 find 内部,不能和管道混用,所以内层单独起一次。
失败不中断也是刻意的:一个目录删不掉,不该让后面几百个跟着跳过。失败路径写进日志下一轮再试,第六章讲它为什么可能永远删不掉。
完整版资料清单:本文用到的对照表与实测记录都整理在里面了,扫码即可获取:
六、清理不掉的四种情况
清理脚本返回成功,不等于空间回来了。
6.1 句柄没释放
Linux 的语义是:文件被删除时若有进程还开着它,目录项消失、inode 保留、空间不释放,直到最后一个句柄关闭。
现象很好认:du -sh 明显下降,df -h 几乎不动。直接证据是 lsof +L1,能看到 (deleted) 标记但 SIZE 还占着的行。
根因通常是子进程继承了 fd。Agent 执行 shell 工具,工具 fork 出子进程,子进程继承了输出日志、工作目录,甚至某个打开的临时文件;父进程退出,子进程还在跑,句柄一直挂着。
处置顺序:先找出持有者,确认属于哪个任务,给它所在进程组发 SIGTERM,等 5 秒再 SIGKILL。句柄没释放时反复重试删除没用,删不掉,只刷日志。
预防放在执行器里:每次工具调用结束时关闭子进程组,subprocess 用 start_new_session=True 起,收尾时对整个进程组发信号。这比任何清理脚本都有效。
6.2 崩溃残留:启动时的孤儿扫描
进程被 OOM 杀掉、节点断电、容器被强制驱逐,都会留下没有终态的目录。它不在任何任务列表里,按终态时间筛也筛不到——它没有终态时间。
判据要三条同时成立:有 task.json 但状态不是终态;心跳表里没有这个任务;目录超过一小时没被修改。第三条是缓冲,防止把刚启动、还没写心跳的任务当孤儿。
⚠️ 代码待验证
import json
import time
from pathlib import Path
def scan_orphans(tenant_root: str, live_ids: set[str], grace: int = 3600):
found = []
for task_dir in Path(tenant_root).glob("tasks/*"):
meta = task_dir / "task.json"
if not meta.exists():
found.append((task_dir, "no_meta"))
continue
state = json.loads(meta.read_text("utf-8")).get("status")
if state in ("succeeded", "failed", "canceled"):
continue # 正常终态,交给 TTL
if task_dir.name in live_ids:
continue # 心跳还在
if time.time() - meta.stat().st_mtime < grace:
continue # 给启动留缓冲
found.append((task_dir, f"stale:{state}"))
return found
扫出来不要直接删,先 rename 到 quarantine/ 观察一天。扫描逻辑本身会出错——心跳表读失败返回空集合,一次误判就清掉全部运行中的任务。
no_meta 单独看:目录建了但 task.json 没写成,通常启动阶段就崩了,数量多,适合按天批量清。
6.3 删了但没消失:对象存储与归档
工作目录挂到对象存储上,rm 返回 0 只代表请求被接受,不代表对象没了,更不代表不再计费。
三个账实不符的来路:版本化桶里删当前版本只是加一个删除标记,历史版本还在计费;未完成的分片上传不在对象列表里,但占着空间;生命周期规则执行有延迟,小时级甚至更久。处置:列未完成分片并 abort,版本化桶显式删版本,对账要和账单或用量指标对。判据:清理跑完 24 小时后对一次账,差值超过 5% 说明有异步残留。
有审计要求的任务(资金、审批、对外承诺),流程改成:冻结 → 打包 → 校验可读 → 记录归档位置 → 才允许删。顺序不能反。先删后归档,归档脚本失败那一刻数据就没了,而失败往往不报错——tar 遇到坏文件只是退出码非零,脚本没检查就往下走了。
归档格式要能被将来的工具读,tar 加 zstd,或者原样上传对象存储加一份 NDJSON 清单。清单至少记:原始路径、大小、sha256、归档包路径和偏移。归档本身也要有 TTL,不然删除只是搬家,三年后归档桶比生产桶还大。
| 现象 | 判据 | 大概率原因 | 处置 |
|---|---|---|---|
du 降了 df 不降 | lsof +L1 有 deleted 行 | 子进程持有句柄 | 杀进程组再重试 |
| 目录不在任务列表里 | 有 task.json、无心跳、超 1 小时 | 崩溃残留 | 移入隔离区观察一天 |
| 对象列表空但计费涨 | 24 小时后对账差 > 5% | 版本残留或未完成分片 | abort 分片、删版本 |
| 归档后不可读 | 抽样解包失败 | 归档未校验 | 回滚流程,暂停删除 |
七、观测与容量
工作目录的问题有个特点:它不会突然坏,只会慢慢满。
7.1 四个指标
使用量,按租户和任务两个维度。别用 du -s 现算,十万个文件的目录算一次几十秒,监控会超时。用配额记账值,每天 du 对账一次,偏差超过 10% 说明记账漏了路径。
活跃任务数,配合使用量算出单任务平均占用,这个数决定容量规划的分母。
清理失败率,失败目录数除以候选目录数。它比「清理了多少」有用,直接说明清理还生不生效。
平均保留时长,看 P50 和 P95,不看均值。均值会被几个长任务拉偏。
7.2 水位告警与降级
关键原则:先停新任务,别让所有任务一起失败。
70% 预警,触发加速清理(提前跑一轮 TTL 到期的),同时扩容。85% 拒绝新任务,返回明确的「容量不足,请稍后重试」——排队是最差的选择,它把容量问题变成超时问题,最后所有任务一起失败。95% 只允许收尾,停止接受任何写入,运行中的任务允许把 out/ 写完。
⚠️ 代码待验证
#!/usr/bin/env bash
set -euo pipefail
usage=$(df --output=pcent /data | tail -1 | tr -dc '0-9')
if [ "$usage" -ge 95 ]; then mode=drain
elif [ "$usage" -ge 85 ]; then mode=reject_new
elif [ "$usage" -ge 70 ]; then mode=warn
else mode=normal
fi
# 带 TTL 写进共享状态,执行器取任务时读一次
redis-cli set agent:workdir:mode "$mode" ex 120 >/dev/null
echo "$(date -Is) $usage $mode"
模式带 120 秒 TTL 是刻意的取舍:采集器挂掉后模式会过期、回落到 normal,比永久锁死在 drain 好——锁死会让系统在采集中断时彻底停摆。代价是这段时间失去保护,所以另配一条告警:模式超过 5 分钟没被刷新就报。
drain 状态下最容易出的问题是清理自己也写不了日志。清理任务要能容忍日志写失败,否则盘满时正好是清理最该跑的时候,它自己先挂了。
7.3 演练:把盘写满一次
没演练过的降级逻辑等于没有。方法很土:预发环境用 fallocate 占掉 10%,逐次加到 90%,每步观察三件事。
新任务是否被拒绝、错误信息能不能看懂;运行中任务失败率是否可控,理想值低于 5%,且失败信息指向容量而不是「未知错误」;清理链路是否还能跑——这步最容易被忽略,清理脚本自己要写日志、读配置,盘满时可能第一步就失败。
判据三条:注入后 60 秒内告警到人;5 分钟内新任务被拒;运行中任务失败率低于 5%。有一条不达标,说明降级只写在文档里。
演练完清掉占位文件,还要验证一次恢复:从 90% 降到 60% 之后,reject_new 要在 2 分钟内自动回到 normal,不需要人工干预。恢复比重降级更容易被忘掉。
完整版资料清单:本文用到的对照表与实测记录都整理在里面了,扫码即可获取:
附表 A:关键取舍一览
| 工程取舍 | 原因 | 依据章节 |
|---|---|---|
| 工作目录按租户/任务/步骤三层分 | 配额、删除、重跑各需要一层边界 | 1.3 |
| 弃用系统临时目录,改用数据盘托管目录 | /tmp 共享、无配额、重启即丢、被系统清 | 1.2 |
| 模型只见相对路径,绝对根由执行器注入 | 根路径可见就可被改写,合理请求也能越界 | 2.1 |
绝对路径与 ~ 开头一律拒绝,不做清洗 | 清洗规则越复杂,绕过方式越多 | 2.1 |
越界校验用 commonpath 而非 startswith | 字符串前缀会把 /data/t1 与 /data/t10 判成同树 | 2.2 |
| 大文件用只读挂载,小文件用显式拷贝 | 前者省空间但生命周期耦合,后者简单但占双份 | 2.3 |
| 文件名只带来源与内容哈希 | 路径已表达位置,文件名只负责辨识与去重 | 3.1 |
| 落盘前统一 NFC 并转小写 | NFD/NFC 导致比较失败,大小写差异跨平台行为不同 | 3.2 |
| 单文件超限写前拒绝,不截断 | 截断产生损坏文件,报错位置离真因很远 | 4.1 |
| 配额用「写前预占 + 写后结算」 | 写后检查并发超卖,纯预占留下幽灵占用 | 4.3 |
TTL 起点用任务终态时间,不用 mtime | mtime 会被拷贝、解压、追加写改写 | 5.1 |
| 引用计数记在元数据库,键用内容哈希 | 扩展属性会被拷贝丢掉,硬链接数会被解压打散 | 5.2 |
| 删除失败的目录不阻塞整轮清理 | 一个句柄未释放不该让几百个目录一起跳过 | 5.3 |
| 孤儿目录先移入隔离区,不直接删 | 扫描逻辑本身会误判,隔离区可看可恢复 | 6.2 |
| 容量 85% 时拒新任务,不排队 | 排队把容量问题转成超时问题,最终全体失败 | 7.2 |
附表 B:术语速查表
| 术语 | 含义 | 备注 |
|---|---|---|
| 工作目录 | Agent 执行期间可写的那块空间 | 与上下文并列为两份状态 |
| 中间件 | 执行中产生的可重建文件 | 解压结果、转换格式、切片 |
| 路径穿越 | 用 .. 或绝对路径跳出根目录 | 要在解析后按段比较 |
| 预占 | 写之前先把配额记上 | 与结算成对,否则幽灵占用 |
mtime | 文件内容最后修改时间 | 会被解压和拷贝改写 |
| 引用计数 | 记录一份内容被多少任务持有 | 键用内容哈希,归零加宽限期 |
| 孤儿目录 | 没有终态也没有心跳的任务目录 | 崩溃或强制驱逐留下 |
| inode | 文件系统索引节点 | df -i 查看,小文件多先撞它 |
写在最后:这篇用到的资料
写这篇文章时,我把几个模型的官方文档、参数表和实测记录都对了一遍,顺手整理成几份配套的东西:
- 大模型学习路线图:从 LLM 基础到 Agent 开发,各阶段该学什么、用什么资料
- 大模型全套教程:按主题分好的视频与文档清单
- 大模型实战好书:24 本,附每本适合的阶段
资料是我自己整理的,放在下面这个码上,扫码即可获取:
添加时备注「大模型」,优先通过。
拿到之后建议先看学习路线图那一份,先定位自己在哪个阶段,再决定学什么,比一上来就啃框架效率高得多。
更多推荐




所有评论(0)