README.md

---
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