配置环境文件不是 Shell 脚本

本文定义 MINIO_CONFIG_ENV_FILE 的启动契约，并记录 SILO 提交 ce456dba0 中的兼容性修复。

截至 2026-08-28 的状态： 实现、定向测试、完整 cmd 与 internal 套件、tagged tests、race、vet、lint、生成物检查、rebrand 守卫、构建与本机 Fable Max 独立评审均已完成。服务器提交已在本地创建；push、远端 CI、merge、tag、软件包、镜像、部署和生产验证仍是独立门槛。
范围： 只修改环境文件解析与命名 target 发现；不改配置键、子系统、取值优先级、存储格式或客户端 API。
兼容性原则： 这是 SILO 的输入格式。支持可选的 export 前缀，并不意味着它是一段 POSIX shell 程序。

太长不看（TL;DR）

SILO 可以从文件加载启动环境变量：

export MINIO_CONFIG_ENV_FILE=/etc/default/silo
silo server /data

解析器接受如下写法：

MINIO_ROOT_USER = silo-admin
MINIO_ROOT_PASSWORD = "  两侧空格有意义  "
MINIO_NOTIFY_WEBHOOK_ENABLE_my-hook = off
MINIO_NOTIFY_WEBHOOK_ENDPOINT_my-hook = https://events.example.com/minio

最后两个键尤其关键。支持多 target 的配置会把 target 名原样拼到下划线之后；配置子系统并没有要求 target 必须是 shell identifier。带 -、.、:、数字或可见 Unicode 的名称，都可以被精确发现和解析。

此前一轮加固意外把每个键都限制成 [A-Za-z_][A-Za-z0-9_]*。结果是 my-hook 变成非法名称，旧 loader 与配置模型原本接受的文件，会在服务器下次重启时阻止启动。最终修复改为验证 SILO 真正需要的约束：

• 键名非空、是合法 UTF-8，并且只包含可见的非空白字符；
• 键名不能包含 = 或 NUL；
• 值不能包含 NUL；
• 错误报告文件与行号，但不报告 value；
• 整个文件先完整解析，再开始设置环境变量。

为什么这是真实兼容回归

环境文件 loader 解析完成后调用 os.Setenv。操作系统环境是一组字符串，不是 shell 变量命名空间。Shell 的赋值语法更窄，是因为 shell 还要在自己的语言中对变量名做分词和展开。

SILO 命名配置 target 的结构是：

MINIO_<SUBSYSTEM>_<PARAMETER>_<target>

例如：

MINIO_NOTIFY_WEBHOOK_ENABLE_my-hook
MINIO_NOTIFY_WEBHOOK_ENDPOINT_my-hook

Target discovery 会按固定 parameter 前缀枚举变量，并把剩余后缀当成 target；读取时也用同一个原样后缀重建变量名，不会大写或净化 target。环境文件解析器拒绝 -，因此破坏的是一条本来完整可用的发现—读取链，而不是在保护某条 shell 执行路径——因为这个文件根本不会被 shell 执行。

该问题的运维影响很尖锐：MINIO_CONFIG_ENV_FILE 只在启动时读取。服务器可能继续使用旧进程环境正常运行，却在文件或二进制更新后的下一次重启突然失败。错误输入当然应该 fail fast，但 parser 不能擅自发明比配置系统更窄的 target 语法。

文件语法

行与注释

• 忽略空行；
• 忽略第一个非空白字符为 # 的整行；
• 删除后面紧跟空白的独立 export 前缀；
• exportFOO=value 的键仍然是 exportFOO，不会误删前缀；
• 第一个 = 分隔 key/value，后续 = 全部保留在 value 中。

这个文件不是 shell，不执行变量展开、命令替换、反斜杠处理或行尾注释解释。

键名

键名两侧空白会先删除，剩余内容必须：

1. 非空且为合法 UTF-8；
2. 只包含 Unicode graphic 字符；
3. 不包含空白、=、NUL、控制字符或不可见格式字符。

这个契约保留 OS 兼容名称与多 target 后缀，同时拒绝视觉上为空或结构含糊的键。以数字或标点开头的键可以通过 parser；SILO 仍只读取自身组件实际使用的精确名称。

值与引号

未加引号的值会 trim。需要保留首尾空格时，请用匹配的单引号或双引号包裹完整值：

PLAIN = value
SPACED = "  两侧空格有意义  "
TOKEN = scheme://user:password@example.com?a=b
EMPTY =

解析器只删除一对匹配的外层引号，不解释引号内部的转义。NUL 永远非法，因为操作系统环境项无法表示它。

失败与保密契约

语法错误会阻止启动。诊断包含文件路径、行号和非法键或错误类别，但绝不包含 value；密码即使出现在坏行中，也不能被复制进日志。

语法解析是全有或全无：任一行出错都会返回空结果，只有整个文件成功后才开始赋值。如果操作系统拒绝一个已经通过 parser 的赋值，SILO 同样停止启动，并指出键名与文件。进程会退出，因此不会以“只加载一半”的环境继续对外服务。

环境文件本身仍然是包含机密的高权限输入。操作员必须设置正确的属主与权限；parser 校验不能替代文件系统访问控制。

回归矩阵

提交中的测试覆盖：

• = 两侧的空格与 tab；
• 需要保留空格的 quoted value；
• 独立 export，包括后接 Unicode 空白；
• _、数字或标点开头的键；
• 使用 -、.、: 与 Unicode 的命名 target；
• 通过配置子系统实际发现命名 target；
• 空键、空白、NUL 与不可见 format character；
• NUL value；
• URL/token 中的多个 =；
• 不泄漏 value 的文件/行号诊断；
• 解析失败返回空结果。

实现通过了完整本地服务器验证矩阵与只读对抗性评审。Windows runner 尚未实测新放行名称的 os.Setenv 行为；若平台拒绝，契约仍是显式 fail fast，而不是静默忽略。

兼容性与交付

不需要迁移配置。普通环境键行为不变；带 shell 风格空白的文件更可预测，原本合法的命名 target 恢复工作。

外部可见变化都是刻意的：

• 非法或不可见键名现在失败，而不再静默失效；
• 未加引号的 value 会删除首尾空白，有意义时必须加引号；
• 畸形输入以带位置且脱敏的错误阻止启动；
• 仅仅因为 shell 不能用 NAME=value 语法直接赋值，不再拒绝一个合法的标点 target。

本文记录的是 source commit，不是已交付 release。在提交完成 push、远端测试、merge、tag、打包、制镜像和部署之前，不能假设公开 SILO 二进制已经具备此契约。

结论

配置兼容性的前提，是验证 SILO 真正消费的格式。MINIO_CONFIG_ENV_FILE 只借用了少量 dotenv 风格语法方便运维，并不会被 shell 执行。最终修复在恢复命名 target 兼容性的同时，保留了 NUL、不可见字符、脱敏与 fail-fast 保障。