README.md

metadata

title: HF Framework
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

HF Framework

基于 Hugging Face Space 部署的模块化服务框架。

架构

单容器部署，Ubuntu 基础镜像，Caddy 路由 + 多进程模块：

┌───────────── 容器 ─────────────┐
│                                │
│  用户请求 → Caddy(:7860)       │
│                │               │
│     ┌──────────┼──────────┐   │
│     │          │          │   │
│  localhost   localhost  localhost│
│    :8000      :8001     :8002  │
│   (api 模块) (example)  (...)  │
│                                │
└────────────────────────────────┘

快速开始

docker build -t hf-framework .
docker run -p 7860:7860 hf-framework

访问 http://localhost:7860

添加新模块

在 modules/ 下创建目录，至少提供 start.sh：

modules/my-module/
├── install.sh       # [可选] 构建时安装依赖
├── start.sh         # [必需] 进程启动入口
└── app/             # [可选] 模块代码

模块生命周期：

• 构建时 → Dockerfile 自动执行 modules/*/install.sh
• 运行时 → start.sh 自动遍历执行 modules/*/start.sh

示例：Python 模块

mkdir -p modules/my-py-module/app

install.sh：

apt-get update && apt-get install -y python3 python3-pip
pip3 install -r requirements.txt

start.sh：

exec python3 app/main.py

示例：Node.js 模块

install.sh：

apt-get update && apt-get install -y nodejs npm
npm install

start.sh：

exec node app/server.js

添加路由

编辑 caddy/Caddyfile，在 :7860 块中添加：

handle /my-module/* {
    reverse_proxy localhost:PORT
}

项目结构

hf-framework/
├── caddy/
│   └── Caddyfile           # 路由配置
├── modules/
│   └── example/            # 示例模块
│       ├── app/main.py
│       ├── install.sh
│       ├── requirements.txt
│       └── start.sh
├── Dockerfile              # Ubuntu + Caddy + 模块安装
├── start.sh                # 入口：后台启动所有模块 → Caddy 前台
├── AGENTS.md
└── README.md

端口规划

端口	用途
7860	Caddy（对外，HF Space 默认）
8000	api 模块
8001	example 模块
8002	webssh 模块（ttyd）
8003+	预留