README.md

---
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)  (...)  │
│                                │
└────────────────────────────────┘
```

## 快速开始

```bash
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 模块

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

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

`start.sh`：
```sh
exec python3 app/main.py
```

### 示例：Node.js 模块

`install.sh`：
```sh
apt-get update && apt-get install -y nodejs npm
npm install
```

`start.sh`：
```sh
exec node app/server.js
```

## 添加路由

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

```caddy
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+ | 预留 |