MinIO 维护手册

1. 文档目标

本文是面向日常运维的 MinIO 维护手册，重点覆盖：

如何连接本机 MinIO
如何用 mc 查看和维护桶
如何维护匿名访问策略
如何维护版本化、生命周期、标签、加密、复制
如何进行变更前备份、变更后校验与回滚
如何排查常见问题
如有必要，如何重新开启 MinIO Console

配套调研说明见：

MinIO 部署现状与维护调研.md

2. 当前环境概况

2.1 当前服务形态

当前环境由两层组成：

MinIO 本体
- 本机 systemd 服务
- 监听 9000
- 数据目录 /root/minio
自定义上传页
- 外部域名：https://minio.898311.xyz/
- 对外暴露桶列表与上传能力
- 不是 MinIO 官方 Console

2.2 配置文件位置

核心配置位置：

MinIO systemd 单元：
- minio.service
MinIO 环境文件：
- minio

当前确认信息：

API 地址：http://127.0.0.1:9000
当前正式配置未开启 Console
本机已安装 mc
http://minio.898311.xyz/ 和 https://minio.898311.xyz/ 当前都不是可直接给 mc 使用的 S3 endpoint

2.3 当前上传页返回的桶列表

公开接口返回：

["blogfile","blogimg","image","tmp-image","upload"]

默认桶：

blogimg

注意：

这是上传页暴露给前端的桶列表
不一定等于 MinIO 内部全部真实桶
真实事实源以 mc ls 为准

2.4 域名能否直接给 mc 使用

当前已确认：

http://minio.898311.xyz/ 返回 text/html
https://minio.898311.xyz/ 返回 text/html
页面内容是 MinIO 图片上传器
mc ls 直连该域名会失败

因此：

该域名当前是上传页，不是真正的 MinIO S3 API 根入口
外网同事不能把这个域名直接配置为 mc endpoint
当前唯一已确认可用的管理入口是本机 http://127.0.0.1:9000

2.5 当前已确认的外网 MinIO API 地址

当前还额外确认了 frpc 映射关系：

本机 MinIO API：127.0.0.1:9000
frpc 远端映射：tx2.898311.xyz:9010

因此外网真正可用于 mc 的地址是：

http://tx2.898311.xyz:9010

这个地址已通过以下方式确认：

env MC_HOST_remote=http://<user>:<pass>@tx2.898311.xyz:9010 mc ls remote
env MC_HOST_remote=http://<user>:<pass>@tx2.898311.xyz:9010 mc admin info remote

两条命令均已成功。

3. 维护原则

3.1 管理分层

后续维护应区分两类动作：

MinIO 本体配置维护
- 桶创建/删除
- 匿名策略
- 版本化
- 生命周期
- 标签
- 加密
- 复制
上传中间层维护
- 前端允许看到哪些桶
- 默认上传到哪个桶
- 上传规则是否限制为图片

本手册只覆盖第一类，即 真实桶配置维护。

3.2 操作顺序

所有写操作建议遵循以下顺序：

先做只读检查
导出当前配置做备份
执行变更
立即校验
把变更记录写入仓库文档

3.3 凭证原则

不要把 root 凭证再次硬编码到仓库文档和脚本中。

推荐做法：

从 /etc/default/minio 读取
手工导入 shell 环境变量
脚本中只引用环境变量，不写明文

4. 准备工作

4.1 检查 MinIO 服务状态

systemctl status minio

目标：

服务状态为 active (running)
启动命令正常
没有持续报错

4.2 查看 MinIO 配置

sed -n '1,160p' /etc/default/minio
systemctl cat minio

确认内容：

MINIO_VOLUMES
MINIO_OPTS
MINIO_ROOT_USER
MINIO_ROOT_PASSWORD
是否存在 --console-address
是否配置 MINIO_BROWSER=off

4.3 确认 mc 已安装

mc --version

如果未安装，再补安装；当前环境已经安装完成。

5. 配置 mc 连接

5.1 建议优先使用本地地址

推荐使用：

http://127.0.0.1:9000

不建议优先使用：

https://minio.898311.xyz/

原因：

