MinIO 相关内容解析

MinIO 相关内容解析

对，你理解得基本正确。你说的应该是 MinIO ，它就是一个非常常见的对象存储（Object Storage）服务，可以用来存储文件。

简单来说：

MinIO ≈ 自己部署的"类似 Amazon S3 的文件对象存储服务"

1. MinIO 是干什么的？

比如你的后端系统需要保存：

用户上传的头像
PDF
Word
Excel
图片
视频
音频
AI生成的文件
知识库文档
聊天附件

你可以直接存到服务器磁盘：

/data/uploads/
    ├── a.pdf
    ├── b.jpg
    └── c.docx

但是大型项目通常不会让业务代码直接管理这些文件，而是使用对象存储：

                ┌──────────────┐
                │   FastAPI    │
                │    后端      │
                └──────┬───────┘
                       │
                       │ 上传文件
                       ▼
                ┌──────────────┐
                │    MinIO     │
                │ Object Store │
                └──────┬───────┘
                       │
                       ▼
                ┌──────────────┐
                │    磁盘      │
                │ /data/minio  │
                └──────────────┘

---

2. MinIO 里面不是简单的"文件夹"

MinIO 使用的是 Bucket + Object 的概念。

例如：

Bucket: manus-files

Objects:
    users/10001/avatar.jpg
    documents/test.pdf
    documents/report.docx
    images/abc.png

可以理解成：

MinIO
│
├── manus-files       ← Bucket
│   ├── users/10001/avatar.jpg
│   ├── documents/test.pdf
│   └── images/abc.png
│
└── backup            ← Bucket
    ├── db/xxx.sql
    └── ...

虽然看起来像目录，但 users/10001/avatar.jpg 本质上是 Object Key。

---

3. 它和 PostgreSQL 是不同的东西

你最近正在配置的：

PostgreSQL
Redis
FastAPI

如果再加入 MinIO，通常职责是：

服务	主要作用
PostgreSQL	存业务数据
Redis	缓存、队列、临时数据
MinIO	存文件
FastAPI	提供业务 API

例如用户上传一个 PDF：

                    用户
                     │
                     │ 上传 PDF
                     ▼
                  FastAPI
                 /       \
                /         \
               ▼           ▼
        PostgreSQL       MinIO
        文件信息          PDF文件
        ─────────         ────────
        id                xxx.pdf
        filename          xxx.docx
        size
        minio_key

PostgreSQL 一般不直接存 PDF 二进制内容，而是保存文件的元数据，例如：

id = 123
filename = "测试报告.pdf"
size = 1024000
object_key = "documents/123/test.pdf"

真正的 PDF 放在 MinIO。

---

4. MinIO 和阿里云 OSS / AWS S3 是什么关系？

它们属于同一类东西：

对象存储
│
├── AWS S3
├── MinIO
├── 阿里云 OSS
├── 腾讯云 COS
├── 华为云 OBS
└── 七牛云 Kodo

其中 MinIO 最大的特点之一就是：

可以自己部署，不需要把文件交给云厂商。

例如你自己的服务器：

192.168.8.221

可以部署：

FastAPI       : 8000
PostgreSQL    : 5432
Redis         : 6379
MinIO API     : 9000
MinIO Console : 9001

然后：

FastAPI
   │
   │ S3 API
   ▼
MinIO :9000
   │
   ▼
/data/minio/

---

5. MinIO 有两个常见端口

如果你用 Docker 部署，经常看到：

-p 9000:9000
-p 9001:9001

通常：

9000 → MinIO S3 API
9001 → MinIO Web Console

也就是说：

浏览器
   │
   ▼
http://服务器IP:9001
   │
   ▼
MinIO 管理界面

而程序一般访问：

http://服务器IP:9000

---

6. 为什么 AI 项目特别喜欢 MinIO？

你现在做的 FastAPI + AI + 知识库/MCP/Manus 这类项目，非常容易用到 MinIO。

例如：

用户上传
    │
    ├── PDF
    ├── Word
    ├── Excel
    ├── 图片
    ├── 音频
    └── 视频
         │
         ▼
       MinIO
         │
         ├── 原始文件
         │
         └── 文件URL/Object Key
                  │
                  ▼
              AI处理
             /       \
            ▼         ▼
         OCR/ASR     文档解析
                       │
                       ▼
                    向量数据库

