Upload 7 files

Dockerfile

@@ -0,0 +1,31 @@
+FROM debian:bookworm-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV MINIO_DATA_DIR=/data/minio
+ENV MINIO_BUCKET=great-editor-backup
+ENV MINIO_REGION=us-east-1
+ENV MINIO_BROWSER=off
+ENV PUBLIC_BUCKET=1
+ENV PORT=7860
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates curl tini \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -fsSL https://dl.min.io/server/minio/release/linux-amd64/minio -o /usr/local/bin/minio \
+    && chmod +x /usr/local/bin/minio \
+    && curl -fsSL https://dl.min.io/client/mc/release/linux-amd64/mc -o /usr/local/bin/mc \
+    && chmod +x /usr/local/bin/mc
+
+WORKDIR /app
+COPY scripts/start-minio.sh /app/start-minio.sh
+RUN chmod +x /app/start-minio.sh \
+    && mkdir -p /data/minio
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=60s --timeout=10s --start-period=30s --retries=3 \
+  CMD curl -fsS http://127.0.0.1:7860/minio/health/live || exit 1
+
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["/app/start-minio.sh"]

README.md

@@ -1,10 +1,238 @@
 ---
-title: COS HF
-emoji: 📈
+title: COS HF MinIO
+emoji: 🗄️
 colorFrom: blue
-colorTo: gray
+colorTo: green
 sdk: docker
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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。

docs/GITHUB_LOGIN_AND_PRIVATE_DEPLOYMENT.md

