MinIO 服务器配置完全指南：配置存储机制、子系统参数与 mc admin config 实战

2026-09-05 17:50:47作者：吴年前Myrtle

本文以 MinIO 官方配置文档 docs/config/README.md 为核心，系统讲解 MinIO 服务器配置的存储与加密机制、证书目录约定、site/storage_class/etcd/api 等核心子系统的完整参数（含源码中可核实的默认值）、mc admin config 的交互式用法，以及 scanner、heal 等可热更新的动态子系统调优方法。读完本文，你可以独立为一套 MinIO 部署完成根凭据、TLS 证书、站点标识、存储冗余、联邦 etcd、API 限流与后台扫描/修复节奏的全套配置，并能从源码层面理解每个参数的生效路径。

一、配置的存储位置与生命周期

MinIO 将所有服务器配置作为部署的一部分存储：配置本身以纠删码（erasure coded）的形式保存在 MinIO 服务端上，而不是依赖某个独立的数据库或外部配置文件。在全新部署时，MinIO 会自动生成一份新配置，此后即可通过 mc admin config 命令对其进行变更。如果配置了 KMS，MinIO 还会对配置、IAM 与策略内容进行加密，加密方式详见仓库中的 KMS IAM 文档。

从源码结构看，这一机制的入口在 cmd/config-current.go：newSrvConfig() 在全新部署时创建空配置并落盘，loadConfig() 在服务启动时从后端读取配置、叠加环境变量覆盖，再调用 lookupConfigs() 完成各子系统的初始化；applyDynamicConfig() 则负责将支持热更新的子系统参数即时应用到运行时。每个子系统的默认键值（DefaultKVS）与帮助文本在 cmd/config-current.go 的 initHelp() 中统一注册，这也是 mc admin config set 能"自我描述"每个 key 参数的根本原因。

证书目录（Certificate Directory）

启用 HTTPS 访问时，TLS 证书默认存放在 ${HOME}/.minio/certs 目录下。cmd/config-dir.go 中定义了这套约定的常量：

默认配置目录为 ~/.minio（defaultMinioConfigDir = ".minio"）；
证书子目录为 certs（certsDir），CA 证书子目录为 CAs（certsCADir）；
服务端证书与私钥文件名固定为 public.crt（publicCertFile）与 private.key（privateKeyFile）。

示例目录结构：

$ mc tree --files ~/.minio
/home/user1/.minio
└─ certs
   ├─ CAs
   ├─ private.key
   └─ public.crt

如需自定义证书目录，使用 --certs-dir 命令行选项。从 cmd/common-main.go 中证书目录初始化逻辑看：当未显式提供 --certs-dir 时，MinIO 会回退到 ~/.minio/certs（即 globalConfigDir/certs），CAs 目录始终作为其子目录存在——这解释了为什么 CA 证书必须放在 certs/CAs 下而不是任意位置。

根凭据（Credentials）

MinIO 的管理员（root）凭据只能通过环境变量 MINIO_ROOT_USER 和 MINIO_ROOT_PASSWORD 设置，且只能在服务启动时生效：

export MINIO_ROOT_USER=minio
export MINIO_ROOT_PASSWORD=minio13
minio server /data

注意：minio13 仅符合密码最小长度要求的示例值，生产环境务必使用高强度随机口令，且凭据一旦写入存储格式即不可在线修改，只能通过重建部署更换。

二、核心子系统配置：site、storage_class、etcd

site：标注服务器与位置

site 子系统用于标注服务器名称与所处区域：

KEY:
site  label the server and its location

ARGS:
name     (string)    name for the site e.g. "cal-rack0"
region   (string)    name of the location of the server e.g. "us-west-1"
comment  (sentence)  optionally add a comment to this setting

等价的环境变量形式：

KEY:
site  label the server and its location

ARGS:
MINIO_SITE_NAME     (string)    name for the site e.g. "cal-rack0"
MINIO_SITE_REGION   (string)    name of the location of the server e.g. "us-west-1"
MINIO_SITE_COMMENT  (sentence)  optionally add a comment to this setting

