craftlabs-authorization-sdk/docs/engineering/SYSTEM_ARCHITECTURE.md

系统架构设计 — 全景图与组件清单

角色：资深架构师视角的 系统上下文、容器划分、逻辑组件、数据流与部署边界 的单一汇总页。
读者：研发、测试、运维、产品与集成方。
关联：工作区工程划分 · 并行迭代索引 · 功能模块 M1–M11 · 比特对接总览 · engineering/workspace-manifest.json
安全专章：本章 §9（含 §9.0 小团队阶段、§9.8 SDK 发布完整性）；与工作区 WORKSPACE §10 安全边界 互补。

---

1. 架构目标与原则

原则	说明
边界清晰	客户端授权运行时（SDK + Native + 现场进程）与 商业交付平台（Web + 双后端 + 数据持久化）在 依赖、发布周期、classpath 上严格分离。
契约先行	客户端配置以 schemas/craftlabs-auth-config.schema.json 为契约；Callback / OpenAPI 以 文档与版本化契约 对齐多轨迭代（见 PARALLEL_ITERATION_INDEX）。
可运维	每个可独立扩缩的后端服务 一枚 Fat JAR（spring-boot-maven-plugin repackage 仅挂在启动模块）；密钥与连接串 不进 SDK 与示例仓库。
数据栈锁定	平台持久化：PostgreSQL 15 + MyBatis-Plus（详见 WORKSPACE_ENGINEERING_LAYOUT §9.1）。
安全默认	最小权限、纵深防御、可审计；对外入口 TLS；敏感面（Webhook、管理 API、SN/许可数据）单独威胁建模与门禁。
阶段目标（创飞当前）	小团队：优先 功能与需求闭环；并发与规模 不高。平台侧 单/双 Fat JAR + 单机或少量 VM 上 java -jar 即可；不将 K8s、云 KMS、服务网格 作为现阶段必选项，待业务量与合规要求上升再演进。 安全重心 放在 已发布 SDK 的完整性（不易被 替换、假冒），见 §9.0 / §9.8。

---

2. 系统上下文（C4 Level 1）

展示本体系与 外部环境 的关系：谁使用谁、谁回调谁。

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）

本工作区与规划仓库中的 可构建、可部署或可分发单元。

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 模块，但边界应一致）。

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/）

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）。

---

6. 关键运行时序

6.1 比特 Callback → 平台

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 管理员使用平台

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 客户现场授权（与平台解耦）

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 信任边界

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（补充安全步骤）：

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

管理端（补充安全步骤）：

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. 部署与网络（简图）

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 的同步点更新版本号。