本地地址直连 MinIO API
避开自定义上传页和反向代理
排障更直接

不要使用：

mc alias set local-domain http://minio.898311.xyz "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"

原因：

根域名返回的是 HTML 上传页
不是 S3 ListBuckets API
mc 会因为收到非 S3 XML 响应而失败

如果是在外网维护，使用：

http://tx2.898311.xyz:9010

5.2 手工导出凭证

建议先在 shell 中导出：

export MINIO_ROOT_USER='<MINIO_ROOT_USER>'
export MINIO_ROOT_PASSWORD='<MINIO_ROOT_PASSWORD>'

这里的真实值来自：

/etc/default/minio

5.3 配置 alias

内网维护：

mc alias set local http://127.0.0.1:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"

外网维护：

mc alias set remote http://tx2.898311.xyz:9010 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"

验证：

mc alias list
mc ping local
mc ls local

如果配置的是外网 alias，则执行：

mc ping remote
mc ls remote
mc admin info remote

如果能正常列出桶，说明连接成功。

5.4 可选：调试模式

如果连接异常，可加调试：

mc --debug ls local

6. 日常只读巡检

建议所有维护前先执行以下巡检。

6.1 列出全部桶

mc ls local

用途：

获取真实桶列表
与上传页暴露的桶列表对比

当前已确认真实桶为：

blogfile
blogimg
generalandroid
image
tmp-image
upload

6.2 查看桶大小

mc du local/blogimg
mc du local/blogfile
mc du local/image
mc du local/tmp-image
mc du local/upload

用途：

看实际占用
判断是否存在长期不用的临时桶

6.3 浏览桶目录结构

mc tree local/blogimg
mc tree local/blogfile

用途：

看对象前缀结构
判断桶用途是否清晰

6.4 查看对象样例

mc ls local/blogimg --recursive | head
mc ls local/blogfile --recursive | head

用途：

确认是否主要用于图片 / 附件
检查是否有异常对象命名

6.5 查看匿名访问策略

mc anonymous get local/blogimg
mc anonymous get local/blogfile

6.6 查看版本化状态

mc version info local/blogimg
mc version info local/blogfile

6.7 导出生命周期

mc ilm export local/blogimg
mc ilm export local/blogfile

6.8 查看桶标签

mc tag list local/blogimg
mc tag list local/blogfile

6.9 查看桶加密

mc encrypt info local/blogimg
mc encrypt info local/blogfile

6.10 查看复制规则

mc replicate ls local/blogimg
mc replicate ls local/blogfile

说明：

当前服务日志里已经出现 blogimg 的 replication 报错，因此应重点检查 blogimg。

7. 变更前备份

所有写操作前，都建议先备份当前配置。

7.1 创建备份目录

mkdir -p ~/minio-backup/$(date +%F)

7.2 备份单桶配置

以 blogimg 为例：

mc anonymous get local/blogimg > ~/minio-backup/$(date +%F)/blogimg.anonymous.txt
mc version info local/blogimg > ~/minio-backup/$(date +%F)/blogimg.version.txt
mc ilm export local/blogimg > ~/minio-backup/$(date +%F)/blogimg.lifecycle.json
mc tag list local/blogimg > ~/minio-backup/$(date +%F)/blogimg.tags.txt
mc encrypt info local/blogimg > ~/minio-backup/$(date +%F)/blogimg.encrypt.txt
mc replicate ls local/blogimg > ~/minio-backup/$(date +%F)/blogimg.replicate.txt

对 blogfile、image、tmp-image、upload 也做同样处理。

7.3 备份全部桶基础列表

mc ls local > ~/minio-backup/$(date +%F)/buckets.txt

8. 桶的创建与删除

8.1 创建桶

mc mb local/<bucket-name>

示例：

mc mb local/generalandroid

创建后验证：

mc ls local
mc stat local/generalandroid

8.2 删除空桶

mc rb local/<bucket-name>

示例：

mc rb local/tmp-image

注意：

只能删除空桶
生产桶删除前必须确认无业务引用

8.3 删除前确认

删除前至少执行：