@@ -0,0 +1,170 @@
+# GitHub 登录与 Private 部署说明
+
+本项目是 MinIO / S3 兼容对象存储服务，不是普通 Web 应用。登录方式需要区分两类访问：
+
+```text
+1. 浏览器访问：人打开网页、查看控制台、健康检查
+2. S3 API 访问：GreatEditor / mc / SDK 上传、下载、同步文件
+```
+
+## 结论
+
+不建议把 GitHub OAuth 登录直接加在 MinIO S3 API 前面。
+
+原因是 S3 客户端使用的是 Access Key / Secret Key 签名认证，而 GitHub OAuth 是浏览器交互登录。两者认证机制不同。如果在 S3 API 前强行加 GitHub 登录，会导致 GreatEditor、MinIO Client `mc`、AWS SDK 等无法正常请求。
+
+因此推荐以下部署策略：
+
+```text
+生产主存储：腾讯 COS / Cloudflare R2
+HF MinIO：备份、应急、MVP 临时对象存储
+HF MinIO 写入权限：MinIO Access Key / Secret Key
+HF MinIO 访问范围：由 Space 可见性、bucket policy、S3 key 权限控制
+```
+
+## 什么是 Private 部署
+
+这里的 Private 部署有两层含义：
+
+### 1. GitHub 仓库 Private
+
+`CaPaCaptain/COS_HF` 可以保持 GitHub Private。这样源码和部署配置不公开。
+
+如果 Hugging Face 不能直接关联 GitHub Private 仓库，可以选择：
+
+```text
+1. 临时设为 Public，部署成功后再转回 Private
+2. 手动把文件上传到 Hugging Face Space 仓库
+3. 使用 Hugging Face 自己的 Space Git 仓库作为部署仓库
+```
+
+### 2. Hugging Face Space Private
+
+如果 Hugging Face Space 设置为 Private，则普通浏览器访问需要 Hugging Face 账号权限。
+
+这适合：
+
+```text
+1. 冷备份
+2. 内部应急存储
+3. 不需要公开图片 URL 的场景
+```
+
+但不适合：
+
+```text
+1. GreatEditor 直接把图片 URL 展示给公网用户
+2. 需要浏览器匿名加载图片缩略图
+3. 需要第三方 S3 客户端无 HF 登录访问
+```
+
+原因是 Private Space 的访问会被 Hugging Face 登录层拦截，普通图片 URL 和 S3 SDK 请求可能无法像公开对象存储一样直接工作。
+
+## 推荐部署模式
+
+### 模式 A：Public Space + MinIO 私有写权限（推荐给 MVP / 应急）
+
+```text
+Hugging Face Space：Public
+MINIO_ROOT_USER / MINIO_ROOT_PASSWORD：保密
+PUBLIC_BUCKET=1 或 0 按需求选择
+```
+
+特点：
+
+```text
+1. GreatEditor / mc / SDK 可以正常使用 S3 API
+2. 写入仍然需要 MinIO key
+3. 如果 PUBLIC_BUCKET=1，图片 URL 可直接访问
+4. 最适合作为 COS 爆满时的临时对象存储
+```
+
+适合 GreatEditor 的应急存储。
+
+### 模式 B：Private Space + MinIO 私有写权限（推荐给冷备份）
+
+```text
+Hugging Face Space：Private
+MINIO_ROOT_USER / MINIO_ROOT_PASSWORD：保密
+PUBLIC_BUCKET=0
+```
+
+特点：
+
+```text
+1. 更私密
+2. 适合备份
+3. 不适合直接作为公开图片 CDN
+4. GreatEditor 前端不应直接依赖这种 URL
+```
+
+适合作为腾讯 COS 的长期备份仓库。
+
+### 模式 C：GitHub 登录保护管理页，不保护 S3 API（后续增强）
+
+如果后续确实需要“使用 GitHub 账号登录管理界面”，建议单独开发一个轻量管理面板：
+
+```text
+/admin        -> GitHub OAuth 登录
+/s3 API       -> 仍然保持 MinIO S3 Access Key / Secret Key
+/health       -> 可公开或用简单 token
+```
+
+这种方式不会破坏 S3 API。
+
+不建议做成：
+
+```text
+所有路径都强制 GitHub OAuth
+```
+
+因为这会破坏 S3 API 的签名认证流程。
+
+## 当前项目默认策略
+
+当前项目默认采用：
+
+```text
+Public Space + MinIO S3 Key 认证 + 可选公开 bucket
+```
+
+也就是：
+
+```text
+MINIO_ROOT_USER / MINIO_ROOT_PASSWORD 控制写入和管理权限
+PUBLIC_BUCKET=1 控制图片是否可匿名读取
+MINIO_BROWSER=off 优先暴露 S3 API
+```
+
+## 如果必须要 GitHub 登录
+
+建议不是改 MinIO 本身，而是在 Cloudflare 侧做访问控制：
+
+```text
+1. 给 HF Space 绑定自定义域名，例如 cos.example.com
+2. 用 Cloudflare Access 配置 GitHub / GitHub Organization 登录
+3. 只保护管理面板或内部路径
+4. 不要保护 S3 API 上传下载路径
+```
+
+如果一定要保护全部路径，则该服务只能作为“人类浏览器访问”的后台，不适合 GreatEditor / S3 SDK 直接使用。
+
+## 实用建议
+
+对当前目标，建议这样配置：
+
+```text
+COS_HF GitHub 仓库：Private
+HF Space：Public 或 Private 分场景
+备份 Space：Private
+应急 Space：Public
+MinIO bucket：备份 private，应急 public-read
+写入权限：MinIO Access Key / Secret Key
+```
+
+可以创建两个 Space：
+
+```text
+cos-hf-backup-private   # Private，冷备份
+cos-hf-overflow-public  # Public，COS 爆满时应急承接图片访问
+```

docs/HF_DEPLOYMENT_OPTIONS.md

