Spaces:
Runtime error
Runtime error
| 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 配置示例 + 环境变量注入 + 定时任务脚本 | |