mc ls local/<bucket-name> --recursive | head
mc du local/<bucket-name>

必要时补充：

检查仓库中是否引用该桶
检查上传页是否仍然暴露该桶

9. 匿名访问策略管理

适用于图片公开访问和附件公开下载场景。

9.1 查看当前策略

mc anonymous get local/blogimg

9.2 设置为私有

mc anonymous set private local/blogimg

9.3 设置为仅下载公开

mc anonymous set download local/blogimg

含义：

外部可读
不允许匿名写入

9.4 设置为完全公开

mc anonymous set public local/blogimg

一般不建议直接使用，除非明确需要公开列目录或其他公共能力。

9.5 变更后验证

mc anonymous get local/blogimg
curl -I https://minio.898311.xyz/blogimg/<sample-object>

建议：

图片桶优先 download
临时桶优先 private

10. 桶版本化管理

适用于：

防误删
对象历史追踪
复制与审计需求

10.1 查看版本化状态

mc version info local/blogimg

10.2 启用版本化

mc version enable local/blogimg

10.3 暂停版本化

mc version suspend local/blogimg

10.4 建议

建议：

核心业务桶可启用版本化
高频临时桶谨慎启用，避免容量增长过快

变更前后应记录：

mc version info local/blogimg

11. 生命周期管理

生命周期规则通常用于：

自动过期临时文件
控制版本化后的历史对象数量
降低存储占用

11.1 导出当前配置

mc ilm export local/tmp-image > tmp-image.lifecycle.json

11.2 导入配置

mc ilm import local/tmp-image < tmp-image.lifecycle.json

11.3 临时桶建议

对临时桶如 tmp-image，可以考虑：

对 7 天或 30 天前对象自动过期
对非当前版本对象设置更短保留期

11.4 生命周期规则变更流程

导出现有规则
拷贝成新文件修改
导入新规则
再导出确认内容一致

示例：

mc ilm export local/tmp-image > before.lifecycle.json
cp before.lifecycle.json after.lifecycle.json
# 手工编辑 after.lifecycle.json
mc ilm import local/tmp-image < after.lifecycle.json
mc ilm export local/tmp-image > verify.lifecycle.json

12. 标签管理

标签适合做轻量元数据登记。

12.1 查看标签

mc tag list local/blogimg

12.2 设置标签

mc tag set local/blogimg "purpose=blog,owner=zbc,visibility=public"

12.3 覆盖标签前注意

执行 set 前先导出当前标签，避免覆盖掉已有业务标签：

mc tag list local/blogimg > blogimg.tags.before.txt

12.4 推荐标签字段

建议最少维护：

purpose
owner
visibility
lifecycle

例如：

purpose=blog
owner=zbc
visibility=public
lifecycle=manual

13. 桶加密管理

适用于需要服务端默认加密的桶。

13.1 查看当前状态

mc encrypt info local/blogfile

13.2 启用 SSE-S3

mc encrypt set sse-s3 local/blogfile

13.3 注意事项

加密策略变更前必须先确认应用兼容性
如果涉及外部 SDK 直连，需要确认客户端读取是否正常
如果启用了 KMS，需同步确认 KMS 配置

14. 复制管理

当前日志显示：

blogimg 存在 replication 相关报错
提示远端目标离线

因此复制配置需要重点检查。

14.1 查看复制规则

mc replicate ls local/blogimg

14.2 日志中已有风险信号

systemctl status minio 中曾看到类似报错：

remote target is offline for bucket:blogimg

说明：

blogimg 可能配置了桶复制
远端复制目标当前不可达

14.3 处理建议

先做三步：

mc replicate ls local/blogimg
确认是否确实需要复制
如果需要，排查远端 alias / 网络 / 凭证

如果该复制已废弃，应评估是否清理旧规则。

15. 上传页相关维护

上传页不是桶管理工具，但会影响“前端能看到哪些桶”。

15.1 当前暴露接口

GET /upload/api/buckets
POST /upload/api/upload

15.2 影响范围

如果你新增或删除桶，仅做 mc mb/rb 还不够。

还要确认上传中间层是否：

自动读取全部桶
或只暴露白名单桶

