# koupleless-springboot-demo

**Repository Path**: hivedark/koupleless-springboot-demo

## Basic Information

- **Project Name**: koupleless-springboot-demo
- **Description**: 测试koupeless
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Koupleless SpringBoot Demo

基于 Koupleless 的 SpringBoot 多业务服务示例项目，演示基座（Base）与业务（Biz）的混合部署架构。

## 功能特性

- **多 Biz 部署**：支持 biz1（用户服务）、biz2（订单服务）、biz3（商品服务）同时运行
- **热部署**：Biz jar 放入目录自动检测部署，支持 Web 控制台操作
- **MQTT 远程部署**：通过 MQTT 协议远程下发 biz 包
- **Web 控制台**：可视化管理仓库、部署/卸载 biz
- **隔离架构**：Base 提供共享依赖，Biz 使用 provided scope 不打包

## 快速开始

### 构建

```bash
mvn clean install -DskipTests
```

### 启动

```bash
java -jar base/base-bootstrap/target/base-bootstrap-1.0.0.jar
```

### 访问

| 服务 | 地址 |
|------|------|
| 入口首页 | http://localhost:8080/ |
| Web 控制台 | http://localhost:8080/console |
| 用户服务 | http://localhost:8080/biz1/users |
| 订单服务 | http://localhost:8080/biz2/orders |
| 商品服务 | http://localhost:8080/biz3/products |

## 项目结构

```
koupleless-springboot-demo/
├── base/                       # 基座（提供共享依赖）
│   └── base-bootstrap/         # 基座启动模块
├── biz1/                       # 用户服务（SQLite）
│   └── biz1-bootstrap/
├── biz2/                       # 订单服务（Redis）
│   └── biz2-bootstrap/
├── biz3/                       # 商品服务（MyBatis-Plus + SQLite）
│   └── biz3-bootstrap/
├── biz-jars/                   # 仓库目录（存储 biz jar）
├── biz-deploy/                 # 部署目录（UUID 隔离）
├── db/                         # SQLite 数据库目录
└── init/                       # 初始化脚本
```

## 目录说明

| 目录 | 用途 |
|------|------|
| `biz-jars/` | 仓库，存储 biz jar 文件 |
| `biz-deploy/` | 部署目录，UUID 子目录隔离，轮询检测自动部署 |

**目录可配置：**
```yaml
biz:
  jars-dir: biz-jars
  deploy-dir: biz-deploy
```

## 部署方式

### Web 控制台（推荐）

1. 访问 http://localhost:8080/console
2. 在 Repository 页面查看仓库中的 biz 及部署状态
3. 点击 **Deploy** 按钮部署，或 **Undeploy** 卸载

### MQTT 远程部署

**Topic:** `biz/deploy/command`

```json
{
  "bizName": "biz1",
  "bizJarPath": "https://example.com/biz1-1.0.0-ark-biz.jar"
}
```

`bizJarPath` 支持本地路径和 HTTP/HTTPS 地址。

**结果通知：** `biz/deploy/command/result`

### arkctl

```bash
arkctl deploy biz1-1.0.0-ark-biz.jar --port 1238
arkctl undeploy biz1:1.0.0 --port 1238
```

## 架构说明

### Base 与 Biz 依赖关系

**Base 提供依赖，Biz 使用 provided scope：**

| Base pom.xml（正常依赖） | Biz pom.xml（provided） |
|-------------------------|-------------------------|
| mybatis-plus-boot-starter | `<scope>provided</scope>` |
| spring-boot-starter-jdbc | `<scope>provided</scope>` |
| sqlite-jdbc | `<scope>provided</scope>` |
| spring-boot-starter-data-redis | `<scope>provided</scope>` |

### Base 自动配置排除

Base 有 MyBatis 依赖但不做数据库初始化：

```java
@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    MybatisPlusAutoConfiguration.class
})
```

## Biz 服务说明

| Biz | 数据存储 | 技术栈 |
|-----|---------|--------|
| biz1 | SQLite | JDBC（用户管理） |
| biz2 | Redis | Redis（订单管理） |
| biz3 | SQLite | MyBatis-Plus（商品管理） |

## 开发模式

独立运行 biz（使用 dev profile，不依赖 Base）：

```bash
java -jar biz1/biz1-bootstrap/target/biz1-bootstrap-1.0.0.jar --spring.profiles.active=dev
java -jar biz2/biz2-bootstrap/target/biz2-bootstrap-1.0.0.jar --spring.profiles.active=dev
java -jar biz3/biz3-bootstrap/target/biz3-bootstrap-1.0.0.jar --spring.profiles.active=dev
```

## 构建命令

```bash
# 全量构建
mvn clean install -DskipTests

# 只构建 base
mvn clean install -DskipTests -pl base/base-bootstrap -am

# 只构建 biz1
mvn clean install -DskipTests -pl biz1/biz1-bootstrap -am
```

### 构建产物

| 模块 | 路径 |
|------|------|
| 基座 | `base/base-bootstrap/target/base-bootstrap-1.0.0.jar` |
| biz1 | `biz1/biz1-bootstrap/target/biz1-bootstrap-1.0.0-ark-biz.jar` |
| biz2 | `biz2/biz2-bootstrap/target/biz2-bootstrap-1.0.0-ark-biz.jar` |
| biz3 | `biz3/biz3-bootstrap/target/biz3-bootstrap-1.0.0-ark-biz.jar` |

## 数据库

- **路径**：`jdbc:sqlite:./db/{bizName}.db`
- **初始化脚本**：`file:./init/schema.sql`, `file:./init/data.sql`
- **时间字段**：使用 `java.util.Date`（非 `LocalDateTime`）

### Thymeleaf 格式化

```html
<!-- 正确 -->
<td th:text="${#dates.format(user.createTime, 'yyyy-MM-dd HH:mm')}">-</td>
```

## MQTT 配置

```yaml
mqtt:
  enabled: true
  broker: tcp://192.168.77.3:1883
  client-id: base-service
  username: mqtt_admin
  password: 1q2w3e
  status:
    topic: biz/status/report
    interval: 10000
  deploy:
    topic: biz/deploy/command
```

## 技术栈

- Spring Boot: 2.7.16
- MyBatis-Plus: 3.5.4.1
- SQLite JDBC: 3.42.0.0
- SOFA Ark: 2.2.7
- Koupleless: 1.0.0