mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00:30 +08:00
huangping
3f577b34d5
Deliver dual Spring Boot services (platform API + webhook ingress), JWT auth, Flyway with isolated history tables, customer/project/dictionary endpoints, OpenAPI snapshot under contracts/, RUNBOOK, and CI that runs on services/web/contracts paths plus enforcer + dependency tree ban on craftlabs-auth-bitanswer. Made-with: Cursor
98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# 平台后端部署 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**；回滚需 **人工迁移脚本** 或从备份恢复（生产变更前应备份）。
|