核心设置

本页介绍用于控制 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 选项

`MINIO_OPTS`

envvar

此变量没有对应的配置项，因为这些设置在服务器启动时生效。

可选

设置一个参数字符串，在启动 SILO Server 时使用。

对于采用推荐 SILO systemd 服务的类 Unix 系统，请使用 /etc/default/silo 文件并创建环境变量 MINIO_OPTS，用于指定要附加到 silo systemd 进程的参数：

# Editing /etc/default/silo

MINIO_OPTS='--console-address=:9001 --ftp=address=:8021 --ftp=passive-port-range=30000-40000'

对于在命令行运行 silo 的系统，MINIO_OPTS 是可选项。如需使用，请按标准 shell 语义声明该环境变量，然后在启动 SILO Server 时引用该环境变量：

export MINIO_OPTS='--console-address=:9001 --ftp=address=:8021 --ftp=passive-port-range=30000-40000'

silo server $MINIO_OPTS ...

# The above is equivalent to running the following:
# silo server --console-address=":9001" \
#              --ftp="address=:8021"     \
#              --ftp="passive-port-range=30000-40000"

警告

重要

silo server 命令不会直接读取 $MINIO_OPTS。该变量仅在按上述方式使用时才会生效。

存储卷

`MINIO_VOLUMES`

envvar

silo server 进程用作存储后端的目录或磁盘。

在功能上等价于设置 silo server DIRECTORIES。在通过环境文件配置 SILO 运行时使用此值。

此设置没有对应的配置项。

环境变量文件路径

`MINIO_CONFIG_ENV_FILE`

envvar

指定 SILO server 进程用于加载环境变量的文件完整路径。

对于由 systemd 管理的文件，将该值设置为环境文件路径（/etc/default/silo），以便在使用 mc admin service restart 重启部署时，指示 SILO 重新加载该文件中的变更。

此设置没有对应的配置项。

过期处理工作线程

`MINIO_ILM_EXPIRY_WORKERS`

envvar

指定用于处理按 ILM 过期规则配置对象过期任务的工作线程数。未设置时，MinIO 默认最多使用可用处理器核心数的一半。

此设置没有对应的配置项。

域名

`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_SPEED`

envvar

`scanner speed`

mc-conf

用于在平衡 MinIO 读写性能与扫描进程时，管理 scanner 的最大等待周期。

MinIO 使用 scanner 执行存储桶复制、站点复制、生命周期管理和自愈任务。

有效值包括：

`fastest`	移除扫描器在读/写延迟上的等待时间，使扫描器以最高速度和 IOPS 消耗运行。此设置可能导致读取和写入性能下降。
`fast`	将扫描器在读/写延迟上的等待时间设置为较短，使扫描器以更高速度和 IOPS 消耗运行。此设置可能导致读取和写入性能下降。
`default`	将扫描器在读/写延迟上的等待时间设置为中等，使扫描器以平衡的速度和 IOPS 消耗运行。此设置旨在在保持读写性能的同时允许扫描器持续工作。
`slow`	将扫描器在读/写延迟上的等待时间设置为中等，此时扫描器以较低速度和 IOPS 消耗运行。该设置在降低扫描器性能的同时，可提供更好的读写性能。可能影响依赖扫描器的功能，例如生命周期管理和复制。
`slowest`	将扫描器在读/写延迟上的等待时间设置为较长，此时扫描器以显著更低的速度和 IOPS 消耗运行。该设置优先保障读写操作，但可能以牺牲扫描器操作为代价。可能影响依赖扫描器的功能，例如生命周期管理和复制。

批量复制

此设置没有对应的配置项。

数据压缩

以下部分记录用于为对象启用数据压缩的设置。有关如何使用这些配置设置的教程，请参见数据压缩。

本节中的所有设置都归属于以下顶层键：

`compression`

mc-conf

启用压缩

`MINIO_COMPRESSION_ENABLE`

envvar

`compression enable`

mc-conf

可选

设置为 on 以对新对象启用数据压缩。默认为 off。

启用或禁用数据压缩不会更改现有对象。

允许加密

`MINIO_COMPRESSION_ALLOW_ENCRYPTION`

envvar

`compression allow_encryption`

mc-conf

可选

设置为 on 以在压缩后对对象进行加密。默认为 off。

