# 使用方法

> 快速使用 MINIO 模块部署的 Silo，并通过 mcli、rclone 与 pgBackRest 接入。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

当您 [配置](/docs/minio/config/) 并执行 [剧本](/docs/minio/playbook/) 部署 Silo 后，可以参考本页通过 S3 与 `mcli` 兼容接口使用它。



--------

## 部署集群

首先在 [配置清单](/docs/setup/config/) 中定义单机单盘对象存储集群，并显式锁定引擎：

```yaml
minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio, minio_type: silo } }
```

然后，针对定义的分组（这里为 `minio`）执行 Pigsty 提供的 [`minio.yml`](/docs/minio/playbook/) 剧本即可：

```bash
./minio.yml -l minio
```

请注意在 [`deploy.yml`](/docs/setup/playbook#部署剧本) 中，事先定义好的 Silo 集群会自动创建，无需手动再次执行 `minio.yml` 剧本。

生产多节点部署应通读 Pigsty [配置文档](/docs/minio/config/)，并核对实际 Silo 版本的操作约束。



--------

## 接入集群

生产环境建议通过域名与 HTTPS 访问对象存储（默认配置也是 HTTPS）。
如果您显式设置 [`minio_https`](/docs/minio/param#minio_https) 为 `false`，也可以使用 HTTP 访问。
无论哪种方式，都请确保对象存储服务域名（默认为 `sss.pigsty`）正确指向服务节点或负载均衡器。

1. 您可以在 [`node_etc_hosts`](/docs/node/param#node_etc_hosts) 中添加静态解析记录，或者手工修改 `/etc/hosts` 文件
2. 您可以在内网的 DNS 服务器上添加一条记录，如果已经有了现成的 DNS 服务
3. 如果您启用了 Infra 节点上的 DNS 服务器，可以在 [`dns_records`](/docs/infra/param#dns_records) 中添加记录

生产环境通常建议使用第一种方式：静态 DNS 解析记录，避免对象存储服务依赖动态 DNS。

应将 S3 服务域名指向 Silo 节点或负载均衡器的 IP 地址与服务端口。
Pigsty 默认使用 `sss.pigsty` 作为 S3 服务域名，并在 `9000` 端口提供服务；角色不会自动为 `minio_domain` 创建全局 DNS 解析，需要按上文显式配置。

部分示例在 Silo 集群上部署 HAProxy 对外暴露服务，此时模板使用 `9002` 作为统一服务端口。







--------

## 添加别名

要使用 `mcli` 客户端访问 `minio` 服务器集群，首先要配置服务器的别名（`alias`）：

```bash
mcli alias ls  # 列出 minio 别名（默认使用sss）
mcli alias set sss https://sss.pigsty:9000 minioadmin S3User.MinIO            # root 用户
mcli alias set sss https://sss.pigsty:9002 minioadmin S3User.MinIO            # root 用户，使用负载均衡器 9002 端口

mcli alias set pgbackrest https://sss.pigsty:9000 pgbackrest S3User.Backup    # 使用备份用户
```

完整执行 `minio.yml` 且启用 `minio_provision` 后，角色会为所有 Infra 节点与按 `minio_cluster` 发现的实际对象存储成员上的 Ansible 执行用户配置默认别名；同一主机同时属于两者时只写入一次。

MinIO 客户端工具 `mcli` 的完整功能参考，请查阅文档： [MinIO 客户端](https://min.io/docs/minio/linux/reference/minio-mc.html)。

> [!WARNING] 注意：请使用您实际配置的密码
> 上述示例中的密码 `S3User.MinIO` 是 Pigsty 的默认值。如果您在部署时修改了 [`minio_secret_key`](/docs/minio/param#minio_secret_key)，请使用您实际配置的密码。



----------------

## 用户管理

使用 `mcli` 可以管理 Silo 中的业务用户。默认置备已经创建 `pgbackrest`、`s3user_meta` 与 `s3user_data`；下面创建一个额外用户，并附加默认生成的 `data` 桶策略：

```bash
mcli admin user list sss
set +o history
mcli admin user add sss appuser 'Replace.With.Strong.Password'
mcli admin policy attach sss data --user=appuser
set -o history
```


----------------

## 存储桶管理

**您可以对 Silo 中的存储桶进行增删改查**：

```bash
mcli ls sss/                         # 列出别名 'sss' 的所有桶
mcli mb --ignore-existing sss/hello  # 创建名为 'hello' 的桶
mcli rb --force sss/hello            # 强制删除 'hello' 桶
```


----------------

## 对象管理

**您也可以对存储桶内的对象进行增删改查**，详情请参考官方文档：[对象管理](https://min.io/docs/minio/linux/administration/object-management.html)

```bash
mcli cp /www/pigsty/* sss/data/      # 将本地软件源的内容上传到默认创建的 data 桶中
mcli cp sss/data/plugins.tgz /tmp/   # 从 Silo 下载文件到本地
mcli ls sss/data                     # 列出 data 桶中的所有文件
mcli rm sss/data/plugins.tgz         # 删除 data 桶中的特定文件
mcli cat sss/data/repo_complete      # 查看 data 桶中的文件内容
```


----------------

## 使用rclone

Pigsty 仓库中提供了 [rclone](https://rclone.org/)，一个方便的多云对象存储客户端，可以用它访问 Silo 服务。

```bash
yum install rclone;  # EL 系列系统
apt install rclone;  # Debian/Ubuntu 系统

mkdir -p ~/.config/rclone/;
tee ~/.config/rclone/rclone.conf > /dev/null <<EOF
[sss]
type = s3
access_key_id = minioadmin
secret_access_key = S3User.MinIO
endpoint = https://sss.pigsty:9000
EOF

rclone ls sss:/
```

> [!WARNING] 注意：HTTPS 与证书信任
> 如果 Silo 使用 HTTPS（默认配置），需要确保客户端信任 Pigsty CA 证书（`/etc/pki/ca.crt`），或者在 rclone 配置中添加 `no_check_certificate = true` 跳过证书验证（不建议在生产环境使用）。


----------------

## 配置备份仓库

在 Pigsty 中，MINIO 模块的主要用例是作为 pgBackRest 的 S3 备份仓库。
当您将 [`pgbackrest_method`](/docs/pgsql/param#pgbackrest_method) 设为 `minio` 时，PGSQL 模块会使用同名的 S3 兼容仓库预设；MINIO 模块部署的 Silo 可以直接使用该预设。

```yaml
pgbackrest_method: local          # pgbackrest repo method: local,minio,[user-defined...]
pgbackrest_repo:                  # pgbackrest repo: https://pgbackrest.org/configuration.html#section-repository
  local:                          # default pgbackrest repo with local posix fs
    path: /pg/backup              # local backup directory, `/pg/backup` by default
    retention_full_type: count    # retention full backups by count
    retention_full: 2             # keep 2, at most 3 full backup when using local fs repo
  minio:                          # optional minio repo for pgbackrest
    type: s3                      # minio is s3-compatible, so s3 is used
    s3_endpoint: sss.pigsty       # minio endpoint domain name, `sss.pigsty` by default
    s3_region: us-east-1          # minio region, us-east-1 by default, useless for minio
    s3_bucket: pgsql              # minio bucket name, `pgsql` by default
    s3_key: pgbackrest            # minio user access key for pgbackrest
    s3_key_secret: S3User.Backup  # minio user secret key for pgbackrest
    s3_uri_style: path            # use path style uri for minio rather than host style
    path: /pgbackrest             # minio backup path, default is `/pgbackrest`
    storage_port: 9000            # minio port, 9000 by default
    storage_ca_file: /etc/pki/ca.crt  # minio ca file path, `/etc/pki/ca.crt` by default
    bundle: y                     # bundle small files into a single file
    cipher_type: aes-256-cbc      # enable AES encryption for remote backup repo
    cipher_pass: pgBackRest       # AES encryption password, default is 'pgBackRest'
    retention_full_type: time     # retention full backup by time on minio repo
    retention_full: 14            # keep full backup for last 14 days
```

如果使用多节点 Silo 集群并通过负载均衡器对外提供服务，需要相应修改这里的 `s3_endpoint` 与 `storage_port`。