docs/HF_LIMITATIONS.md

Hugging Face Spaces 限制与 HuggingRun 应对

本文档整理 Hugging Face 官方文档 中的 Spaces 限制，以及 HuggingRun 通用工具如何通过技术手段应对。

---

1. 持久化存储（无本地持久盘）

官方说明	HuggingRun 方案
免费 Space 磁盘为 非持久：重启/停止后内容丢失。付费持久盘方案已不再对新用户开放。	Dataset 同步：将 PERSIST_PATH（默认 /data）定时同步到私有 HF Dataset 仓库；启动时先拉取再启动应用。设置 HF_TOKEN + AUTO_CREATE_DATASET=true 或 HF_DATASET_REPO 即可。

参考：Disk usage on Spaces、Dataset storage

---

2. 单端口暴露

官方说明	HuggingRun 方案
仅 一个端口 对外暴露，默认 7860，可在 README 的 app_port 中修改。内部可开多端口，但外部只能通过这一端口访问。	应用需监听 app_port（默认 7860）。多端口服务需在 容器内自建反向代理（如 Nginx/Caddy）在 7860 上统一入口，再转发到内部各端口；或使用 HuggingRun 的 APP_PORT 与 RUN_CMD 约定应用只监听该端口。

参考：Docker Spaces

---

3. 出站网络

官方说明	HuggingRun 方案
出站请求仅允许 80、443、8080。其他端口会被拦截。	应用只发起 HTTP/HTTPS 或 8080 出站即可。若依赖其他端口，需使用可经 443 转发的代理或 API。

参考：Spaces Overview — Networking

---

4. DNS / 域名解析

现象	HuggingRun 方案
部分环境存在 DNS 解析失败或特定域名不可达（如部分 API 域名）。	可选：在自定义 RUN_CMD 前通过 DoH（DNS over HTTPS） 或自定义 resolver 绕过；或使用系统/语言层代理。HuggingRun 通用层可预留 DNS_OVER_HTTPS=1 等开关，由启动脚本在需要时配置。

参考：Issue with URL Resolution/Blocked on Hugging Face Spaces

---

5. 资源与休眠

官方说明	HuggingRun 方案
免费：2 vCPU、16 GB 内存、50 GB 非持久磁盘。长时间无访问会 Sleep，需付费硬件才可长期运行。	无法通过工具绕过；建议在 README 中说明。持久化通过 Dataset 保证重启/休眠后 状态可恢复。

---

6. Cookie / iframe

官方说明	HuggingRun 方案
Space 运行在 *.hf.space，若被嵌入 iframe，会受浏览器跨域 Cookie 限制。	与通用部署接口无直接关系；若应用依赖 Cookie，需在应用层处理（如禁用 XSRF 或使用 Token）。

参考：Cookie limitations in Spaces

---

总结：HuggingRun 通用接口提供的应对

• 持久化：PERSIST_PATH + HF Dataset 同步（启动恢复 + 定时上传 + 退出上传）。
• 单端口：约定 APP_PORT（默认 7860），应用或自建反向代理只暴露该端口。
• 出站：文档约束（仅 80/443/8080）；复杂场景用代理或 API。
• DNS：可选 DoH/自定义 resolver，由启动脚本在通用层按需开启。
• 资源/休眠：文档说明；依赖持久化保证“重启后状态保留”。

用户只需：设置 RUN_CMD（及可选 HF_TOKEN、PERSIST_PATH 等），即可在 HF 上部署任意兼容 Docker 的应用，由通用工具统一处理上述限制。