MinIO 社区仓库已于 2026-04-25 归档，社区版改为源码分发。下面保留单机实验的服务和 SDK 用法，使用固定历史源码版本；旧的“下载最新二进制”步骤不能再当作当前安装方式。仓库与发行说明。

目录与端口如下：

  • Server：/opt/minio/server/minio
  • Client：/opt/minio/client/mc
  • Data：/opt/minio/data
  • S3 API：8071
  • Console：8070

注意：如果系统另行安装了 Midnight Commander，mc 命令可能指向该文件管理器。先用 command -v mc 确认；本文为避免歧义，使用 ./mc（在 /opt/minio/client 下）或 /opt/minio/client/mc 的绝对路径。

1. 目录规划与权限

1.1 目录结构

/opt/minio/
  server/   # minio server 二进制
  client/   # MinIO mc 二进制
  data/     # 数据目录（对象存储数据）

1.2 创建数据目录并设置权限

使用专用用户 minio-user。以下命令在 Ubuntu 的 Bash 中执行，先创建账号与完整目录：

id minio-user >/dev/null 2>&1 || sudo useradd --system --no-create-home --shell /usr/sbin/nologin minio-user
sudo mkdir -p /opt/minio/server /opt/minio/client /opt/minio/data
sudo chown -R minio-user:minio-user /opt/minio/data
sudo chmod 750 /opt/minio/data

2. 安装 MinIO Server（二进制）

先按 Go 官方安装说明 准备该源码版本所需的 Go 工具链。编译并复制到规划目录：

go install github.com/minio/minio@RELEASE.2025-10-15T17-29-55Z
sudo install -m 0755 "$(go env GOPATH)/bin/minio" /opt/minio/server/minio
/opt/minio/server/minio --version

3. 前台启动验证（API=8071 / Console=8070）

先用前台方式验证参数与端口是否正确（确保不是 systemd/权限问题）：

cd /opt/minio/server


export MINIO_ROOT_USER='localadmin'
read -r -s -p '本地 MinIO 管理密码: ' MINIO_ROOT_PASSWORD
printf '\n'
export MINIO_ROOT_PASSWORD
sudo --preserve-env=MINIO_ROOT_USER,MINIO_ROOT_PASSWORD -u minio-user ./minio server /opt/minio/data \
  --address ":8071" \
  --console-address ":8070"

验证监听端口：

ss -lntp | egrep '8070|8071'

访问地址：

  • Console：http://<服务器IP>:8070
  • S3 API（SDK/接口）：http://<服务器IP>:8071

mc、Python SDK、S3 兼容接口全部走 8071；8070 仅用于控制台页面。

4. 安装 MinIO Client（mc）并避免“系统 mc”冲突

4.1 下载 MinIO 的 mc

cd /opt/minio/client
sudo wget -O mc https://dl.min.io/client/mc/release/linux-amd64/mc
sudo chmod +x mc

4.2 强制使用 ./mc（关键点）

  • 输入 mc：由 PATH 决定，可能是 Midnight Commander，也可能是 MinIO 客户端
  • 输入 ./mc：走当前目录的 MinIO 客户端

验证版本：

cd /opt/minio/client
./mc --version

前台验证结束后先按 Ctrl+C 停止进程，再配置 systemd，避免两次启动占用同一端口。重新打开终端时，需要再次设置下方 mc 命令使用的环境变量，值与服务配置保持一致。

5. systemd 后台运行 + 开机自启动

systemd 最稳的写法：把 ExecStart 参数写清楚，不依赖拼接变量，避免“参数没展开导致启动失败”。

5.1 创建服务配置

创建 /etc/minio/minio.env，填写自己设置的凭据，并将权限设为仅 root 可读。systemd 以 root 读取该文件后再按 User 运行服务：

Terminal window
sudo install -d -m 0700 /etc/minio
sudo install -m 0600 /dev/null /etc/minio/minio.env
sudoedit /etc/minio/minio.env
Terminal window
MINIO_ROOT_USER=localadmin
MINIO_ROOT_PASSWORD=填写自己的本地管理密码

写入 /etc/systemd/system/minio.service：

sudo tee /etc/systemd/system/minio.service >/dev/null <<'EOF'
[Unit]
Description=MinIO Object Storage
Wants=network-online.target
After=network-online.target


[Service]
User=minio-user
Group=minio-user
WorkingDirectory=/opt/minio


EnvironmentFile=/etc/minio/minio.env


ExecStart=/opt/minio/server/minio server /opt/minio/data --address :8071 --console-address :8070


Restart=always
RestartSec=5
LimitNOFILE=65536


[Install]
WantedBy=multi-user.target
EOF

5.2 启动并设置开机自启

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