示例：

export MINIO_SITE_REGION="us-west-0"
export MINIO_SITE_NAME="sfo-rack-1"
minio server /data

从源码看，site 的加载发生在 cmd/config-current.go 的 lookupConfigs() 中：config.LookupSite() 解析 name/region 后通过 globalSite.Update(siteCfg) 写入全局站点信息，供 OpenID 身份配置、用户代理上报等场景使用。

storage_class：定义对象级冗余

storage_class 仅存在于纠删码（erasure）部署中。cmd/config-current.go 显示：只有当 globalIsErasure 为真时，storage_class 与 heal 子系统才会被注册进配置系统。

默认规则：Standard 存储类的对象奇偶（parity）副本数为 N/2（N 为单个纠删集合内的磁盘数），RRS（Reduced Redundancy Storage，降低冗余存储类）的 parity 为 2。更多背景见 docs/erasure/storage-class/README.md。

KEY:
storage_class  define object level redundancy

ARGS:
standard  (string)    set the parity count for default standard storage class e.g. "EC:4"
rrs       (string)    set the parity count for reduced redundancy storage class e.g. "EC:2"
comment   (sentence)  optionally add a comment to this setting

等价环境变量：

KEY:
storage_class  define object level redundancy

ARGS:
MINIO_STORAGE_CLASS_STANDARD  (string)    set the parity count for default standard storage class e.g. "EC:4"
MINIO_STORAGE_CLASS_RRS       (string)    set the parity count for reduced redundancy storage class e.g. "EC:2"
MINIO_STORAGE_CLASS_COMMENT   (sentence)  optionally add a comment to this setting

取值格式为 EC:<parity>。源码中的校验函数 validateParity()（internal/config/storageclass/storage-class.go）规定了硬约束：RRS parity 不得低于最小值、不得超过集合磁盘数的一半；当同时指定两者时，Standard parity 必须大于等于 RRS parity。此外 storage-class_test.go 覆盖的测试用例表明 EC:4:5 这类多段格式与 EC:A 这类非数字格式会被直接拒绝。

etcd：IAM 与 Bucket DNS 的多集群联邦

MinIO 支持将加密后的 IAM 资产持久化到 etcd（前提同样是配置了 KMS，参见 docs/kms/IAM.md）。

注意：如果设置了 path_prefix，MinIO 将不会联邦桶（bucket）——带命名空间的 IAM 资产被视为相互隔离的租户，桶名仍然全局唯一，但对其他租户桶执行 lookup 会直接失败；而在未设 path_prefix 的联邦部署中，MinIO 会通过端口转发将请求路由到相关集群。联邦部署不应设置 path_prefix。

这一点在 cmd/config-current.go 中有直接对应：globalBucketFederation = etcdCfg.PathPrefix == "" && etcdCfg.Enabled，即"etcd 已启用且未指定 path_prefix"才开启桶联邦。

KEY:
etcd  federate multiple clusters for IAM and Bucket DNS

ARGS:
endpoints*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
path_prefix      (path)      namespace prefix to isolate tenants e.g. "customer1/"
coredns_path     (path)      shared bucket DNS records, default is "/skydns"
client_cert      (path)      client cert for mTLS authentication
client_cert_key  (path)      client cert key for mTLS authentication
comment          (sentence)  optionally add a comment to this setting

等价环境变量：

KEY:
etcd  federate multiple clusters for IAM and Bucket DNS

ARGS:
MINIO_ETCD_ENDPOINTS*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
MINIO_ETCD_PATH_PREFIX      (path)      namespace prefix to isolate tenants e.g. "customer1/"
MINIO_ETCD_COREDNS_PATH     (path)      shared bucket DNS records, default is "/skydns"
MINIO_ETCD_CLIENT_CERT      (path)      client cert for mTLS authentication
MINIO_ETCD_CLIENT_CERT_KEY  (path)      client cert key for mTLS authentication
MINIO_ETCD_COMMENT          (sentence)  optionally add a comment to this setting

