完善域名服务器多对多关联与共享路径预检,补齐回归源码及进度文档
支持同项目内域名与服务器双向复用,局部修改和清空不影响其他域名;在绑定保存、服务器编辑和部署前拒绝已知共享路径冲突。 新增仓储、接口、工作流与页面回归源码,同步任务状态和第三版接口交接。按要求先开发后统一测试,本批未运行测试、构建或部署,保留在途任务与主机别名等待办。
This commit is contained in:
1 parent
f38e290b22
commit
e2200534d3
25 files changed
+740
-41
No files matched your search
@@ -0,0 +1,86 @@
|
||||
# 项目生命周期、资源读取及多对多绑定接口交接
|
||||
|
||||
日期:2026-09-28。本文对应已编写但尚未统一测试的源码;不表示接口、浏览器或生产部署验收通过。前两版保留历史范围,不修改作为 Smail 参考的《后端接口说明文档》。
|
||||
|
||||
## 业务范围与认证
|
||||
|
||||
域名与服务器是同项目内的多对多关系,一个域名可部署多台服务器,一台服务器也能承载多个域名。取消关联只改变当前域名,不删除服务器或远端文件、不影响其他域名。保存关联不执行 SSH、证书签发或推送。
|
||||
|
||||
使用原有会话 Cookie,操作者只能取服务端身份。全局普通管理员和用户分组不隐式授予项目权限;账户停用、成员撤权必须实时拒绝。成功和失败响应均使用 `Cache-Control: private, no-store`、`Vary: Cookie`。跨来源写入由现有保护拒绝。
|
||||
|
||||
## 项目生命周期
|
||||
|
||||
| 接口 | 请求 | 成功响应 |
|
||||
|---|---|---|
|
||||
| `POST /api/v1/projects` | `{"name":"生产证书","description":"生产环境"}` | 201,项目对象 |
|
||||
| `PUT /api/v1/projects/:projectID` | `{"name":"生产证书","description":"更新说明"}` | 200,`{"message":"项目资料已更新"}` |
|
||||
| `DELETE /api/v1/projects/:projectID` | `{"confirmation":"目标项目标识"}` | 204,无正文 |
|
||||
|
||||
- 创建只允许活跃超级管理员,编辑/删除依实际项目管理权限;前端能力字段仅用于显示,不作为授权凭证。
|
||||
- 标识由服务端创建,格式 `^[a-z0-9][a-z0-9_-]{0,35}$`;请求不得伪造标识、操作者或其他未知字段,不接受查询参数。
|
||||
- 名称去除首尾空白后为 1~128 个 Unicode 字符,不含控制字符;说明最多 4096 个字符,允许换行、回车和制表符。
|
||||
- 默认项目不可删除,资源或成员尚有关联也不能删除。删除确认必须与目标 ID 一致,不代替用户自动清理资源。
|
||||
- 参数错误 400、未认证 401、无权或未知项目 403、默认项/引用冲突 409、依赖未就绪 503、内部错误 500。错误为 `{"error":"中文提示"}`。
|
||||
- 成功变更和审计同事务。前端生命周期与成员操作共用忙状态,禁止相互冲突的重复提交;切换项目或失去权限后丢弃旧响应。
|
||||
|
||||
## 资源读取入口
|
||||
|
||||
| 接口 | 权限 | 返回 |
|
||||
|---|---|---|
|
||||
| `GET /api/v1/domains` | `certificate.read` | 当前可见域名 `items` |
|
||||
| `GET /api/v1/servers` | `server.read` | 当前可见服务器 `items` |
|
||||
| `GET /api/v1/servers/:id` | `server.read` | 服务器对象 |
|
||||
| `GET /api/v1/domains/:id/servers` | 双方读取权限,同项目 | 关联服务器 `items` |
|
||||
| `GET /api/v1/certificates` | `certificate.read` | 当前可见证书元数据 `items` |
|
||||
| `GET /api/v1/certificates/:id` | 域名的 `certificate.read` | 证书元数据 |
|
||||
| `GET /api/v1/domains/:id/certificate/versions` | `certificate.read` | 版本 `items` |
|
||||
|
||||
沿用原有响应字段;本批资源列表没有新增游标参数,不与项目目录分页混淆。列表在 SQL 内过滤,多角色不重复返回;空列表为 `[]` 而不是 `null`。未知与越权详情均为 403,缺少授权依赖为 503,不回退全量基础仓储。证书文件读取前先检查实际域名权限。
|
||||
|
||||
## 多对多关联写入
|
||||
|
||||
### `PUT /api/v1/domains/:id/servers`
|
||||
|
||||
请求必须明确包含数组:
|
||||
|
||||
```json
|
||||
{"server_ids":["server-one","server-two"]}
|
||||
```
|
||||
|
||||
清空当前域名:
|
||||
|
||||
```json
|
||||
{"server_ids":[]}
|
||||
```
|
||||
|
||||
- 成功 200,`{"items":[服务器对象]}`;清空返回 `{"items":[]}`。按服务器名称、ID 排序,不能依赖请求顺序。
|
||||
- 有效超级管理员可操作;其他活跃账户需同时具备当前项目的 `certificate.read`、`server.read`、`deployment.execute`。当前角色矩阵中项目管理员和部署管理员符合,多个角色能力可合并。
|
||||
- 所有服务器必须与实际域名同项目,包括超级管理员;不接受客户端 `project_id`、`actor_id` 或任何查询参数。
|
||||
- ID 为 1~128 位 ASCII 字母、数字、连字符或下划线。最多输入 100 个服务器 ID,上限按去重前计算;重复 ID 去重后仅保存一条关联。
|
||||
- 缺字段、`null`、错误类型、未知字段、非法 ID、超限为 400;无权、跨项目或未知资源统一 403;已知共享路径冲突为 409;缺依赖为 503;内部失败为 500。401 表示未认证。
|
||||
- 成功审计 `domain.servers.replace` 与关联同事务,失败不清空旧绑定。失败审计根据实际域名归属写入,不保存请求体、密钥或原始数据库错误。
|
||||
|
||||
## 路径隔离与错误处理
|
||||
|
||||
默认目标为 `/ssl/{域名}/{证书类型}/` 下的 `cert.pem`、`fullchain.pem`、`key.pem`,也接受英文占位符 `{domain}`、`{certificate_type}`。
|
||||
|
||||
绑定保存、服务器配置修改及部署预检会比较实际展开并规范化后的各文件路径。多个域名共用固定路径、占位符被 `..` 抵消、不同文件类型相互占用或文件目录重叠时拒绝;单个域名的固定路径仍可使用。409 只返回中文修正提示,不暴露其他域名或私钥路径。
|
||||
|
||||
前端保留多选复选框,不因服务器已被其他域名使用而禁用或复制服务器。说明放入 `HelpTip`。409 时保留用户选择,引导修改服务器模板后重试;无权限或未知资源不显示区别提示。不要乐观清空列表,500/网络失败需刷新确认真实状态。
|
||||
|
||||
域名资料保存与绑定保存仍是两个请求,不应显示为跨请求原子提交。当前域名创建后绑定失败的重复提交体验及全资源写入授权仍需后续前端/权限整改,不能误称已闭环。
|
||||
|
||||
## 当前未覆盖的边界
|
||||
|
||||
- 本批路径预检只针对同一服务器记录的当前绑定,不识别多个记录指向同一主机、远端别名或解除绑定后的遗留文件;配置并发变化与在途任务的完整路径占用协调仍待部署整改。
|
||||
- 其他资源 CRUD、签发/导入/部署、DNS/SSH、任务读取/执行/取消/重试和审计读取的项目权限仍待补齐。
|
||||
- 本批只编写回归源码,尚未执行测试、构建或浏览器验收,旧批次通过结果不可复用为本批证据。
|
||||
|
||||
## 待统一执行的关键场景
|
||||
|
||||
1. A、B 两个域名均关联 S1、S2;分别读取均得到两台服务器,重复输入不产生重复关联。
|
||||
2. 修改或清空 A,B 的两条关联和服务器本身保持不变;只有显式空数组才能清空。
|
||||
3. 跨项目、越权、停用/撤权、未知资源、缺依赖或审计故障均不改变旧关联。
|
||||
4. 两个域名在同一服务器解析为不同路径;固定私钥/证书/链路径、规范化和跨文件冲突拒绝。
|
||||
5. 修改服务器不能引入共享冲突;历史危险配置必须在部署前被拒绝,不能调用远端写入。
|
||||
6. Vue 模板同时渲染两个已选复选框及悬浮提示;SSR 回归不代替真实浏览器、SSH 或多服务器生产推送验收。
|
||||
Reference in new issue
Block a user