安装与快速上手

部署方式怎么选

MinIO 只有三条路，选起来没什么纠结的：

方式	适合场景	优点	缺点
二进制 + systemd	裸机/虚机上的生产部署	透明、可控、升级就是换个文件	要自己准备磁盘、用户、服务单元
Docker / Compose	学习、本地验证、小环境	一条命令起，环境干净	数据卷、时区、权限要额外注意
Kubernetes Operator	云原生环境、多租户	声明式、自动扩缩	组件多，学习曲线陡

本篇以 Ubuntu 22.04 + 二进制 + systemd 为主线，这是生产环境最常见也最好排障的形态；Docker 方式放在后面作为快速验证手段。

版本口径

MinIO 用日期形式的版本号（形如 RELEASE.2026-xx-xxTxx-xx-xxZ），没有 1.0、2.0 这种语义化版本。生产环境请锁定一个具体 release，升级前先在测试环境验证。

部署前的准备

准备数据盘

MinIO 要求独占磁盘，推荐 XFS 文件系统（官方测试和推荐的都是 XFS，EXT4/BTRFS/ZFS 不作保证）。假设已经挂了一块 /dev/vdb：

# 格式化为 XFS
sudo mkfs.xfs -f /dev/vdb

# 挂载点固定，重启后自动挂载（务必写进 fstab，否则重启顺序不对会起不来）
sudo mkdir -p /mnt/data
echo '/dev/vdb /mnt/data xfs defaults,noatime 0 0' | sudo tee -a /etc/fstab
sudo mount -a
df -h /mnt/data

多盘环境按同样方式挂成 /mnt/disk1 到 /mnt/diskN，挂载点保持连续编号，后面分布式部署的扩展写法依赖这个顺序。

关闭 swap、同步时间

# MinIO 不推荐使用 swap，避免延迟抖动
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

# 时间必须准，否则签名校验会失败（集群模式还会影响节点通信）
sudo apt install -y chrony
sudo systemctl enable --now chrony
chronyc tracking

时间偏差是隐形杀手

Access Denied 排到最后，经常发现是服务器时间差了几分钟：S3 签名带时间戳，偏差超过 15 分钟服务端直接拒签。装好系统第一件事就是把 NTP 配好。

二进制 + systemd 部署

下载二进制

# amd64；ARM 机器把 URL 里的 amd64 换成 arm64
wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/
minio --version

建用户和目录

MinIO 不应该用 root 跑。建一个专用的服务账号，并把数据目录的属主给它：

sudo groupadd -r minio-user
sudo useradd -M -r -g minio-user -s /sbin/nologin minio-user
sudo chown -R minio-user:minio-user /mnt/data

写环境变量文件

凭据、监听端口、数据目录都放在 /etc/default/minio 里，systemd 启动时读取：

# /etc/default/minio
MINIO_ROOT_USER=admin
MINIO_ROOT_PASSWORD=ChangeMe-Str0ng-Pass

# 单机多盘就写多个路径，空格分隔
MINIO_VOLUMES="/mnt/data"

# 控制台单独占一个端口，API 默认 9000
MINIO_OPTS="--console-address :9001"

# 可选：客户端访问用的外部地址，影响预签名 URL 里生成的域名
# MINIO_SERVER_URL="https://s3.example.net:9000"

凭据规则

MINIO_ROOT_USER 至少 3 个字符，MINIO_ROOT_PASSWORD 至少 8 个字符，否则服务直接启动失败。默认的 minioadmin/minioadmin 只能用于本地测试，生产环境必须换掉，并且不要把环境变量文件提交到 Git。

写 systemd 单元

# /etc/systemd/system/minio.service
[Unit]
Description=MinIO
Wants=network-online.target
After=network-online.target
AssertFileIsExecutable=/usr/local/bin/minio

[Service]
WorkingDirectory=/usr/local
User=minio-user
Group=minio-user
ProtectProc=invisible
EnvironmentFile=-/etc/default/minio
ExecStartPre=/bin/bash -c "if [ -z \"${MINIO_VOLUMES}\" ]; then echo 'MINIO_VOLUMES not set'; exit 1; fi"
ExecStart=/usr/local/bin/minio server $MINIO_OPTS $MINIO_VOLUMES
Restart=always
LimitNOFILE=65536
TasksMax=infinity
TimeoutStopSec=infinity
SendSIGKILL=no

[Install]
WantedBy=multi-user.target

要点：EnvironmentFile 前面的减号表示文件不存在也不报错；Restart=always 保证进程崩了会自动拉起；TimeoutStopSec=infinity 让大文件传输有足够时间优雅退出。

启动与验证

sudo systemctl daemon-reload
sudo systemctl enable --now minio
sudo systemctl status minio --no-pager

# 健康检查：返回 200 就说明 API 活着
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9000/minio/health/live

# 看启动日志里打印的 API 和 Console 地址
sudo journalctl -u minio -n 30 --no-pager

