核心设置
本页介绍用于控制 SILO 进程核心行为的设置。
你可以通过以下方式建立或修改设置：
- 在启动或重启 SILO Server 之前，在宿主机系统上定义 环境变量。 如何定义环境变量，请参考所用操作系统的文档。
- 使用
mc admin config set定义 配置项。
如果同时定义了环境变量和对应的配置项，SILO 使用环境变量的值。
有些设置只有环境变量或配置项中的一种，而不是两者同时存在。
重要
每个配置项都会控制 SILO 的基础行为和功能。 SILO 强烈建议 先在 DEV 或 QA 等较低级别环境中测试配置变更，再应用到生产环境。
SILO 软件包安装的是 silo.service。服务单元为迁移兼容先读取 /etc/default/minio，再读取 /etc/default/silo，后者的同名变量覆盖前者。SILO 配置应写入后者；MINIO_* 变量名与既有参考锚点继续保留。
SILO Server CLI 选项
可选
设置一个 参数 字符串，在启动 SILO Server 时使用。
对于采用推荐 SILO systemd 服务的类 Unix 系统，请使用 /etc/default/silo 文件并创建环境变量 MINIO_OPTS，用于指定要附加到 silo systemd 进程的参数：
对于在命令行运行 silo 的系统，MINIO_OPTS 是可选项。 如需使用，请按标准 shell 语义声明该环境变量，然后在启动 SILO Server 时引用该环境变量：
重要
silo server 命令不会直接读取 $MINIO_OPTS。 该变量仅在按上述方式使用时才会生效。
存储卷
MINIO_VOLUMES
envvar
silo server 进程用作存储后端的目录或磁盘。
在功能上等价于设置 silo server DIRECTORIES。 在通过环境文件配置 SILO 运行时使用此值。
此设置没有对应的配置项。
环境变量文件路径
MINIO_CONFIG_ENV_FILE
envvar
指定 SILO server 进程用于加载环境变量的文件完整路径。
该文件在进程启动时解析（包括执行 mcli admin service restart 之后）。它不是 shell 脚本：请使用 KEY=value 条目（可选添加 export 前缀）；支持引号值与整行注释，但不执行 shell 变量展开或命令替换。文件中的条目会覆盖进程环境中已有的同名变量。
软件包提供的 systemd 单元会单独先后读取 /etc/default/minio 与 /etc/default/silo。修改任一 EnvironmentFile 通常需要执行 systemd 服务重启；仅执行管理端重启不会使 systemd 重新读取这些文件。仅在需要让 SILO 自行额外解析指定文件时才显式设置 MINIO_CONFIG_ENV_FILE。优先级与解析细节请参阅环境文件设计说明。
此设置没有对应的配置项。
YAML 配置文件
MINIO_CONFIG
envvar
指定 YAML 服务端配置文件路径（version: v1 或 version: v2），功能等价于传入 silo server --config。
SILO 20261109 集成 silo-pkg v3.16.0（go.yaml.in/yaml/v3 v3.0.6），在 YAML 编码时会对字面量键 << 添加引号，避免在保存并重新加载配置时将 << 误解析为 YAML 合并指令。
此设置没有对应的配置项。
过期处理工作线程
域名
MINIO_DOMAIN
envvar
为 MinIO 部署启用 Virtual Host 风格请求。 将该值设置为完全限定域名（FQDN），使 MinIO 能够接受传入的虚拟主机请求。
省略此设置时，MinIO 仅接受默认的 path-style 请求。
例如，某个 MinIO 部署分配的 FQDN 为 minio.example.net。
- 使用 path-style 访问时，应用可通过完整路径
minio.example.net/mybucket访问存储桶。 - 使用 virtual-host 访问时，应用可通过虚拟主机
mybucket.minio.example.net/访问存储桶。
重要
如果配置了 MINIO_DOMAIN，你 必须 将指定 FQDN 的所有子域名视为专用于存储桶名称。 任何与这些域名冲突的 MinIO 服务（例如复制目标）都可能因为冲突而表现出意外或非预期行为。
例如，若设置 MINIO_DOMAIN=minio.example.net，则 不能 将 minio.example.net 的任何子域名（即 *.minio.example.net 形式）分配给任何 MinIO 服务或目标。 这包括用于 bucket、batch 或 site replication 的主机名。
此设置没有对应的配置项。
扫描器速度
用于在平衡 MinIO 读写性能与扫描进程时，管理 scanner 的最大等待周期。
MinIO 使用 scanner 执行 存储桶复制、 站点复制、 生命周期管理 和 自愈 任务。
有效值包括：
|
移除扫描器在读/写延迟上的等待时间，使扫描器以最高速度和 IOPS 消耗运行。 此设置可能导致读取和写入性能下降。 |
|
将扫描器在读/写延迟上的等待时间设置为较短， 使扫描器以更高速度和 IOPS 消耗运行。 此设置可能导致读取和写入性能下降。 |
|
将扫描器在读/写延迟上的等待时间设置为中等， 使扫描器以平衡的速度和 IOPS 消耗运行。 此设置旨在在保持读写性能的同时允许扫描器持续工作。 |
|
将扫描器在读/写延迟上的等待时间设置为中等， 此时扫描器以较低速度和 IOPS 消耗运行。 该设置在降低扫描器性能的同时，可提供更好的读写性能。 可能影响依赖扫描器的功能，例如生命周期管理和复制。 |
|
将扫描器在读/写延迟上的等待时间设置为较长， 此时扫描器以显著更低的速度和 IOPS 消耗运行。 该设置优先保障读写操作，但可能以牺牲扫描器操作为代价。 可能影响依赖扫描器的功能，例如生命周期管理和复制。 |
批量复制
此设置没有对应的配置项。
数据压缩
以下部分记录用于为对象启用数据压缩的设置。 有关如何使用这些配置设置的教程，请参见 数据压缩。
本节中的所有设置都归属于以下顶层键：
compression
mc-conf
启用压缩
可选
设置为 on 以对新对象启用数据压缩。 默认为 off。
启用或禁用数据压缩不会更改现有对象。
允许加密
可选
设置为 on 以在压缩后对对象进行加密。 默认为 off。
对压缩对象加密可能会削弱安全性
MinIO 强烈不建议对压缩对象进行加密。 如果你需要加密，请仔细评估可能泄露加密对象内容信息的风险。
压缩扩展名
可选
要压缩的文件扩展名列表，以逗号分隔。 设置新的扩展名列表会替换先前已配置的列表。 默认为 ".txt, .log, .csv, .json, .tar, .xml, .bin"。
变更: RELEASE.2024-03-15T01-07-19Z
可指定 "*" 以指示 MinIO 压缩所有受支持的文件类型。
即使在此参数中显式指定，MinIO 也不支持压缩 Excluded File Types 列表中的文件类型。
压缩 MIME 类型
可选
要压缩的 MIME 类型列表，以逗号分隔。 设置新的类型列表会替换先前已配置的列表。 默认为 "text/*, application/json, application/xml, binary/octet-stream"。
默认排除文件
某些类型的文件无法显著减小体积。 MinIO 不会 压缩这些文件，即使它们在 mime_types 参数中被指定。 详见 Excluded types。
注释
可选
指定一个与数据压缩配置关联的注释。
纠删码条带大小
可选
应用于指定 服务器池 中所有驱动器的 erasure set size。
如果设置此值，你 必须 在初始化集群 之前 完成设置。 集群初始化后，所选条带大小为 不可变，并会影响后续添加到集群中的所有 服务器池。
初始化部署前，请校验纠删码集合布局、读写仲裁、可用容量与故障恢复行为。请参阅 纠删码。
警告
请在初始化对应服务器池之前选定显式条带大小；切勿直接修改既有存储元数据以强行变更布局。
条带大小变更会对部署功能、可用性、性能和行为产生重大影响。 MinIO 的条带选择算法已为大多数工作负载设置了适当默认值。 偏离该默认值来调整条带大小并不常见，通常也没有必要或不被建议。
最大对象版本数
可选
定义每个对象允许的默认最大版本数。
默认情况下，MinIO 允许每个对象的版本数最高达到 Int64 的最大值，即超过 9.2 quintillion。
说明
RELEASE.2023-08-04T17-40-21Z 到 RELEASE.2024-03-26T22-10-45Z 之间的 MinIO 版本，默认上限为 10,000 个对象版本。 可使用此设置将该上限覆盖为其他值。
为对象设置任意高的版本数可能导致某些操作（如 LIST）性能下降。 在使用低成本硬件或机械硬盘（HDD）的系统上，这一点尤为明显。 对于每个对象会生成数千个或更多版本的应用或工作负载，可能需要进行设计或架构评审，以缓解潜在的性能下降。
将上限设置为不超过 100，通常可满足大多数常见使用场景。
客户端源地址信任
MINIO_API_TRUSTED_PROXIES
envvar
指定哪些对端有资格告诉服务器"请求来自哪里"。
默认情况下，MinIO 会采信来自任何对端的 X-Forwarded-For、X-Real-IP 与 RFC 7239 Forwarded 头，因此一个能直接连到 API 端口的客户端可以自行设定它表面上的源地址。该地址会流入 aws:SourceIp 策略条件、审计日志的 remotehost 字段，以及事件通知的 Host 字段。
将其设为以逗号分隔的地址或 CIDR 列表，则 只 采信名单内对端送来的转发头。此时转发链会从右向左、跳过名单内的跳数来解析，这也会丢弃"追加型代理"在链首留下的、由客户端自己提供的那一项——nginx 默认的 $proxy_add_x_forwarded_for 写法与 HAProxy 追加的第二行头都会产生这一项。
将其设为 none（同义词 off），则完全不采信任何转发头，始终使用对端地址。取值大小写不敏感；条目之间可用逗号、分号或空白分隔。
三个头按固定顺序查阅——先 X-Forwarded-For，再 X-Real-IP，最后 RFC 7239 Forwarded——第一个产出地址者生效。在允许列表模式下，X-Forwarded-For 只有经过可信链解析才会产出地址；X-Real-IP 是单值、没有链可校验，因此仅当 X-Forwarded-For 的遍历没有产出时才逐字采信。代理若把 X-Real-IP 设为真实客户端地址（nginx：proxy_set_header X-Real-IP $remote_addr;），该头保持准确；代理若原样转发客户端提供的 X-Real-IP，该头即可被伪造。在代理侧剥离不可信头仍是最可靠的做法。
条目请用普通形式书写。::ffff:10.0.0.7 这类 IPv4 映射写法会被接受，但不会匹配 IPv4 对端，因此这样写的条目永远不会生效。
说明
不设置是默认值，保持历史行为，因此在你主动配置之前该设置完全惰性。
要列出 代理本身，而不是它们所在的网段。名单内的条目在遍历转发链时会被跳过，因此一个同时覆盖了客户端的网段，等于让那些客户端可以伪造。多节点部署必须把自己各节点的地址也列进去，因为 MinIO 会在节点之间转发部分请求。回环地址始终被视为可信对端，以便 FTP 与 SFTP 能正确归属其会话。取值格式错误、或没有指向任何代理，都会阻止启动。
如果你使用 IpAddress 或 NotIpAddress 策略条件，那么在此设置指明你的代理之前（或部署本身除代理外不可达之前），这些条件是无法强制执行的。
LDAP STS 登录限流有自己独立的允许列表 MINIO_IDENTITY_LDAP_STS_TRUSTED_PROXIES（见 LDAP 设置）；它只影响登录限流的分桶，从不影响 aws:SourceIp。除非刻意想让两者信任不同的对端，否则两个列表应设为相同的值。
此设置没有对应的配置项。
旧版存储桶资源匹配
MINIO_API_LEGACY_BUCKET_RESOURCE_MATCH
envvar
设为 on 可恢复桶级请求在 IAM 策略资源匹配上的历史行为。
默认情况下，有十二个桶级写操作不再能通过 arn:aws:s3:::mybucket/* 这样的对象级资源模式获得授权。动作清单以及正确授予它们的策略改法，见存储桶资源与对象资源。
设为 on 会回到"把桶级请求与字符串 mybucket/ 相匹配"的做法，而对象模式同样命中该字符串。该值在启动时读取一次，仅用作更新存量策略期间的临时手段。
这会恢复一处过度授予
正是这种历史匹配方式，让一个只持有 arn:aws:s3:::mybucket/* 上 s3:* 的主体能够改写桶策略（包括把桶变为公开），或者直接删除该桶。这个开关是全有全无的：为了一个动作打开它，会把十二个动作一并放开。
此设置没有对应的配置项。
多段上传列举：退役模式开关
SILO 20261109（自 20261018 起）： 忽略 MINIO_API_MULTIPART_LISTING，启动时说明公开列表恢复旧缓存／精确 key 行为，持久列举延期。不增加替代设置。旧共享配置键 api multipart_listing 继续被容忍，不因它拒绝启动或丢弃其他 API 设置，也不自动清理用户配置。此前启用 strict 的用户会失去可选持久列表和严格取消能力，需要评估升级影响。
只读签名接口 GET /minio/admin/v3/multipart-preflight 仍要求 admin:StorageInfo，返回 mode=legacy。complete 和 ready 描述磁盘诊断覆盖与历史记录，不是启动或列表开关。仅诊断保留 100,000 目录项、30 秒和并发预算；公开列表不依赖这些预算。无 prefix 的旧缓存仍有重启漏项和分页缺陷；非空 prefix 仍按完整对象名查找。已知 ID 的操作及后台清理保留。见最新决策与取舍。
已发布的 Server 20260916： 旧环境开关仍接受 legacy（默认）或 strict，strict 仍需满足当时的升级、排空和容量条件；Server 20260903 不提供该开关。运行旧二进制时，请参考 9 月 16 日契约。
HTTP 请求头与空闲超时
MINIO_READ_HEADER_TIMEOUT / --read-header-timeout 默认 30s；参数可用，但在普通 CLI 帮助中隐藏。Server 20260916 将其接入 HTTP/1 请求头绝对截止时间，Server 20260903 尚未正确执行这个可配置限制。零值回退到读取超时；负值禁用请求头上限，可能重新放开慢请求头资源耗尽路径。该限制也影响 TLS 握手读取。超时可能直接关闭连接，并不保证返回 HTTP 错误状态。
MINIO_IDLE_TIMEOUT / --idle-timeout 同样默认 30s，控制请求体的滚动空闲超时。持续有进展的长 HTTP/1 上传不会因此被限制为总共 30 秒。两者都没有服务端 YAML 字段；启动时 CLI 参数优先于环境变量。HTTP/2 及 TLS 写侧限制见超时设计。
旧式桶资源匹配
MINIO_API_LEGACY_BUCKET_RESOURCE_MATCH=on 是恢复桶级策略动作旧对象资源匹配行为的兼容开关，值区分大小写。策略包在进程初始化时读取它，早于 SILO 加载 MINIO_CONFIG_ENV_FILE；只在后者文件中设置不会生效。必须在启动前通过真实进程环境传入，例如 systemd 的 EnvironmentFile。应优先修正策略，避免恢复较弱的匹配规则。详见 SN-2026-004。
SILO 自身的环境文件解析器与 systemd 不同，详见环境文件设计。与工具链相关的身份提供方启动故障，见 TLS 与 OIDC 发现诊断。
站点复制元数据墓碑
MINIO_SITE_REPLICATION_METADATA_TOMBSTONES 接受 on 或 off，默认 off。它控制站点复制元数据导出是否暴露可删除桶元数据类型的真实删除时间（墓碑）信息。为 off 时，普通删除事件仍会复制，既有的策略删除时间导出保持不变，但新暴露的删除时间保持隐藏。为 on 时，缺失的标签、SSE 配置与配额的删除时间也会导出，初始同步将包含全部四种可删除类型。
该开关不探测远端站点的消费能力：只有当 mesh 中每个站点都运行能理解墓碑的构建之后才应启用，并将其视为协调升级的一部分。详见桶元数据收敛设计的发布小节。