@@ -0,0 +1,152 @@
+# Hugging Face 部署方式：完整迁移 vs 单 Dockerfile 拉取
+
+## 结论
+
+推荐方式：把本仓库内容同步到 Hugging Face Space 仓库，或直接用 Hugging Face 的 GitHub 仓库关联/同步能力。
+
+不推荐方式：只在 Hugging Face Space 放一个 Dockerfile，然后在 Dockerfile 里从 GitHub Private 仓库拉取整个项目。
+
+原因：Private GitHub 仓库需要 token，Docker build 阶段使用 token 容易泄露到镜像层、构建日志或缓存中；并且 Hugging Face Space 本身就是一个 Git 仓库，每次提交会自动 rebuild，没必要绕一层 git clone。
+
+## 方式 A：Hugging Face Space 直接保存完整项目文件（推荐）
+
+Hugging Face Space 本身就是 Git 仓库。把本项目这些文件同步到 Space 仓库即可：
+
+```text
+README.md
+Dockerfile
+scripts/start-minio.sh
+scripts/mirror-cos-minio.md
+worker/keepalive.js
+docs/*
+```
+
+优点：
+
+```text
+1. 最符合 Hugging Face Space 的工作方式
+2. 每次 push 自动构建和重启
+3. 不需要 GitHub token 参与 Docker build
+4. Secret 只保存在 Hugging Face Space Secrets
+5. 出错时日志更清晰
+```
+
+适合：
+
+```text
+正式部署
+长期维护
+Private Space
+备份或应急对象存储
+```
+
+## 方式 B：GitHub Actions 同步到 Hugging Face Space（推荐）
+
+如果你希望继续以 GitHub 仓库 `CaPaCaptain/COS_HF` 为主仓库，可以使用 GitHub Actions 自动把 main 分支推送到 Hugging Face Space 仓库。
+
+流程：
+
+```text
+GitHub COS_HF main push
+        ↓
+GitHub Actions
+        ↓
+Push 到 Hugging Face Space Git 仓库
+        ↓
+Hugging Face 自动 rebuild
+```
+
+这种方式适合 GitHub Private 仓库。
+
+需要在 GitHub Secrets 中配置：
+
+```text
+HF_TOKEN
+HF_SPACE_REPO，例如 username/cos-hf
+```
+
+示例 workflow 可后续添加到：
+
+```text
+.github/workflows/sync-to-hf.yml
+```
+
+## 方式 C：HF Space 关联 GitHub 仓库
+
+如果 Hugging Face 当前界面允许直接关联 GitHub 仓库，也可以直接关联 `CaPaCaptain/COS_HF`。
+
+但注意：
+
+```text
+1. GitHub Private 仓库可能需要授权 Hugging Face 访问
+2. 关联失败时，改用方式 B 更稳
+3. Space 仍建议设置 Secrets，而不要把密钥写进仓库
+```
+
+## 方式 D：只放一个 Dockerfile，Dockerfile 自动 git clone（不推荐）
+
+技术上可以：
+
+```Dockerfile
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y git
+RUN git clone https://github.com/CaPaCaptain/COS_HF.git /app
+WORKDIR /app
+RUN chmod +x scripts/start-minio.sh
+CMD ["scripts/start-minio.sh"]
+```
+
+但这只适合 Public GitHub 仓库。
+
+如果是 Private GitHub 仓库，需要 token，例如：
+
+```Dockerfile
+ARG GITHUB_TOKEN
+RUN git clone https://$GITHUB_TOKEN@github.com/CaPaCaptain/COS_HF.git /app
+```
+
+不推荐原因：
+
+```text
+1. token 可能进入 Docker 镜像层
+2. token 可能出现在构建日志或缓存里
+3. Dockerfile 变成部署入口，但真实代码不在 Space 仓库，排查困难
+4. Hugging Face Secrets 更适合运行时，不适合作为 Docker build clone 私有仓库的认证来源
+5. 与 Hugging Face Space 自动 rebuild 的 Git 工作流重复
+```
+
+## 推荐选择
+
+### 当前 COS_HF 推荐部署方式
+
+```text
+GitHub 仓库：Private，作为源码主仓库
+Hugging Face Space：Docker Space
+同步方式：GitHub Actions 推送完整文件到 HF Space 仓库
+运行密钥：Hugging Face Space Secrets
+持久目录：/data/minio
+```
+
+### 备用快速方式
+
+如果只是先跑通：
+
+```text
+手动把 GitHub 仓库所有文件上传到 HF Space 仓库
+配置 Space Secrets
+启动 Docker Space
+```
+
+## 为什么不是“只迁移 Dockerfile”
+
+本项目 Dockerfile 依赖：
+
+```text
+scripts/start-minio.sh
+README.md metadata
+可选 docs 与 worker 模板
+```
+
+如果只迁移 Dockerfile，至少还要在 Dockerfile 中内嵌启动脚本或远程下载脚本。这样可维护性更差。
+
+所以更建议迁移完整项目文件，而不是只迁移 Dockerfile。

