# MinIO mc 指令筆記
## 先建立畫面：mc 就是雲端版的 ls / cp / rm
mc 把你熟悉的 `ls`、`cp`、`rm`、`find` 搬到 MinIO 上，指令名稱幾乎一樣，差別只在路徑前面多一段「alias」，用來告訴 mc 要連哪一台伺服器。
想像你的檔案系統多了一個資料夾叫 `local`：`local/mybucket/photos/a.jpg` 就像 `/mybucket/photos/a.jpg`，只是這顆「磁碟」其實住在 MinIO 裡。本機路徑（`./photos`）和遠端路徑（`local/mybucket/photos`）可以混著寫，mc 會依方向自己判斷是上傳、下載，還是伺服器內複製。
| 你熟悉的 | mc 對應 | 用途 |
| --- | --- | --- |
| `ls` | `mc ls` | 列出 bucket / 物件 |
| `cp -r` | `mc cp --recursive` | 複製（上傳、下載） |
| `rsync` | `mc mirror` | 同步兩邊的資料夾 |
| `rm -r` | `mc rm --recursive --force` | 刪除 |
| `find` | `mc find` | 依名稱、大小、時間搜尋 |
| `du` | `mc du` | 看用量 |
| `tree` | `mc tree` | 樹狀列出 |
| `cat` | `mc cat` | 直接印物件內容 |
| `diff` | `mc diff` | 比較兩邊差異 |
## 連線設定：alias 只要設一次
alias 就是「伺服器的暱稱」，設好之後每個指令都用暱稱開頭，不用再打網址和金鑰。
```bash
# 設定（名稱自訂，這裡叫 local）
mc alias set local http://localhost:9000 <ACCESS_KEY> <SECRET_KEY>
# 查看 / 移除
mc alias list
mc alias remove local
# 驗證連線（需要 admin 權限）
mc admin info local
```
設定會寫進 `~/.mc/config.json`，secret key 是明文，要注意這個檔案的權限。
如果不想留下設定檔（例如 CI、臨時機器），改用環境變數，格式是 `MC_HOST_<alias>`：
```bash
export MC_HOST_local=http://ACCESS_KEY:SECRET_KEY@localhost:9000
mc ls local
```
連 HTTPS 但用自簽憑證時，在指令後加 `--insecure`。注意 alias 要指向 API 埠（預設 9000），不是 Web Console 的 9001。
## Bucket 與物件的基本操作
bucket 像最上層的資料夾，物件就是裡面的檔案；`photos/2026/a.jpg` 裡的斜線只是名稱的一部分，MinIO 並沒有真的資料夾。
```bash
mc mb local/mybucket # 建立 bucket
mc mb --ignore-existing local/mybucket # 已存在就略過，不報錯
mc ls local # 列出所有 bucket
mc ls local/mybucket/ # 列出 bucket 的第一層
mc ls --recursive local/mybucket # 連子目錄一起列
mc stat local/mybucket/a.jpg # 看大小、ETag、metadata
mc cat local/mybucket/notes.txt # 直接印出內容
mc rb local/mybucket # 刪除 bucket（必須是空的）
mc rb --force local/mybucket # 連裡面的物件一起刪，無法復原
```
## 上傳與下載：cp 與 mirror
先想一個情境：本機有 `./my-folder`，裡面是 `a.txt` 和 `sub/b.txt`，要放進 `mybucket`。
**cp --recursive：一次性搬運。** 路徑結尾有沒有 `/`，決定資料夾本身會不會多包一層：
```bash
# 來源有斜線：只搬「內容」
mc cp --recursive ./my-folder/ local/mybucket/backup/
# → backup/a.txt、backup/sub/b.txt
# 來源沒斜線：連資料夾名稱一起搬
mc cp --recursive ./my-folder local/mybucket/backup/
# → backup/my-folder/a.txt、backup/my-folder/sub/b.txt
```
不確定結果長怎樣，傳完立刻用 `mc ls --recursive local/mybucket/backup/` 看一眼，比事後找檔案快。
其他方向都是同一個指令，只是來源與目的對調：
```bash
mc cp ./a.txt local/mybucket/ # 單檔上傳
mc cp --recursive local/mybucket/backup/ ./restore/ # 整個下載
mc cp local/bucket1/a.txt local/bucket2/ # 伺服器內複製，資料不經過本機
```
**mirror：反覆同步。** 如果這個資料夾每天都會有新檔案，用 `mirror` 比 `cp` 合適，它會比對兩邊，只處理有差異的部分：
```bash
mc mirror ./my-folder local/mybucket/my-folder # 本機 → MinIO
mc mirror local/mybucket/my-folder ./my-folder # MinIO → 本機
mc mirror --dry-run ./my-folder local/mybucket/my-folder # 只預覽，不動手
mc mirror --overwrite ./my-folder local/mybucket/my-folder # 已存在但內容不同 → 覆蓋
mc mirror --remove ./my-folder local/mybucket/my-folder # 目標端多出來的檔案刪掉
mc mirror --watch ./my-folder local/mybucket/my-folder # 持續監看，有變動就同步
mc mirror --exclude "*.tmp" ./my-folder local/mybucket/my-folder
```
`--remove` 會讓目標端變得跟來源一模一樣，包含刪檔，第一次用請先加 `--dry-run` 看清單。
簡單的判斷法：只做一次、想保留目標端原有檔案 → `cp -r`；要長期保持兩邊一致 → `mirror`。
## 查詢與檢視：find、tree、du、diff
傳完之後想確認內容、找特定檔案、看吃了多少空間，都靠這幾個：
```bash
mc tree local/mybucket # 樹狀結構
mc du local/mybucket # 總用量
mc find local/mybucket --name "*.jpg" # 依檔名
mc find local/mybucket --larger 100MB # 大於 100MB 的物件
mc find local/mybucket --older-than 30d # 超過 30 天沒動的物件
mc diff ./my-folder local/mybucket/my-folder # 比較本機與 MinIO 差在哪
```
`mc diff` 很適合在 `mirror --remove` 之前跑一次，先看兩邊到底差哪些檔案。
## 刪除與清理
`mc rm` 刪資料夾時一定要加 `--recursive --force`，少了 `--force` 它會拒絕執行，這是故意設計來擋手滑的。
```bash
mc rm local/mybucket/a.jpg # 刪單一物件
mc rm --recursive --force local/mybucket/old-folder/ # 刪整個「資料夾」
mc rm --recursive --force --older-than 30d local/mybucket/logs/ # 只刪超過 30 天的
```
刪之前先用同樣條件的 `mc find` 列出會命中的物件，確認清單沒問題再換成 `rm`：
```bash
mc find local/mybucket/logs/ --older-than 30d
```
如果 bucket 有開 versioning，`rm` 只是加上一個 delete marker，舊版本還在；要真正清掉要加 `--versions`。
## 分享與權限
三種層次，從輕到重：給一次性連結、開放匿名存取、建立帳號授權。
**1. 產生暫時連結（presigned URL）**，對方不需要帳號，期限內拿連結就能下載或上傳，最長 7 天：
```bash
mc share download --expire 2h local/mybucket/a.jpg
mc share upload --expire 1h local/mybucket/inbox/
```
**2. 開放匿名存取**，整個路徑對所有人公開，要小心使用：
```bash
mc anonymous set download local/mybucket/public # 匿名可下載
mc anonymous get local/mybucket/public # 查看目前設定
mc anonymous set none local/mybucket/public # 關閉
```
**3. 建立使用者並授權**，內建 policy 有 `readonly`、`readwrite`、`writeonly`、`consoleAdmin`：
```bash
mc admin user add local alice <password>
mc admin policy attach local readwrite --user alice
mc admin user list local
# 給程式用的 access key（不用綁真人帳號）
mc admin user svcacct add local alice
```
指令名稱在不同 mc 版本有改過：舊版的 `mc policy` 現在是 `mc anonymous`，舊版的 `mc admin policy set` 現在是 `mc admin policy attach`。遇到 `command not found` 先用 `mc --version` 和 `mc admin policy --help` 對照。
## 常見坑與速查表
實際用起來最常踩到的幾個：
- **結尾斜線**：`cp -r` 的來源有沒有 `/`，決定會不會多包一層資料夾，傳完先 `mc ls -r` 確認。
- **連錯埠**：alias 要指向 API 埠 9000，Web Console 的 9001 連不上 mc。
- **MinIO 在 k3s / Docker 裡**：`localhost:9000` 要先有 port-forward 或 port mapping，否則 alias 設定成功但指令會逾時。
- **mirror --remove**：會刪掉目標端多餘的檔案，先 `--dry-run`。
- **檔名含空白或中文**：路徑一律用引號包起來。
- **不熟的指令**：`mc <指令> --help` 的範例最準，比搜尋文件快，也不會遇到版本不符。
速查表：
| 想做的事 | 指令 |
| --- | --- |
| 設定連線 | `mc alias set local <URL> <KEY> <SECRET>` |
| 建 bucket | `mc mb local/mybucket` |
| 上傳資料夾（一次性） | `mc cp -r ./dir/ local/mybucket/dir/` |
| 同步資料夾 | `mc mirror --overwrite ./dir local/mybucket/dir` |
| 下載資料夾 | `mc cp -r local/mybucket/dir/ ./dir/` |
| 列出全部物件 | `mc ls -r local/mybucket` |
| 看用量 | `mc du local/mybucket` |
| 搜尋物件 | `mc find local/mybucket --name "*.log"` |
| 刪資料夾 | `mc rm -r --force local/mybucket/dir/` |
| 產生下載連結 | `mc share download --expire 2h local/mybucket/a.jpg` |
| 建使用者並授權 | `mc admin user add` + `mc admin policy attach` |