| title | LibreFS HFS |
|---|---|
| emoji | 🗄️ |
| colorFrom | gray |
| colorTo | blue |
| sdk | docker |
| app_port | 7860 |
| pinned | false |
| license | agpl-3.0 |
LibreFS HFS 是一个面向 Hugging Face Docker Space 的 libreFS 部署包装项目，用于在 HF Space 上运行一个轻量级、S3-compatible 的对象存储服务。
本项目的部署策略是：
- 从
ubuntu:24.04原始镜像开始。 - Docker build 阶段安装 Go，并从
https://github.com/libreFS/libreFS.git拉取源码编译。 - Runtime 阶段仍然使用
ubuntu:24.04。 - 不使用 libreFS 官方 Docker image。
- 仓库根目录同时作为 Hugging Face Space root 和 GitHub 维护 root；
hfs-dev.toml声明 HFS v2 Pattern A /port/source关系：生产版本始终由LIBREFS_COMMIT的上游 commit 固定，多服务 runtime glue 集中在hfs/。 - 标准交付只上传由
scripts/export-space-bundle.sh从干净、不可变 Git commit 导出的最小 wrapper；bundle 自带BUILD_SOURCE.json和SHA256SUMS，同时绑定 wrapper SHA 与实际 libreFS source SHA，不含 libreFS 产品源码、.env*、local/、缓存、生成数据或凭证。 - 使用 Nginx 把 libreFS 的 S3 API 和 Web Console 合并到 Hugging Face Space 对外暴露的单端口
7860。
Space 仓库:
https://huggingface.co/spaces/BlueSkyXN/libreFS-HFS
公开 endpoint:
https://blueskyxn-librefs-hfs.hf.space
Web Console:
https://blueskyxn-librefs-hfs.hf.space/console/
| 能力 | 状态 | 说明 |
|---|---|---|
| S3-compatible API | 可用 | 公开域名根路径 / 转发到 libreFS S3 API。 |
| Web Console | 可用 | /console/ 转发到 libreFS Web Console；公开页面、静态资源和 iframe header 已回读正常，登录需 root 凭证复测。 |
| 只读 Ops | 可用 / 需 token | /_ops/ 提供浏览器诊断面板，并提供 /_ops/health、/_ops/system、/_ops/storage、/_ops/config、/_ops/version、/_ops/metrics API；默认使用 OPS_TOKEN 保护，只返回非敏感摘要和 /data 可见文件树统计。 |
| Admin 管理面 | 代码默认关闭 / 当前线上已开启 | 代码默认 ADMIN_ENABLED=false；当前 HF Variable 为 ADMIN_ENABLED=true，访问 /_admin/ 需要 ADMIN_TOKEN，只提供白名单 action。 |
| 签名上传/下载 | 需凭证验收 | 设计上走 AWS SigV4 path-style；仓库提供 scripts/smoke-s3-curl.sh，涉及 Secret 的 smoke test 需在操作时重新执行。 |
| HTTP 直链 | 条件可用 | bucket policy 允许匿名 s3:GetObject 后可直链访问。 |
| 持久化 | 已挂载 / 需验收 | 当前 hf spaces volumes list 显示 Storage Bucket 挂载到 /data；仍需上传、重启、rebuild 后读取验证。 |
| 生产对象存储 | 不建议 | HF Space 是应用托管环境，不是专用对象存储基础设施。 |
Hugging Face Docker Space 只对外暴露一个 app port。本项目用 Nginx 在 7860 上统一接入，再分流到 libreFS 的两个内部端口。
| 公开路径 | 内部服务 | 用途 |
|---|---|---|
/ |
127.0.0.1:9000 |
S3 API 和 path-style 对象 URL。 |
/_ops/ |
127.0.0.1:8081 |
只读诊断面板和 API；需要 OPS_TOKEN。 |
/_admin/ |
127.0.0.1:8082 |
默认关闭的管理面；开启后需要独立 ADMIN_TOKEN。 |
/console/ |
127.0.0.1:9001 |
libreFS / MinIO-compatible Web Console。 |
不要创建名为 console、minio、_ops、_admin 的公开 bucket。这些路径被 Web Console、health、ops 和 admin 路由保留。
在 Space Settings 里配置：
| 类型 | 名称 | 必需 | 说明 |
|---|---|---|---|
| Secret | MINIO_ROOT_USER |
是 | libreFS root user，同时用于 Console 登录和 S3 root access key。 |
| Secret | MINIO_ROOT_PASSWORD |
是 | libreFS root password，同时用于 Console 登录和 S3 root secret key。 |
| Secret | OPS_TOKEN |
建议 | /_ops/ 只读诊断入口 token；不设置时使用 demo 默认值，公开长期运行建议覆盖。 |
| Secret | ADMIN_TOKEN |
仅开启 admin 时 | /_admin/ 独立 Secret/header；只有 ADMIN_ENABLED=true 时需要。 |
| 类型 | 名称 | 默认值 | 说明 |
|---|---|---|---|
| Variable | PUBLIC_BASE_URL |
从 SPACE_HOST 推导 |
公开访问根地址；使用自定义域名时建议显式设置。 |
| Variable | LIBREFS_COMMIT |
无 | bundle-only build 必须设置具体 40 位 upstream commit SHA，且必须与 bundle provenance 一致；build 会直接 fetch/checkout 并校验实际 checkout。 |
| Variable | HFS_RELEASE_BUILD |
true |
bundle-only build 必须保持 true；任何缺失、false 或可变 source 都会让 Docker build 失败。 |
| Variable | GO_VERSION |
1.26.3 |
Docker build 阶段下载的 Go 版本。 |
| Variable | ADMIN_ENABLED |
false |
是否开启 /_admin/；默认保持关闭。 |
| Variable | CONTROL_PLANE_DEFAULT_LANG |
en |
/_ops/ 和 /_admin/ JSON 文案默认语言；支持 en、zh-CN。 |
最近回读时间：2026-06-03。实时状态以命令重新查询为准。
| 项目 | 当前值 / 状态 |
|---|---|
GitHub origin/main |
以 git ls-remote origin refs/heads/main 回读为准。 |
Hugging Face hf/main / runtime |
以 git ls-remote hf refs/heads/main 和 hf spaces info BlueSkyXN/libreFS-HFS 的 runtime sha 回读为准；发布完成后应与 GitHub main 对齐。 |
| Health endpoint | /minio/health/ready 回读 HTTP 200。 |
| HF Variables | 已显式配置 ADMIN_ENABLED=true、ADMIN_AUDIT_LOG=/tmp/librefs-hfs/admin-audit.jsonl、LIBREFS_COMMIT=e194bd779f36fdc08f310d2819d9356f0c1f991b、公开 URL、Go/ref 默认值和若干 MinIO 兼容变量；详见 docs/contract-alignment.md。 |
| HF Secrets | MINIO_ROOT_USER、MINIO_ROOT_PASSWORD、OPS_TOKEN、ADMIN_TOKEN 已配置；HF 不回显 value。 |
| HF Volume | BlueSkyXN/librefs-hfs-data -> /data，read_only=False |
详细文档拆分在 docs/ 目录：
curl -fsS https://blueskyxn-librefs-hfs.hf.space/minio/health/ready预期结果：
HTTP 200，响应体为空
浏览器打开只读诊断面板：
https://blueskyxn-librefs-hfs.hf.space/_ops/
首次网页登录可临时使用：
https://blueskyxn-librefs-hfs.hf.space/_ops/?token=<ops-token>
浏览器 HTML 请求的 token 验证成功后，服务会设置 HttpOnly cookie 并跳转到不带 token 的 /_ops/；后续浏览器访问 /_ops/health、/_ops/system 等不需要继续把 token 放在 URL 里。脚本/API 请求不接受 query token 鉴权，应使用 header 或 bearer token；容器内 Nginx access log 不记录 query string，ops-service 日志会 redact token= 值，但仍不要把带 ?token= 的链接写入文档、截图或分享链接。
OPS_TOKEN='<ops-token>' \
curl -fsS -H "X-Ops-Token: $OPS_TOKEN" \
https://blueskyxn-librefs-hfs.hf.space/_ops/health外部 ops API 路径必须带 /_ops/ 前缀：
/_ops/health
/_ops/system
/_ops/storage
/_ops/config
/_ops/version
/_ops/metrics
/_ops/config 只返回非敏感配置和 Secret 是否存在，不返回 MINIO_ROOT_PASSWORD、OPS_TOKEN 或 ADMIN_TOKEN 原文。
/_ops/storage 只扫描 DATA_DIR 当前可见文件树，返回路径、size、mtime 和聚合统计；它不能回读 Hugging Face bucket 的 info.size 账面值。
/_ops/ 和 /_admin/ 支持中文/英文文案。脚本可用 ?lang=zh-CN 或 X-Control-Language: zh-CN 指定语言，浏览器会按 Accept-Language 自动选择；未指定时默认英文。
打开 Web Console：
https://blueskyxn-librefs-hfs.hf.space/console/
S3-compatible client 的 endpoint：
https://blueskyxn-librefs-hfs.hf.space
公开对象直链格式：
https://blueskyxn-librefs-hfs.hf.space/<bucket>/<object>
公开直链需要 bucket policy 显式允许匿名 s3:GetObject。
- 当前
hf spaces volumes list显示/data已挂载 Hugging Face Storage Bucket；如果后续移除挂载，上传对象可能在 Space 重启、重建、迁移或停止后丢失。 - 当前生产环境已显式开启
/_admin/。如果需要恢复默认安全姿态，应把 HF VariableADMIN_ENABLED改回false或移除。 - 当前
cpu-basic硬件适合功能测试和轻量使用，不适合高吞吐对象存储。 - 未签名浏览器直接访问根路径
/可能返回 S3 XML error，这是正常现象；签名 S3 请求和配置了 policy 的对象直链才是预期访问方式。 - 本仓库 license 使用 AGPL-3.0，因为 libreFS 本身是 AGPL-3.0。