docs/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Notes
+
+## Access keys
+
+`MINIO_ROOT_USER` and `MINIO_ROOT_PASSWORD` are equivalent to S3 Access Key and Secret Key.
+
+Do not commit real keys into GitHub.
+
+Configure them as Hugging Face Space Secrets.
+
+## Public bucket
+
+`PUBLIC_BUCKET=1` makes the default bucket anonymously readable. This is convenient for image hosting, but anyone with the object URL can read the file.
+
+For private user files, set:
+
+```bash
+PUBLIC_BUCKET=0
+```
+
+Then proxy downloads through your application backend, or generate temporary signed URLs.
+
+## Recommended usage
+
+This repository is designed for backup, emergency overflow, and MVP object storage. It is not a substitute for a highly available production object storage service.
+
+## Backup strategy
+
+Keep at least one additional backup outside the Hugging Face Space persistent volume.
+
+Suggested minimum:
+
+```text
+Tencent COS -> HF MinIO
+HF MinIO -> local archive or another object storage
+```

scripts/mirror-cos-minio.md

@@ -0,0 +1,82 @@
+# 腾讯 COS ↔ Hugging Face MinIO 同步指南
+
+本文件用于在腾讯云 COS 与 Hugging Face MinIO 之间做备份、恢复和临时迁移。
+
+推荐工具：MinIO Client `mc`。
+
+## 1. 安装 mc
+
+macOS：
+
+```bash
+brew install minio/stable/mc
+```
+
+Linux：
+
+```bash
+curl -fsSL https://dl.min.io/client/mc/release/linux-amd64/mc -o mc
+chmod +x mc
+sudo mv mc /usr/local/bin/mc
+```
+
+## 2. 配置别名
+
+把下面变量替换成你自己的值。
+
+腾讯 COS endpoint 示例：
+
+```text
+https://cos.ap-guangzhou.myqcloud.com
+```
+
+Hugging Face MinIO endpoint 示例：
+
+```text
+https://your-space-name.hf.space
+```
+
+```bash
+mc alias set cos https://cos.ap-guangzhou.myqcloud.com "$COS_ID" "$COS_KEY"
+mc alias set hfminio https://your-space-name.hf.space "$MINIO_USER" "$MINIO_PASS"
+```
+
+## 3. COS 备份到 HF MinIO
+
+```bash
+mc mirror --overwrite cos/your-cos-bucket hfminio/great-editor-backup
+```
+
+只同步新增和变化文件：
+
+```bash
+mc mirror cos/your-cos-bucket hfminio/great-editor-backup
+```
+
+## 4. HF MinIO 恢复回 COS
+
+```bash
+mc mirror --overwrite hfminio/great-editor-backup cos/your-cos-bucket
+```
+
+## 5. 定时备份建议
+
+可以用 GitHub Actions、Cloudflare Worker 调度外部任务、VPS cron 或本地定时任务执行。
+
+建议策略：
+
+```text
+每日：COS -> HF MinIO 增量备份
+COS 爆满：GreatEditor 临时切换到 HF MinIO
+COS 扩容：HF MinIO -> COS 恢复
+恢复完成：GreatEditor 切回 COS
+```
+
+## 6. 注意事项
+
+```text
+1. mc mirror 默认会保持对象路径结构。
+2. 如果你希望删除目标端多余文件，可以使用 --remove，但备份场景不建议轻易使用。
+3. 首次全量同步可能耗时较长。
+4. HF Space 适合备份和应急，不建议作为高并发主存储。
+```

