docs/HF_LIMITATIONS.md

# Hugging Face Spaces 限制与 HuggingRun 应对

本文档整理 [Hugging Face 官方文档](https://huggingface.co/docs/hub/en/spaces-overview) 中的 Spaces 限制，以及 HuggingRun 通用工具如何通过技术手段应对。

---

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

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

参考：[Disk usage on Spaces](https://huggingface.co/docs/hub/main/en/spaces-storage)、[Dataset storage](https://huggingface.co/docs/hub/main/en/spaces-storage#dataset-storage)

---

## 2. 单端口暴露

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

参考：[Docker Spaces](https://huggingface.co/docs/hub/en/spaces-sdks-docker)

---

## 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](https://discuss.huggingface.co/t/issue-with-url-resolution-blocked-on-hugging-face-spaces/95982)

---

## 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](https://huggingface.co/docs/hub/spaces-cookie-limitations)

---

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

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

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