所以如果你在看 MoocManus / Manus / FastAPI 项目的 Docker Compose，看到：

minio:

一般就是在解决：

这个项目需要一个地方统一存放用户上传和系统生成的文件。

---

7. 一句话理解

你可以把它记成：

PostgreSQL = 数据库
Redis      = 缓存
MinIO      = 文件仓库
FastAPI    = 后端服务

或者更准确一点：

MinIO 是一个兼容 S3 API 的高性能对象存储服务，适合自建，用来集中存储图片、文档、音视频、模型文件等非结构化数据。

有，而且 MinIO 非常适合用 Docker 部署 。如果你现在是在搭建类似你前面 PostgreSQL + Redis + FastAPI 的项目，可以直接把 MinIO 加进去。

1. 最简单的 Docker 部署

推荐先用这个方式测试：

docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin123 \
  -v /data/minio:/data \
  minio/minio:latest \
  server /data --console-address ":9001"

这里：

9000 → MinIO API
9001 → MinIO Web 管理界面
/data/minio → 宿主机实际存储文件的位置

启动后：

MinIO API:
http://服务器IP:9000

MinIO Console:
http://服务器IP:9001

浏览器打开：

http://服务器IP:9001

然后使用：

用户名：minioadmin
密码：minioadmin123

---

2. 查看 MinIO 是否启动成功

docker ps | grep minio

查看日志：

docker logs -f minio

如果看到类似：

API: http://0.0.0.0:9000
Console: http://0.0.0.0:9001

基本就启动成功了。

---

3. Docker Compose 部署

如果你的项目本身就是 Docker Compose，我更推荐这种。

services:

  minio:
    image: minio/minio:latest
    container_name: manus-minio
    restart: unless-stopped

    ports:
      - "9000:9000"
      - "9001:9001"

    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin123

    volumes:
      - /data/minio:/data

    command: server /data --console-address ":9001"

然后：

docker compose up -d minio

查看：

docker compose ps

日志：

docker compose logs -f minio

停止：

docker compose stop minio

删除容器：

docker compose down

---

4. MinIO 最核心的概念

你需要记住三个东西：

MinIO
  │
  └── Bucket
        │
        ├── Object
        ├── Object
        └── Object

例如创建一个：

Bucket: manus-files

里面放：

manus-files/
├── user/
│   └── 10001/
│       └── avatar.jpg
│
├── documents/
│   ├── test.pdf
│   └── report.docx
│
└── images/
    └── xxx.png

---

5. 使用 MinIO Web 管理界面

启动之后访问：

http://服务器IP:9001

你可以在 Web 页面里面：

Buckets
   ↓
Create Bucket
   ↓
manus-files

然后上传文件。

这是最简单的使用方式。

---

6. 命令行使用

MinIO 官方命令行工具叫：

mc

也就是：

MinIO Client

例如配置一个 MinIO：

mc alias set local http://127.0.0.1:9000 minioadmin minioadmin123

查看 Bucket：

mc ls local

创建 Bucket：

mc mb local/manus-files

查看：

mc ls local/manus-files

上传：

mc cp test.pdf local/manus-files/

下载：

mc cp local/manus-files/test.pdf ./

删除：

mc rm local/manus-files/test.pdf

---

7. Python + MinIO

这个对你目前的 FastAPI 项目尤其重要。

Python 可以使用：

pip install minio

然后：

from minio import Minio

client = Minio(
    "127.0.0.1:9000",
    access_key="minioadmin",
    secret_key="minioadmin123",
    secure=False,
)

创建 Bucket：

bucket_name = "manus-files"

if not client.bucket_exists(bucket_name):
    client.make_bucket(bucket_name)

上传文件：

client.fput_object(
    bucket_name,
    "documents/test.pdf",
    "/tmp/test.pdf",
)

下载：

client.fget_object(
    bucket_name,
    "documents/test.pdf",
    "/tmp/download.pdf",
)

---

8. FastAPI 中通常怎么用？

例如：

from fastapi import FastAPI, UploadFile, File
from minio import Minio
import uuid

app = FastAPI()

minio_client = Minio(
    "minio:9000",  # Docker Compose 中使用服务名
    access_key="minioadmin",
    secret_key="minioadmin123",
    secure=False,
)

BUCKET = "manus-files"