设置带 * 的 endpoints 即表示启用 etcd；validateSubSysConfig() 在 cmd/config-current.go 中还会真实建立一次 etcd 连接并关闭，以验证配置有效性。

三、api 子系统：API 级限流、复制与生命周期参数

默认情况下，服务器/集群处理并发请求的数量不受限制；可以通过 api 子系统施加限制。限流细节参见 docs/throttle/README.md。

KEY:
api  manage global HTTP API call specific features, such as throttling, authentication types, etc.

ARGS:
requests_max                    (number)    set the maximum number of concurrent requests (default: 'auto')
cluster_deadline                (duration)  set the deadline for cluster readiness check (default: '10s')
cors_allow_origin               (csv)       set comma separated list of origins allowed for CORS requests (default: '*')
remote_transport_deadline       (duration)  set the deadline for API requests on remote transports while proxying between federated instances e.g. "2h" (default: '2h')
list_quorum                     (string)    set the acceptable quorum expected for list operations e.g. "optimal", "reduced", "disk", "strict", "auto" (default: 'strict')
replication_priority            (string)    set replication priority (default: 'auto')
replication_max_workers         (number)    set the maximum number of replication workers (default: '500')
replication_max_lrg_workers     (number)    set the maximum number of replication workers MinIO uses to replicate large objects between sites. (default: '10')
transition_workers              (number)    set the number of transition workers (default: '100')
stale_uploads_expiry            (duration)  set to expire stale multipart uploads older than this values (default: '24h')
stale_uploads_cleanup_interval  (duration)  set to change intervals when stale multipart uploads are expired (default: '6h')
delete_cleanup_interval         (duration)  set to change intervals when deleted objects are permanently deleted from ".trash" folder (default: '5m')
odirect                         (boolean)   set to enable or disable O_DIRECT for writes under special conditions. NOTE: do not disable O_DIRECT without prior testing (default: 'on')
root_access                     (boolean)   turn 'off' root credential access for all API calls including s3, admin operations (default: 'on')
sync_events                     (boolean)   set to enable synchronous bucket notifications (default: 'off')
object_max_versions             (number)    set max allowed number of versions per object (default: '9223372036854775807')

以上默认值与 internal/config/api/api.go 中 DefaultKVS 完全一致：requests_max 源码默认值为 0（即"auto"，不做限制）、cluster_deadline 为 10s、remote_transport_deadline 为 2h、replication_max_workers 为 500、stale_uploads_expiry 为 24h、object_max_versions 为 int64 最大值 9223372036854775807。

等价环境变量：

MINIO_API_REQUESTS_MAX                    (number)    set the maximum number of concurrent requests (default: 'auto')
MINIO_API_CLUSTER_DEADLINE                (duration)  set the deadline for cluster readiness check (default: '10s')
MINIO_API_CORS_ALLOW_ORIGIN               (csv)       set comma separated list of origins allowed for CORS requests (default: '*')
MINIO_API_REMOTE_TRANSPORT_DEADLINE       (duration)  set the deadline for API requests on remote transports while proxying between federated instances e.g. "2h" (default: '2h')
MINIO_API_LIST_QUORUM                     (string)    set the acceptable quorum expected for list operations e.g. "optimal", "reduced", "disk", "strict", "auto" (default: 'strict')
MINIO_API_REPLICATION_PRIORITY            (string)    set replication priority (default: 'auto')
MINIO_API_REPLICATION_MAX_WORKERS         (number)    set the maximum number of replication workers (default: '500')
MINIO_API_TRANSITION_WORKERS              (number)    set the number of transition workers (default: '100')
MINIO_API_STALE_UPLOADS_EXPIRY            (duration)  set to expire stale multipart uploads older than this values (default: '24h')
MINIO_API_STALE_UPLOADS_CLEANUP_INTERVAL  (duration)  set to change intervals when stale multipart uploads are expired (default: '6h')
MINIO_API_DELETE_CLEANUP_INTERVAL         (duration)  set to change intervals when deleted objects are permanently deleted from ".trash" folder (default: '5m')
MINIO_API_ODIRECT                         (boolean)   set to enable or disable O_DIRECT for writes under special conditions. NOTE: do not disable O_DIRECT without prior testing (default: 'on')
MINIO_API_ROOT_ACCESS                     (boolean)   turn 'off' root credential access for all API calls including s3, admin operations (default: 'on')
MINIO_API_SYNC_EVENTS                     (boolean)   set to enable synchronous bucket notifications (default: 'off')
MINIO_API_OBJECT_MAX_VERSIONS             (number)    set max allowed number of versions per object (default: '9223372036854775807')