说明

对压缩对象加密可能会削弱安全性

MinIO 强烈不建议对压缩对象进行加密。如果你需要加密，请仔细评估可能泄露加密对象内容信息的风险。

压缩扩展名

`MINIO_COMPRESSION_EXTENSIONS`

envvar

`compression extensions`

mc-conf

可选

要压缩的文件扩展名列表，以逗号分隔。设置新的扩展名列表会替换先前已配置的列表。默认为 ".txt, .log, .csv, .json, .tar, .xml, .bin"。

说明

变更: RELEASE.2024-03-15T01-07-19Z

可指定 "*" 以指示 MinIO 压缩所有受支持的文件类型。

即使在此参数中显式指定，MinIO 也不支持压缩 Excluded File Types 列表中的文件类型。

压缩 MIME 类型

`MINIO_COMPRESSION_MIME_TYPES`

envvar

`compression mime_types`

mc-conf

可选

要压缩的 MIME 类型列表，以逗号分隔。设置新的类型列表会替换先前已配置的列表。默认为 "text/*, application/json, application/xml, binary/octet-stream"。

说明

默认排除文件

某些类型的文件无法显著减小体积。 MinIO 不会压缩这些文件，即使它们在 mime_types 参数中被指定。详见 Excluded types。

注释

此设置没有环境变量选项。请改用配置项。

`compression comment`

envvar

可选

指定一个与数据压缩配置关联的注释。

纠删码条带大小

`MINIO_ERASURE_SET_DRIVE_COUNT`

envvar

此设置没有对应的配置项。

可选

应用于指定服务器池中所有驱动器的 erasure set size。

如果设置此值，你必须在初始化集群之前完成设置。集群初始化后，所选条带大小为 不可变，并会影响后续添加到集群中的所有服务器池。

MinIO SUBNET 用户应先登录并提交 issue，讨论条带大小设置后再在任何环境中实施。

注意

警告

除非 MinIO 工程团队明确指导，否则不要更改条带大小设置。

条带大小变更会对部署功能、可用性、性能和行为产生重大影响。 MinIO 的条带选择算法已为大多数工作负载设置了适当默认值。偏离该默认值来调整条带大小并不常见，通常也没有必要或不被建议。

最大对象版本数

`MINIO_API_OBJECT_MAX_VERSIONS`

envvar

`api object_max_versions`

mc-conf

可选

定义每个对象允许的默认最大版本数。

默认情况下，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:* 的主体能够改写桶策略（包括把桶变为公开），或者直接删除该桶。这个开关是全有全无的：为了一个动作打开它，会把十二个动作一并放开。

此设置没有对应的配置项。

多段上传列举模式

仅当前 main 提供，Server 20260903 尚未包含。MINIO_API_MULTIPART_LISTING 接受 legacy 或 strict，默认 legacy。在每个服务进程的环境中设置并重启；不支持共享的 api multipart_listing 配置键，不能用 mcli admin config set 选择模式。无效值会记录诊断并使用 legacy，不会丢弃其它 API 设置。

Legacy 保留精确键/cache 列举限制。Strict 扫描持久上传元数据，启用前必须升级所有写入方并排空旧上传。缺少身份字段时无法证明旧上传属于哪个桶，因此另一个桶的上传仍可能导致本桶 strict 列举返回 503。有效身份可以提前过滤，所以并不是所有旧原生 ID 记录都会无条件导致跨桶失败。

使用只读、SigV4 认证的 GET /minio/admin/v3/multipart-preflight，需要 admin:StorageInfo。检查 mode、ready、complete、scannedEntries、legacyUploads 以及各 set 的磁盘覆盖。扫描不完整不等于结果干净；就绪结果也不能证明旧写入方不会再产生旧格式上传。100,000 条预算统计每块盘返回的目录条目，包括哈希目录，而不是唯一上传数。两种模式的每页上限均从 10,000 降为 1,000。详见升级、预检与回滚步骤。

HTTP 请求头与空闲超时

MINIO_READ_HEADER_TIMEOUT / --read-header-timeout 默认 30s；参数可用，但在普通 CLI 帮助中隐藏。当前 main 将其接入 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 发现诊断。

加载评论需要启用 JavaScript。在 GitHub 上查看讨论。