Spaces:
Running
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 兼容对象存储。对象存储协议本身使用的是： | |
| ```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。 |