结合 internal/config/api/api.go 的 LookupConfig() 实现，还有几点值得注意：

CORS 校验：cors_allow_origin 按逗号切分为列表，若列表中出现空串（如 a.com,,b.com）会返回 invalid cors value 错误；配置为空时回退为 *。
requests_max 语义：该值通过 strconv.Atoi 解析，0（auto）表示不限制并发请求数。
odirect 的双开关：源码同时维护 odirect 与 disable_odirect 两个键，EnableODirect = enableODirect || !disableODirect，即只要 odirect=on（默认）或 disable_odirect 未显式设为 on，O_DIRECT 就保持启用——这也呼应了文档中"未经充分测试不要关闭 O_DIRECT"的警告。

Notifications：支持的桶事件通知目标

MinIO 支持以下通知目标（各目标的详细配置键值参见 docs/bucket/notifications 相关文档）：

notify_webhook        publish bucket notifications to webhook endpoints
notify_amqp           publish bucket notifications to AMQP endpoints
notify_kafka          publish bucket notifications to Kafka endpoints
notify_mqtt           publish bucket notifications to MQTT endpoints
notify_nats           publish bucket notifications to NATS endpoints
notify_nsq            publish bucket notifications to NSQ endpoints
notify_mysql          publish bucket notifications to MySQL databases
notify_postgres       publish bucket notifications to Postgres databases
notify_elasticsearch  publish bucket notifications to Elasticsearch endpoints
notify_redis          publish bucket notifications to Redis datastores

从源码结构看，这十类目标在 internal/config/config.go 的 NotifySubSystems 集合中集中声明；validateSubSysConfig() 对任意通知子系统的设置都会调用 notify.TestSubSysNotificationTargets() 实际连接目标做连通性验证，连通失败则拒绝该配置变更。此外每个 notify 目标都支持 MultipleTargets（多目标），即可以用 notify_webhook:1、notify_webhook:2 这样的后缀配置多个同类型端点——这一点由 cmd/config-current.go 中各 notify 子系统的 MultipleTargets: true 标记确认。

四、使用 mc admin config 访问配置

所有配置变更都通过 mc admin config 的 get/set/reset/export/import 命令完成。mc 客户端通过管理 API 与 MinIO 交互，帮助文本即来自上文 initHelp() 注册的 HelpSubSysMap（由 cmd/config-current.go 的 GetHelp() 统一提供，--env 标志只是把每个 key 改写为 MINIO_<SUBSYS>_<KEY> 形式）。

列出所有可用配置键：

~ mc admin config set myminio/

查看单个键的帮助：

~ mc admin config set myminio/ <key>

例如 mc admin config set play/ etcd 返回 etcd 的可用参数：

~ mc admin config set play/ etcd
KEY:
etcd  federate multiple clusters for IAM and Bucket DNS

ARGS:
endpoints*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
path_prefix      (path)      namespace prefix to isolate tenants e.g. "customer1/"
coredns_path     (path)      shared bucket DNS records, default is "/skydns"
client_cert      (path)      client cert for mTLS authentication
client_cert_key  (path)      client cert key for mTLS authentication
comment          (sentence)  optionally add a comment to this setting

使用 --env 标志可获取每个配置参数的环境变量等价物：

~ mc admin config set play/ etcd --env
KEY:
etcd  federate multiple clusters for IAM and Bucket DNS

