mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00:30 +08:00
huangping
76ff98db87
Add PARALLEL_ITERATION_INDEX, workspace layout, system architecture, three-track execution packs, BPM/product references, and planned service manifests. Supports I1 alignment across backend, web, and SDK. Made-with: Cursor
563 lines
27 KiB
Markdown
563 lines
27 KiB
Markdown
# 系统架构设计 — 全景图与组件清单
|
||
|
||
> **角色**：资深架构师视角的 **系统上下文、容器划分、逻辑组件、数据流与部署边界** 的单一汇总页。
|
||
> **读者**：研发、测试、运维、产品与集成方。
|
||
> **关联**：[工作区工程划分](./WORKSPACE_ENGINEERING_LAYOUT.md) · [并行迭代索引](./PARALLEL_ITERATION_INDEX.md) · [功能模块 M1–M11](../chuangfei-platform-product-modules.md) · [比特对接总览](../chuangfei-bitanswer-integration-platform.md) · [`engineering/workspace-manifest.json`](../../engineering/workspace-manifest.json)
|
||
> **安全专章**：本章 **§9**（含 **§9.0** 小团队阶段、**§9.8** SDK 发布完整性）；与工作区 [WORKSPACE §10 安全边界](./WORKSPACE_ENGINEERING_LAYOUT.md) 互补。
|
||
|
||
---
|
||
|
||
## 1. 架构目标与原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **边界清晰** | **客户端授权运行时**（SDK + Native + 现场进程）与 **商业交付平台**（Web + 双后端 + 数据持久化）在 **依赖、发布周期、classpath** 上严格分离。 |
|
||
| **契约先行** | 客户端配置以 **`schemas/craftlabs-auth-config.schema.json`** 为契约；Callback / OpenAPI 以 **文档与版本化契约** 对齐多轨迭代（见 [PARALLEL_ITERATION_INDEX](./PARALLEL_ITERATION_INDEX.md)）。 |
|
||
| **可运维** | 每个可独立扩缩的后端服务 **一枚 Fat JAR**（`spring-boot-maven-plugin` **repackage** 仅挂在启动模块）；密钥与连接串 **不进** SDK 与示例仓库。 |
|
||
| **数据栈锁定** | 平台持久化：**PostgreSQL 15** + **MyBatis-Plus**（详见 [WORKSPACE_ENGINEERING_LAYOUT §9.1](./WORKSPACE_ENGINEERING_LAYOUT.md)）。 |
|
||
| **安全默认** | **最小权限**、**纵深防御**、**可审计**；对外入口 **TLS**；敏感面（Webhook、管理 API、SN/许可数据）**单独威胁建模**与门禁。 |
|
||
| **阶段目标（创飞当前）** | **小团队**：优先 **功能与需求闭环**；并发与规模 **不高**。平台侧 **单/双 Fat JAR + 单机或少量 VM** 上 `java -jar` 即可；**不将 K8s、云 KMS、服务网格** 作为现阶段必选项，待业务量与合规要求上升再演进。 **安全重心** 放在 **已发布 SDK 的完整性**（不易被 **替换、假冒**），见 **§9.0 / §9.8**。 |
|
||
|
||
---
|
||
|
||
## 2. 系统上下文（C4 Level 1）
|
||
|
||
展示本体系与 **外部环境** 的关系：谁使用谁、谁回调谁。
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Actors["参与者"]
|
||
OPS[运维/管理员]
|
||
BIZ[商务/交付/License Ops]
|
||
DEV[客户侧研发]
|
||
end
|
||
|
||
subgraph CraftLabs["创飞侧系统（本方案范围）"]
|
||
UI[交付管理平台 Web UI]
|
||
API[交付平台 API]
|
||
WH[License Webhook Ingress]
|
||
DB[(PostgreSQL 15)]
|
||
end
|
||
|
||
subgraph ClientSite["客户现场 / 边缘环境"]
|
||
APP[客户业务应用]
|
||
SDK[CraftLabs 授权 SDK]
|
||
NAT[BitAnswer Native 库]
|
||
end
|
||
|
||
subgraph External["外部系统"]
|
||
BA[比特安索云 / 控制台]
|
||
end
|
||
|
||
OPS --> UI
|
||
BIZ --> UI
|
||
UI --> API
|
||
API --> DB
|
||
WH --> DB
|
||
WH -->|内部 HTTP / MQ 异步| API
|
||
|
||
BA -->|规则 Callback HTTPS POST| WH
|
||
SDK -->|Bit_Login / 许可 API| BA
|
||
APP --> SDK
|
||
SDK --> NAT
|
||
|
||
DEV -->|依赖 Maven 工件 + JSON 配置| SDK
|
||
DEV -.->|阅读 Schema/文档| CraftLabs
|
||
```
|
||
|
||
**读图要点**：
|
||
|
||
- **比特** 只与 **Webhook**（服务端入站）和 **SDK**（客户端出站授权）发生 **不同方向** 的交互；平台 UI **不** 替代 SDK 完成现场授权。
|
||
- **SDK 不依赖** 平台 API 运行时；二者仅通过 **契约（Schema、文档、可选 OpenAPI 导出配置）** 弱耦合。
|
||
|
||
---
|
||
|
||
## 3. 容器架构（C4 Level 2）
|
||
|
||
本工作区与规划仓库中的 **可构建、可部署或可分发单元**。
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Browser["用户浏览器"]
|
||
SPA[Vue 3 SPA<br/>delivery-platform-ui]
|
||
end
|
||
|
||
subgraph DMZ["接入层（可选 Gateway）"]
|
||
GW[API Gateway / 反向代理<br/>规划]
|
||
end
|
||
|
||
subgraph SimpleHost["机房或云主机（单机为主）"]
|
||
JAR_API[delivery-platform-api<br/>Fat JAR :8080]
|
||
JAR_WH[license-webhook-ingress<br/>Fat JAR :8081]
|
||
PG[(PostgreSQL 15)]
|
||
MQ[[消息队列<br/>可选·低并发可省]]
|
||
end
|
||
|
||
subgraph ArtifactRepo["制品与契约"]
|
||
MVN[Maven：cn.craftlabs / cn.craftlabs.platform]
|
||
SCH[JSON Schema + examples]
|
||
NATIVE[各 OS Native 动态库]
|
||
end
|
||
|
||
subgraph CI["持续集成"]
|
||
WF_SDK[ci-java.yml]
|
||
WF_PLAT[ci-platform.yml]
|
||
end
|
||
|
||
SPA -->|HTTPS /api| JAR_API
|
||
GW -.-> JAR_API
|
||
GW -.-> JAR_WH
|
||
JAR_API --> PG
|
||
JAR_WH --> PG
|
||
JAR_WH -.-> MQ
|
||
MQ -.-> JAR_API
|
||
|
||
MVN --> APPX[客户应用构建]
|
||
SCH --> APPX
|
||
NATIVE --> APPX
|
||
|
||
WF_SDK --> MVN
|
||
WF_PLAT --> JAR_API
|
||
WF_PLAT --> JAR_WH
|
||
WF_PLAT --> SPA
|
||
```
|
||
|
||
**阶段说明（创飞当前）**：并发不高时 **可不部署 MQ**（Webhook 直写库或由 API 轮询即可）；后端以 **一台或两台云主机** 各跑 `java -jar …` 为主，**无需 K8s**。
|
||
|
||
| 容器 | 技术 / 形态 | 默认端口或产出 | 职责摘要 |
|
||
|------|-------------|----------------|----------|
|
||
| **delivery-platform-ui** | Vue 3 + Vite + Pinia + Element Plus | 静态资源 / dev server | 管理端 SPA：登录、领域页面、调用平台 REST。 |
|
||
| **delivery-platform-api** | Spring Boot 3.4.x（目标 4.0.x）、Security、Actuator、MyBatis-Plus | **8080**、Fat JAR | 领域 API、认证、M1–M11 业务能力、读写字段库。 |
|
||
| **license-webhook-ingress** | Spring Boot、Actuator | **8081**、Fat JAR | 比特 Callback 入站、验签/Token、快速 2xx、异步投递（表/MQ）。 |
|
||
| **PostgreSQL** | 15.x | 5432 | 平台主库；与 SDK **无** 直连。 |
|
||
| **SDK Java 模块** | 多模块 Maven，**非** Spring Boot | 多枚 `craftlabs-auth-*.jar` | 配置模型、BitAnswer 桥接、自托管占位等。 |
|
||
| **Native** | CMake | `.so` / `.dylib` / `.dll` | 比特官方运行时绑定，随 SDK 版本发布。 |
|
||
| **schemas + examples** | JSON Schema、样例 JSON | 无进程 | 配置契约与集成样例。 |
|
||
|
||
---
|
||
|
||
## 4. 平台后端逻辑组件（领域视图）
|
||
|
||
与产品模块 **M1–M11** 对齐的 **逻辑分包**（实现可跨多 Maven 模块，但边界应一致）。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph API["delivery-platform-api（逻辑）"]
|
||
M11[identity / platform M11]
|
||
M1[customer-project M1]
|
||
M2[contract M2]
|
||
M3[delivery M3]
|
||
M4[licensing SN M4]
|
||
M5[inbox callback M5]
|
||
M6[integration mapping M6]
|
||
M7[device M7]
|
||
M8[notification M8]
|
||
M9[reporting M9]
|
||
M10[audit M10]
|
||
PERS[persistence MyBatis-Plus]
|
||
end
|
||
|
||
M11 --> M1
|
||
M1 --> M2
|
||
M2 --> M3
|
||
M2 --> M4
|
||
M3 --> M4
|
||
M6 --> M4
|
||
M5 --> M4
|
||
M4 --> M7
|
||
M5 --> M8
|
||
M4 --> M9
|
||
M1 & M2 & M3 & M4 & M5 --> M10
|
||
|
||
M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 & M9 & M10 & M11 --> PERS
|
||
```
|
||
|
||
**Webhook 侧（license-webhook-ingress）逻辑组件**（精简）：
|
||
|
||
| 组件 | 职责 |
|
||
|------|------|
|
||
| **Ingress Controller** | 接收 POST、限流与尺寸约束（规划加固）。 |
|
||
| **Token / 签名验证** | `x-bitanswer-token` 或约定头；与 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 等环境变量对齐。 |
|
||
| **幂等与投递** | `Idempotency-Key` 或 payload 内事件 ID；写入 **inbox** 或 **MQ**（I5+），由平台 API 消费。 |
|
||
| **观测** | Actuator、结构化日志、指标（与平台统一约定）。 |
|
||
|
||
---
|
||
|
||
## 5. 客户端 SDK 组件（本仓库 `java/` + `native/`）
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph SDK["CraftLabs Authorization SDK"]
|
||
CORE[craftlabs-auth-core<br/>配置 / NativeBridge / 校验]
|
||
BIT[craftlabs-auth-bitanswer<br/>Provider + loadLibrary]
|
||
SH[craftlabs-auth-selfhosted<br/>占位实现]
|
||
TST[craftlabs-auth-tests]
|
||
end
|
||
|
||
SCH2[schemas + examples]
|
||
JNI[libcraftlabs_auth_bitanswer]
|
||
|
||
CORE --> BIT
|
||
CORE --> SH
|
||
BIT --> JNI
|
||
TST --> CORE
|
||
SCH2 -.-> CORE
|
||
```
|
||
|
||
**硬约束**：平台服务端 **禁止** 依赖 `craftlabs-auth-bitanswer` 与 **禁止** `System.loadLibrary("craftlabs_auth_bitanswer")`（见 [WORKSPACE §5](./WORKSPACE_ENGINEERING_LAYOUT.md)）。
|
||
|
||
---
|
||
|
||
## 6. 关键运行时序
|
||
|
||
### 6.1 比特 Callback → 平台
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant BA as 比特安索云
|
||
participant WH as license-webhook-ingress
|
||
participant Store as PG / MQ
|
||
participant API as delivery-platform-api
|
||
participant UI as 管理端 UI
|
||
|
||
BA->>WH: POST /webhook/bitanswer/callback
|
||
WH->>WH: 校验 Token / 幂等键
|
||
WH->>Store: 持久化或入队（异步）
|
||
WH-->>BA: 2xx 快速响应
|
||
API->>Store: 拉取 / 消费事件
|
||
UI->>API: 查询 Inbox / 处置状态
|
||
```
|
||
|
||
### 6.2 管理员使用平台
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户
|
||
participant UI as delivery-platform-ui
|
||
participant API as delivery-platform-api
|
||
participant DB as PostgreSQL 15
|
||
|
||
U->>UI: 登录 / 操作业务页
|
||
UI->>API: REST（Session / JWT 由迭代约定）
|
||
API->>DB: MyBatis-Plus 读写
|
||
API-->>UI: DTO / 错误码
|
||
```
|
||
|
||
### 6.3 客户现场授权（与平台解耦）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant APP as 客户应用
|
||
participant SDK as craftlabs-auth-*
|
||
participant NAT as Native
|
||
participant BA as 比特安索云
|
||
|
||
APP->>SDK: 初始化 + 加载配置 JSON
|
||
SDK->>SDK: Schema/规则校验（可选）
|
||
SDK->>NAT: JNI 调用
|
||
NAT->>BA: 许可 / 登录协议
|
||
BA-->>NAT: 授权结果
|
||
NAT-->>SDK: 回调结果
|
||
SDK-->>APP: 授权状态 / 特征项
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 全量组件清单（Master Inventory）
|
||
|
||
下表覆盖 **本工作区已实现或已占位** 的组件；规划项标注为 **（规划）**。
|
||
|
||
| ID | 组件名称 | 类型 | 路径 / 坐标 / 产物 | 技术栈 | 主要职责 |
|
||
|----|----------|------|-------------------|--------|----------|
|
||
| C01 | **craftlabs-auth-parent** | Maven 聚合 | `java/pom.xml` | Java 17 | SDK 父工程、依赖与模块编排。 |
|
||
| C02 | **craftlabs-auth-core** | Library JAR | `java/craftlabs-auth-core` | Java | 配置模型、`NativeBridge`、与 Schema 对齐的校验入口。 |
|
||
| C03 | **craftlabs-auth-bitanswer** | Library JAR | `java/craftlabs-auth-bitanswer` | Java + JNI | `BitAnswerProvider`、`System.loadLibrary`、**仅客户端**。 |
|
||
| C04 | **craftlabs-auth-selfhosted** | Library JAR | `java/craftlabs-auth-selfhosted` | Java | 自托管授权占位 / 扩展点。 |
|
||
| C05 | **craftlabs-auth-tests** | 测试模块 | `java/craftlabs-auth-tests` | JUnit 等 | SDK 侧集成与回归测试。 |
|
||
| C06 | **libcraftlabs_auth_bitanswer** | Native | `native/` | CMake | 各平台动态库，与 C02/C03 **同版本发布**。 |
|
||
| C07 | **craftlabs-auth-config Schema** | 契约 | `schemas/craftlabs-auth-config.schema.json` | JSON Schema Draft 2020-12 | 客户端配置 **单一契约**；CI 与 SDK 测试可对齐校验。 |
|
||
| C08 | **examples** | 样例 | `examples/` | JSON / 脚本 | 配置样例与烟测引用。 |
|
||
| C09 | **documentation** | 文档 | `docs/` | Markdown | 产品、对接、工程、架构。 |
|
||
| C10 | **engineering-meta** | 元数据 | `engineering/` | JSON / MD | `workspace-manifest.json`、planned 占位、README 索引。 |
|
||
| C11 | **craftlabs-platform-services-parent** | Maven 聚合 | `services/pom.xml` | Java 17 + Spring Boot 3.4.x | 平台后端父 POM；**与 C01 分构建线**。 |
|
||
| C12 | **delivery-platform-api** | 可执行 Fat JAR | `services/delivery-platform-api` | Spring Web/Security/Actuator、MyBatis-Plus、PostgreSQL 驱动 | 平台 REST、领域逻辑（迭代扩展）、**8080**。 |
|
||
| C13 | **license-webhook-ingress** | 可执行 Fat JAR | `services/license-webhook-ingress` | Spring Web/Actuator | Callback 入站、Token、**8081**。 |
|
||
| C14 | **PostgreSQL** | 基础设施 | 部署环境 / `services/docker-compose.yml` | 15.x | 平台主数据存储。 |
|
||
| C15 | **delivery-platform-ui** | SPA | `web/delivery-platform-ui` | Vue 3、Vite、Pinia、vue-router、axios、Element Plus | 管理端界面；dev 代理 `/api` → API。 |
|
||
| C16 | **CI：SDK Java** | 流水线 | `.github/workflows/ci-java.yml` | GitHub Actions | `java/` 构建与测试（JDK 版本以 workflow 为准）。 |
|
||
| C17 | **CI：Platform + Web** | 流水线 | `.github/workflows/ci-platform.yml` | GitHub Actions | `services/` Maven verify + `web/` npm build。 |
|
||
| C18 | **API Gateway** | 接入（规划） | 未在本仓 | 待定 | 统一 TLS、路由、限流（可选）。 |
|
||
| C19 | **Message Queue** | 中间件（规划） | 未在本仓 | 待定 | Webhook 与 API 解耦、削峰（I5+ 常见形态）。 |
|
||
| C20 | **企业 IdP** | 身份（规划） | 未在本仓 | OIDC/SAML 等 | 与 M11 企业登录集成（若需）。 |
|
||
| C21 | **密钥与凭据** | 运维配置 | 部署机 | **环境变量**、**chmod 600 配置文件** | 注入 Webhook Token、DB 密码；**禁止** 进 Git；**不强制** 云 KMS。 |
|
||
| C22 | **WAF / 边缘限流** | 安全（可选） | 边界 | 云 WAF 或 Nginx 限流模块 | 低并发阶段可省；对外暴露或合同要求时再上。 |
|
||
|
||
---
|
||
|
||
## 8. 技术栈总览
|
||
|
||
| 分层 | 选型 | 备注 |
|
||
|------|------|------|
|
||
| 管理端 | Vue 3、Vite、Pinia、vue-router、axios、Element Plus | 构建产物静态托管或 CDN。 |
|
||
| 平台 API | Spring Boot 3.4.x（路线图 4.0.x）、Spring Security、Actuator | Fat JAR 部署。 |
|
||
| Webhook | 同上（独立进程） | 与 API **进程隔离**，失败域分离。 |
|
||
| ORM | MyBatis-Plus（`mybatis-plus-spring-boot3-starter`） | Boot 4 时切换 `boot4-starter`。 |
|
||
| 数据库 | PostgreSQL 15 | 测试可用 H2 PG 模式或 Testcontainers。 |
|
||
| 客户端 SDK | Java 17、多模块薄 JAR | 不打 Spring Boot repackage。 |
|
||
| 客户端 Native | CMake、比特官方 API | 与 Java **同版本 tag**。 |
|
||
| 契约 | JSON Schema 2020-12 | `schemas/` 与 `examples/`。 |
|
||
|
||
---
|
||
|
||
## 9. 安全架构（授权与平台）
|
||
|
||
授权与许可数据直接影响 **商业履约与合规**，安全需求高于一般内部后台。本节给出 **信任边界、威胁面、控制措施与演进要求**，供架构评审与渗透测试对齐。
|
||
|
||
### 9.0 阶段与重心（广州创飞 · 小团队）
|
||
|
||
| 维度 | 当前立场 |
|
||
|------|----------|
|
||
| **部署** | **单 Fat JAR / 进程** 部署在云主机或内网服务器；PostgreSQL 可与应用 **同机或同 VPC 内另一台**；**不强制** 容器编排与云 KMS。 |
|
||
| **密钥** | Webhook Token、数据库密码等放在 **宿主机环境变量** 或 **权限受限的配置文件**（`chmod 600`、仅运行用户可读），**绝不** 提交 Git。 |
|
||
| **优先级** | 先保证 **功能与需求闭环**；平台侧 **基础 TLS + 认证 + 日志脱敏** 即可满足多数早期场景。 |
|
||
| **安全重心** | **对外发布的 SDK（JAR + Native）**：防范 **供应链篡改与假冒制品**；**破解/逆向** 的硬防线主要在 **比特安索 Native 与许可密码学**，Java 层需 **诚实评估**（见 **§9.8**）。 |
|
||
|
||
### 9.1 安全目标（CIA + 授权特有）
|
||
|
||
| 目标 | 含义 | 在本体系的落点 |
|
||
|------|------|----------------|
|
||
| **机密性** | 许可状态、SN、合同金额、Callback 原文、密钥不外泄 | TLS、日志脱敏、DB 访问控制、前端不持久化敏感令牌到不安全存储 |
|
||
| **完整性** | Callback 与台账不被篡改；配置与制品未被替换 | Webhook 验签/共享密钥、幂等键、审计日志（M10）、依赖与镜像签名（供应链） |
|
||
| **可用性** | 授权链路与管理端在约定 SLA 内可服务 | Webhook 快速 2xx + 异步处理；低并发阶段 **单机 + 健康检查** 即可，**不必** 预设 K8s 弹性扩容 |
|
||
| **不可否认性**（按需） | 关键操作可追溯 | 审计表、WORM 或日志外送（合规场景） |
|
||
|
||
### 9.2 信任边界
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Untrusted["不可信或半可信"]
|
||
Internet((Internet))
|
||
BA[比特云]
|
||
CustomerNet[客户现场网络]
|
||
Dev[集成方研发环境]
|
||
end
|
||
|
||
subgraph TrustHigh["高信任 — 创飞数据面"]
|
||
PG[(PostgreSQL)]
|
||
Secrets[(凭据：宿主机环境变量<br/>或受限配置文件)]
|
||
end
|
||
|
||
subgraph TrustMed["中信任 — 应用进程"]
|
||
API[delivery-platform-api]
|
||
WH[license-webhook-ingress]
|
||
end
|
||
|
||
subgraph TrustUser["用户终端"]
|
||
Browser[管理员浏览器]
|
||
ClientApp[客户业务进程 + SDK]
|
||
end
|
||
|
||
Internet -->|TLS 仅| WH
|
||
Internet -->|TLS 仅| API
|
||
Internet --> Browser
|
||
BA -->|HTTPS Callback| WH
|
||
CustomerNet --> ClientApp
|
||
Dev -.->|Maven/文档| ClientApp
|
||
|
||
Browser -->|HTTPS + 会话/JWT| API
|
||
ClientApp -->|TLS 至比特/自托管| BA
|
||
|
||
WH --> PG
|
||
API --> PG
|
||
API --> Secrets
|
||
WH --> Secrets
|
||
```
|
||
|
||
**边界规则**：
|
||
|
||
- **Webhook URL** 暴露在公网或 DMZ：视为 **持续被扫描**；必须 **TLS + 强认证 + 限流 + 最小响应体**。
|
||
- **管理端 API**：仅对 **已认证主体** 开放业务写能力；**禁止** 将平台账号用于客户现场 SDK。
|
||
- **SDK 配置 JSON**：含 `bitanswer.url`、`applicationData`、特征映射等，属 **客户环境机密**；**不得** 回传至创飞平台作为默认遥测（除非单独签署数据处理协议并做脱敏设计）。
|
||
|
||
### 9.3 威胁面与缓解（摘要）
|
||
|
||
| 威胁 | 示例 | 架构层缓解 |
|
||
|------|------|------------|
|
||
| **伪造 Callback** | 攻击者 POST 恶意 payload | **共享密钥**（如 `x-bitanswer-token` 与 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 常量时间比较）；**比特官方 IP/证书钉扎**（若文档支持）；**payload 大小与 JSON 深度限制** |
|
||
| **重放** | 重复投递同一事件污染台账 | **幂等键**（`Idempotency-Key` / 事件 ID）+ 唯一约束；重复返回成功语义 |
|
||
| **撞库 / 会话窃取** | 管理端弱口令、Token 泄露 | **密码策略 / MFA（规划）**、**HttpOnly + Secure Cookie** 或 **短期 JWT + 刷新**、**CORS 严格白名单** |
|
||
| **越权** | 用户访问他人合同或 SN | **RBAC（M11）**、**行级授权**（组织/客户维度）、API **资源级鉴权** |
|
||
| **注入** | SQL / 反序列化 | **参数化查询**（MyBatis `#{}`）、**禁用不安全的反序列化 gadget**、DTO 白名单 |
|
||
| **SSRF**（若存在出站拉取） | 服务端替用户请求内网 | **出站 URL 白名单**、**禁用 file://**、独立网络分区 |
|
||
| **供应链 / 假冒 SDK** | 第三方镜像站替换 JAR、客户误下「绿色版」 | **官方唯一分发渠道** + **GPG/SHA-256 校验**（§9.8）；Maven 依赖 **锁定版本**；CI **依赖漏洞扫描**（力所能及） |
|
||
| **日志泄露** | Callback 原文、Token 打日志 | **结构化日志字段脱敏**、**禁止 debug 打印完整 Authorization** |
|
||
|
||
### 9.4 分组件控制要求
|
||
|
||
#### 9.4.1 `license-webhook-ingress`
|
||
|
||
| 控制项 | 要求 |
|
||
|--------|------|
|
||
| 传输 | **仅 HTTPS**；HTTP 仅允许本机健康检查（若必须）且不得承载业务 |
|
||
| 认证 | 配置 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN` 时 **强制校验** `x-bitanswer-token`（或比特约定头）；生产 **禁止** 长期关闭校验 |
|
||
| 处理 | **先校验后解析大对象**；限制 body 大小；超时快速失败仍返回约定错误码（避免资源耗尽） |
|
||
| 观测 | 日志记录 **事件 ID、幂等键、结果码**；**不** 记录完整密钥与完整 payload（或脱敏后） |
|
||
| 网络 | 云厂商 **安全组** 仅开放 443/业务端口；数据库 **不对公网**；单机阶段 **本机回环或内网 IP** 连库即可 |
|
||
|
||
#### 9.4.2 `delivery-platform-api`
|
||
|
||
| 控制项 | 要求 |
|
||
|--------|------|
|
||
| 认证 | I1 演示账号 **不得用于生产**；生产至少 **强口令**；团队具备条件时再上 **MFA / 企业 IdP（C20）** |
|
||
| 授权 | 每个 mutating 接口 **显式角色/权限**；与 M11 角色矩阵一致 |
|
||
| 数据 | DB 账号 **最小权限**（读写分离账号可选）；连接串来自 **环境变量或宿主机配置**，禁止提交仓库 |
|
||
| Actuator | **生产关闭或仅本机访问** `env`、`heapdump`；`health` 可给 **本机监控脚本或 Nginx 探活** |
|
||
| CORS | **显式允许源**，禁用 `*` 携带凭证 |
|
||
|
||
#### 9.4.3 `delivery-platform-ui`
|
||
|
||
| 控制项 | 要求 |
|
||
|--------|------|
|
||
| 存储 | **不** 将 refresh token 写入 `localStorage`（优先 HttpOnly Cookie 或安全内存策略） |
|
||
| CSP | 生产启用 **Content-Security-Policy**，限制内联脚本与未知域 |
|
||
| 依赖 | `npm audit` 纳入 CI；锁定 lockfile |
|
||
|
||
#### 9.4.4 客户端 SDK 与 Native
|
||
|
||
| 控制项 | 要求 |
|
||
|--------|------|
|
||
| 配置 | `craftlabs-auth-config` 由 **宿主应用** 安全加载（文件权限、必要时磁盘加密）；**禁止** 将含敏感字段的示例提交到客户代码库模板 |
|
||
| 完整性 | Native **与 JAR 同版本** 分发；**正式发布** 必须带 **校验与/或签名**（见 **§9.8**） |
|
||
| 运行时 | **不信任** 客户进程内存防护；敏感字符串尽量 **缩短生命周期**（比特 SDK 能力范围内） |
|
||
|
||
#### 9.4.5 PostgreSQL
|
||
|
||
| 控制项 | 要求 |
|
||
|--------|------|
|
||
| 网络 | DB **不暴露公网**；仅应用子网可达 |
|
||
| 加密 | 云盘默认加密或宿主机全盘加密即可；敏感列 **应用层加密** 为可选增强 |
|
||
| 审计 | 高危 DML/DDL 与 **管理员账号** 变更记入 M10 或 DB 审计扩展 |
|
||
|
||
### 9.5 与时序对齐的安全步骤（示意）
|
||
|
||
**Callback（补充安全步骤）**：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant BA as 比特安索云
|
||
participant WH as Webhook
|
||
participant Store as PG/MQ
|
||
|
||
BA->>WH: TLS + POST
|
||
WH->>WH: TLS 终结校验（mTLS 仅在高合规客户场景考虑）
|
||
WH->>WH: 校验 Token（常量时间）
|
||
WH->>WH: 限制 body 大小 + 解析
|
||
WH->>WH: 幂等键去重
|
||
WH->>Store: 写入 inbox（脱敏日志）
|
||
WH-->>BA: 2xx
|
||
```
|
||
|
||
**管理端（补充安全步骤）**：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户
|
||
participant UI as SPA
|
||
participant API as Platform API
|
||
|
||
U->>UI: 登录
|
||
UI->>API: HTTPS + CSRF 防护（Cookie 模式）
|
||
API->>API: 认证 + 颁发会话/JWT
|
||
UI->>API: 业务请求 + 凭证
|
||
API->>API: 鉴权（角色 + 资源）
|
||
API-->>UI: 最小必要 DTO
|
||
```
|
||
|
||
### 9.6 合规与审计衔接
|
||
|
||
- **M10 审计与合规**：登录、合同变更、SN 绑定/解绑、Callback 处置、权限变更等 **必须** 产生不可抵赖审计记录（谁、何时、对象 ID、前后摘要）。
|
||
- **数据出境**：若 Callback 或日志含个人信息，需对齐 **个人信息保护法** 与客户 DPA。
|
||
- **渗透测试**：有对外暴露或合同要求时，对 **Webhook** 与 **管理 API** 做专项测试（认证绕过、IDOR、批量枚举）；小团队可 **采购外包渗透** 或分阶段补做。
|
||
|
||
### 9.7 架构评审安全清单（节选）
|
||
|
||
- [ ] Webhook 生产环境 **已启用** 共享密钥或更强机制（签名/HMAC 以比特文档为准）。
|
||
- [ ] 管理 API **无** 默认弱口令路径；Actuator 敏感端点 **已收敛**。
|
||
- [ ] 平台与 Webhook **未引入** `craftlabs-auth-bitanswer`。
|
||
- [ ] 日志与异常栈 **无** 明文数据库密码、Token、完整 Callback。
|
||
- [ ] OpenAPI 中 **错误码** 不泄露内部堆栈或枚举用户存在性（登录接口需谨慎）。
|
||
- [ ] `examples/config/*.json` **无** 真实生产 URL/密钥（仅占位）。
|
||
- [ ] **SDK 发布**：每个对外版本具备 **SHA-256 清单**；**强烈建议** GPG 签名与 **唯一官方下载说明**。
|
||
- [ ] **SDK 发布**：`java` 与 `native` **同 tag**，CHANGELOG 与交付说明 **可追溯**。
|
||
|
||
### 9.8 SDK 发布完整性（当前安全重心）
|
||
|
||
客户侧 **Java 字节码可被反编译**，单靠混淆无法对抗动机足够的攻击者。**真正承担许可与密码学校验的**，应是 **比特安索 Native 与云端许可体系**。创飞 SDK 的安全目标应定位为：
|
||
|
||
1. **防篡改、防假冒**：客户拿到的是 **官方构建** 的 JAR/Native，未被中间人替换。
|
||
2. **防版本错配**：JAR 与 `.so/.dylib/.dll` **同一次发布**（同 Git tag / 同一 Release 页），避免「新 JAR + 旧库」导致异常或绕过路径。
|
||
3. **可追溯**：出问题能对照 **确切版本与校验和** 复现。
|
||
|
||
| 措施 | 说明 | 小团队可执行性 |
|
||
|------|------|------------------|
|
||
| **官方唯一渠道** | 仅通过 **公司控制的 Maven 私服 / GitHub Release / 合同交付包** 分发；**禁止** 引导客户从匿名网盘、论坛下载「整合包」。 | 必做 |
|
||
| **SHA-256 清单** | 每个 Release 发布 `SHA256SUMS`；仓库内 **`scripts/sdk-release-checksums.sh`** 已落地，说明见 **`java/RELEASING.md`**；客户用 `sha256sum -c` / `shasum -a 256 -c` 校验。 | 必做 |
|
||
| **GPG 签名** | Maven：**`mvn -f java/pom.xml -Prelease-sign verify`**（`maven-gpg-plugin`，各 JAR 旁生成 `.asc`）；清单文件：`SIGN=1` 跑上述脚本生成 `SHA256SUMS.asc`。公布 **公钥指纹** 固定页。 | 强烈建议 |
|
||
| **Git Tag = 发布单元** | `java/` 与 `native/` **同一 tag** 打发布；CHANGELOG 写清 **兼容的比特 SDK 版本**。 | 必做 |
|
||
| **依赖锁定** | 客户工程使用 **明确版本号** 或 BOM；避免「浮动版本」被投毒依赖间接替换。 | 建议 |
|
||
| **ProGuard 等混淆** | 仅增加逆向成本，**不能**替代 Native 侧安全；若上，只作 **非关键路径** 的辅助手段。 | 可选 |
|
||
| **法务条款** | 许可协议中约定 **禁止反编译、再分发**（民事约束，与技术防护互补）。 | 建议 |
|
||
|
||
**客户集成检查清单（可印在交付文档）**：
|
||
|
||
- [ ] JAR/Native 均来自 **创飞官方渠道**，并已核对 **SHA-256**（或验签）。
|
||
- [ ] 各工件版本号 **一致**，与发布说明中的 **比特依赖版本** 一致。
|
||
- [ ] 未混入第三方「破解补丁」或修改版 `libcraftlabs_auth_bitanswer`。
|
||
|
||
---
|
||
|
||
## 10. 部署与网络（简图）
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Public["公网 / 比特侧可达"]
|
||
BA[比特 Callback 出口 IP]
|
||
end
|
||
|
||
subgraph Perimeter["边界（常为一台 Nginx/Caddy）"]
|
||
LB[TLS 终结 + 反代]
|
||
end
|
||
|
||
subgraph AppTier["应用层（单机或双机 java -jar）"]
|
||
WH_P[Webhook Fat JAR]
|
||
API_P[Platform API Fat JAR]
|
||
UI_S[静态 UI 或同机 Nginx 托管]
|
||
end
|
||
|
||
subgraph DataTier["数据层"]
|
||
PG_P[PostgreSQL 15<br/>单实例或云托管]
|
||
end
|
||
|
||
BA --> LB --> WH_P
|
||
Users((管理员浏览器)) --> LB --> UI_S
|
||
Users --> LB --> API_P
|
||
WH_P --> PG_P
|
||
API_P --> PG_P
|
||
```
|
||
|
||
**阶段注记（创飞当前）**：**不依赖 K8s**；扩容以 **加机器 + 多实例反代** 即可。**安全注记**：云安全组 **收紧**；PG **仅内网**；WAF/mTLS **按合同与预算** 选装，非 MVP 必选。
|
||
|
||
---
|
||
|
||
## 11. 修订记录
|
||
|
||
| 日期 | 说明 |
|
||
|------|------|
|
||
| 2026-04-06 | 初版：系统上下文、容器、领域与 SDK 组件图、时序、全量组件表、技术栈与部署简图。 |
|
||
| 2026-04-06 | **§9 安全架构**：信任边界、威胁与缓解、分组件控制、安全时序、合规与评审清单；原则表增加 **安全默认**；部署节增加安全注记。 |
|
||
| 2026-04-06 | **对齐小团队**：§1 **阶段目标**、§3 单机部署说明、§9.0、凭据改为宿主机配置、部署图改为 `java -jar` + Nginx；新增 **§9.8 SDK 发布完整性**（防篡改/假冒重心）。 |
|
||
|
||
---
|
||
|
||
**下一步**：领域表结构、OpenAPI 与事件 Schema 建议单独维护为 **版本化契约仓库** 或 `contracts/` 子模块，并在 [PARALLEL_ITERATION_INDEX](./PARALLEL_ITERATION_INDEX.md) 的同步点更新版本号。
|