---
title: COS HF MinIO
emoji: 🗄️
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
---

# COS_HF

在 Hugging Face Docker Space 上部署一个 **S3/COS 兼容的 MinIO 对象存储服务**，作为腾讯云 COS 的长期备份、应急溢出存储，以及其他 MVP 项目的共享对象存储。

## 重要说明：GitHub 登录 vs MinIO 凭证

本项目的核心服务是 MinIO，也就是 S3/COS 兼容对象存储。对象存储协议本身使用的是：

```text
Access Key / Secret Key 签名认证
```

因此，下面两个环境变量是 **MinIO 服务启动和 S3 API 写入所必需的内部凭证**，不是普通用户网页登录方式：

```bash
MINIO_ROOT_USER=内部 S3 Access Key
MINIO_ROOT_PASSWORD=内部 S3 Secret Key
```

如果设置：

```bash
MINIO_BROWSER=off
```

则 MinIO Web Console 默认关闭，浏览器里不会出现“管理员 + 密码”的管理后台登录页。GreatEditor、mc、AWS SDK 等客户端仍然需要使用这组 S3 凭证完成上传、同步和备份。

如果要“使用 GitHub 账号登录”，推荐放在外层访问控制完成，而不是替代 MinIO S3 凭证：

```text
方案 1：Hugging Face Space 设为 Private，浏览器访问由 Hugging Face 登录保护
方案 2：使用 Cloudflare Access + GitHub 登录保护自定义域名
方案 3：后续单独开发 /admin 管理页使用 GitHub OAuth，S3 API 仍用 Access Key / Secret Key
```

不建议把 GitHub OAuth 强行加到所有 S3 API 路径前面，否则 GreatEditor、MinIO Client、AWS SDK 等对象存储客户端会无法正常工作。

## 适用定位

推荐定位：

```text
主存储：腾讯云 COS / Cloudflare R2 / 正式对象存储
备份与应急：Hugging Face MinIO
MVP 临时存储：Hugging Face MinIO
业务数据库：PostgreSQL
缓存 / Session / 配置：KV
```

不建议把 Hugging Face MinIO 作为高并发生产主存储。它更适合作为：

```text
1. 腾讯云 COS 爆满时的临时写入目标
2. 腾讯云 COS 的周期性备份目标
3. GreatEditor / 其他 MVP 项目的低成本对象存储
4. 后续 COS 扩容后迁移回 COS 的中转仓库
```

## 项目结构

```text
.
├── Dockerfile                  # Hugging Face Docker Space 入口
├── scripts/start-minio.sh       # 启动 MinIO，并自动初始化 bucket
├── scripts/mirror-cos-minio.md  # 腾讯 COS ↔ MinIO 迁移/同步命令
├── worker/keepalive.js          # Cloudflare Worker 保活模板
├── docs/                        # 部署、安全、GitHub 登录说明
└── README.md
```

## Hugging Face 部署步骤

### 1. 创建 Hugging Face Space

创建 Docker Space，连接本仓库或直接上传本仓库文件。

建议启用 Persistent Storage，并确保数据目录挂载到：

```text
/data
```

本项目默认 MinIO 数据目录为：

```text
/data/minio
```

### 2. 配置 Space Secrets

在 Hugging Face Space 的 `Settings → Variables and secrets` 中配置：

```bash
MINIO_ROOT_USER=内部 S3 Access Key，例如 coshf_admin
MINIO_ROOT_PASSWORD=内部 S3 Secret Key，请使用强密码
MINIO_BUCKET=great-editor-backup
MINIO_REGION=us-east-1
MINIO_BROWSER=off
PUBLIC_BUCKET=1
```

可选：

```bash
MINIO_SERVER_URL=https://your-space-name.hf.space
MINIO_API_CORS_ALLOW_ORIGIN=*
```

说明：

```text
MINIO_ROOT_USER / MINIO_ROOT_PASSWORD：S3 Access Key / Secret Key，用于程序上传和同步，不是 GitHub 登录
MINIO_BUCKET：默认自动创建的 bucket
PUBLIC_BUCKET=1：设置 bucket 为匿名可读，适合图片 URL 直接访问
PUBLIC_BUCKET=0：bucket 私有，适合冷备份
MINIO_BROWSER=off：关闭 Web Console，HF 默认只暴露一个端口，优先暴露 S3 API
```

### 3. 访问健康检查

部署成功后，可以访问：

```text
https://your-space-name.hf.space/minio/health/live
https://your-space-name.hf.space/minio/health/ready
```

Cloudflare Worker 保活建议定时访问：

```text
/minio/health/live
```

## Private 部署建议

如果这个 Space 主要作为冷备份：

```text
HF Space Visibility：Private
PUBLIC_BUCKET=0
MINIO_BROWSER=off
```

这样浏览器访问由 Hugging Face 自己的登录体系保护。你可以使用 Hugging Face 账号登录；如果你的 Hugging Face 账号绑定了 GitHub，也可以通过 GitHub 方式进入 Hugging Face。

如果这个 Space 要临时承接 GreatEditor 图片访问：

```text
HF Space Visibility：Public
PUBLIC_BUCKET=1
MINIO_BROWSER=off
```

这样图片 URL 可以被浏览器直接读取，写入仍然需要 MinIO S3 凭证。

## S3 / COS 兼容连接参数

给 GreatEditor 或其他 MVP 应用使用时，可以配置为：

```bash
S3_ENDPOINT=https://your-space-name.hf.space
S3_ACCESS_KEY_ID=MINIO_ROOT_USER 的值
S3_SECRET_ACCESS_KEY=MINIO_ROOT_PASSWORD 的值
S3_BUCKET=great-editor-backup
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true
```

MinIO 的 URL 通常是 path-style：

```text
https://your-space-name.hf.space/great-editor-backup/path/to/file.jpg
```

## 腾讯 COS 与 MinIO 同步

推荐使用 MinIO Client `mc` 做同步。详见：

```text
scripts/mirror-cos-minio.md
```

典型命令：

```bash
mc alias set cos https://cos.ap-guangzhou.myqcloud.com "$COS_SECRET_ID" "$COS_SECRET_KEY"
mc alias set hfminio https://your-space-name.hf.space "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD"

# COS -> HF MinIO 备份
mc mirror --overwrite cos/your-cos-bucket hfminio/great-editor-backup

# HF MinIO -> COS 恢复
mc mirror --overwrite hfminio/great-editor-backup cos/your-cos-bucket
```

## 与 GreatEditor 的集成建议

建议后续在 GreatEditor 中增加统一存储抽象：

```text
STORAGE_PROVIDER=cos | s3 | r2 | hf_minio
```

当腾讯 COS 空间不足时，临时切换：

```text
STORAGE_PROVIDER=hf_minio
```

当腾讯 COS 扩容完成后，执行 MinIO → COS 同步，再切回：

```text
STORAGE_PROVIDER=cos
```

## 重要风险

Hugging Face Space + MinIO 不等于正式云对象存储，存在以下风险：

```text
1. Space 可能重启、冷启动或被限流
2. 单节点 MinIO 不具备高可用
3. 大量公网图片访问可能不适合 HF 流量模型
4. 需要自行负责备份、迁移和访问控制
5. MinIO 许可证为 AGPLv3，商业闭源集成需注意合规
```

因此，本项目推荐作为备份、应急、MVP 低成本存储，不建议一开始替代正式 COS/R2。