日志里出现 API: http://...:9000 http://...:9000 和 WebUI: http://...:9001 两行，就说明起来了。

Docker 方式

快速验证用 Docker 更省事，生产也能跑，但要处理好数据卷和证书目录的挂载：

docker run -d \
  --name minio \
  --restart unless-stopped \
  -p 9000:9000 -p 9001:9001 \
  -v /mnt/data:/data \
  -v /etc/minio/certs:/root/.minio/certs \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD='ChangeMe-Str0ng-Pass' \
  quay.io/minio/minio server /data --console-address ":9001"

镜像地址

官方镜像现在主推 quay.io/minio/minio，Docker Hub 上的 minio/minio 可能受拉取限流影响。国内环境拉不动时配个镜像加速，或者干脆用二进制方式。

两个容易踩的点：容器内时区默认 UTC，日志时间和本地对不上，加 -e TZ=Asia/Shanghai；数据目录必须挂出来，否则容器一删数据全没。

mc 客户端接入

mc 是和 MinIO 配套的命令行客户端，兼容所有 S3 服务。安装和常用命令的完整清单在博客 MinIO 运维日常：mc 命令实战笔记 里，这里只走一遍上手流程。

# 安装（Linux amd64）
curl -o /usr/local/bin/mc https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x /usr/local/bin/mc

# 注册一个别名，后续所有命令都用 local 指代这个集群
mc alias set local http://127.0.0.1:9000 admin 'ChangeMe-Str0ng-Pass'

# 验证连通性，同时看集群概况
mc admin info local

mc alias set 会把凭据写进 ~/.mc/config.json，所以不要把 home 目录打包分享出去；CI 环境里可以用 MC_HOST_local 环境变量临时注入。

第一次上传下载

# 建桶
mc mb local/photos

# 看桶列表
mc ls local

# 上传单个文件（目标以 / 结尾表示放进该前缀）
mc cp ./logo.png local/photos/2024/

# 递归上传整个目录
mc cp --recursive ./dist local/photos/static/

# 列对象
mc ls local/photos/2024/

# 下载回来
mc cp local/photos/2024/logo.png ./

# 看对象元数据（大小、ETag、内容类型）
mc stat local/photos/2024/logo.png

一个小细节：mc cp 上传时会根据扩展名猜 Content-Type，猜错会导致浏览器直接下载而不是显示。要覆盖就加 --attr "Content-Type=image/svg+xml"。

浏览器控制台

浏览器打开 http://服务器IP:9001，用 root 账号登录。能看到什么功能，取决于版本：

版本	控制台能力
2025 年 6 月之前的社区版	功能完整：Buckets、Monitoring、Identity、Settings 都有
2025 年 6 月及之后的社区版	精简对象浏览器：建桶、传文件、看对象详情、拿分享链接
商业版 AIStor	完整管理界面，含账户、策略、配置、监控

社区版管理功能已从控制台移除

2025 年 6 月，官方以「简化控制台」为由删掉了社区版 Web UI 里的账户与策略管理、配置管理、桶管理工具和监控面板，官方给出的替代方案是 mc 命令行或商业版 AIStor Custom。所以本系列的管理操作一律用 mc 演示，别对着新版本找菜单。

控制台别直接暴露公网

9001 端口没有额外的登录保护，只靠账号密码。生产环境请用 Nginx 反代加 TLS + IP 白名单，或者只允许内网/VPN 访问。9000 的 API 端口同理，至少套一层 TLS。

常见问题

服务起不来，日志报 Unable to initialize backend

九成是数据目录权限问题。确认 minio-user 对挂载点有读写权限，且磁盘确实挂上了（df -h 看一眼，别是写进了根分区）。

端口被占用

9000 或 9001 被别的服务占了，改 MINIO_OPTS 里的 --address 和 --console-address 即可，改完 systemctl restart minio。

浏览器访问 9000 打不开

9000 是 S3 API 端口，直接访问根路径返回的是一段 XML 错误，看着像坏了其实正常。要图形界面请访问 9001。

重启后数据目录空了

/etc/fstab 没写或者写错了，重启后磁盘没挂上，MinIO 在根分区上重新初始化了一个空目录。这种事故很常见，部署完一定重启验证一次。

小结

• 生产首选二进制 + systemd：专用用户、XFS 数据盘、时间同步、环境变量文件，四件事备齐。
• 凭据放在 /etc/default/minio，MINIO_ROOT_USER / MINIO_ROOT_PASSWORD 有最小长度限制，必须换掉默认值。
• 验证三连：systemctl status、curl /minio/health/live、journalctl -u minio 看 API 与 Console 地址。
• Docker 适合快速验证，注意挂数据卷、证书目录和时区。
• mc alias set 是所有操作的第一步，接着 mb 建桶、cp 传文件，mc 命令笔记 里有完整速查。

装好只是起点。下一篇《核心使用》把桶和对象的日常操作、版本控制、生命周期和预签名 URL 一次讲透。