scripts/start-minio.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PORT="${PORT:-7860}"
+MINIO_DATA_DIR="${MINIO_DATA_DIR:-/data/minio}"
+MINIO_BUCKET="${MINIO_BUCKET:-great-editor-backup}"
+MINIO_REGION="${MINIO_REGION:-us-east-1}"
+PUBLIC_BUCKET="${PUBLIC_BUCKET:-1}"
+MINIO_BROWSER="${MINIO_BROWSER:-off}"
+
+if [[ -z "${MINIO_ROOT_USER:-}" || -z "${MINIO_ROOT_PASSWORD:-}" ]]; then
+  echo "[COS_HF] ERROR: MINIO_ROOT_USER and MINIO_ROOT_PASSWORD are required." >&2
+  exit 1
+fi
+
+mkdir -p "$MINIO_DATA_DIR"
+
+export MINIO_BROWSER
+export MINIO_REGION_NAME="$MINIO_REGION"
+
+# Hugging Face Space usually exposes one HTTP port. We expose S3 API on PORT.
+# The MinIO Console is disabled by default because it needs a second port.
+echo "[COS_HF] Starting MinIO on :$PORT"
+echo "[COS_HF] Data dir: $MINIO_DATA_DIR"
+echo "[COS_HF] Default bucket: $MINIO_BUCKET"
+
+minio server "$MINIO_DATA_DIR" --address ":${PORT}" &
+MINIO_PID=$!
+
+cleanup() {
+  echo "[COS_HF] Stopping MinIO..."
+  kill "$MINIO_PID" 2>/dev/null || true
+  wait "$MINIO_PID" 2>/dev/null || true
+}
+trap cleanup SIGTERM SIGINT
+
+# Wait until MinIO is ready.
+for i in $(seq 1 60); do
+  if curl -fsS "http://127.0.0.1:${PORT}/minio/health/ready" >/dev/null 2>&1; then
+    break
+  fi
+  echo "[COS_HF] Waiting for MinIO readiness... ($i/60)"
+  sleep 2
+  if ! kill -0 "$MINIO_PID" 2>/dev/null; then
+    echo "[COS_HF] MinIO exited before readiness." >&2
+    wait "$MINIO_PID"
+    exit 1
+  fi
+done
+
+mc alias set local "http://127.0.0.1:${PORT}" "$MINIO_ROOT_USER" "$MINIO_ROOT_PASSWORD" >/dev/null
+
+if ! mc ls "local/${MINIO_BUCKET}" >/dev/null 2>&1; then
+  echo "[COS_HF] Creating bucket: ${MINIO_BUCKET}"
+  mc mb "local/${MINIO_BUCKET}" >/dev/null
+else
+  echo "[COS_HF] Bucket exists: ${MINIO_BUCKET}"
+fi
+
+if [[ "$PUBLIC_BUCKET" == "1" || "$PUBLIC_BUCKET" == "true" ]]; then
+  echo "[COS_HF] Setting bucket anonymous download policy: ${MINIO_BUCKET}"
+  mc anonymous set download "local/${MINIO_BUCKET}" >/dev/null || true
+else
+  echo "[COS_HF] Bucket remains private: ${MINIO_BUCKET}"
+fi
+
+cat <<EOF
+[COS_HF] Ready.
+Health live:  /minio/health/live
+Health ready: /minio/health/ready
+Bucket:       ${MINIO_BUCKET}
+S3 Endpoint:  https://<your-space>.hf.space
+Path URL:     https://<your-space>.hf.space/${MINIO_BUCKET}/path/to/file
+EOF
+
+wait "$MINIO_PID"