Spaces:
Sleeping
Sleeping
| title: HuggingRun | |
| emoji: 🚀 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: docker | |
| pinned: false | |
| license: mit | |
| app_port: 7860 | |
| startup_duration_timeout: 1h | |
| tags: | |
| - docker | |
| - huggingface-spaces | |
| - persistence | |
| - deployment | |
| - run-anything | |
| # HuggingRun | |
| **Run anything on Hugging Face.** | |
| HuggingRun 是面向 Hugging Face Spaces 的**通用部署接口**：用同一套工具解决 HF 上的持久化、单端口、网络等限制，让**任意 Docker 应用**都能按同一套流程部署、重启后状态保留。 | |
| - **通用用法（用户最少步骤）**：[docs/GENERAL_USAGE.md](docs/GENERAL_USAGE.md) — 不按其他云容器收费或复杂配置，所有能力围绕通用工具展开。 | |
| - **通用工具优先**：主要维护的是通用层（持久化同步、单入口、可配置端口）。示例仅演示“最少配置”用法，不在核心脚本中为任何案例写死逻辑。 | |
| - **HF 限制与应对**：见 [docs/HF_LIMITATIONS.md](docs/HF_LIMITATIONS.md)（持久化、单端口、出站网络、DNS 等）。 | |
| ## 通用接口：你只需做两件事 | |
| 1. **Duplicate 本 Space**，在 Settings 里配好 **Secrets / Variables**（见下表）。 | |
| 2. 设置 **`RUN_CMD`** 为你要跑的进程（例如 `uvicorn app:app --host 0.0.0.0 --port 7860`）；不设则运行内置 demo。 | |
| | 配置项 | 必填 | 说明 | | |
| |--------|------|------| | |
| | `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 只暴露此端口） | | |
| ## 通用工具提供了什么 | |
| - **持久化**：启动时从 HF Dataset 恢复 `PERSIST_PATH`，运行中定时上传，退出时再上传一次。解决 HF 无本地持久盘的问题。 | |
| - **单端口约定**：应用只需监听 `APP_PORT`（默认 7860）；多端口服务需自己在容器内做反向代理。 | |
| - **统一入口**：同一 entrypoint 先做恢复与同步，再 `exec` 你的 `RUN_CMD`，便于任意镜像复用。 | |
| 详见 [docs/HF_LIMITATIONS.md](docs/HF_LIMITATIONS.md)。 | |
| 远端构建/运行日志：[docs/REMOTE_LOGS.md](docs/REMOTE_LOGS.md)。**Push → 部署 → 监控 → 测试** 循环：[docs/PUSH_DEBUG.md](docs/PUSH_DEBUG.md)。**本地 SSH 进 HF Ubuntu**（反向 SSH）：[docs/SSH_ACCESS.md](docs/SSH_ACCESS.md)。 | |
| ## 示例（最小用法） | |
| 示例仅展示“用通用工具、最少配置”的用法，维护量保持在最低。 | |
| ### 默认 demo | |
| 不设 `RUN_CMD`：容器会跑一个 7860 端口的简单 HTTP 页，并把计数存到 `/data`，用于验证持久化。 | |
| ### FastAPI + SQLite | |
| 在 Secrets 里设： | |
| - `RUN_CMD=uvicorn app.fastapi_sqlite:app --host 0.0.0.0 --port 7860` | |
| （可选）设 `HF_TOKEN` 与 `AUTO_CREATE_DATASET=true`，重启后 SQLite 数据仍在。 | |
| ### Ubuntu Server（Web Terminal + SSH） | |
| 使用同一套 `scripts/`，通过 ttyd 提供浏览器 Web Terminal，nginx 反代 + WebSocket-SSH 桥接支持远程 SSH 登录。全盘持久化：整个文件系统镜像同步到 HF Dataset。 | |
| ## 环境变量速查 | |
| | 变量 | 默认 | 说明 | | |
| |------|------|------| | |
| | `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 | |
| MIT | |