ARGS:
MINIO_ETCD_ENDPOINTS*       (csv)       comma separated list of etcd endpoints e.g. "http://localhost:2379"
MINIO_ETCD_PATH_PREFIX      (path)      namespace prefix to isolate tenants e.g. "customer1/"
MINIO_ETCD_COREDNS_PATH     (path)      shared bucket DNS records, default is "/skydns"
MINIO_ETCD_CLIENT_CERT      (path)      client cert for mTLS authentication
MINIO_ETCD_CLIENT_CERT_KEY  (path)      client cert key for mTLS authentication
MINIO_ETCD_COMMENT          (sentence)  optionally add a comment to this setting

该行为对所有 key 一致：每个 key 都能自我描述其合法参数与示例。

五、无需重启的动态子系统

以下子系统是动态的，其配置参数可以在服务器运行期间变更并即时生效：

api                   manage global HTTP API call specific features, such as throttling, authentication types, etc.
heal                  manage object healing frequency and bitrot verification checks
scanner               manage namespace scanning for usage calculation, lifecycle, healing and more

注意：如果通过环境变量设置上述子系统的配置，则动态（热更新）行为不受支持——环境变量只在启动时读取一次。

从源码看，热更新的边界由 internal/config/config.go 的 SubSystemsDynamic 集合定义，除文档列出的 api/heal/scanner 外，还包括 compression、storage_class、browser、ilm、batch、drive 与各 logger/audit 目标；运行时通过 cmd/config-current.go 的 applyDynamicConfigForSubSys() 按子系统分发：例如 scanner 分支直接 scannerSleeper.Update(delay, maxWait)，heal 分支调用 globalHealConfig.Update(healCfg)，api 分支重建 globalAPIConfig 与远端传输超时。

使用量扫描器（Usage scanner）

数据使用扫描器默认启用。其延迟参数允许更平缓的用量计算节奏：扫描器会自适应系统速度，并在系统负载升高时完全暂停，因此可以调整其速度从而改变用量更新的时延。

~ mc admin config set alias/ scanner
KEY:
scanner  manage namespace scanning for usage calculation, lifecycle, healing and more

ARGS:
delay     (float)     scanner delay multiplier, defaults to '10.0'
max_wait  (duration)  maximum wait time between operations, defaults to '15s'
cycle     (duration)  time duration between scanner cycles

示例：把扫描器速度降低 3 倍，减少系统资源占用，代价是更新反映变慢：

~ mc admin config set alias/ scanner delay=30.0

设置后扫描器配置自动生效，无需重启服务器。

补充源码层面的现状：在 internal/config/scanner/scanner.go 中，delay/max_wait/cycle 已被标注为"2022 年 10 月弃用，由单一 speed 参数替代"，同时新增了 idle_speed、alert_excess_versions（默认 100）、alert_excess_folders（默认 50000）等键；但旧键仍保留在 DefaultKVS 中并在 LookupConfig() 中被解析，因此上文的 delay=30.0 用法仍然有效。speed 取值为 default 时回退到基于延迟系数的旧算法，这保持了与既有部署的兼容。

修复（Healing）

修复（healing）默认启用。修复系统默认自适应系统速度：当系统并发请求达到 max_io 上限时，每个对象最多暂停 250ms。可以通过调整 max_sleep 与 max_io 提高修复速度：

mc admin config set alias/ heal max_sleep=1s
mc admin config set alias/ heal max_io=30

默认值是等待延迟 250ms、并发上限 100——这与 internal/config/heal/heal.go 中 DefaultKVS 的 Sleep: "250ms"、IOCount: "100" 一致。含义是：当并发客户端请求超过 100 个时，每次 heal 操作最多睡眠 250 毫秒。

每个节点只负责修复其本地磁盘；每块盘拥有多个修复 worker，数量为节点 CPU 核数的四分之一，或该盘配置的 nr_requests 的四分之一（可取内核文档 Documentation/block/queue-sysfs 了解后者）。也可以用命令显式指定 worker 数：

mc admin config set alias/ heal drive_workers=100

完整键值帮助：

~ mc admin config set alias/ heal
KEY:
heal  manage object healing frequency and bitrot verification checks

