HuggingRun: 通用接口 + HF 限制文档 + APP_PORT + ubuntu-desktop 示例

.env.example

@@ -16,5 +16,6 @@ RUN_CMD=
 # Sync interval in seconds
 SYNC_INTERVAL=60
 
-# Port for default demo (HF Spaces expect 7860)
+# Port your app listens on (HF exposes only this one port; default 7860)
 PORT=7860
+APP_PORT=7860

DEPLOY.md

@@ -0,0 +1,54 @@
+# 部署 HuggingRun 到 Hugging Face Spaces
+
+## 1. 创建 Space
+
+在 [huggingface.co/new-space](https://huggingface.co/new-space) 新建 Space：
+
+- **SDK**: 选 **Docker**
+- **Space name**: 例如 `HuggingRun`
+- 创建后得到 `https://huggingface.co/spaces/<你的用户名>/HuggingRun`
+
+## 2. 推送代码
+
+在本地项目目录执行（把 `tao-shen` 换成你的 HF 用户名）：
+
+```bash
+cd /Users/tao.shen/HuggingRun
+git remote remove origin 2>/dev/null || true
+git remote add origin https://huggingface.co/spaces/<你的用户名>/HuggingRun
+git push -u origin main
+```
+
+若 HF 需要认证，先执行：
+
+```bash
+pip install -q huggingface_hub && huggingface-cli login
+```
+
+或使用 Git 凭证（HF 支持 Personal Access Token 作为密码）。
+
+## 3. 本地验证（可选）
+
+确保 Docker 已启动后：
+
+```bash
+docker build -t huggingrun:local .
+docker run --rm -p 7860:7860 -e PORT=7860 huggingrun:local
+```
+
+浏览器打开 http://localhost:7860 应看到默认 demo（访问计数）。Ctrl+C 停止。
+
+## 4. 难例测试（FastAPI + SQLite）
+
+在 Space 的 **Settings → Repository secrets** 中增加：
+
+- `RUN_CMD` = `uvicorn app.fastapi_sqlite:app --host 0.0.0.0 --port 7860`
+- （可选）`HF_TOKEN`、`AUTO_CREATE_DATASET` = `true` 以开启持久化
+
+保存后 Space 会重新构建。打开 App 查看首页和 `/api`，重启 Space 后访问次数应保持（若已配 HF 持久化）。
+
+## 完成标准
+
+- [ ] Space 创建并推送代码成功
+- [ ] 默认 demo 在 Space 中可访问（7860）
+- [ ] 设置 `RUN_CMD` 后 FastAPI+SQLite 难例可访问且（可选）重启后数据仍在

DESIGN.md

@@ -33,7 +33,8 @@
 
 ## 完成标准（迭代开发）
 
+- [ ] **通用工具**：README 与 docs/HF_LIMITATIONS.md 明确“通用接口 + HF 限制应对”；entrypoint/sync 可配置 PERSIST_PATH、APP_PORT、RUN_CMD。
 - [ ] 本地 `docker build` 与 `docker run` 成功，默认 demo 在 7860 响应。
 - [ ] 持久化：重启容器后，写入 `PERSIST_PATH` 的内容仍在（通过 HF Dataset 恢复）。
-- [ ] 至少一个难例（如 FastAPI+SQLite 或 Gradio+状态）在 README 中说明并在 HF 上可复现。
+- [ ] 示例最小化：FastAPI+SQLite、Ubuntu 桌面等仅演示“用通用工具”的用法，不增加额外通用逻辑。
 - [ ] 代码推送到 HF Space，且在该 Space 中成功运行并通过验证。

README.md

@@ -19,57 +19,64 @@ tags:
 
 **Run anything on Hugging Face.**
 
-Turn Hugging Face Spaces into a generic container: run any Docker-friendly app with optional persistence via HF Datasets. No Mac Mini, no paid cloud — 2 vCPU, 16GB RAM, 50GB storage, free tier.
+HuggingRun 是面向 Hugging Face Spaces 的**通用部署接口**：用同一套工具解决 HF 上的持久化、单端口、网络等限制，让任意 Docker 应用都能一键部署、重启后状态保留。
 
-## Why HuggingRun?
+- **通用工具优先**：主要维护的是通用层（持久化同步、单入口、可配置端口）。示例仅演示“最少配置”用法。
+- **HF 限制与应对**：见 [docs/HF_LIMITATIONS.md](docs/HF_LIMITATIONS.md)（持久化、单端口、出站网络、DNS 等）。
 
-- **Generic**: Not tied to one app. Set `RUN_CMD` to run your server, API, or bot.
-- **Persistent**: Sync a directory (e.g. `/data`) to a private HF Dataset so state survives restarts.
-- **One Dockerfile**: Parameterized with `BASE_IMAGE` and `RUN_CMD`; duplicate the Space and configure.
+## 通用接口：你只需做两件事
 
-## Quick Start
+1. **Duplicate 本 Space**，在 Settings 里配好 **Secrets / Variables**（见下表）。
+2. 设置 **`RUN_CMD`** 为你要跑的进程（例如 `uvicorn app:app --host 0.0.0.0 --port 7860`）；不设则运行内置 demo。
 
-### 1. Duplicate this Space
+| 配置项 | 必填 | 说明 |
+|--------|------|------|
+| `HF_TOKEN` | 需持久化时 | HF 写权限 Token，用于把 `PERSIST_PATH` 同步到 Dataset |
+| `HF_DATASET_REPO` | 可选 | 备份用 Dataset 仓库，默认 `{SPACE_ID}-data` |
+| `AUTO_CREATE_DATASET` | 可选 | `true` 时自动创建私有 Dataset |
+| `RUN_CMD` | 可选 | 要执行的命令；空则跑默认 demo（7860 端口） |
+| `PERSIST_PATH` | 可选 | 持久化目录，默认 `/data` |
+| `APP_PORT` / `PORT` | 可选 | 应用监听端口，默认 `7860`（HF 只暴露此端口） |
 
-Click **Duplicate this Space** on the HuggingRun Space page. After duplicating, set your Space **Repository secrets**:
+## 通用工具提供了什么
 
-| Secret | Required | Description |
-|--------|----------|-------------|
-| `HF_TOKEN` | For persistence | HF token with write access ([create](https://huggingface.co/settings/tokens)) |
-| `HF_DATASET_REPO` | Optional | Dataset repo for backup (e.g. `your-name/HuggingRun-data`). Default: `{SPACE_ID}-data` |
-| `RUN_CMD` | Optional | Command to run (e.g. `python3 my_app.py`). Empty = default demo on port 7860 |
+- **持久化**：启动时从 HF Dataset 恢复 `PERSIST_PATH`，运行中定时上传，退出时再上传一次。解决 HF 无本地持久盘的问题。
+- **单端口约定**：应用只需监听 `APP_PORT`（默认 7860）；多端口服务需自己在容器内做反向代理。
+- **统一入口**：同一 entrypoint 先做恢复与同步，再 `exec` 你的 `RUN_CMD`，便于任意镜像复用。
 
-### 2. Persistence (optional)
+详见 [docs/HF_LIMITATIONS.md](docs/HF_LIMITATIONS.md)。
 
-- **Manual**: Create a private Dataset repo (e.g. `your-name/HuggingRun-data`), set `HF_DATASET_REPO` and `HF_TOKEN`. Data under `PERSIST_PATH` (default `/data`) syncs every `SYNC_INTERVAL` seconds (default 60).
-- **Auto**: Set `AUTO_CREATE_DATASET=true` and `HF_TOKEN`; a private dataset is created on first run.
+## 示例（最小用法）
 
-### 3. Open your Space
+示例仅展示“用通用工具、最少配置”的用法，维护量保持在最低。
 
-Visit your Space URL. You’ll see the default demo (visit counter with persistence). To run your own app, set `RUN_CMD` in secrets and rebuild.
+### 默认 demo
 
-## Environment variables
+不设 `RUN_CMD`：容器会跑一个 7860 端口的简单 HTTP 页，并把计数存到 `/data`，用于验证持久化。
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `RUN_CMD` | (default demo) | Command to run (e.g. `uvicorn app:app --host 0.0.0.0 --port 7860`) |
-| `PERSIST_PATH` | `/data` | Directory to sync to the HF Dataset |
-| `HF_TOKEN` | — | HF token for persistence |
-| `HF_DATASET_REPO` | `{SPACE_ID}-data` | Dataset repo ID |
-| `AUTO_CREATE_DATASET` | `false` | Create dataset repo if missing |
-| `SYNC_INTERVAL` | `60` | Seconds between uploads |
-| `PORT` | `7860` | Port for default demo (HF expects 7860) |
+### FastAPI + SQLite
 
-## Hard example: FastAPI + SQLite
+在 Secrets 里设：
 
-This repo includes a **hard example** (FastAPI + SQLite) in the image. To run it:
+- `RUN_CMD=uvicorn app.fastapi_sqlite:app --host 0.0.0.0 --port 7860`
 
-1. In your Space **Repository secrets**, set:
-   - `RUN_CMD=uvicorn app.fastapi_sqlite:app --host 0.0.0.0 --port 7860`
-2. (Optional) Set `HF_TOKEN` and `AUTO_CREATE_DATASET=true` for persistence so the SQLite DB in `/data` survives restarts.
-3. Rebuild the Space. Open the app: you’ll see a visit counter and `/api` returning JSON. Restart the Space and refresh — the count persists.
+（可选）设 `HF_TOKEN` 与 `AUTO_CREATE_DATASET=true`，重启后 SQLite 数据仍在。
 
-This proves a stateful, “hard” app (FastAPI + SQLite + persistence) runs on HuggingRun.
+### Ubuntu 桌面（noVNC）
+
+见 [ubuntu-desktop/](ubuntu-desktop/)：使用同一套通用脚本（同步 + entrypoint），仅 `RUN_CMD` 改为启动 XFCE + noVNC。作为“用通用工具跑复杂应用”的示例，不做额外封装。
+
+## 环境变量速查
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `RUN_CMD` | 默认 demo | 要执行的命令 |
+| `PERSIST_PATH` | `/data` | 同步到 HF Dataset 的目录 |
+| `HF_TOKEN` | — | 持久化用 Token |
+| `HF_DATASET_REPO` | `{SPACE_ID}-data` | Dataset 仓库 |
+| `AUTO_CREATE_DATASET` | `false` | 是否自动创建 Dataset |
+| `SYNC_INTERVAL` | `60` | 同步间隔（秒） |
+| `PORT` / `APP_PORT` | `7860` | 应用监听端口 |
 
 ## License
 

docs/HF_LIMITATIONS.md

@@ -0,0 +1,73 @@
+# 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 的应用，由通用工具统一处理上述限制。

docs/plans/2025-03-03-ubuntu-desktop-design.md

@@ -0,0 +1,26 @@
+# Ubuntu 桌面版 on HuggingRun 设计
+
+**目标**: 在 HuggingRun 上部署最新版 Ubuntu 桌面（浏览器内 noVNC 完整桌面），打通常用功能，重启后状态完整保留。
+
+## 方案
+
+- **基础镜像**: Ubuntu 24.04 LTS
+- **桌面**: XFCE（轻量，适合 2 vCPU / 16GB）
+- **显示**: Xvfb 虚拟显示 + TigerVNC + noVNC（noVNC 监听 7860，满足 HF Spaces）
+- **持久化**: 桌面用户 HOME 放在 `PERSIST_PATH`（默认 `/data/desktop-home`），由现有 sync_hf.py 同步到 HF Dataset；启动时先恢复再挂载/HOME 指向该目录
+- **入口**: 独立 `ubuntu-desktop/` 目录，自有 Dockerfile；entrypoint 先执行 sync 恢复，再启动 Xvfb → 桌面 → VNC → noVNC
+
+## 完成标准（迭代开发）
+
+- [ ] `ubuntu-desktop/` 可独立构建并运行，浏览器访问 7860 看到完整 XFCE 桌面
+- [ ] 桌面功能可用：文件管理器、终端、浏览器（Firefox）、文本编辑器
+- [ ] 设置 HF_TOKEN + AUTO_CREATE_DATASET 后，重启 Space 后桌面状态（桌面文件、配置、已装软件状态）保留，无报错
+- [ ] 周期性同步与退出时同步正常，无遗漏
+
+## 实现要点
+
+1. **Dockerfile.ubuntu-desktop**: FROM ubuntu:24.04，装 python3、huggingface_hub、XFCE、TigerVNC、noVNC、Firefox；复制 HuggingRun scripts；用户 uid 1000；HOME 指向持久化目录
+2. **entrypoint_desktop**: 恢复 `/data` → 创建并绑定 `/data/desktop-home` 为桌面 HOME → 启动 sync 后台 → 启动 Xvfb、dbus、XFCE、x11vnc/tigervnc、noVNC（监听 7860）
+3. **PERSIST_PATH**: 使用 `/data`，`/data/desktop-home` 存桌面主目录；sync 继续上传/下载整个 `/data`
+
+日期: 2025-03-03

scripts/sync_hf.py

@@ -27,10 +27,12 @@ os.environ.setdefault("HF_HUB_UPLOAD_TIMEOUT", "600")
 from huggingface_hub import HfApi, snapshot_download
 
 # ── Configuration ───────────────────────────────────────────────────────────
+# See docs/HF_LIMITATIONS.md for how HuggingRun addresses HF Spaces limits.
 
 HF_TOKEN = os.environ.get("HF_TOKEN")
 PERSIST_PATH = Path(os.environ.get("PERSIST_PATH", "/data"))
 RUN_CMD = os.environ.get("RUN_CMD", "")
+APP_PORT = os.environ.get("APP_PORT", os.environ.get("PORT", "7860"))  # Single port exposed by HF
 SYNC_INTERVAL = int(os.environ.get("SYNC_INTERVAL", "60"))
 AUTO_CREATE_DATASET = os.environ.get("AUTO_CREATE_DATASET", "false").lower() in ("true", "1", "yes")
 # In dataset we store under this path_in_repo subfolder
@@ -167,10 +169,13 @@ class GenericSync:
             return None
         print(f"[HuggingRun] Running: {cmd}")
         try:
-            process = subprocess.Popen(
+            env = os.environ.copy()
+        env.setdefault("PORT", APP_PORT)
+        env.setdefault("APP_PORT", APP_PORT)
+        process = subprocess.Popen(
                 cmd,
                 shell=True,
-                env=os.environ.copy(),
+                env=env,
                 stdout=sys.stdout,
                 stderr=sys.stderr,
             )

ubuntu-desktop/Dockerfile

@@ -0,0 +1,47 @@
+# Ubuntu 24.04 Desktop on HuggingRun — noVNC on 7860, persistence via /data
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# System + Python (for sync)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates curl python3 python3-pip python3-venv \
+    && pip3 install --no-cache-dir --break-system-packages huggingface_hub \
+    && rm -rf /var/lib/apt/lists/*
+
+# Desktop stack: Xvfb, XFCE, dbus, x11vnc, Firefox
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    xvfb \
+    xfce4 xfce4-goodies \
+    dbus-x11 \
+    x11vnc \
+    firefox \
+    procps \
+    && rm -rf /var/lib/apt/lists/*
+
+# noVNC (web client on 7860)
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && git clone --depth 1 https://github.com/novnc/noVNC.git /opt/noVNC \
+    && git clone --depth 1 https://github.com/novnc/websockify /opt/noVNC/utils/websockify \
+    && rm -rf /var/lib/apt/lists/* /opt/noVNC/.git
+
+# HF Spaces run as user 1000
+RUN useradd -m -u 1000 user
+ENV HOME=/home/user
+RUN mkdir -p /data && chown user:user /data
+
+# HuggingRun scripts (build context = repo root)
+COPY scripts /scripts
+COPY ubuntu-desktop/start-desktop.sh /opt/start-desktop.sh
+RUN chmod +x /scripts/entrypoint.sh /opt/start-desktop.sh
+
+ENV PERSIST_PATH=/data
+ENV RUN_CMD="/opt/start-desktop.sh"
+ENV DESKTOP_HOME=/data/desktop-home
+ENV DISPLAY=:99
+ENV VNC_PORT=5901
+ENV NOVNC_PORT=7860
+
+USER user
+EXPOSE 7860
+ENTRYPOINT ["/scripts/entrypoint.sh"]

ubuntu-desktop/README.md

@@ -0,0 +1,14 @@
+# Ubuntu 桌面示例
+
+本目录是 **HuggingRun 通用工具** 的一个示例：在 HF 上跑 Ubuntu + XFCE + noVNC，使用与主仓库相同的持久化与 entrypoint，仅 `RUN_CMD` 不同。
+
+- **通用工具**：根目录的 `scripts/sync_hf.py`、`scripts/entrypoint.sh` 和主 Dockerfile 的 entrypoint。
+- **本示例**：`Dockerfile` 在此目录，构建时从仓库根 COPY `scripts/`，并设置 `RUN_CMD=/opt/start-desktop.sh`；`start-desktop.sh` 启动 Xvfb + XFCE + x11vnc + noVNC（监听 7860），桌面 HOME 放在 `PERSIST_PATH/desktop-home`，由通用同步脚本持久化。
+
+## 最小用法
+
+1. 新建 Space 或 Duplicate HuggingRun，将 **Dockerfile** 换成本目录的 `Dockerfile` 内容（或从仓库根构建：`docker build -f ubuntu-desktop/Dockerfile .`）。
+2. 设置 Secrets：`HF_TOKEN`、可选 `AUTO_CREATE_DATASET=true`。
+3. 构建并运行，浏览器打开 Space 即可看到 noVNC 桌面；重启后状态由通用持久化保留。
+
+维护重点在通用层；本示例仅做最小封装。

ubuntu-desktop/start-desktop.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Start Ubuntu desktop: Xvfb + XFCE + x11vnc + noVNC on 7860
+# HOME is set to persistent dir by caller (sync/entrypoint). Here we ensure and use it.
+set -e
+
+export PERSIST_PATH="${PERSIST_PATH:-/data}"
+export DESKTOP_HOME="${DESKTOP_HOME:-$PERSIST_PATH/desktop-home}"
+export DISPLAY="${DISPLAY:-:99}"
+export VNC_PORT="${VNC_PORT:-5901}"
+export NOVNC_PORT="${NOVNC_PORT:-7860}"
+
+mkdir -p "$DESKTOP_HOME"
+export HOME="$DESKTOP_HOME"
+
+# Ensure minimal XFCE dirs
+mkdir -p "$HOME/.config" "$HOME/.local/share" "$HOME/Desktop"
+
+# Start Xvfb
+Xvfb "$DISPLAY" -screen 0 1280x720x24 -ac +extension GLX +render -noreset &
+XVFB_PID=$!
+sleep 2
+
+# Start dbus for session (user session only; no system dbus as we run as non-root)
+dbus-daemon --session
+
+# Start XFCE (lightweight)
+startxfce4 &
+DESKTOP_PID=$!
+sleep 3
+
+# x11vnc: share display :99 on port 5901
+x11vnc -display "$DISPLAY" -rfbport "$VNC_PORT" -forever -shared -noxdamage -bg
+
+# noVNC: web on 7860, proxy to VNC
+if [ -x /opt/noVNC/utils/novnc_proxy ]; then
+  /opt/noVNC/utils/novnc_proxy --listen "$NOVNC_PORT" --vnc "localhost:$VNC_PORT"
+else
+  # Fallback: websockify + simple http serve
+  (cd /opt/noVNC && ./utils/novnc_proxy --listen "$NOVNC_PORT" --vnc "localhost:$VNC_PORT")
+fi