如果是白名单模式，新增桶后前端不会自动可见。

15.3 建议做法

在新增桶后执行：

mc ls local
curl -sS https://minio.898311.xyz/upload/api/buckets
比较二者是否一致

如果不一致，说明还需要修改上传中间层配置。

补充说明：

当前已确认 generalandroid 存在于 MinIO 中，但没有暴露在上传页桶列表里。

16. 变更后校验清单

每次变更后至少执行以下校验。

16.1 桶是否存在

mc ls local

16.2 权限是否符合预期

mc anonymous get local/<bucket>

16.3 版本化是否符合预期

mc version info local/<bucket>

16.4 生命周期是否符合预期

mc ilm export local/<bucket>

16.5 标签是否符合预期

mc tag list local/<bucket>

16.6 上传页是否能看到桶

curl -sS https://minio.898311.xyz/upload/api/buckets

16.7 实际对象访问是否正常

如果是公开桶，抽样校验一个对象：

curl -I https://minio.898311.xyz/<bucket>/<object>

17. 回滚方法

17.1 匿名策略回滚

根据备份文件重新设置：

mc anonymous set private local/<bucket>

或恢复到之前记录的目标状态。

17.2 生命周期回滚

mc ilm import local/<bucket> < before.lifecycle.json

17.3 标签回滚

根据备份重新设置：

mc tag set local/<bucket> "<backup-tags>"

17.4 版本化回滚

如果只是误启用，可执行：

mc version suspend local/<bucket>

注意：

这不会删除已经产生的历史版本对象

17.5 复制回滚

复制配置回滚前，应先导出当前规则并评估影响，避免误删生产复制链路。

18. 常见问题排查

18.1 `mc alias set` 成功但 `mc ls local` 失败

检查：

systemctl status minio
ss -ltnp | rg 9000
凭证是否和 /etc/default/minio 一致

18.2 上传页能上传，但 `mc` 访问失败

说明：

上传页可能走了中间层或代理
但 mc 直连的是 MinIO 本体

优先检查：

本机 9000 监听
alias 地址是否写对
root 凭证是否正确

18.3 `mc ls local` 能看到桶，但上传页看不到

说明：

上传中间层没有暴露该桶

需要检查：

/upload/api/buckets 来源代码
上传页是否存在白名单配置

18.4 `blogimg` 复制报错

优先执行：

mc replicate ls local/blogimg

然后判断：

复制是否仍然需要
远端目标是否离线
凭证或网络是否失效

18.5 公开链接访问失败

依次检查：

桶匿名策略是否为 download 或 public
对象是否真的存在
反代是否正确转发
上传页生成的 URL 是否正确

19. 如何重新开启 MinIO Console

当前正式配置没有开启 Console。如果后续确实需要图形化管理，可按如下思路恢复。

19.1 修改环境文件

编辑：

/etc/default/minio

把：

MINIO_OPTS="--address 0.0.0.0:9000"

改成类似：

MINIO_OPTS="--address 0.0.0.0:9000 --console-address :9001"

19.2 重启服务

systemctl daemon-reload
systemctl restart minio
systemctl status minio

19.3 检查监听

ss -ltnp | rg 9001

19.4 安全建议

不要直接把 9001 暴露到公网。

推荐做法：

仅监听内网
通过受控反向代理暴露
加访问控制
必要时配 Basic Auth / IP 白名单

20. 建议的标准维护流程

后续建议固定为下面这套流程。

20.1 新增桶流程

mc mb local/<bucket>
设置匿名策略
配置版本化
配置生命周期
配置标签
更新上传页白名单或桶列表逻辑
更新仓库登记文档

20.2 变更桶配置流程

导出当前配置
执行修改
再导出校验
抽样访问对象验证
更新文档

20.3 下线桶流程

确认仓库和业务不再引用
导出配置
统计对象数量和容量
清理对象
删除桶
更新上传页
更新文档

21. 推荐维护命令速查表

21.1 连接与基础信息

mc alias set local http://127.0.0.1:9000 "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"
mc alias list
mc ping local
mc ls local

21.2 桶管理