ARGS:
bitrotscan     (on|off)    perform bitrot scan on drives when checking objects during scanner
max_sleep      (duration)  maximum sleep duration between objects to slow down heal operation. eg. 2s
max_io         (int)       maximum IO requests allowed between objects to slow down heal operation. eg. 3
drive_workers  (int)       the number of workers per drive to heal a new disk replacement.

示例：允许 heal 在无延迟状态下运行至多 100 并发请求，且每次 heal 操作间最大延迟设为 300ms：

~ mc admin config set alias/ heal max_sleep=300ms max_io=100

设置后修复器配置自动生效，无需重启服务器。源码侧，heal 分支的动态更新路径是 cmd/config-current.go 中的 globalHealConfig.Update(healCfg)；另外 bitrotscan 除 on/off 外还支持以"月"为单位的扫描周期（parseBitrotConfig()，最小周期 1 个月），用于控制扫描器做位腐检查的频率。

六、仅环境变量设置的配置项（不在 config 中）

Browser：控制台 Web UI 开关

控制是否启用控制台 Web UI，默认 on，通过 MINIO_BROWSER 覆盖：

export MINIO_BROWSER=off
minio server /data

从 cmd/common-main.go 的实现看，该值以布尔方式解析（config.ParseBool），非法取值会导致服务启动失败（Invalid MINIO_BROWSER value）；此外还存在一族相关变量，如 MINIO_BROWSER_REDIRECT_URL、MINIO_BROWSER_SESSION_DURATION 等，用于重定向与 Web 会话时长控制。值得注意 browser 子系统本身已列入 SubSystemsDynamic，即 mc admin config set alias/ browser 也能在运行时切换控制台可见性。

Domain：路径样式与虚拟主机样式访问

默认情况下 MinIO 支持路径样式（path-style）请求，格式为 <http://mydomain.com/bucket/object>。设置 MINIO_DOMAIN 环境变量可启用虚拟主机样式（virtual-host-style）：当请求 Host 头匹配 (.+).mydomain.com 时，捕获组 $1 被解析为桶名，路径部分作为对象名。

export MINIO_DOMAIN=mydomain.com
minio server /data

高级用法支持逗号分隔的多域名：

export MINIO_DOMAIN=sub1.mydomain.com,sub2.mydomain.com
minio server /data

虚拟主机解析出的域名集合会进入 globalDomainNames；结合 cmd/config-current.go 的逻辑可以看到，当启用了 etcd 且存在域名/IP 时，MinIO 会基于 etcd 建立 CoreDNS 桶记录（dns.NewCoreDNS），这正是"etcd + 虚拟主机 = 跨集群桶 DNS 联邦"的底层实现；若已配置远端 Webhook DNS（EnvDNSWebhook），则会记录提示"DNS store 已由 webhook 配置，etcd 不再用于 DNS 存储"。

七、小结：一条配置从设置到生效的完整链路

把本文各节串起来，一个配置项（如 heal.max_sleep）在 MinIO 中的完整生命周期是：

设置：mc admin config set alias/ heal max_sleep=300ms 经管理 API 下发，服务端经 validateSubSysConfig() 校验（heal 分支调用 heal.LookupConfig()）；
持久化：配置以纠删码形式写回服务端存储，KMS 启用时内容被加密；
热更新：applyDynamicConfigForSubSys() 将新值写入 globalHealConfig 等全局运行时对象，立即生效；
重启兜底：下次启动时 loadConfig() 从存储读回配置、环境变量覆盖（若设置了对应 MINIO_* 变量）、再由 lookupConfigs() 统一初始化。

掌握这条链路后，你就能对任意子系统判断：它是启动期配置（如 site、etcd、storage_class 的初始结构），还是可热更新配置（api、heal、scanner、browser 等 SubSystemsDynamic 成员），以及环境变量与 mc admin config 设置之间的优先级关系（环境变量优先，但会失去动态更新能力）。更多部署与加密实践可参考 docs/kms/IAM.md、docs/erasure/storage-class/README.md 与 docs/throttle/README.md。