修复校验任务幂等键并更新双版本数据库回归进度
This commit is contained in:
1 parent
24a9683c43
commit
4ab3f93beb
6 files changed
+92
-11
No files matched your search
@@ -4,7 +4,7 @@
|
||||
|
||||
## 业务范围
|
||||
|
||||
证书申请、当前证书部署、证书导入及申请/部署手动重试先持久化任务,再交给后台工作线程执行。浏览器断线不取消已接收工作,前端通过任务接口确认最终结果。提交成功、证书保存成功、逐服务器推送成功、整体任务成功是不同层级,不能混用。
|
||||
证书申请、当前证书部署、证书导入、本地证书校验及申请/部署手动重试先持久化任务,再交给后台工作线程执行。浏览器断线不取消已接收工作,前端通过任务接口确认最终结果。提交成功、证书保存成功、本地校验成功、逐服务器推送成功、整体任务成功是不同层级,不能混用。
|
||||
|
||||
## 接口与权限
|
||||
|
||||
@@ -15,12 +15,14 @@
|
||||
| POST /api/v1/domains/:id/issue | 提交申请及关联部署,无请求体 | 可见域名、证书管理、部署执行、DNS 凭据使用权限;202 |
|
||||
| POST /api/v1/domains/:id/deploy | 提交已有证书部署,无请求体 | 可见域名、部署执行权限;202 |
|
||||
| POST /api/v1/domains/:id/certificate/import | 上传证书后提交导入及部署任务 | 可见域名、证书管理、部署执行权限;不要求 DNS 凭据权限;202 |
|
||||
| POST /api/v1/domains/:id/certificate/validate | 提交当前本地证书校验,无请求体 | 可见域名、私钥读取权限;不额外要求证书管理、DNS 或部署执行权限;202 |
|
||||
| POST /api/v1/tasks/:id/retry | 同一任务新增一次尝试,无请求体 | 重试、证书管理、部署执行权限;申请类还检查 DNS 凭据;202 |
|
||||
| DELETE /api/v1/tasks/:id | 请求取消 | 任务可见及取消权限;后台任务返回 202,非异步历史任务可能返回 200 |
|
||||
| GET /api/v1/tasks | 当前身份可见任务列表 | 支持 domain_id 和 limit;返回 200 与 items 数组 |
|
||||
| GET /api/v1/tasks/:id | 单个任务最新状态 | 返回 200 与任务对象本身,不包 task 字段 |
|
||||
| GET /api/v1/tasks/:id/attempts | 任务尝试历史 | 返回 200 与 items 数组 |
|
||||
| GET /api/v1/tasks/:id/deployment-results | 逐尝试的逐服务器结果与完整报告 | 返回 200、items 和 reports 数组;按任务、最近尝试编号及尝试 ID 精确匹配 |
|
||||
| GET /api/v1/tasks/:id/validation-results | 读取本地校验公开元数据 | 任务读取权限;返回 200 与 items 数组,仓储查询实时复核可见范围 |
|
||||
|
||||
列表 limit 默认 50,有效范围为 1~200,越界由仓储回退至 50。不存在和无权访问的任务都返回 403,不能根据接口泄露其他项目资源是否存在。
|
||||
|
||||
@@ -56,7 +58,7 @@
|
||||
|
||||
### 幂等与错误
|
||||
|
||||
- 首次申请和部署支持 Idempotency-Key:长度 8~128,只允许英文字母、数字、连字符、下划线及英文句点。前端当前为每次明确操作生成新键,网络重发若需要去重必须复用原键。
|
||||
- 首次申请、部署、导入和校验支持 Idempotency-Key:长度 8~128,只允许英文字母、数字、连字符、下划线及英文句点。校验前端使用 certificate-validate 前缀,不将接口路径中的斜线写入请求头。前端当前为每次明确操作生成新键,网络重发若需要去重必须复用原键。
|
||||
- 同一域名、同一键命中已结束任务返回 200、task 和 replayed: true;命中活动任务返回 409、task 和 replayed: true,不再次执行。跨操作复用同一键返回 409。
|
||||
- 同类活动任务、仍在收尾、成功任务重试或不支持的任务类型返回 409。部署的 partial_success 允许重试;申请类只允许 failed 或 cancelled。
|
||||
- 取消 202 只说明接收取消意图,状态为 cancelling;不能提前显示已取消或允许重试。已经完成的外部操作仍可最终成功,并提示取消未撤销该操作。
|
||||
@@ -71,6 +73,7 @@
|
||||
| TaskAttempt | id、task_id、attempt_number、stage、status、message、scope_type、project_id、created_at;可选 started_at、finished_at |
|
||||
| TaskDeploymentResult | task_id、attempt_id、attempt_number、result_index、server_id、server、status、message、created_at;可选 backup_id |
|
||||
| TaskDeploymentReport | task_id、attempt_id、attempt_number、report、created_at;report 保留汇总、逐目标结果、verification_status 与 recovery_status |
|
||||
| TaskValidationResult | task_id、attempt_id、attempt_number、validation、created_at;validation 包含 domains、serial_number、fingerprint_sha256、not_before、not_after、chain_length |
|
||||
|
||||
编号和时间为字符串,时间使用带时区的 RFC3339 表示;attempt_number 与 result_index 为整数。Task 与 TaskAttempt 的状态含义如下:
|
||||
|
||||
@@ -119,6 +122,17 @@ deployment-results 响应保留旧 items,新增 reports;每次尝试独立
|
||||
|
||||
## 执行及前端交互边界
|
||||
|
||||
### 本地证书校验
|
||||
|
||||
- 提交返回 202,task_type 为 certificate_validate。提交与取得执行槽之后均复核私钥读取权限和域名归属;响应断开不取消已接收工作,不返回证书或私钥路径。
|
||||
- 只有成功校验才保存 validation;失败、排队取消、关停、执行异常不生成通过结果。校验结果、任务、尝试和完成审计共用一个事务,不生成空的部署报告。
|
||||
- validation 中 domains 为字符串数组,serial_number 和 fingerprint_sha256 为字符串,not_before 和 not_after 为带时区时间,chain_length 为整数。结果读取形式为 items 数组,每条记录关联原 task_id、attempt_id 和 attempt_number。
|
||||
- 前端仅为校验任务额外读取 validation-results;任务与最近一次尝试均为 success,且三个关联字段全部一致时展示结果。切换、关闭详情和撤权后清除缓存;历史成功任务没有详情时明确说明未留存,不推断当前证书仍然有效。
|
||||
- 结果只证明执行时的本地证书、私钥匹配及信任链校验,不代表远端部署、HTTPS 或生产验收通过。
|
||||
- 校验不接入通用手动重试入口,POST /tasks/:id/retry 返回 409。用户需要重新校验时,应从域名校验入口明确创建新任务。
|
||||
|
||||
### 公共执行约束
|
||||
|
||||
- 当前后台最多接收 32 个在途任务,4 个执行槽,总执行预算 30 分钟;这些是实现限制,不是保证耗时。
|
||||
- 队列满或关闭时拒绝执行,并尝试保存失败终态;持久化失败保留中断状态,不伪造已完成。
|
||||
- 服务关闭停止接收、发送取消信号并等待工作线程收尾。启动恢复将中断记录标为失败,不自动重放外部签发、部署。
|
||||
@@ -153,5 +167,6 @@ deployment-results 响应保留旧 items,新增 reports;每次尝试独立
|
||||
- [x] HTTP 异步完成审计、逐服务器结果与任务终态同事务,已覆盖三类保存失败整体回滚;其他工作流及三库实机复审仍待完成。
|
||||
- [x] 后台证书共用执行器新增五处故障回滚、每次重试报告、等待取消及无活动尝试收尾回归;应用、仓储、HTTP 三包原生 Linux 测试、全后端测试及 go vet 均通过,未正式部署。
|
||||
- [x] 生产导入入口及前端任务跟踪已接入异步执行;专项回归通过,未正式部署。
|
||||
- [ ] 版本恢复、校验及手动续期等其他长操作尚未全部异步化;当前历史版本恢复的真实实现仍拒绝恢复,不能用模拟工作流测试替代功能验收。
|
||||
- [x] 校验入口、独立结果持久化和详情展示已接入异步任务;前端幂等键契约缺陷已先复现后修复,最新 266 项测试及生产构建通过,尚未正式部署。
|
||||
- [ ] 版本恢复及手动续期等其他长操作尚未全部异步化;当前历史版本恢复的真实实现仍拒绝恢复,不能用模拟工作流测试替代功能验收。
|
||||
- [ ] 正式构建部署后验证超过反代等待窗口的真实操作、断线查询、取消回滚和服务重启;本说明不替代生产验收。
|
||||
Reference in new issue
Block a user