查看日志（排障首选）：

journalctl -u minio -f

确认端口：

ss -lntp | egrep '8070|8071'

6. 用 mc 初始化：alias、建桶、创建业务密钥、上传/下载

以下操作全部用 MinIO 的 ./mc。

6.1 绑定别名（alias）

cd /opt/minio/client


./mc alias set myminio http://127.0.0.1:8071 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"
./mc admin info myminio

6.2 创建桶（bucket）

./mc mb myminio/images
./mc ls myminio

6.3 创建业务用户（AccessKey/SecretKey）

业务系统不应长期使用 root（admin），建议为每个应用创建独立 AK/SK。

./mc admin user add myminio imgapp 'ImgAppSecret@123'

此时：

  • AccessKey：imgapp
  • SecretKey：ImgAppSecret@123

6.4 授权（先跑通再收口）

先用 readwrite 跑通：

./mc admin policy attach myminio readwrite --user imgapp

6.5 上传与下载（mc）

对象存储“目录”本质是 object key 的前缀：

# 上传
./mc cp ./test.jpg myminio/images/uploads/2026/02/27/test.jpg


# 列表
./mc ls myminio/images/uploads/2026/02/27/


# 下载
./mc cp myminio/images/uploads/2026/02/27/test.jpg ./test-down.jpg

7. Python SDK：上传、下载、图片访问

7.1 安装 SDK

python3 -m venv .venv
. .venv/bin/activate
python -m pip install minio

7.2 初始化 Client（HTTP + 8071）

先设置 MINIO_APP_SECRET 为前面创建的业务用户密码。上传、下载和预签名片段在同一个 Python 脚本中依次使用；local_path 必须指向实际存在的图片。

endpoint 建议写 host:port，并设置 secure=False（因为你当前是 http）。

import os
from minio import Minio


client = Minio(
    "127.0.0.1:8071",
    access_key="imgapp",
    secret_key=os.environ["MINIO_APP_SECRET"],
    secure=False,
)

7.3 上传文件（fput_object）

import os
from minio import Minio
from datetime import datetime


client = Minio(
    "127.0.0.1:8071",
    access_key="imgapp",
    secret_key=os.environ["MINIO_APP_SECRET"],
    secure=False,
)


bucket = "images"
if not client.bucket_exists(bucket):
    client.make_bucket(bucket)


local_path = "/tmp/test.jpg"
object_key = "uploads/{:%Y/%m/%d}/test.jpg".format(datetime.now())


client.fput_object(
    bucket_name=bucket,
    object_name=object_key,
    file_path=local_path,
    content_type="image/jpeg",
)


print("uploaded:", bucket, object_key)

7.4 下载文件（fget_object）

client.fget_object(
    bucket_name="images",
    object_name=object_key,
    file_path="/tmp/test-down.jpg",
)
print("download ok")

8. 图片在线访问：两种常用方案

方案 A：预签名 URL（私有桶推荐）

不开放匿名访问，通过临时 URL 直接在浏览器打开图片。

from datetime import timedelta


url = client.presigned_get_object(
    bucket_name="images",
    object_name=object_key,
    expires=timedelta(minutes=30),
)
print(url)

输出的 URL 直接用浏览器访问即可，30 分钟后失效。

方案 B：公开读（简单但有风险）

把桶设置为匿名下载：

cd /opt/minio/client
./mc anonymous set download myminio/images

此时图片可通过路径风格 URL 访问（无反代时）：

http://<服务器IP>:8071/images/uploads/2026/02/27/test.jpg

公开读适合明确“对外公开”的资源；内部系统或敏感图片建议使用预签名 URL 或在网关层做鉴权。

9. 常见问题与排查清单

9.1 输入 mc 进入蓝色界面

这是另一款同名文件管理器。可通过绝对路径调用 MinIO 客户端：

cd /opt/minio/client
./mc --version

9.2 mc 连不上

确认连的是 8071（S3 API），不是 8070（Console）：

ss -lntp | egrep '8070|8071'

9.3 systemd 启动失败（端口不监听）

先看状态与日志：

sudo systemctl status minio --no-pager
sudo journalctl -u minio -n 200 --no-pager

重点检查：

  • /opt/minio/server/minio 是否可执行
  • minio-user 是否能读写 /opt/minio/data
  • 端口是否被占用

10. 最小可用结果（验收标准）

满足以下几点，说明部署链路完整：

  1. systemctl status minio 为 active (running)
  2. ss -lntp | egrep '8070|8071' 能看到监听
  3. ./mc admin info myminio 返回信息
  4. Python fput_object 上传成功，fget_object 下载成功
  5. 预签名 URL 或公开读 URL 可以在浏览器打开图片