README.md

metadata

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 — 不按其他云容器收费或复杂配置，所有能力围绕通用工具展开。
• 通用工具优先：主要维护的是通用层（持久化同步、单入口、可配置端口）。示例仅演示“最少配置”用法，不在核心脚本中为任何案例写死逻辑。
• HF 限制与应对：见 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/REMOTE_LOGS.md。Push → 部署 → 监控 → 测试 循环：docs/PUSH_DEBUG.md。本地 SSH 进 HF Ubuntu（反向 SSH）：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