Spaces:
Running
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 兼容对象存储。对象存储协议本身使用的是：
Access Key / Secret Key 签名认证
因此，下面两个环境变量是 MinIO 服务启动和 S3 API 写入所必需的内部凭证，不是普通用户网页登录方式：
MINIO_ROOT_USER=内部 S3 Access Key
MINIO_ROOT_PASSWORD=内部 S3 Secret Key
如果设置：
MINIO_BROWSER=off
则 MinIO Web Console 默认关闭，浏览器里不会出现“管理员 + 密码”的管理后台登录页。GreatEditor、mc、AWS SDK 等客户端仍然需要使用这组 S3 凭证完成上传、同步和备份。
如果要“使用 GitHub 账号登录”，推荐放在外层访问控制完成，而不是替代 MinIO S3 凭证：
方案 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 等对象存储客户端会无法正常工作。
适用定位
推荐定位：
主存储：腾讯云 COS / Cloudflare R2 / 正式对象存储
备份与应急：Hugging Face MinIO
MVP 临时存储：Hugging Face MinIO
业务数据库：PostgreSQL
缓存 / Session / 配置：KV
不建议把 Hugging Face MinIO 作为高并发生产主存储。它更适合作为：
1. 腾讯云 COS 爆满时的临时写入目标
2. 腾讯云 COS 的周期性备份目标
3. GreatEditor / 其他 MVP 项目的低成本对象存储
4. 后续 COS 扩容后迁移回 COS 的中转仓库
项目结构
.
├── 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，并确保数据目录挂载到：
/data
本项目默认 MinIO 数据目录为：
/data/minio
2. 配置 Space Secrets
在 Hugging Face Space 的 Settings → Variables and secrets 中配置：
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
可选：
MINIO_SERVER_URL=https://your-space-name.hf.space
MINIO_API_CORS_ALLOW_ORIGIN=*
说明：
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. 访问健康检查
部署成功后，可以访问：
https://your-space-name.hf.space/minio/health/live
https://your-space-name.hf.space/minio/health/ready
Cloudflare Worker 保活建议定时访问：
/minio/health/live
Private 部署建议
如果这个 Space 主要作为冷备份：
HF Space Visibility：Private
PUBLIC_BUCKET=0
MINIO_BROWSER=off
这样浏览器访问由 Hugging Face 自己的登录体系保护。你可以使用 Hugging Face 账号登录；如果你的 Hugging Face 账号绑定了 GitHub，也可以通过 GitHub 方式进入 Hugging Face。
如果这个 Space 要临时承接 GreatEditor 图片访问：
HF Space Visibility：Public
PUBLIC_BUCKET=1
MINIO_BROWSER=off
这样图片 URL 可以被浏览器直接读取，写入仍然需要 MinIO S3 凭证。
S3 / COS 兼容连接参数
给 GreatEditor 或其他 MVP 应用使用时，可以配置为：
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：
https://your-space-name.hf.space/great-editor-backup/path/to/file.jpg
腾讯 COS 与 MinIO 同步
推荐使用 MinIO Client mc 做同步。详见：
scripts/mirror-cos-minio.md
典型命令：
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 中增加统一存储抽象：
STORAGE_PROVIDER=cos | s3 | r2 | hf_minio
当腾讯 COS 空间不足时，临时切换：
STORAGE_PROVIDER=hf_minio
当腾讯 COS 扩容完成后，执行 MinIO → COS 同步，再切回：
STORAGE_PROVIDER=cos
重要风险
Hugging Face Space + MinIO 不等于正式云对象存储，存在以下风险：
1. Space 可能重启、冷启动或被限流
2. 单节点 MinIO 不具备高可用
3. 大量公网图片访问可能不适合 HF 流量模型
4. 需要自行负责备份、迁移和访问控制
5. MinIO 许可证为 AGPLv3，商业闭源集成需注意合规
因此，本项目推荐作为备份、应急、MVP 低成本存储，不建议一开始替代正式 COS/R2。