# 平台后端部署 Runbook（单机 Fat JAR）

面向 **广州创飞** 小团队：**单/双进程 `java -jar`** + **PostgreSQL 15**，无 K8s 前提。

## 1. 组件与端口

| 进程 | JAR | 默认端口 | 说明 |
|------|-----|----------|------|
| 交付平台 API | `delivery-platform-api-*-SNAPSHOT.jar` | **8080** | JWT、M1+ 领域 API、Flyway 表 **`flyway_platform_api`** |
| License Webhook | `license-webhook-ingress-*-SNAPSHOT.jar` | **8081** | 比特 Callback；Flyway 表 **`flyway_webhook`** |

两进程可部署在 **同一主机** 或 **两台主机**；共用同一数据库实例时，须使用 **不同 Flyway 历史表**（已在 `application.yml` 配置）。

## 2. 构建产物

```bash
mvn -f services/pom.xml -pl delivery-platform-api -am clean package
mvn -f services/pom.xml -pl license-webhook-ingress -am clean package
```

产物：`services/*/target/*.jar`（Spring Boot repackage）。

## 3. PostgreSQL 15

本地/联调示例：

```bash
docker compose -f services/docker-compose.yml up -d
```

默认库 `craftlabs_platform`、用户/密码 `craftlabs`/`craftlabs`（**生产须替换**）。

**网络**：数据库 **不对公网**；仅应用主机或 VPC 内可达。

## 4. 环境变量（摘要）

### 共用数据源（两服务均可）

| 变量 | 说明 |
|------|------|
| `SPRING_DATASOURCE_URL` | 例：`jdbc:postgresql://db:5432/craftlabs_platform` |
| `SPRING_DATASOURCE_USERNAME` | 数据库用户 |
| `SPRING_DATASOURCE_PASSWORD` | 数据库密码 |

### 平台 API 专有

| 变量 | 说明 |
|------|------|
| `PLATFORM_JWT_SECRET` | **必填（生产）**，长度 ≥ **32** 字符；用于签发/校验 JWT |
| `PLATFORM_JWT_EXPIRY_SECONDS` | 可选，默认 `43200`（12h） |

### Webhook 专有

| 变量 | 说明 |
|------|------|
| `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` | **生产强烈建议设置**；与请求头 `x-bitanswer-token` 一致 |

## 5. 启动顺序与迁移

- **Flyway**：各 JAR **首次启动** 时自动迁移；无强制先后，但 **同一库** 上两应用使用 **不同历史表**，互不覆盖。
- **建议**：先确认数据库已创建且账号可连，再先后启动 **API** 与 **Webhook**（顺序可互换）。

示例（生产请用 systemd/supervisor 等托管）：

```bash
export SPRING_DATASOURCE_URL=jdbc:postgresql://127.0.0.1:5432/craftlabs_platform
export SPRING_DATASOURCE_USERNAME=craftlabs
export SPRING_DATASOURCE_PASSWORD='********'
export PLATFORM_JWT_SECRET='至少32字符的随机密钥'

java -jar delivery-platform-api-0.1.0-SNAPSHOT.jar

# 另一终端
export CRAFTLABS_WEBHOOK_EXPECTED_TOKEN='与比特控制台配置一致'
java -jar license-webhook-ingress-0.1.0-SNAPSHOT.jar
```

## 6. 健康检查

- API：`GET http://127.0.0.1:8080/actuator/health`
- Webhook：`GET http://127.0.0.1:8081/actuator/health`

## 7. 契约与前端

- OpenAPI 快照：`contracts/openapi/delivery-platform-api.json`
- 运行时文档：`http://<api-host>:8080/swagger-ui.html`（生产建议 **限制 IP** 或 **关闭**）

前端静态资源由 **Nginx/Caddy** 托管，`/api` **反代** 至 8080；参见 `web/delivery-platform-ui` README / `vite` 开发代理配置。

## 8. 禁止事项（架构）

- 平台 **classpath 禁止** `craftlabs-auth-bitanswer`（Maven Enforcer + CI 门禁）；详见根目录 `contracts/README.md` 与 `services/pom.xml` 说明。

## 9. 回滚

- 应用：回退上一版 JAR 并重启。
- 数据库：Flyway **无自动 down**；回滚需 **人工迁移脚本** 或从备份恢复（生产变更前应备份）。