mirror of https://github.com/hpd840321/craftlabs-authorization-sdk.git synced 2026-06-09 10:00:30 +08:00

Files

T

huangping 3f577b34d5 feat(platform): I1 bootstrap, I2 M1 APIs, OpenAPI SSOT, and CI guards

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

2026-04-06 21:04:56 +08:00

3.5 KiB

Raw Blame History

平台后端部署 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. 构建产物

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

本地/联调示例：

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 等托管）：

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；回滚需 人工迁移脚本 或从备份恢复（生产变更前应备份）。

3.5 KiB Raw Blame History Unescape Escape