README.md

metadata

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（本文）	快速入门 + 本地运行 + 基础部署
ARCHITECTURE.md	零成本生产级架构（MySQL / Redis / CloudFlare DDNS）
DEPLOY.md	部署 Checklist（逐步操作清单 + 常见问题）
application.yml.example	Spring Boot 配置模板
.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 和源码，干净又轻量。

本地运行（快速验证）

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

# 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（和线上环境一致）

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

验证接口

• 首页：http://localhost:7860 （含完整接口列表）
• MySQL CRUD：

  # 列表
  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 缓存：

  # 健康检查
  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

# 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 — 零成本生产级部署架构

涵盖：

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