---
title: HF Space Spring Boot Demo
emoji: 🚀
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# HuggingFace Space Spring Boot Demo

**基于 wfly-spring 生产配置的最简示例**（SQLPub MySQL + Upstash Redis + Druid + MyBatis Plus）。

> ⚠️ 本文件顶部的 YAML 头是 HuggingFace Space **必需**的配置块：
> - `sdk: docker` 声明用 Docker 部署
> - `app_port: 7860` 告诉平台容器监听哪个端口

## ✨ 特性

- **真实凭据**：直接复用 `wfly-spring/application-dev.yaml` 的 SQLPub + Upstash 配置，无需另外注册
- **生产级组件**：Druid 连接池 + MyBatis Plus + Redisson
- **Druid 监控**：访问 `/druid/` 查看连接池实时状态
- **零配置启动**：凭据已内置在 `application.yml`（敏感信息可改走环境变量）

## 📚 文档索引

| 文档 | 说明 |
|---|---|
| [README.md](./README.md)（本文） | 快速入门 + 本地运行 + 基础部署 |
| [ARCHITECTURE.md](./ARCHITECTURE.md) | **零成本生产级架构**（MySQL / Redis / CloudFlare DDNS） |
| [DEPLOY.md](./DEPLOY.md) | **部署 Checklist**（逐步操作清单 + 常见问题） |
| [application.yml.example](./application.yml.example) | Spring Boot 配置模板 |
| [.env.example](./.env.example) | 环境变量模板 |

## 目录结构

```
huggingface-space-springboot-demo/
├── Dockerfile                  # 多阶段构建：Maven 打包 + JRE 运行
├── .dockerignore
├── pom.xml                     # 依赖：Druid / MyBatis Plus / Redis / Redisson
├── init.sql                    # 数据库初始化脚本（建表 + 测试数据）
├── README.md                   # 本文件，顶部 YAML 是 Space 配置
└── src/main/
    ├── java/com/example/hfspace/
    │   ├── HfSpaceApplication.java        # 启动类（@MapperScan）
    │   ├── config/
    │   │   └── MyBatisPlusMetaObjectHandler.java  # 自动填充 createTime/updateTime
    │   ├── controller/
    │   │   ├── HelloController.java       # 首页 HTML + /api/hello
    │   │   ├── DemoController.java        # Demo CRUD（MyBatis Plus）
    │   │   └── CacheController.java       # Redis 缓存示例
    │   ├── dataobject/
    │   │   └── DemoDO.java                # Demo 实体（MyBatis Plus）
    │   └── mapper/
    │       └── DemoMapper.java            # MyBatis Plus Mapper
    └── resources/
        └── application.yml                # 配置（直接含 wfly-spring 凭据）
```

## 为什么用多阶段 Dockerfile

Java 是编译型语言，需要先把源码打成 jar 再运行。所以 Dockerfile 分两段：

1. **构建阶段**（`maven:3.9-eclipse-temurin-17`）：`mvn package` 打出 jar
2. **运行阶段**（`eclipse-temurin:17-jre`）：只装 JRE，体积小、启动快

这样最终镜像不含 Maven 和源码，干净又轻量。

## 本地运行（快速验证）

### 方式一：直接跑（凭据已内置）

```bash
# 1. 先在 SQLPub 数据库执行 init.sql（建表）
mysql -h mysql6.sqlpub.com -P 3311 -u vftdream -p vftdream < init.sql
# 密码：jwKGBhsqVEbwyviK

# 2. 启动应用
mvn spring-boot:run

# 3. 浏览器打开
open http://localhost:7860
```

### 方式二：Docker（和线上环境一致）

```bash
docker build -t hf-springboot-demo .
docker run -p 7860:7860 hf-springboot-demo
```

### 验证接口

- **首页**：http://localhost:7860 （含完整接口列表）
- **MySQL CRUD**：
  ```bash
  # 列表
  curl http://localhost:7860/api/demo
  
  # 创建
  curl -X POST http://localhost:7860/api/demo \
    -H "Content-Type: application/json" \
    -d '{"title":"Test","content":"Hello World"}'
  
  # 查询
  curl http://localhost:7860/api/demo/1
  ```
- **Redis 缓存**：
  ```bash
  # 健康检查
  curl http://localhost:7860/api/cache/health
  
  # 存缓存
  curl -X POST http://localhost:7860/api/cache \
    -H "Content-Type: application/json" \
    -d '{"key":"foo","value":"bar","ttl":60}'
  
  # 读缓存
  curl http://localhost:7860/api/cache/foo
  ```
- **Druid 监控**：http://localhost:7860/druid/ （用户名 `admin` / 密码 `admin123`）

## 部署到 HuggingFace Space

```bash
# 1. 在 https://huggingface.co/new-space 创建 Docker / Blank 空间
# 2. 克隆该空间仓库
git clone https://huggingface.co/spaces/<用户名>/<空间名>
cd <空间名>

# 3. 把本目录所有文件拷进去，提交推送
git add .
git commit -m "init spring boot demo"
git push
# push 时用户名填用户名，密码填 write 权限的 Access Token
```

推送后平台自动构建（首次构建会下依赖，约几分钟），状态变 `Running` 即可访问：
`https://<用户名>-<空间名>.hf.space`

## 接口

| 路径 | 方法 | 说明 |
|---|---|---|
| **基础接口** | | |
| `/` | GET | 首页 HTML（含接口列表） |
| `/api/hello` | GET | 返回 JSON |
| **MySQL 示例**（Demo CRUD，MyBatis Plus） | | |
| `/api/demo` | GET | 列出所有项 |
| `/api/demo` | POST | 创建（Body: `{"title":"Test","content":"Hello"}`） |
| `/api/demo/{id}` | GET | 查询单个 |
| `/api/demo/{id}` | PUT | 更新 |
| `/api/demo/{id}` | DELETE | 删除（逻辑删除） |
| **Redis 示例**（Upstash 缓存） | | |
| `/api/cache/health` | GET | Redis 健康检查 |
| `/api/cache` | POST | 存缓存（Body: `{"key":"foo","value":"bar","ttl":60}`） |
| `/api/cache/{key}` | GET | 读缓存 |
| `/api/cache/{key}` | DELETE | 删缓存 |
| **Druid 监控** | | |
| `/druid/` | GET | 数据库连接池监控（用户名: admin / 密码: admin123） |

## 凭据来源

此 demo 直接复用 `wfly-spring/application-dev.yaml` 的真实配置：

| 组件 | 地址 | 说明 |
|---|---|---|
| **MySQL master** | `mysql6.sqlpub.com:3311/vftdream` | SQLPub 免费实例（用户 `vftdream`） |
| **Redis** | `hot-boa-127738.upstash.io` | Upstash 主库（TLS 端口 6379） |

⚠️ **注意**：
- Demo 数据会写入真实数据库（`demo_items` 表）
- 生产环境建议单独配置数据源（通过 HF Space Secrets 覆盖环境变量）

## 生产部署（完整架构）

本 demo 只演示最小可运行容器。要接入真实的数据库 / Redis / 自定义域名，见：

**📘 [ARCHITECTURE.md](./ARCHITECTURE.md) — 零成本生产级部署架构**

涵盖：
- 免费 MySQL（SQLPub 500MB）
- 免费 Redis（Upstash 10K 命令/天）
- CloudFlare DDNS（自定义域名 + CDN + WAF）
- Spring Boot 配置示例 + 环境变量注入 + 定时任务脚本