82 lines
5.9 KiB
Markdown
82 lines
5.9 KiB
Markdown
 
|
# 需求
|
||
|
|
|
||
|
|
> 本文只描述**要什么**与**怎么算达成**,不涉及技术实现。
|
||
|
|
> 技术方案、组件边界见 [架构设计](04-architecture.md);协议字段见 [协议合约](api.md)(权威源为客户端仓库 `soft_quay`)。
|
||
|
|
|
||
|
|
## 一、业务现状
|
||
|
|
|
||
|
|
| 项 | 状态 |
|
||
|
|
| --- | --- |
|
||
|
|
| 客户端 | `soft_quay` 已完成 Phase 0~4:清单验签、下载、安装、更新、自更新均可运行,但**真实 Catalog 来源未配置**,显示 `catalog_source_unconfigured` |
|
||
|
|
| 协议 | 清单 / 包 / 许可证协议 v1 已在 `soft_quay/docs/api.md` + `schemas/` 定稿;canonicalization corpus 已冻结(soft_quay/T-614) |
|
||
|
|
| 发布侧 | 本仓库为全新项目,尚无代码;客户端当前 blocker 之一就是缺可信发布源 |
|
||
|
|
| 约束 | 客户端不做在线校验;下架、撤销、兼容都必须离线表达在签名文件里 |
|
||
|
|
|
||
|
|
## 二、用户角色
|
||
|
|
|
||
|
|
- **发布者(操作者)**:登记软件、触发发布 / 下架 / 撤销、签发许可证、查看审计。
|
||
|
|
- **子软件 CI**:提交标准 ZIP 候选包与 Release 元数据。
|
||
|
|
- **soft_quay 客户端**:只消费对象存储 / CDN 上的静态签名文件,不访问本系统任何接口。
|
||
|
|
|
||
|
|
## 三、功能清单
|
||
|
|
|
||
|
|
### 第一版(按阶段交付,阶段见 [任务路线图](06-tasks.md))
|
||
|
|
|
||
|
|
| 功能 | 发布者能做什么 | 优先级 |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| 协议对齐签名 | 产出与客户端字节级一致的规范 JSON + Ed25519 签名;corpus 全向量回归通过 | P0 |
|
||
|
|
| Schema 校验 | 发布前自动校验 manifest / app.json 合规,不合规拒绝发布 | P0 |
|
||
|
|
| 双通道清单生成 | 一键产出 `manifest-modern.json` / `manifest-win7.json`,通道互不交叉 | P0 |
|
||
|
|
| 本地静态发布模拟 | 本地生成签名清单 + 静态 HTTP 服务,客户端可跑通「清单→下载→安装」闭环 | P0 |
|
||
|
|
| 软件登记 | 维护每款软件的元数据(id/name/version/channel/status/…) | P1 |
|
||
|
|
| 构建包接收校验 | 接收 CI 的 ZIP 候选包,校验结构与声明一致性,计算 size/SHA-256 | P1 |
|
||
|
|
| 发布记录 | 每次发布登记 url/size/sha256/signature 坐标,可浏览历史 | P1 |
|
||
|
|
| 正式发布 | 原子上传对象存储 / CDN:先包后清单 | P1 |
|
||
|
|
| 签名服务隔离 | 私钥进 KMS/HSM 或独立签名服务;Web 端只经受控接口请求签名 | P1 |
|
||
|
|
| 下架与撤销 | 用 status 下架软件;维护签名的许可证撤销名单 | P2 |
|
||
|
|
| 许可证签发 | 绑定 machine_hash + products 签发 Ed25519 许可证 | P2 |
|
||
|
|
| Web 管理后台 | 登记 / 发布 / 下架 / 撤销 / 签发 / 审计查看的操作界面 | P2 |
|
||
|
|
| 审计 | 每次发布 / 下架 / 撤销 / 签发的 append-only 记录 | P2 |
|
||
|
|
|
||
|
|
### 后续迭代(记录不实现)
|
||
|
|
|
||
|
|
| 功能 | 描述 |
|
||
|
|
| --- | --- |
|
||
|
|
| 密钥轮换 | 需先与客户端协调协议升级(key ID 字段);单公钥期间禁止另造签名域 |
|
||
|
|
| package.signature 独立验签域 | v1 客户端不独立验证;定义待签名字节 + 公钥域后再实现 |
|
||
|
|
| 图标分发映射 | `sha256:` 内容哈希到实际下载位置 / 分辨率变体的发布端映射 |
|
||
|
|
| 多操作者与审批流 | 多人权限模型、发布审批;首期单操作者 |
|
||
|
|
|
||
|
|
## 四、核心用户故事
|
||
|
|
|
||
|
|
1. 作为发布者,我在本地用测试密钥对生成一份签名清单,soft_quay 客户端验签通过并显示软件列表——这是第一里程碑,在任何 UI 之前达成。
|
||
|
|
2. 子软件 CI 产出 `json-parser_1.4.2_windows_amd64.zip` 后,我把它提交给发布系统;系统校验包结构与登记信息一致、算出 size/SHA-256,生成新清单、签名并发布;客户端下次刷新即看到新版本。
|
||
|
|
3. 我下架一款软件时,只改它的 `status`,不改名;客户端按 status 过滤,旧用户不受影响。
|
||
|
|
4. 我给一台机器签发许可证时,只提交 machine_hash 与产品列表;系统不保存任何原始硬件序列号。
|
||
|
|
5. 任何人拿到发布系统的数据库或 Web 服务器权限,都拿不到签名私钥;伪造清单在客户端必然验签失败。
|
||
|
|
|
||
|
|
## 五、验收标准
|
||
|
|
|
||
|
|
- **字节级对齐**:对 corpus 中每个合法向量,本系统 canonicalizer 产出的规范字节与 `signed_payload_base64` 逐字节一致;每个非法向量按 `want_error` 拒绝;期望值不得自举。
|
||
|
|
- **客户端验签**:生成的 manifest 被 soft_quay 客户端(内置对应测试公钥)验签通过;篡改任一字节后验签失败。
|
||
|
|
- **Schema 合规**:不合规清单(未知字段、重复 id、非法 SemVer、architectures 与 packages 不对应、非 HTTPS URL)被拒绝且有明确错误信息。
|
||
|
|
- **通道隔离**:win7 清单中不出现 `min_os` 高于 win7 或仅 modern 的包;两清单 `channel` 字段正确。
|
||
|
|
- **发布原子性**:清单可见时,其引用的所有包与图标已可下载;模拟"清单先于包"的发布被系统拒绝。
|
||
|
|
- **私钥隔离**:代码库、配置样例、日志、数据库 dump 中均无私钥材料;签名只能通过受控接口对已知结构进行。
|
||
|
|
- **Ingestion**:包结构非法、app.json 与登记不一致、声明版本 / 架构不符的候选包被拒绝并给出原因。
|
||
|
|
- **审计**:每次发布 / 下架 / 撤销 / 签发均产生含操作者、时间、内容摘要、签名指纹的记录;记录不可修改。
|
||
|
|
|
||
|
|
## 六、范围边界与决策
|
||
|
|
|
||
|
|
| 问题 | 决策 |
|
||
|
|
| --- | --- |
|
||
|
|
| 客户端接口 | 无;客户端只拉静态文件,本系统无面向客户端的运行时 API |
|
||
|
|
| 账号体系 | 首期单发布者;多操作者 / 审批流为后续迭代(裁定项 W-501) |
|
||
|
|
| 首期部署 | 本地 / 静态文件模拟,不先建正式对象存储 |
|
||
|
|
| 首期密钥 | 离线生成的测试密钥对(与客户端内置测试公钥、corpus 配对);正式私钥管理另裁(W-003) |
|
||
|
|
| 包目标 | 只登记实际支持并测试过的目标,不生成占位包 |
|
||
|
|
|
||
|
|
## 七、待确认 / 风险点
|
||
|
|
|
||
|
|
设计规格 §十 的九个未定项已全部登记为裁定任务或 Backlog,映射见 [任务路线图](06-tasks.md) 的「未定项裁定清单」。其中立项前必须裁定的是:签名私钥管理(W-003)、协议权威源引用方式(W-001 内裁定)、正式域名与对象存储(W-004,Phase 3 前)。
|