文件、缓存与持久存储配置

文件、缓存与持久存储配置

按配置总览理解类型和重载。未注明必填的项均可选。工作账号与目录属主参数在安全配置，Rust 产物参数在运行时，SQLite 路径在数据库配置。这些白名单互不替代。

变量	类型；二进制默认值	范围、作用域与覆盖
VIAT_STORAGE_ROOTS	string; unset / 未设置	D。冒号分隔绝对目录白名单，用于 local storage 资源；未设不允许保存本地存储根。资源 root 经路径检查后须位于允许范围内。
VIAT_STORAGE_SPOOL_DIR	path; <tmp>/viat-spool	S + D。须绝对路径；相对值警告并忽略。由平台拥有，Unix 权限 0711。不要交给 worker 或混入持久业务文件。
VIAT_STORAGE_MAX_FILE_BYTES	u64; 104857600 bytes	D。正的部署单文件上限，默认 100 MiB；资源 max_file_bytes 只能降低。0/非法回退默认。
VIAT_S3_MULTIPART_THRESHOLD_BYTES	u64; 67108864 bytes	D。正阈值，默认 64 MiB，超过时分段上传；不提高资源单文件上限。
VIAT_S3_MULTIPART_PART_BYTES	u64; 67108864 bytes	D。正数，限制到 5 MiB..5 GiB；为不超过 10,000 段，实现可增大分段。
VIAT_S3_HELPER_MAX_BYTES	u64; 8388608 bytes	D。ctx.resources S3 helper 的 8 MiB 缓冲上限。接受 0，但不是无限制开关。大对象改用 /_s3 流式路径，不要一味放大缓冲。
VIAT_WATCH_ROOTS	string; unset / 未设置	S + D。冒号分隔绝对目录白名单，用于文件监听；未设则禁用。须挂载容器内路径；不是 storage 或 SQLite 白名单。
VIAT_CACHE_REDIS_URL	URL; unset / 未设置	S。可选共享响应缓存；已配置但格式错误的 URI 阻止启动。运行中故障视为未命中且不存储，不让端点因此失败。设置 Redis 后取代内存后端。
VIAT_CACHE_MEMORY_MAX_BYTES	u64; 67108864 bytes	F。单进程按权重计算的内存缓存预算，默认 64 MiB；仅未配置 Redis 时 0 才关闭缓存。不是进程总内存。
VIAT_CACHE_MAX_ENTRY_BYTES	u64 → usize; 262144 bytes	F。正的缓存响应体上限，默认 256 KiB；更大响应正常返回但不缓存。0/非法回退。
VIAT_CACHE_MAX_TTL_SECS	u32 via u64; 86400 s	D。正数且须适配 u32；端点 ttl_secs 只能降低。非法/0/超范围回退 24 小时。

规划目录与挂载

VIAT_STORAGE_ROOTS=/srv/viat-files
VIAT_STORAGE_SPOOL_DIR=/var/tmp/viat-spool
VIAT_STORAGE_MAX_FILE_BYTES=104857600
VIAT_WATCH_ROOTS=/srv/viat-input

这是未执行的示例，目录必须真实存在或允许服务端创建，并映射到容器相同路径。建议把持久文件、输入目录、上传暂存、解释器缓存、编译缓存分开。不要把平台数据目录、私钥目录、/etc、宿主根或 Docker socket 放进项目作者可选择的根目录。

local storage 文件由平台后端访问，不需要为了可读就把整棵目录 chown 给脚本账号。脚本直接写普通挂载目录是另一个能力，可显式使用 VIAT_WORKER_DATA_DIRS，但它递归更改属主；宿主已有固定 UID 时用匹配 worker UID，并从 adoption 列表移除无需改属主的树。只读监听目录尽量只读挂载。检查容器内路径和账号权限，而不只是宿主目录权限。

暂存、上传和失败清理

multipart 文件按请求写入平台 spool，正常完成后删除。Unix 目录为 0711（可遍历而不可列出），worker 只应读取交给它的具体句柄。崩溃残留在启动时及每小时按保守年龄清理；年龄与同步运行/幂等陈旧阈值相关，并非“文件上传后整点删除”。不要在还有活跃请求时手工清空 spool，也不要用 spool 保存最终文件。

上传可能同时消耗反代临时盘、平台 spool 和目标对象存储空间；单文件上限不是整个部署总配额。估算并发上传峰值与失败残留，监控磁盘/ inode。遇到 413 先区分普通 2 MiB 缓冲体、multipart 文本字段、文件上限和反代限制。S3 分段失败后的残留分段也应由对象存储生命周期规则兜底，不能假定平台清理永远成功。

缓存不是备份

未配置 Redis 时，响应缓存每进程独立，重启后消失；VIAT_CACHE_MEMORY_MAX_BYTES=0 只在此模式关闭。Redis 配置存在但不可达时，运行请求会未命中，不能保证缓存命中率。缓存键区分已发布快照和允许的调用方范围，命中仍经过认证/授权等检查。不要把业务真相放在缓存中；敏感共享响应须审查端点的 cache scope。

缓存 Redis 与端点限流 Redis（VIAT_RATELIMIT_REDIS_URL）是独立配置，可指向同一受控服务但须分别预算、保护和验证。后者故障会退回每实例限流，不是严格集群限额，详见集成。

备份范围和恢复验证

平台数据库保存资源配置及管理元数据；不会自动备份 local storage 字节、SQLite 文件、业务库、S3 桶或外部秘密。文件记录/审计可能存在项目自己的业务数据库，恢复元数据与文件字节应选择一致时点。Rust 本地产物若没有其他可用副本/工具链，也可能是恢复必需数据；Cargo/uv 缓存通常可重建，但离线环境不能假定可以重新下载。

用备份与隔离恢复演练：把原目录/桶隔离，挂载恢复副本，检查权限与一个已知样本哈希，验证脚本不会写回生产。恢复测试不能只证明 PostgreSQL 可以导入。