Знание должно быть доступно!

Путь /ОС/Linux

mcli Полное руководство (быстрый вход за 10 минут)

Это практическая шпаргалка по MinIO S3 и клиенту mcli.
Подходит для self-host установки через Traefik / reverse proxy.

Что такое MinIO

MinIO - это S3-совместимое object storage.

То есть любой инструмент, работающий с AWS S3, будет работать и с MinIO.

Примеры клиентов:

  • aws-cli
  • rclone
  • restic
  • borg
  • obsidian S3 plugins
  • backup системы
  • CI/CD

Основные понятия S3

MinIO
├── Bucket
│ ├── object1
│ ├── object2
│ └── object3

Bucket - это аналог папки верхнего уровня.

Объект:

bucket/key

пример:

mind/test.txt

URL объекта:

https://s3.example.com/mind/test.txt

Установка клиента

Linux

pacman -S minio-client

Подключение к серверу

Добавить alias:

mcli alias set s3 https://s3.example.com ACCESS_KEY SECRET_KEY

пример:

mcli alias set s3 https://s3.example.com admin password

Проверить:

mcli alias list

Основные команды

список bucket

mcli ls s3

создать bucket

mcli mb s3/bucket

пример:

mcli mb s3/mind

удалить bucket

mcli rb s3/bucket

Работа с файлами

загрузить файл

mcli cp file.txt s3/mind/

скачать файл

mcli cp s3/mind/file.txt .

копировать между bucket

mcli cp s3/a/file s3/b/

удалить файл

mcli rm s3/mind/file.txt

рекурсивная загрузка

mcli cp --recursive folder/ s3/mind/

Просмотр объектов

mcli ls s3/mind

рекурсивно

mcli ls --recursive s3/mind

Версии файлов (Versioning)

версионирование файлов

включить

mcli version enable s3/mind

проверить

mcli version info s3/mind

посмотреть версии

mcli ls --versions s3/mind

Lifecycle правила

Lifecycle автоматически:

  • удаляет файлы
  • удаляет старые версии
  • удаляет incomplete uploads

пример:

delete objects older than 30 days

Публичный доступ

сделать bucket публичным

mcli anonymous set public s3/mind

Теперь файл доступен:

https://s3.example.com/mind/file.png

Временные ссылки (Presigned URLs)

Создать временную ссылку:

mcli share download s3/mind/file.txt

пример результата:

https://s3.example.com/mind/file.txt?X-Amz-Signature=...

Можно указать время:

mcli share download --expire 1h s3/mind/file.txt

Пользователи

список

mcli admin user list s3

создать пользователя

mcli admin user add s3 USERE PASSWD

удалить

mcli admin user remove s3 user1

Группы

Посмотреть группы

mcli admin group list s3

Создать группу

//Это сделает сразу две вещи:
// - создаст группу `devs` 
// - добавит пользователя `xh7` в неё
mcli admin group add s3 devs xh7

Посмотреть содержимое группы

mcli admin group info s3 devs

Удалить группу

mcli admin group remove s3 devs

Политики доступа

список

mcli admin policy list s3

применить политику

mcli admin policy set s3 readwrite user=user1

Назначит политику группе

mcli admin policy attach s3 readwrite --group devs

//она разрешает:
s3:GetObject  
s3:PutObject  
s3:DeleteObject  
s3:ListBucket

Удалить политику группе

mcli admin policy detach s3 readwrite --group devs

применить свою политику для anonymous:


//Скидываем политики
mcli anonymous set none s3/mind

//Создаём новую
nvim policy_custom.json

//вставляем примерное
{
 "Statement": [
  {
   "Action": [
    "s3:GetBucketLocation",
    "s3:ListBucket" //просмотр файлов в директории, удалить если не надо
   ],
   "Effect": "Allow",
   "Principal": {
    "AWS": [
     "*"
    ]
   },
   "Resource": [
    "arn:aws:s3:::mind"
   ]
  },
  {
   "Action": [
    "s3:GetObject"
   ],
   "Effect": "Allow",
   "Principal": {
    "AWS": [
     "*"
    ]
   },
   "Resource": [
    "arn:aws:s3:::mind/*"
   ]
  }
 ],
 "Version": "2012-10-17"
}



mcli anonymous set-json policy_custom.json s3/mind

Применить свою политику для группы

//Создай файл, назови как хочешь
nvim mind-rw.json 

Пример:

{  
	"Version": "2012-10-17",  
	"Statement": [  
	{  
	"Effect": "Allow",  
	"Action": [  
		"s3:ListBucket"  
	],  
	"Resource": [  
		"arn:aws:s3:::mind"  
	]  
	},  
	{  
	"Effect": "Allow",  
	"Action": [  
		"s3:GetObject",  
		"s3:PutObject",  
		"s3:DeleteObject"  
	],  
	"Resource": [  
		"arn:aws:s3:::mind/*"  
	]  
	}  
	]  
}

//добавить policy в MinIO
mcli admin policy create s3 mind-rw mind-rw.json

//назначить группе
mcli admin policy attach s3 mind-rw --group devs

Минимальный набор для нормальной работы S3 клиента:

|действие|зачем| |---|---| |s3:ListBucket|видеть список файлов| |s3:GetObject|скачивать| |s3:PutObject|загружать| |s3:DeleteObject|удалять|

Иногда ещё добавляют:

| действие | зачем | | ------------------------------- | ----------------- | | s3:AbortMultipartUpload | отменять загрузку | | s3:ListBucketMultipartUploads | multipart upload |

проверка политики

mcli admin group info s3 devs

Информация о сервере

mcli admin info s3

пример:

Uptime  
Version  
Drives  
Network

Диагностика

посмотреть API запросы

mcli admin trace s3

Очень полезно для дебага.

Конфигурация сервера

список секций

mcli admin config get s3

посмотреть секцию

mcli admin config get s3 api

экспорт всей конфигурации

mcli admin config export s3

Важные параметры

API

cors_allow_origin=*  
root_access=on  
requests_max=0

Browser

hsts_seconds  
csp_policy

Lifecycle

transition_workers  
expiration_workers

Полезные функции MinIO

Versioning

защита от удаления файлов.

Presigned URLs

временные ссылки.

Lifecycle

автоматическая очистка.

Event system

MinIO может отправлять события:

Kafka  
NATS  
Redis  
PostgreSQL  
webhooks

Архитектура MinIO

Пример:

Internet
↓
Traefik
├── s3.example.com → MinIO API
└── console.example.com → MinIO Console

Где хранятся данные

/data

и метаданные:

.minio.sys

Лучшие практики

не использовать root

создать пользователя:

mcli admin user add

включить versioning

mcli version enable

делать backups

MinIO — это storage, а не backup система.

Полезные команды

health

curl https://s3.example.com/minio/health/live

тест upload

echo test > test.txt  
mcli cp test.txt s3/mind/

Полная строка

arn:aws:s3:::mind

разбирается так:

| часть | значение | | ------ | --------------------------------------- | | arn | идентификатор ресурса | | aws | partition | | s3 | сервис | | ::: | region + account (в S3 не используются) | | mind | bucket |

Примеры S3 ARN

bucket

arn:aws:s3:::mind

объект

arn:aws:s3:::mind/image.png

все объекты

arn:aws:s3:::mind/*

Итог

MinIO = self-host S3.

Подходит для:

  • backup
  • storage
  • CI/CD artifacts
  • datasets
  • static files
  • uploads

Дополнительные ресурсы

MinIO docs:

https://min.io/docs/