Docker 部署 MinIO：单机对象存储和常用运维命令

MinIO 单机部署很轻，一个容器、两个端口、一个数据目录就够。麻烦的地方在于控制台和 API 是两套端口、改账号要重建容器、以及反向代理下的上传和 WebSocket。下面按单机单盘模式讲，最后说清它的边界。

一、镜像、端口和目录

docker pull minio/minio:latest
sudo mkdir -p /data/minio/data

正式环境不要用 latest，把 tag 固定到具体的 RELEASE 版本，升级时才有据可查。

二、启动

docker run -d --name minio \
  -p 9000:9000 -p 9001:9001 \
  -v /data/minio/data:/data \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD='至少八位的密码' \
  -e TZ=Asia/Shanghai \
  --restart=always \
  minio/minio:latest server /data --console-address ":9001"

三个参数不能少：

1. server /data：告诉 MinIO 数据目录在哪，容器里就是 /data，必须挂出来。
2. --console-address ":9001"：不给的话控制台端口是随机的，docker ps 里还要再查一次。
3. MINIO_ROOT_USER / MINIO_ROOT_PASSWORD：不设的话会用默认的 minioadmin / minioadmin，这是公认的默认口令，必须改。用户名至少 3 位，密码至少 8 位，不满足时容器启动即退出。

老资料里的 MINIO_ACCESS_KEY / MINIO_SECRET_KEY 已经废弃，写了也不生效，直接用 MINIO_ROOT_*。

三、compose 版本

services:
  minio:
    image: minio/minio:latest
    container_name: minio
    restart: always
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      TZ: Asia/Shanghai
      MINIO_ROOT_USER: admin
      MINIO_ROOT_PASSWORD: 至少八位的密码
    volumes:
      - /data/minio/data:/data
    command: server /data --console-address ":9001"
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 30s
      timeout: 10s
      retries: 3

密码写在 compose 里等于写在文件里，权限收到 600，或者用 env_file 单独放：

sudo chmod 600 /data/minio/docker-compose.yml

四、验证

容器起来后，先看健康检查接口，这个不需要认证：

curl -i http://127.0.0.1:9000/minio/health/live

返回 200 OK 说明服务在跑。然后进控制台 http://服务器IP:9001，用上面设置的用户名密码登录，能建桶就说明读写正常。

再看一眼数据目录，首次启动后 /data/minio/data 下会出现 .minio.sys：

ls -la /data/minio/data

如果这里报权限问题，先确认容器内进程的 uid：

docker exec minio id
sudo chown -R <uid>:<gid> /data/minio/data

五、用 mc 管理

mc 是 MinIO 的客户端，单文件二进制，和 Docker 无关，装在宿主机或运维机上：

mc alias set local http://127.0.0.1:9000 admin '密码'
mc admin info local

常用的几条：

mc mb local/backup                 # 建桶
mc ls local                        # 列桶
mc ls local/backup                 # 列对象
mc cp app.tar.gz local/backup/     # 上传
mc cp local/backup/app.tar.gz ./   # 下载
mc rm local/backup/old.tar.gz      # 删除
mc mirror ./dist local/static      # 目录同步，增量
mc du local/backup                 # 统计用量

mc mirror 是最实用的一个，可以把它当成对象存储版的 rsync，做目录发布和备份都行。加 --remove 会删掉目标端多余的文件，用之前确认方向别写反。

六、反向代理

API 和控制在同一个域名下，用路径区分：

server {
    listen 443 ssl;
    server_name s3.example.com;

    client_max_body_size 0;
    proxy_request_buffering off;
    proxy_buffering off;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /minio/ {
        proxy_pass http://127.0.0.1:9001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
    }
}

client_max_body_size 0 是必须的：MinIO 上传大对象时走的是分片，但单个分片也可能超过 Nginx 默认的 1 MB，不放开就会遇到 413。proxy_buffering off 是为了避免大文件先落到 Nginx 的临时目录。

控制台那一段必须带 Upgrade 和 Connection 头，否则页面能打开但登录后一直转圈，因为控制台的 WebSocket 连不上。

反代之后还要告诉 MinIO 外部访问地址，否则登录后跳转和预签名 URL 会指向内网地址：

    environment:
      MINIO_SERVER_URL: https://s3.example.com
      MINIO_BROWSER_REDIRECT_URL: https://s3.example.com/minio/

七、备份

MinIO 的数据是对象文件，直接 cp 数据目录并不可靠，尤其在有写入的时候。用客户端做：

mc mirror --overwrite local/important /backup/minio/important

或者用 mc admin 的导出功能搬全量，数据量大的场景更推荐在存储层做快照，或者上分布式多副本。

八、常见报错

九、边界

单机单盘模式没有冗余，磁盘坏了数据就没了，也没有纠删码。MinIO 的分布式模式至少需要 4 块盘（4 个目录也行），部署形态和多副本策略是另一套东西，单机跑起来之后再往上加节点并不平滑。

另外，MinIO 不是文件服务器，它存的是对象。需要像 Windows 共享目录那样挂载到本地盘的场景，它不合适，得配 S3 网关或者换别的方案。

如果只是给应用做附件、备份包、镜像层这类存储，单机模式配好备份就足够用了。