@app.post("/upload")
async def upload(file: UploadFile = File(...)):

    object_name = f"uploads/{uuid.uuid4()}_{file.filename}"

    minio_client.put_object(
        BUCKET,
        object_name,
        file.file,
        length=-1,
        part_size=10 * 1024 * 1024,
    )

    return {
        "filename": file.filename,
        "object_name": object_name,
    }

这里有一个非常重要的区别。

如果：

FastAPI 在宿主机运行

可能使用：

127.0.0.1:9000

如果：

FastAPI 和 MinIO 都在 Docker Compose

则应该使用：

minio:9000

而不是：

127.0.0.1:9000

因为 Docker Compose 内部通过：

service name

进行容器间通信。

---

9. PostgreSQL + Redis + MinIO + FastAPI

你现在这个项目其实可以形成一个非常典型的架构：

                    ┌──────────────┐
                    │    用户      │
                    └──────┬───────┘
                           │
                           ▼
                    ┌──────────────┐
                    │   FastAPI    │
                    │    :8000     │
                    └─────┬────────┘
                          │
             ┌────────────┼────────────┐
             │            │            │
             ▼            ▼            ▼
       ┌──────────┐ ┌──────────┐ ┌──────────┐
       │PostgreSQL│ │  Redis   │ │  MinIO   │
       │  :5432   │ │  :6379   │ │  :9000   │
       └──────────┘ └──────────┘ └──────────┘
                                      │
                                      ▼
                              文件 / 图片 / PDF

职责非常清晰：

PostgreSQL
    ↓
用户、订单、任务、文件元数据等结构化数据

Redis
    ↓
缓存、队列、Session、临时数据

MinIO
    ↓
PDF、Word、Excel、图片、音频、视频等文件

FastAPI
    ↓
业务逻辑和 API

---

10. 一个实际项目的 .env

建议不要把密码直接写死在 docker-compose.yml：

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=your_strong_password
MINIO_BUCKET=manus-files

Compose：

services:
  minio:
    image: minio/minio:latest
    container_name: manus-minio
    restart: unless-stopped

    ports:
      - "9000:9000"
      - "9001:9001"

    env_file:
      - .env

    volumes:
      - /data/minio:/data

    command: server /data --console-address ":9001"

然后：

docker compose up -d

---

⚠️ 一个生产环境注意点

如果只是本地开发/测试，上面的配置完全可以。

如果是正式生产环境，建议进一步考虑：

• 不直接暴露 9000/9001 到公网
• 使用 HTTPS
• 设置强密码
• 配置 Bucket 权限
• 定期备份
• 不要让应用使用 root Access Key
• 根据需要配置反向代理

可以。结合你前面 MoocManus 的配置，我建议直接使用下面这份，包含 PostgreSQL + Redis + MinIO、数据持久化、健康检查，以及统一的网络配置。

完整 docker-compose.yml

services:

  # =========================
  # PostgreSQL
  # =========================
  postgres:
    image: postgres:16
    container_name: manus-postgres
    restart: unless-stopped

    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: manus
      TZ: Asia/Shanghai

    ports:
      - "5432:5432"

    volumes:
      - manus_postgres_data:/var/lib/postgresql/data

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d manus"]
      interval: 10s
      timeout: 5s
      retries: 5

    networks:
      - manus-network


  # =========================
  # Redis
  # =========================
  redis:
    image: redis:7
    container_name: manus-redis
    restart: unless-stopped

    command: redis-server --appendonly yes

    ports:
      - "6379:6379"

    volumes:
      - manus_redis_data:/data

    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

    networks:
      - manus-network


  # =========================
  # MinIO
  # =========================
  minio:
    image: minio/minio:latest
    container_name: manus-minio
    restart: unless-stopped

    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin123
      TZ: Asia/Shanghai

    ports:
      # MinIO S3 API
      - "9000:9000"

      # MinIO Web Console
      - "9001:9001"

    volumes:
      - manus_minio_data:/data

    command: server /data --console-address ":9001"

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 10s
      timeout: 5s
      retries: 5

    networks:
      - manus-network


# =========================
# 数据持久化
# =========================
volumes:

  manus_postgres_data:
    name: manus_postgres_data

  manus_redis_data:
    name: manus_redis_data

  manus_minio_data:
    name: manus_minio_data


# =========================
# Docker 网络
# =========================
networks:

  manus-network:
    name: manus-network
    driver: bridge

1. 保存文件

例如：

