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

Files

T

huangping 5fe7181b35 feat(i7): async webhook delivery queue, OPS RBAC, UI role routing; docs and runbook

- Architect: I7_DESIGN.md, I7_IMPLEMENTATION_REVIEW.md; parallel index + track B
- Backend: @EnableMethodSecurity; OPS login; CallbackInbox PreAuthorize; IntegrationCatalog triple role
- Webhook: V2 webhook_platform_delivery; planner + scheduler + single-shot forwarder; tests
- Frontend: Pinia hasAnyRole; MainLayout/HomeView/router for OPS vs dev
- Runbook §10.5 delivery config

Made-with: Cursor

2026-04-06 23:01:10 +08:00

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

10. I5/I6：内部 Token、Webhook → 平台与轮换

10.1 变量对照

组件	变量 / 配置键	说明
平台 `delivery-platform-api`	`PLATFORM_INTERNAL_TOKEN` 或 `CRAFTLABS_PLATFORM_INTERNAL_TOKEN` → `platform.internal.token`	校验入站 `X-Platform-Internal-Token`
Webhook `license-webhook-ingress`	`CRAFTLABS_PLATFORM_INTERNAL_TOKEN` → `craftlabs.platform.internal.token`	出站请求头，须与平台一致
Webhook	`PLATFORM_INTERNAL_BASE_URL` → `craftlabs.platform.internal.base-url`	平台根 URL，无尾斜杠；转发 `POST …/internal/v1/callback-events`

未配置 base-url 或 token 时，Webhook 仅落库收据，不向平台投递（本地可只验 bitanswer token）。

10.2 连通性自检（平台已启动）

# 将 <TOKEN> 与平台环境变量一致
curl -sS -o /dev/null -w "%{http_code}\n" \
  -X POST "http://127.0.0.1:8080/internal/v1/callback-events" \
  -H "Content-Type: application/json" \
  -H "X-Platform-Internal-Token: <TOKEN>" \
  -H "Idempotency-Key: runbook-probe-$(date +%s)" \
  -d '{"schemaVersion":"1.0","sourceSystem":"BITANSWER","externalMessageId":"runbook-probe-msg","eventType":"probe","rawPayload":{}}'

期望：401 表示路由可达但 Token 错误；400 可能为体缺字段；200 且 JSON 含 inboxId 表示鉴权与入队逻辑正常。

10.3 Token 轮换（简要）

在平台与 Webhook 同时配置新 Token（滚动窗口内可同时接受旧+新需改代码时另议；MVP 为单值，应选维护窗同步切换）。
重启平台 API，再重启 Webhook（避免 Webhook 仍用旧值调用已切换的平台）。
用 §10.2 探测；再在 UI Callback 收件箱 验证新事件可见。
审计：记录轮换时间与操作人（可另走工单）。

10.4 Flyway 历史表

平台：flyway_platform_api（迁移含 platform_callback_inbox、M6 表等）。
Webhook：flyway_webhook（V1 收据表、V2 webhook_platform_delivery 平台投递出库）。同一 PostgreSQL 实例 下两表共存，勿手动改名或合并。

10.5 I7：异步投递与调度（Webhook）

配置	说明
`craftlabs.platform.delivery.scheduler-enabled`	默认 `true`；单测/特殊场景可 `false`
`craftlabs.platform.delivery.tick-ms`	调度间隔（毫秒）
`craftlabs.platform.delivery.max-attempts`	单条投递最大尝试次数，超限标记 `DEAD`
`craftlabs.platform.delivery.batch-size`	每 tick 最多拉取条数

比特 Callback 2xx 在收据落库与 出站行入队 之后返回；真正 POST 平台由后台线程执行。DEAD 行需人工依据 last_error 与平台侧幂等处理。

6.3 KiB Raw Blame History Unescape Escape