mc mb local/<bucket>
mc rb local/<bucket>
mc stat local/<bucket>
mc du local/<bucket>
mc tree local/<bucket>

21.3 权限

mc anonymous get local/<bucket>
mc anonymous set private local/<bucket>
mc anonymous set download local/<bucket>
mc anonymous set public local/<bucket>

21.4 版本化

mc version info local/<bucket>
mc version enable local/<bucket>
mc version suspend local/<bucket>

21.5 生命周期

mc ilm export local/<bucket>
mc ilm import local/<bucket> < lifecycle.json

21.6 标签

mc tag list local/<bucket>
mc tag set local/<bucket> "key1=value1,key2=value2"

21.7 加密

mc encrypt info local/<bucket>
mc encrypt set sse-s3 local/<bucket>

21.8 复制

mc replicate ls local/<bucket>

22. 文档维护建议

建议后续在 main/blog/minio 下至少维护三份资料：

MinIO 部署现状与维护调研.md
MinIO 维护手册.md
buckets.md 或 buckets.yaml

其中：

调研文档回答“现状是什么”
维护手册回答“怎么操作”
桶清单回答“有哪些桶、谁负责、用途是什么”

23. 最终建议

当前环境下，最稳的维护路径是：

用 mc 作为标准运维入口
把每次改动都先备份再执行
把桶的业务信息沉淀到仓库文档
把上传页视为“内容上传入口”，不要把它当成“完整后台”

如果后续要进一步规范化，建议补一份：

buckets.yaml

把当前 5 个桶先登记清楚，再逐步收敛历史桶和临时桶。

Quartz 4

Explorer

MinIO 维护手册

MinIO 维护手册

1. 文档目标

2. 当前环境概况

2.1 当前服务形态

2.2 配置文件位置

2.3 当前上传页返回的桶列表

2.4 域名能否直接给 mc 使用

2.5 当前已确认的外网 MinIO API 地址

3. 维护原则

3.1 管理分层

3.2 操作顺序

3.3 凭证原则

4. 准备工作

4.1 检查 MinIO 服务状态

4.2 查看 MinIO 配置

4.3 确认 mc 已安装

5. 配置 mc 连接

5.1 建议优先使用本地地址

5.2 手工导出凭证

5.3 配置 alias

5.4 可选：调试模式

6. 日常只读巡检

6.1 列出全部桶

6.2 查看桶大小

6.3 浏览桶目录结构

6.4 查看对象样例

6.5 查看匿名访问策略

6.6 查看版本化状态

6.7 导出生命周期

6.8 查看桶标签

6.9 查看桶加密

6.10 查看复制规则

7. 变更前备份

7.1 创建备份目录

7.2 备份单桶配置

7.3 备份全部桶基础列表

8. 桶的创建与删除

8.1 创建桶

8.2 删除空桶

8.3 删除前确认

9. 匿名访问策略管理

9.1 查看当前策略

9.2 设置为私有

9.3 设置为仅下载公开

9.4 设置为完全公开

9.5 变更后验证

10. 桶版本化管理

10.1 查看版本化状态

10.2 启用版本化

10.3 暂停版本化

10.4 建议

11. 生命周期管理

11.1 导出当前配置

11.2 导入配置

11.3 临时桶建议

11.4 生命周期规则变更流程

12. 标签管理

12.1 查看标签

12.2 设置标签

12.3 覆盖标签前注意

12.4 推荐标签字段

13. 桶加密管理

13.1 查看当前状态

13.2 启用 SSE-S3

13.3 注意事项

14. 复制管理

14.1 查看复制规则

14.2 日志中已有风险信号

14.3 处理建议

15. 上传页相关维护

15.1 当前暴露接口

15.2 影响范围

15.3 建议做法

16. 变更后校验清单

16.1 桶是否存在

16.2 权限是否符合预期

16.3 版本化是否符合预期

18.1 `mc alias set` 成功但 `mc ls local` 失败

18.2 上传页能上传，但 `mc` 访问失败

18.3 `mc ls local` 能看到桶，但上传页看不到

18.4 `blogimg` 复制报错