mkdir -p /data/manus
cd /data/manus

vim docker-compose.yml

把上面的内容保存进去。

然后启动：

docker compose up -d

查看：

docker compose ps

正常情况下应该看到：

NAME              STATUS
manus-postgres    Up
manus-redis       Up
manus-minio       Up

---

2. 三个服务怎么连接

这是非常重要的一点。

因为三个容器都加入了：

networks:
  - manus-network

所以容器之间可以直接使用 服务名通信。

PostgreSQL

在其他 Docker 容器中：

postgresql+asyncpg://postgres:postgres@postgres:5432/manus

注意这里不是：

localhost

而是：

postgres

因为：

postgres:

就是 PostgreSQL 的 Docker 服务名。

---

Redis

其他 Docker 容器连接：

redis://redis:6379/0

这里：

redis

就是 Redis 的服务名。

---

MinIO

其他 Docker 容器连接：

http://minio:9000

例如 Python：

from minio import Minio

client = Minio(
    "minio:9000",
    access_key="minioadmin",
    secret_key="minioadmin123",
    secure=False,
)

---

3. 如果 FastAPI 在宿主机运行

如果你的 FastAPI 不是 Docker 容器，而是直接：

uv run ...

或者：

python ...

那么连接地址应该改成：

PostgreSQL

postgresql+asyncpg://postgres:postgres@127.0.0.1:5432/manus

Redis

redis://127.0.0.1:6379/0

MinIO

127.0.0.1:9000

所以可以简单记：

FastAPI 在 Docker 内
    ↓
postgres:5432
redis:6379
minio:9000


FastAPI 在宿主机
    ↓
127.0.0.1:5432
127.0.0.1:6379
127.0.0.1:9000

---

4. PostgreSQL 测试

进入容器：

docker exec -it manus-postgres psql -U postgres -d manus

进入以后：

\l

查看数据库。

\dt

查看表。

退出：

\q

也可以直接：

docker exec manus-postgres pg_isready -U postgres -d manus

正常会看到：

/var/run/postgresql:5432 - accepting connections

---

5. Redis 测试

直接：

docker exec -it manus-redis redis-cli

然后：

PING

应该返回：

PONG

测试写入：

SET name manus

然后：

GET name

返回：

"manus"

退出：

exit

---

6. MinIO 测试

浏览器访问：

http://服务器IP:9001

登录：

用户名：
minioadmin

密码：
minioadmin123

进入以后可以创建：

manus-files

这样的 Bucket。

MinIO 的 API 地址是：

http://服务器IP:9000

例如你的服务器是：

192.168.8.221

那么：

MinIO Console:
http://192.168.8.221:9001

MinIO API:
http://192.168.8.221:9000

---

7. 查看 Docker 数据卷

docker volume ls | grep manus

应该看到：

manus_minio_data
manus_postgres_data
manus_redis_data

查看：

docker volume inspect manus_postgres_data

---

8. 停止和重新启动

停止：

docker compose stop

重新启动：

docker compose start

或者：

docker compose up -d

删除容器，但保留数据：

docker compose down

然后再次：

docker compose up -d

数据依然存在。

---

⚠️ 不要随便执行这个

docker compose down -v

-v 会删除：

manus_postgres_data
manus_redis_data
manus_minio_data

也就是可能把你的：

PostgreSQL 数据
Redis 持久化数据
MinIO 文件

全部删掉。

---

9. 推荐你的 .env

正式一点，可以把密码独立出来：

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=manus

MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=minioadmin123

然后 Compose 改成：

environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}

MinIO：

environment:
  MINIO_ROOT_USER: ${MINIO_ROOT_USER}
  MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}

这样以后改密码不用修改 Compose 文件。

---

最终结构

你的项目可以整理成：

/data/manus/
│
├── docker-compose.yml
├── .env
│
└── Docker
    │
    ├── manus-postgres
    │      └── manus_postgres_data
    │
    ├── manus-redis
    │      └── manus_redis_data
    │
    └── manus-minio
           └── manus_minio_data

然后你的 FastAPI 配置可以对应：

PostgreSQL
postgresql+asyncpg://postgres:postgres@postgres:5432/manus

Redis
redis://redis:6379/0

MinIO
http://minio:9000

这套结构很适合你现在的 MoocManus + FastAPI + SQLAlchemy AsyncSession + Redis + 文件存储架构。