1016 lines
55 KiB
Markdown
1016 lines
55 KiB
Markdown
# SSL 服务程序需求确认文档
|
||
|
||
- 文档状态：已根据需求确认单更新，73 项用户补充已填写；部分架构事项仍待评审
|
||
- 创建日期：2026-08-25
|
||
- 适用项目：SSL 证书管理服务程序
|
||
- 文档用途：用于确认功能边界、技术方案和验收标准，确认后作为后续设计与开发依据
|
||
- 项目名：Scert
|
||
|
||
> 本文档整理正式需求、待确认事项和开发任务，不代表所有方案已经最终确定。正式需求以已确认结果为准，未确认事项不得擅自假设。
|
||
> 填写规则：需求确认阶段，紧跟待确认项后的 `【用户补充 U-编号】` 为用户填写区；需求确认后，系统根据用户补充区同步更新正式需求、流程和验收标准。
|
||
|
||
---
|
||
|
||
## 一、需求确认清单
|
||
|
||
### 1.1 项目目标
|
||
|
||
- [x] 统一管理多个域名的 SSL/TLS 证书
|
||
- [x] 支持自动申请、自动续期和手动部署
|
||
- [x] 支持将证书部署到多台远程服务器
|
||
- [x] 支持部署完成后的证书校验
|
||
- [x] 支持邮件通知和操作日志
|
||
- [x] 支持命令行、Web 管理界面和桌面图形界面
|
||
- [x] 支持 Windows 和 Linux 运行环境
|
||
- [x] 已确认需求：第一阶段同时提供命令行、Web 管理界面和桌面图形界面；命令行仅负责初始化基础配置，初始化完成后日常管理通过 Web 界面进行。
|
||
- 【用户补充 U-001】（请填写）：
|
||
- 补充内容：命令行系统需要实现，命令行只进行基础信息填写：web页面的域名、dns的配置、ssl证书部署的位置，Web 管理界面需要实现，桌面图形界面需要实现
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：第一阶段同时支持 Windows 和 Linux 两条开发线。
|
||
- 【用户补充 U-002】（请填写）：
|
||
- 补充内容：需要，两条线进行开发
|
||
- 确认结果：已填写
|
||
|
||
### 1.2 域名和证书管理
|
||
|
||
- [x] 支持添加托管域名
|
||
- [x] 支持删除托管域名
|
||
- [x] 支持配置证书类型
|
||
- [x] 支持单域名证书
|
||
- [x] 支持泛域名证书
|
||
- [x] 证书默认存放在配置根目录下的域名目录中
|
||
- [x] 已确认需求：泛域名证书不包含根域名。
|
||
- 【用户补充 U-003】（请填写）：
|
||
- 补充内容：泛域名不需要包含根域名
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：证书按生产证书和开发证书分类管理；多域名 SAN 证书纳入第一阶段。
|
||
- 【用户补充 U-004】（请填写）：
|
||
- 补充内容：确认启用
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：删除域名时同时删除该域名的历史证书文件。
|
||
- 【用户补充 U-005】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：同一域名允许保存多个证书版本；根目录使用 `/ssl/{域名}/`，按生产/开发环境和证书类型分目录，下设泛域名和单域名目录。
|
||
- 【用户补充 U-006】（请填写）：
|
||
- 补充内容：允许，但同一个域名多个版本的证书的话，需要以文件夹区分，文件夹名是证书类型，目录结构为：
|
||
/ssl/{域名}/
|
||
-*（泛域名）
|
||
-{域名}（单域名
|
||
目录格式参考这个进行排布设计
|
||
- 确认结果：已填写
|
||
|
||
|
||
#### 已确认方向的证书目录结构
|
||
|
||
```text
|
||
/ssl/{域名}/
|
||
├── wildcard/ 泛域名证书，例如 *.example.com
|
||
│ └── {日期}-Vx.x/ 当前使用版本
|
||
├── single/ 单域名证书，例如 example.com
|
||
│ └── {日期}-Vx.x/ 当前使用版本
|
||
└── san/{证书标识}/ 多域名 SAN 证书
|
||
└── {日期}-Vx.x/ 当前使用版本
|
||
```
|
||
|
||
版本目录名称格式为 `YYYYMMDD-Vx.x`，例如 `20260830-V1.0`。同一天再次保存时递增版本号，例如 `20260830-V1.1`。生产和开发证书不再使用两套目录层级，统一由域名配置中的 ACME 环境字段区分申请环境。正式证书目录只保留当前使用版本；新证书保存成功后替换旧当前版本，旧文件仅在失败回滚所需时进入备份目录。
|
||
|
||
多域名 SAN 证书纳入第一阶段，证书以主域名作为管理归属，并保存完整的 SAN 域名集合。SAN 证书目录使用证书标识区分不同域名集合：
|
||
|
||
```text
|
||
/ssl/{主域名}/
|
||
└── san/{证书标识}/
|
||
└── {日期}-Vx.x/
|
||
```
|
||
|
||
其中 `{证书标识}` 必须能够稳定对应主域名和 SAN 域名集合；域名集合发生变化时更新当前证书版本目录，不在正式证书目录中保留历史版本。
|
||
|
||
【用户补充 U-074】（2026-08-30）：将生产/开发目录和当前/历史版本目录合并简化；正式证书目录只保留当前使用版本，版本目录名称使用日期加 `Vx.x`。本补充作为当前实现约束，优先于本节之前关于双环境目录和正式目录保留历史版本的描述。
|
||
|
||
### 1.3 DNS 验证
|
||
|
||
- [x] 使用 ACME 协议申请证书
|
||
- [x] 支持 DNS-01 验证
|
||
- [x] 支持 Cloudflare API Token
|
||
- [x] 支持阿里云 DNS/RAM 凭据
|
||
- [x] 支持 DNSPod API Token
|
||
- [x] 预留其他 DNS 服务商适配接口
|
||
- [x] 支持 CNAME 委派方式
|
||
- [x] 已确认需求：配置 DNS API 凭据时允许在 CLI 和 Web 初始化界面中明文查看，便于用户核对输入内容；提交保存后不得将明文凭据写入普通配置文件、数据库字段、日志或命令行输出。
|
||
- 【用户补充 U-074】（请填写）：
|
||
- 补充内容：配置时允许明文显示，存入数据库和调用时加密
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：DNS API 凭据在线验证期间仅在内存中使用；验证成功后写入加密敏感信息存储并返回凭据引用，证书申请和续期时根据凭据引用解密后调用 Provider。
|
||
- 【实现约束】：Web 和 CLI 不得把完整凭据写入响应、日志、错误信息、测试输出或备份；配置文件只保存 `secret://` 凭据引用。
|
||
- [x] 第一阶段 DNS 验证方式支持 Cloudflare、阿里云 DNS、DNSPod、CNAME 委派、华为云、腾讯云、AWS Route 53、Google Cloud DNS，并预留其他服务商适配接口。
|
||
- [x] 已确认需求：第一阶段使用 Let's Encrypt 作为 ACME CA，并使用 `go-acme/lego` 负责证书申请、DNS-01 验证和自动续期。
|
||
- 【用户补充 U-007】（请填写）：
|
||
- 补充内容：Let's Encrypt、ZeroSSL、Buypass Go SSL、SSL.com、Google Trust Services
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持国内外主流 DNS 服务商，并通过适配器扩展。
|
||
- 【用户补充 U-008】（请填写）：
|
||
- 补充内容：需要支持国内外主流dns服务商
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：CNAME 委派默认自动创建；自动创建失败时提示用户手动创建。
|
||
- 【用户补充 U-009】（请填写）：
|
||
- 补充内容：无需用户创建，自动创建失败时，提示用户手动创建
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：自动检测 DNS Zone 和权限。
|
||
- 【用户补充 U-010】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：默认使用一个 API 配置多个域名，并支持后续按域名覆盖配置。
|
||
- 【用户补充 U-011】（请填写）：
|
||
- 补充内容：默认使用一个api配置多个域名
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持 DNS 传播检测和超时设置。
|
||
- 【用户补充 U-012】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
|
||
#### 建议的 DNS 验证抽象
|
||
|
||
```text
|
||
DNS 验证方式
|
||
├── DNS API 自动管理
|
||
│ ├── Cloudflare
|
||
│ ├── 阿里云
|
||
│ ├── DNSPod
|
||
│ └── 其他适配器
|
||
└── CNAME 委派
|
||
├── 显示需要创建的 CNAME 记录
|
||
├── 检查 CNAME 是否生效
|
||
└── 管理委派目标下的 TXT 记录
|
||
```
|
||
|
||
### 1.4 自动续期
|
||
|
||
- [x] 系统按续期调度策略检查托管证书状态：常规每 3 天检查一次；证书剩余有效期低于 10 天时每天检查一次
|
||
- [x] 证书接近到期时自动触发续期
|
||
- [x] 续期失败时保留原证书
|
||
- [x] 支持手动触发续期
|
||
- [x] 支持记录续期任务状态
|
||
- [x] 支持失败重试
|
||
- [x] 已确认需求：证书剩余有效期低于 6 天时开启自动续期。
|
||
- 【用户补充 U-013】（请填写）：
|
||
- 补充内容：低于6天时开启自动续期
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：剩余有效期低于 6 天时触发续期，剩余有效期低于 3 天时进入紧急重试。
|
||
- 【用户补充 U-014】（请填写）：
|
||
- 补充内容：默认提前 6 天尝试，剩余 3 天进入紧急重试
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：每 3 天检查一次；有效期低于 10 天时每天检查一次。
|
||
- 【用户补充 U-015】（请填写）：
|
||
- 补充内容：每3天检查一次，有效期低于10天时，每天检查一次
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：允许用户自定义续期时间和重试次数；默认重试 3 次，每次间隔 30 分钟，并发送邮件提醒。
|
||
- 【用户补充 U-016】（请填写）：
|
||
- 补充内容：允许用户自定义续期时间和重试次数，默认重试3次，每次间隔30分钟，同时发送邮件提醒
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：提供 ACME Staging 测试环境。
|
||
- 【用户补充 U-017】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：申请任务串行执行，同时只运行一个申请任务；多个任务按提交顺序执行。
|
||
- 【用户补充 U-018】（请填写）：
|
||
- 补充内容：需要，每次限制一个申请任务，用户提交多个任务时，按提交的顺序进行申请，避免申请失败出现
|
||
- 确认结果：已填写
|
||
|
||
#### 已确认的续期配置
|
||
|
||
```text
|
||
常规检查间隔：每 3 天
|
||
临近到期检查：剩余有效期低于 10 天时每天检查
|
||
自动续期阈值：剩余有效期低于 6 天
|
||
紧急重试阈值：剩余有效期低于 3 天
|
||
默认最大重试次数：3 次
|
||
默认重试间隔：30 分钟
|
||
自定义配置：用户可以自定义续期时间和重试次数
|
||
```
|
||
|
||
### 1.5 多服务器部署
|
||
|
||
- [x] 一个域名可以关联多台服务器
|
||
- [x] 使用 SSH 密钥认证
|
||
- [x] 不使用服务器登录密码
|
||
- [x] 支持上传证书和私钥
|
||
- [x] 支持替换远程证书文件
|
||
- [x] 支持执行 Web 服务器或反向代理配置检查；默认适配 Nginx
|
||
- [x] 支持执行默认或用户自定义的 reload 命令
|
||
- [x] 支持部署完成后的远程 HTTPS 检查
|
||
- [x] 支持保留旧证书
|
||
- [x] 已确认需求：默认使用 Nginx；检测到其他 Web 服务器或反向代理时提示用户修改，并适配主流软件。
|
||
- 【用户补充 U-019】（请填写）：
|
||
- 补充内容：默认使用Nginx，如果用户使用其他的，提示用户进行修改，同时适配当前主流的web服务器/反向代理软件
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持自定义 reload 命令。
|
||
- 【用户补充 U-020】（请填写）：
|
||
- 补充内容：支持自定义
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：每台服务器允许单独配置证书路径，未配置时使用默认路径。
|
||
- 【用户补充 U-021】（请填写）：
|
||
- 补充内容：允许单独配置，不配置就使用默认的路径
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：每台服务器允许单独配置 SSH 用户、端口和密钥。
|
||
- 【用户补充 U-022】（请填写）：
|
||
- 补充内容：允许
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：记录 SSH 主机指纹。
|
||
- 【用户补充 U-023】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：部署任务重试 3 次仍失败后，报告当前状态并通过邮件发送任务摘要。
|
||
- 【用户补充 U-024】（请填写）：
|
||
- 补充内容：重试3次仍然失败后，将当前状态报告给用户，整理任务状态发送给用户使用邮件
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：部署失败时自动回滚，避免影响生产环境。
|
||
- 【用户补充 U-025】（请填写）：
|
||
- 补充内容：需要，避免影响生产环境
|
||
- 确认结果：已填写
|
||
|
||
#### 建议的部署流程
|
||
|
||
```text
|
||
1. 本地校验证书和私钥
|
||
2. 生成部署版本目录
|
||
3. 推送到远程目录
|
||
4. 设置远程文件权限
|
||
5. 执行 nginx -t
|
||
6. 原子替换证书文件
|
||
7. 执行 nginx -s reload
|
||
8. 发起远程 HTTPS 校验
|
||
9. 校验失败时恢复旧版本
|
||
10. 记录每台服务器的结果
|
||
```
|
||
|
||
### 1.6 部署后校验
|
||
|
||
- [x] 校验本地证书文件存在
|
||
- [x] 校验证书格式有效
|
||
- [x] 校验证书和私钥匹配
|
||
- [x] 校验证书未过期
|
||
- [x] 校验证书域名匹配
|
||
- [x] 校验远程服务器实际返回的证书
|
||
- [x] 校验证书链和 TLS 握手
|
||
- [x] 已确认需求：部署后检查域名的所有 A 记录。
|
||
- 【用户补充 U-026】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：部署后检查 AAAA 记录。
|
||
- 【用户补充 U-027】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：远程 HTTPS 校验超时时间为 2 分钟。
|
||
- 【用户补充 U-028】（请填写）：
|
||
- 补充内容：2分钟
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：生产证书不允许使用自签名临时证书，测试证书允许使用。
|
||
- 【用户补充 U-029】（请填写）：
|
||
- 补充内容：生产证书不允许，测试证书允许
|
||
- 确认结果：已填写
|
||
|
||
### 1.7 用户自有证书
|
||
|
||
- [x] 支持上传已有证书
|
||
- [x] 支持上传私钥
|
||
- [x] 支持手动触发部署
|
||
- [x] 上传证书前进行格式检查
|
||
- [x] 检查证书和私钥是否匹配
|
||
- [x] 检查证书域名和有效期
|
||
- [x] 已确认需求：允许上传加密私钥。
|
||
- 【用户补充 U-030】（请填写）：
|
||
- 补充内容：允许
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：用户上传证书保留最新版本和一个最近的历史版本。
|
||
- 【用户补充 U-031】（请填写）：
|
||
- 补充内容：保留最新的版本与一个最近的历史版本
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：用户上传证书默认不参与自动续期，用户主动选择后才参与。
|
||
- 【用户补充 U-032】（请填写）：
|
||
- 补充内容：默认不参与，除非用户选择参与
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：证书文件最大 5 MB，压缩包最大 10 MB。
|
||
- 【用户补充 U-033】（请填写）：
|
||
- 补充内容：证书文件限制最大5mb，压缩包10mb
|
||
- 确认结果：已填写
|
||
|
||
### 1.8 邮件通知
|
||
|
||
- [x] 每次续期任务完成后发送通知
|
||
- [x] 任务成功时发送通知
|
||
- [x] 任务失败时发送通知
|
||
- [x] 支持多个收件人
|
||
- [x] 通知内容包含域名、任务状态、错误信息和时间
|
||
- [x] 已确认需求：同时保留 HTTP API 和 SMTP 通知方式；HTTP 通知通过调用外部邮件或消息服务 API 完成，Scert 不实现 SMTP、IMAP、POP3 邮件服务器端。
|
||
- 【用户补充 U-034】（请填写）：
|
||
- 补充内容：http和smtp都保留，后期经过测试后决定保留具体方式
|
||
- 确认结果：已填写
|
||
|
||
#### HTTP 通知接口已确认模板
|
||
|
||
```text
|
||
请求方法：POST
|
||
请求地址：用户可自定义
|
||
请求格式：application/json
|
||
认证方式：Bearer Token、HMAC-SHA256、无认证均支持；无认证仅建议用于开发、测试或受控内网环境
|
||
请求头：支持 Scert 标准请求头和用户自定义请求头
|
||
事件模式：详细事件和统一事件均支持，默认使用详细事件
|
||
成功判定：HTTP 状态码 200-299
|
||
请求唯一标识：必须携带 request_id，接收方需要支持幂等处理
|
||
超时时间：默认 10 秒，可配置
|
||
失败重试：默认 3 次，间隔 30 秒、2 分钟、10 分钟，可配置
|
||
敏感信息：Token、签名密钥和密码不得写入日志
|
||
```
|
||
|
||
请求体至少包含：事件类型、任务状态、任务编号、域名、证书类型、运行环境、开始时间、结束时间、错误信息、重试信息和部署结果。用户可选择是否发送完整服务器部署明细、证书序列号和管理后台链接；上述内容默认支持配置。
|
||
|
||
HTTP 通知接口确认项：
|
||
|
||
- [x] 请求路径允许用户自定义。
|
||
- [x] 支持 Bearer Token。
|
||
- [x] 支持 HMAC-SHA256。
|
||
- [x] 保留无认证模式；该模式仅建议用于开发、测试或受控内网环境。
|
||
- [x] 同时支持详细事件和统一事件，默认使用详细事件。
|
||
- [x] 支持发送完整服务器部署明细。
|
||
- [x] 支持发送证书序列号。
|
||
- [x] 支持发送管理后台链接。
|
||
- [x] HTTP 状态码按 200-299 判定为成功。
|
||
- [x] 重试次数和间隔支持使用默认值，也支持用户自定义。
|
||
- [x] 请求字段统一使用英文。
|
||
- [x] 支持用户自定义请求头。
|
||
|
||
建议请求头：
|
||
|
||
```text
|
||
Content-Type: application/json
|
||
Authorization: Bearer {token}
|
||
X-Scert-Event: certificate.renewed
|
||
X-Scert-Request-Id: {request_id}
|
||
X-Scert-Timestamp: {unix_timestamp}
|
||
X-Scert-Signature: sha256={hmac_signature}
|
||
```
|
||
- [x] 已确认需求：SMTP、IMAP、POP3 和 Web 管理后台的协议连接表仅作为外部邮件服务兼容性参考，不作为 Scert 实现邮件服务器端的要求；Scert 后续通过外部 API 接口调用邮件发送服务。
|
||
- 【用户补充 U-035】（请填写）：
|
||
- 补充内容：协议表仅作参考，后续通过 API 接口调用外部邮件发送服务。
|
||
|
||
| 协议 | 明文连接 | STARTTLS/STLS | 隐式 TLS | 端口 |
|
||
|---|---|---|---|---|
|
||
| SMTP 接收 | 支持 | 支持 | 支持 | 25、465 |
|
||
| SMTP Submission | 仅允许建立连接，不允许明文认证 | 支持 | 不在 587 上使用 | 587 |
|
||
| IMAP | 不支持 | 不支持 | 支持 | 993 |
|
||
| POP3 | 仅允许建立连接，不允许明文认证 | 支持，命令为 `STLS` | 支持 | 110、995 |
|
||
| Web 管理后台 | HTTP 初始化期间支持 | 不适用 | HTTPS 支持 | 80、443 |
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：发件人显示名称默认为 Scert，发件人地址待测试后确定。
|
||
- 【用户补充 U-036】（请填写）：
|
||
- 补充内容：发件人：Scert，地址等待我测试后决定
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：通知发送失败时进行重试。
|
||
- 【用户补充 U-037】（请填写）：
|
||
- 补充内容：需要重试
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持按域名配置收件人，默认使用账户绑定的邮箱。
|
||
- 【用户补充 U-038】（请填写）：
|
||
- 补充内容：支持，但是默认使用账户绑定的邮箱
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持通知类型开关。
|
||
- 【用户补充 U-039】（请填写）：
|
||
- 补充内容：支持
|
||
- 确认结果：已填写
|
||
|
||
#### 建议的通知状态
|
||
|
||
```text
|
||
续期结果：成功、失败、错误、未知、根据具体报错进行通知：如dns错误、dns超时等
|
||
部署结果：全部成功、部分成功、全部失败、未执行
|
||
邮件结果：发送成功、发送失败、未配置
|
||
web页面：站内信提示全部的通知状态
|
||
```
|
||
|
||
### 1.9 Web 管理界面
|
||
|
||
- [x] 管理员登录
|
||
- [x] 查看所有托管域名
|
||
- [x] 查看证书类型
|
||
- [x] 查看证书到期时间
|
||
- [x] 查看剩余有效天数
|
||
- [x] 查看关联服务器
|
||
- [x] 查看最近续期状态
|
||
- [x] 添加和删除域名
|
||
- [x] 配置 DNS 验证方式
|
||
- [x] 配置部署服务器
|
||
- [x] 手动续期
|
||
- [x] 手动部署
|
||
- [x] 上传自有证书
|
||
- [x] 修改邮件配置
|
||
- [x] 修改证书存储路径
|
||
- [x] 查看操作日志
|
||
- [x] 已确认需求：管理后台不由核心服务单独终止 HTTPS，前端和后端均需纳入 HTTPS 安全部署；具体终止层待架构评审。
|
||
- 【用户补充 U-040】（请填写）：
|
||
- 补充内容：由你确定边界
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持多个管理员。
|
||
- 【用户补充 U-041】（请填写）：
|
||
- 补充内容：支持
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持一个超级管理员、多个管理员和多个普通用户的角色体系。
|
||
- 【用户补充 U-042】（请填写）：
|
||
- 补充内容：需要：1个超级管理员，n个管理员，n个普通用户
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持用户名加密码、邮箱加密码、邮箱加验证码、用户名加验证码等登录方式。
|
||
- 【用户补充 U-043】（请填写）：
|
||
- 补充内容：需要：通过用户名+密码、邮箱+密码、邮箱+验证码、用户名+验证码
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：5 分钟内登录失败 5 次后禁止登录 30 分钟。
|
||
- 【用户补充 U-044】（请填写）：
|
||
- 补充内容：5分钟内失败5次禁止登录30分钟
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：连续 30 分钟无操作时自动强制退出。
|
||
- 【用户补充 U-045】（请填写）：
|
||
- 补充内容：30分钟未操作自动强制退出
|
||
- 确认结果：已填写
|
||
|
||
### 1.10 命令行版本
|
||
|
||
- [x] 初始化配置
|
||
- [x] 添加域名
|
||
- [x] 删除域名
|
||
- [x] 手动续期
|
||
- [x] 手动部署
|
||
- [x] 查看域名状态
|
||
- [x] 查看证书信息
|
||
- [x] 查看日志
|
||
- [x] 修改系统配置
|
||
- [x] 与 Web 管理界面共享配置和数据
|
||
- [x] 已确认需求：CLI 通过 API 调用核心服务，不直接操作本地数据库。
|
||
- 【用户补充 U-046】（请填写）：
|
||
- 补充内容：通过api调用服务
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：初始化配置时使用交互式输入；初始化完成后不再使用交互式 CLI，转由 Web 页面操作。
|
||
- 【用户补充 U-047】（请填写）：
|
||
- 补充内容：初始化配置时需要交互式输入配置信息，初始化完成后不需要交互式，转由web页面操作
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：不支持 JSON 输出。
|
||
- 【用户补充 U-048】（请填写）：
|
||
- 补充内容：不支持
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：不支持脚本退出码。
|
||
- 【用户补充 U-049】（请填写）：
|
||
- 补充内容：不支持
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持任务等待和轮询。
|
||
- 【用户补充 U-050】（请填写）：
|
||
- 补充内容：支持
|
||
- 确认结果：已填写
|
||
|
||
### 1.11 桌面图形界面
|
||
|
||
- [x] 支持首次初始化
|
||
- [x] 支持配置管理员账号
|
||
- [x] 支持配置邮件服务器
|
||
- [x] 支持配置 DNS 验证
|
||
- [x] 支持配置证书存储路径
|
||
- [x] 支持打开 Web 管理界面
|
||
- [x] 已确认需求：桌面版作为 Web 管理界面的封装。
|
||
- 【用户补充 U-051】（请填写）：
|
||
- 补充内容：是
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：桌面版负责启动本地核心服务。
|
||
- 【用户补充 U-052】（请填写）：
|
||
- 补充内容：是
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：需要系统托盘。
|
||
- 【用户补充 U-053】（请填写）：
|
||
- 补充内容：是
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：需要显示后台任务状态。
|
||
- 【用户补充 U-054】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持开机自启动，但由用户选择是否启用。
|
||
- 【用户补充 U-055】（请填写）：
|
||
- 补充内容：需要，但是根据用户选择执行
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：桌面版安装包格式为 exe。
|
||
- 【用户补充 U-056】（请填写）：
|
||
- 补充内容：exe
|
||
- 确认结果：已填写
|
||
|
||
### 1.12 平台支持
|
||
|
||
- [x] Windows
|
||
- [x] Linux
|
||
- [x] Linux systemd 服务
|
||
- [x] Windows Service 服务
|
||
- [x] 已确认需求：支持 Windows 10 和 Windows 11，目标构建架构为 amd64。
|
||
- 【用户补充 U-057】（请填写）：
|
||
- 补充内容：win10
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：第一阶段以 Ubuntu 22.04 + Nginx 作为 Linux 基础测试环境，并覆盖 Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理软件的兼容性测试。
|
||
- 【用户补充 U-058】（请填写）：
|
||
- 补充内容：Ubuntu20.04、debain11
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：Linux 服务以 Ubuntu 22.04 的 systemd 版本作为最低 systemd 兼容基线，其他 Linux 发行版通过测试矩阵确认兼容性。
|
||
- 【用户补充 U-059】（请填写）：
|
||
- 补充内容：需要支持到当前最新版
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：暂不支持 ARM64。
|
||
- 【用户补充 U-060】（请填写）：
|
||
- 补充内容：暂不需要，没有对应的环境进行测试
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持主流 Windows、Linux、Web 服务器和反向代理软件。
|
||
- 【用户补充 U-061】（请填写）：
|
||
- 补充内容：主流的win、Linux、web服务器/反向代理都需要支持
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持在 Windows 上部署 Nginx，并根据用户需求启用。
|
||
- 【用户补充 U-062】（请填写）：
|
||
- 补充内容：支持这个功能，但是根据用户需求启用
|
||
- 确认结果：已填写
|
||
|
||
### 1.13 安全需求
|
||
|
||
- [x] 管理后台使用 HTTPS
|
||
- [x] 管理员密码使用安全哈希保存
|
||
- [x] Linux 私钥文件权限限制为 600 或更严格
|
||
- [x] Windows 使用等效 ACL 权限保护私钥
|
||
- [x] SSH 私钥加密存储
|
||
- [x] DNS API 密钥加密存储
|
||
- [x] SMTP 密码加密存储
|
||
- [x] 日志中禁止记录明文密钥
|
||
- [x] 已确认需求：敏感凭据在配置录入阶段允许明文显示，但仅限当前配置页面或当前交互输入过程；保存时使用 AES-GCM 等认证加密方式持久化，业务调用时按凭据引用解密，普通配置和数据库业务字段不保存明文。
|
||
- 【安全边界】：明文只允许短时存在于进程内存；验证失败、取消配置或保存失败时不得留下可复用的普通配置记录；敏感信息文件和主密钥继续使用受限权限保护。
|
||
- [x] 所有重要操作记录审计日志
|
||
- [x] 已确认需求：使用主密码保护的加密配置。
|
||
- 【用户补充 U-063】（请填写）：
|
||
- 补充内容：使用主密码保护的加密配置
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：需要管理员恢复机制：超级管理员只能通过配套重置入口重置；管理员和普通用户可由超级管理员重置；普通用户可由管理员重置，且普通用户只能重置自身。
|
||
- 【用户补充 U-064】（请填写）：
|
||
- 补充内容：需要：超级管理员只能通过配套的重置入口进行重置，管理员和普通用户可以通过超级管理员重置，普通用户可以通过管理员重置，普通用户只能重置本身
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持敏感信息轮换。
|
||
- 【用户补充 U-065】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持加密密钥备份。
|
||
- 【用户补充 U-066】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：需要安全审计报告，且仅超级管理员和管理员可以查看。
|
||
- 【用户补充 U-067】（请填写）：
|
||
- 补充内容：需要，但是只能超级管理员和管理员查看
|
||
- 确认结果：已填写
|
||
|
||
### 1.14 可靠性和运维
|
||
|
||
- [x] 失败时保留原证书
|
||
- [x] 续期任务可重试
|
||
- [x] 部署任务可重试
|
||
- [x] 记录操作日志
|
||
- [x] 记录错误原因
|
||
- [x] 服务重启后可以恢复任务状态
|
||
- [x] 已确认需求：支持数据库备份。
|
||
- 【用户补充 U-068】（请填写）：
|
||
- 补充内容：数据库备份
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：日志保留 30 天，默认保留最新 30 天后删除旧日志。
|
||
- 【用户补充 U-069】（请填写）：
|
||
- 补充内容：保留30天，默认保留最新的30天，然后删除旧的
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：日志每天限制 5 MB。
|
||
- 【用户补充 U-070】（请填写）：
|
||
- 补充内容：每天限制5mb
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持日志轮转。
|
||
- 【用户补充 U-071】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：支持配置导出和导入。
|
||
- 【用户补充 U-072】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
- [x] 已确认需求：需要灾难恢复流程。
|
||
- 【用户补充 U-073】（请填写）：
|
||
- 补充内容：需要
|
||
- 确认结果：已填写
|
||
|
||
---
|
||
|
||
## 二、第一阶段范围
|
||
|
||
以下范围已根据需求确认结果纳入第一阶段。具体实现仍需按照开发任务清单逐项完成并复审。
|
||
|
||
- [x] 已确认纳入：核心证书管理服务和统一配置、数据模型
|
||
- [x] 已确认纳入：数据库存储及任务、日志、证书版本数据管理
|
||
- [x] 已确认纳入：Let’s Encrypt ACME CA，并使用 `go-acme/lego` 负责证书申请、DNS-01 验证和自动续期
|
||
- [x] 已确认纳入：Cloudflare、阿里云 DNS、DNSPod、CNAME 委派、华为云、腾讯云、AWS Route 53、Google Cloud DNS 及其他服务商适配器
|
||
- [x] 已确认纳入：DNS-01 验证、DNS Zone 和权限检测、DNS 传播检测
|
||
- [x] 已确认纳入：CNAME 委派自动创建；自动创建失败时提示用户手动创建
|
||
- [x] 已确认纳入：单域名证书、泛域名证书（不包含根域名）、多域名 SAN 证书以及生产/开发证书分类
|
||
- [x] 已确认纳入：证书多版本保存、按证书类型分目录、失败时保留原证书
|
||
- [x] 已确认纳入：通过 SSH 密钥部署到多台服务器，支持独立配置路径、用户、端口和密钥
|
||
- [x] 已确认纳入：默认 Nginx，适配主流 Web 服务器和反向代理，并支持自定义 reload 命令
|
||
- [x] 已确认纳入：部署失败重试、自动回滚、A/AAAA 记录检查和远程 HTTPS 校验
|
||
- [x] 已确认纳入：HTTP API 和 SMTP 通知方式；SMTP、IMAP、POP3 协议表仅作为外部邮件服务兼容性参考，Scert 不实现邮件服务器端
|
||
- [x] 已确认纳入：MySQL 5.7 基础开发、MySQL 8.0 兼容性测试和 SQLite 单机/桌面/开发模式
|
||
- [x] 已确认纳入：Linux 默认目录 `/ssl`、`/scert`、`/scert/conf`、`/scert/log`、`/scert/backups`
|
||
- [x] 已确认纳入：Windows 按自定义安装目录使用 `Scert\ssl`、`Scert\data`、`Scert\config`、`Scert\logs`、`Scert\backups`
|
||
- [x] 已确认纳入：Linux 创建专用 `Scert` 服务运行用户；该用户专门管理证书目录，私钥由 `Scert` 和 `root` 共同受控管理
|
||
- [x] 已确认纳入：CLI 初始化、Web 管理界面和桌面图形界面
|
||
- [x] 已确认纳入：多管理员、超级管理员、管理员和普通用户角色权限
|
||
- [x] 已确认纳入：Windows 10/11、Ubuntu 22.04 + Nginx、Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理测试范围
|
||
- [x] 已确认纳入：Linux systemd 服务、Windows Service 服务和桌面版 exe 安装包；systemd 以 Ubuntu 22.04 默认版本为最低兼容基线
|
||
- [x] 已确认纳入：以当前开发电脑工具链为开发基线，目标构建架构为 amd64；当前记录为 Go 1.26.2、Node.js 24.19.0、npm 11.17.0、Wails 2.11.0
|
||
- [x] 已确认纳入：用户自有证书上传、校验和手动部署；默认不参与自动续期
|
||
|
||
以下内容暂不纳入第一阶段或仍需后续确认：
|
||
|
||
- [!] 自定义 ACME CA：第一阶段固定使用 Let’s Encrypt，后续预留扩展
|
||
- [!] 高可用、多实例和集群部署
|
||
- [!] ARM64 平台支持
|
||
- [x] 已确认：HTTPS 采用双模式；默认由核心服务直接终止 HTTPS，高级模式由 Nginx/Caddy 终止公网 HTTPS，核心服务使用内部 HTTPS
|
||
|
||
---
|
||
|
||
## 三、建议的系统模块
|
||
|
||
```text
|
||
SSL 服务程序
|
||
├── 配置管理模块
|
||
├── 管理员认证模块
|
||
├── 域名管理模块
|
||
├── 证书生命周期模块
|
||
├── ACME 客户端模块
|
||
├── DNS 服务商适配模块
|
||
├── 续期调度模块
|
||
├── SSH 部署模块
|
||
├── Web 服务器和反向代理适配模块
|
||
├── 远程 HTTPS 校验模块
|
||
├── 自有证书导入模块
|
||
├── 邮件通知模块
|
||
├── Web API 模块
|
||
├── CLI 模块
|
||
├── 桌面客户端模块
|
||
├── 审计日志模块
|
||
└── 平台服务模块
|
||
```
|
||
|
||
业务逻辑只放在核心服务中，CLI、Web 和桌面客户端不重复实现证书申请及部署逻辑。
|
||
|
||
---
|
||
|
||
## 四、建议的证书任务状态
|
||
|
||
### 4.1 续期任务状态
|
||
|
||
```text
|
||
pending 等待执行
|
||
running 执行中
|
||
succeeded 成功
|
||
failed 失败
|
||
partial 部分成功
|
||
cancelled 已取消
|
||
unknown 未知
|
||
```
|
||
|
||
### 4.2 部署节点状态
|
||
|
||
```text
|
||
pending 等待部署
|
||
uploading 上传中
|
||
checking 配置检查中
|
||
reloading 重载中
|
||
validating HTTPS 校验中
|
||
succeeded 成功
|
||
failed 失败
|
||
rolled_back 已回滚
|
||
rollback_failed 回滚失败
|
||
```
|
||
|
||
### 4.3 证书来源
|
||
|
||
```text
|
||
acme ACME 自动申请
|
||
uploaded 用户上传
|
||
imported 外部导入
|
||
```
|
||
|
||
---
|
||
|
||
## 五、关键业务流程
|
||
|
||
### 5.1 首次初始化流程
|
||
|
||
```text
|
||
1. 启动程序
|
||
2. 检查是否已完成初始化
|
||
3. 未初始化时进入初始化向导
|
||
4. 配置管理后台域名
|
||
5. 配置管理员账号和密码
|
||
6. 配置证书存储根目录
|
||
7. 配置邮件服务器和通知方式（HTTP、SMTP）
|
||
8. 配置至少一种 DNS 验证方式
|
||
9. 验证 DNS 凭据、DNS Zone、权限和 DNS 传播能力
|
||
10. 检查管理后台域名解析
|
||
11. 使用 Let’s Encrypt 和 `go-acme/lego` 通过 DNS-01 申请管理后台证书
|
||
12. 校验并安装本地 HTTPS 证书
|
||
13. 启动前后端均纳入 HTTPS 部署的管理后台
|
||
14. 标记初始化完成
|
||
```
|
||
|
||
### 5.2 自动续期流程
|
||
|
||
```text
|
||
1. 调度器按每 3 天一次的常规周期检查证书；剩余有效期低于 10 天时改为每天检查
|
||
2. 证书剩余有效期低于 6 天时创建续期任务；低于 3 天时按紧急策略重试
|
||
3. 申请任务进入串行队列，同一时间只运行一个申请任务
|
||
4. 检查 DNS 配置、DNS Zone、权限和 ACME 账户
|
||
5. 调用 `go-acme/lego` 使用 Let’s Encrypt 创建 ACME Order
|
||
6. 创建或委派 DNS TXT 记录
|
||
7. 等待并检测 DNS 记录传播
|
||
8. 执行 ACME DNS-01 验证并下载新证书
|
||
9. 校验新证书和私钥
|
||
10. 保存新的本地证书版本
|
||
11. 部署到关联服务器并执行 Web 服务器或反向代理检查、reload
|
||
12. 检查所有 A/AAAA 记录并执行远程 HTTPS 校验
|
||
13. 校验失败或部署失败时恢复旧版本
|
||
14. 按默认 3 次、每次间隔 30 分钟的策略重试；用户可自定义续期时间和重试次数
|
||
15. 写入任务和审计日志，并发送 HTTP/SMTP 任务通知
|
||
```
|
||
|
||
### 5.3 用户证书部署流程
|
||
|
||
```text
|
||
1. 上传证书和私钥
|
||
2. 校验文件格式
|
||
3. 校验证书和私钥匹配
|
||
4. 校验证书域名和有效期
|
||
5. 保存为新版本
|
||
6. 用户手动确认部署
|
||
7. 部署到关联服务器
|
||
8. 执行目标 Web 服务器或反向代理检查和 reload
|
||
9. 执行 HTTPS 校验
|
||
10. 记录结果并发送通知
|
||
```
|
||
|
||
---
|
||
|
||
## 六、验收标准
|
||
|
||
### 6.1 核心功能验收
|
||
|
||
- [ ] 能通过 CLI 完成首次初始化
|
||
- [ ] 能通过 Web 管理界面完成首次初始化
|
||
- [ ] 能通过桌面版完成首次初始化，并在初始化后打开 Web 管理界面
|
||
- [ ] 能添加单域名
|
||
- [ ] 能添加泛域名
|
||
- [ ] 能通过 Let’s Encrypt 和 `go-acme/lego` 使用 DNS-01 成功申请证书
|
||
- [ ] 能检测 DNS Zone、权限和 DNS 传播状态；CNAME 委派自动创建失败时能提示用户手动创建
|
||
- [ ] 能保存证书、证书链和私钥
|
||
- [ ] 能按生产证书、开发证书、单域名、泛域名和 SAN 证书保存多个证书版本；泛域名证书不包含根域名，SAN 域名集合变化时创建新的证书版本
|
||
- [ ] 能通过 SSH 部署到多台目标服务器，并按服务器独立配置路径、用户、端口和密钥
|
||
- [ ] 默认能部署到远程 Nginx，并能适配主流 Web 服务器和反向代理
|
||
- [ ] 能执行目标 Web 服务器或反向代理的配置检查和 reload，且支持自定义 reload 命令
|
||
- [ ] 能在部署后通过 HTTPS 校验
|
||
- [ ] 能按每 3 天检查、低于 10 天每天检查、低于 6 天续期、低于 3 天紧急重试的策略自动续期
|
||
- [ ] 默认失败重试 3 次、每次间隔 30 分钟，并允许用户自定义续期时间和重试次数
|
||
- [ ] 能在失败时保留旧证书
|
||
- [ ] 能在部署失败时回滚
|
||
- [ ] 能通过 HTTP API 和 SMTP 发送成功、失败、错误、未知等任务通知；HTTP API 支持自定义地址、Bearer Token、HMAC-SHA256、无认证测试模式、详细/统一事件、完整部署明细、证书序列号、管理后台链接、自定义请求头和独立重试
|
||
- [ ] 能上传自有证书并手动部署，且默认不参与自动续期
|
||
- [ ] 能查看操作日志
|
||
|
||
### 6.2 安全验收
|
||
|
||
- [ ] 未登录用户不能访问管理接口
|
||
- [ ] 管理员密码不以明文保存
|
||
- [ ] DNS 密钥、SMTP 密码和 SSH 私钥不出现在日志中
|
||
- [ ] 私钥文件权限符合平台要求
|
||
- [ ] 上传路径不能越权
|
||
- [ ] 远程 SSH 主机指纹可验证
|
||
- [ ] Web 管理后台强制 HTTPS
|
||
- [ ] 续期和部署任务不能被未授权用户触发
|
||
|
||
### 6.3 平台验收
|
||
|
||
- [ ] Windows 10 及以上环境可以启动核心服务
|
||
- [ ] Linux 环境可以启动核心服务
|
||
- [ ] Ubuntu 22.04 + Nginx 可以运行
|
||
- [ ] Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理通过测试矩阵验证
|
||
- [ ] Windows 服务可以自动启动
|
||
- [ ] Linux systemd 服务可以自动启动
|
||
- [ ] 桌面版可以通过 exe 安装包安装，并能启动本地核心服务、显示系统托盘和后台任务状态
|
||
- [ ] Windows 和 Linux 使用同一套业务配置模型
|
||
|
||
---
|
||
|
||
## 七、需求确认结果与待确认事项
|
||
|
||
本节已根据前述用户补充区更新。已确认内容作为正式需求依据，未确认内容不得在实现阶段擅自假设。
|
||
|
||
### 7.1 已确认的关键结论
|
||
|
||
1. 第一阶段使用 Let’s Encrypt 作为 ACME CA，并使用 `go-acme/lego` 负责申请、DNS-01 验证和自动续期；其他 ACME CA 仅预留后续扩展能力。
|
||
2. 第一阶段支持 Cloudflare、阿里云 DNS、DNSPod、CNAME 委派、华为云、腾讯云、AWS Route 53、Google Cloud DNS 及其他服务商适配器；CNAME 委派自动创建失败时提示用户手动创建。
|
||
3. 第一阶段同时保留 HTTP API 和 SMTP 通知方式；SMTP、IMAP、POP3 协议表仅作为外部邮件服务兼容性参考，Scert 通过外部 API 调用邮件发送服务，不实现邮件服务器端。
|
||
4. 管理后台采用双 HTTPS 模式：默认由核心服务直接终止 HTTPS；高级模式由 Nginx/Caddy 终止公网 HTTPS，核心服务使用内部 HTTPS。
|
||
5. 续期策略为：每 3 天常规检查一次，剩余有效期低于 10 天时每天检查，低于 6 天触发续期，低于 3 天进入紧急重试；默认重试 3 次、每次间隔 30 分钟，用户可自定义续期时间和重试次数。
|
||
6. 泛域名证书只申请 `*.example.com` 形式的泛域名，不自动包含 `example.com` 根域名。
|
||
7. CNAME 委派默认由程序自动创建；自动创建失败时，必须向用户展示记录并提示手动创建。
|
||
8. 第一阶段不限定远程目标为 Linux Nginx；默认支持 Nginx，并适配主流 Windows/Linux Web 服务器和反向代理软件。
|
||
9. 桌面版采用 Web 管理界面封装，由桌面版启动本地核心服务，并提供系统托盘、后台任务状态和可选开机自启动。
|
||
10. 协议连接表仅作为外部邮件服务兼容性参考；通知接口支持用户自定义地址、Bearer Token、HMAC-SHA256、无认证测试模式、详细/统一事件、自定义请求头、2xx 成功判定和可配置重试。
|
||
11. 多域名 SAN 证书纳入第一阶段，使用主域名作为管理归属并保存完整 SAN 域名集合；域名集合变化时生成新的证书版本。
|
||
12. 数据库支持 MySQL 和 SQLite；MySQL 5.7 作为基础开发和最低兼容版本，MySQL 8.0 作为兼容性测试版本，SQLite 用于单机、桌面和开发模式。
|
||
13. Linux 默认使用 `/ssl`、`/scert`、`/scert/conf`、`/scert/log`、`/scert/backups`；创建专用 `Scert` 服务运行用户管理证书目录，私钥由 `Scert` 和 `root` 共同受控管理。Windows 按自定义安装目录使用 `Scert\\ssl`、`Scert\\data`、`Scert\\config`、`Scert\\logs`、`Scert\\backups`。
|
||
|
||
### 7.2 仍需确认或架构评审的事项
|
||
|
||
- [x] 已确认：U-004 多域名 SAN 证书纳入第一阶段，目录、申请、续期和部署规则已纳入正式需求。
|
||
- [x] 已确认：U-040 HTTPS 采用双模式，默认核心服务直接终止，高级模式由 Nginx/Caddy 终止公网 HTTPS，核心服务使用内部 HTTPS。
|
||
- [x] 已确认：平台测试范围为 Windows 10/11、Ubuntu 22.04 + Nginx、Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理。
|
||
|
||
---
|
||
|
||
## 八、需求确认后的开发任务清单
|
||
|
||
### 阶段一：基础设计
|
||
|
||
- [ ] 未开始：冻结第一阶段需求范围
|
||
- [ ] 未开始：确定核心服务和数据模型
|
||
- [ ] 未开始：确定配置文件和数据库方案
|
||
- [ ] 未开始：确定敏感信息加密方案
|
||
- [ ] 未开始：确定证书目录和版本结构
|
||
- [ ] 未开始：确定任务状态机
|
||
- [ ] 未开始：确定 Windows、Linux、Windows Service 和 Linux systemd 的运行适配边界
|
||
- [ ] 未开始：建立 Windows 10/11、Ubuntu 22.04 + Nginx、Ubuntu 24.04 + Nginx、CentOS/Rocky Linux、Debian、Caddy、Apache 和其他主流反向代理测试矩阵
|
||
|
||
### 阶段二：证书申请
|
||
|
||
- [ ] 未开始：实现 `go-acme/lego` ACME Issuer 和生命周期管理
|
||
- [ ] 未开始：接入 Let’s Encrypt 生产环境和 ACME Staging 测试环境
|
||
- [ ] 未开始：实现 DNS 服务商适配器接口
|
||
- [ ] 未开始：实现国内外主流 DNS 服务商适配器
|
||
- [ ] 未开始：实现 CNAME 委派自动创建、失败提示和传播检测
|
||
- [ ] 未开始：实现 DNS Zone、权限和 DNS 传播检测
|
||
- [ ] 未开始：实现证书保存和校验
|
||
- [ ] 未开始：实现生产/开发证书分类及单域名、泛域名证书目录
|
||
- [ ] 未开始：实现多域名 SAN 证书标识集合、目录、申请、续期、版本保存和部署关联
|
||
|
||
### 阶段三：续期和部署
|
||
|
||
- [ ] 未开始：实现每 3 天检查、低于 10 天每天检查的调度器
|
||
- [ ] 未开始：实现低于 6 天续期、低于 3 天紧急重试的续期任务
|
||
- [ ] 未开始：实现申请任务串行队列和任务等待、轮询
|
||
- [ ] 未开始：实现默认 3 次、每次间隔 30 分钟且可配置的失败重试
|
||
- [ ] 未开始：实现 SSH 部署
|
||
- [ ] 未开始：实现 Web 服务器和反向代理部署适配器，默认支持 Nginx
|
||
- [ ] 未开始：实现远程配置检查、默认或自定义 reload 命令
|
||
- [ ] 未开始：实现远程 HTTPS 校验
|
||
- [ ] 未开始：实现版本化部署和回滚
|
||
- [ ] 未开始：实现所有 A/AAAA 记录检查
|
||
- [ ] 未开始：实现 HTTP API 和 SMTP 任务通知及通知失败重试
|
||
|
||
### 阶段四：管理界面
|
||
|
||
- [ ] 未开始：实现管理员认证
|
||
- [ ] 未开始：实现超级管理员、管理员和普通用户角色权限
|
||
- [ ] 未开始：实现 Web API
|
||
- [ ] 未开始：实现域名管理页面
|
||
- [ ] 未开始：实现证书状态页面
|
||
- [ ] 未开始：实现服务器配置页面
|
||
- [ ] 未开始：实现任务和日志页面
|
||
- [ ] 未开始：实现初始化向导
|
||
|
||
### 阶段五：平台和扩展
|
||
|
||
- [ ] 未开始：实现 Linux systemd 适配
|
||
- [ ] 未开始：实现 Windows Service 适配
|
||
- [ ] 未开始：实现桌面版 Web 封装、核心服务启动、系统托盘和后台任务状态
|
||
- [ ] 未开始：实现桌面版 exe 安装包和可选开机自启动
|
||
- [ ] 未开始：实现用户证书上传
|
||
- [ ] 未开始：实现数据库备份、配置导入导出和灾难恢复
|
||
- [ ] 未开始：实现敏感信息轮换、加密密钥备份和安全审计报告
|
||
- [ ] 未开始：实现外部邮件服务 API 通知、SMTP 通知和 HTTP 通知配置页面
|
||
- [ ] 未开始：实现双 HTTPS 模式、Linux systemd 最低基线和 Windows Service 适配
|
||
- [ ] 未开始：预留自定义 ACME CA、高可用、多实例和 ARM64 扩展
|
||
|
||
---
|
||
|
||
## 九、确认记录
|
||
|
||
| 日期 | 确认人 | 变更内容 | 结果 |
|
||
|---|---|---|---|
|
||
| 2026-08-25 | 用户与系统整理 | 根据用户补充 U-035 更新协议连接策略、端口和认证限制 | 73 项已填写 |
|
||
|
||
---
|
||
|
||
## 十、文档状态说明
|
||
|
||
- `[ ]` 未开始
|
||
- `[~]` 进行中
|
||
- `[x]` 已完成，等待复审
|
||
- `[✓]` 复审通过
|
||
- `[!]` 暂缓或存在阻塞
|
||
|
||
需求确认后，已填写并整理的条目标记为 `[x]`，等待复审；复审通过后标记为 `[✓]`；暂缓、阻塞或仍需确认的条目标记为 `[!]`。开发任务清单中的任务在实际开发过程中按状态更新。
|
||
|
||
## 二十九、本轮安装部署流程补充（2026-08-26）
|
||
|
||
本节为本轮新增确认内容。为便于逐点对照，每一条用户需求后紧跟实现说明和当前状态；不删除前文既有需求。
|
||
|
||
### 29.1 命令行系统安装流程
|
||
|
||
1. **用户补充：**安装 Scert 本体时，同时安装并打包 `Scert-admin`；`Scert-admin` 用于超级管理员密码重置。
|
||
- **实现说明：**安装产物必须同时包含 `scert` 和 `scert-admin` 两个可执行文件；两个程序共享配置和数据，但作为独立服务运行。
|
||
- **状态：**`[x]` 已完成基础服务入口，安装器和服务注册尚未完成。
|
||
|
||
2. **用户补充：**命令行安装启动时，只进行初始化配置：超级管理员用户名、密码、第三方邮箱和 Scert 主服务端口；密码重置功能不再配置独立端口。
|
||
- **实现说明：**`scert init` 使用交互式向导保存上述字段；系统根据 Web 管理域名或公网 IP 自动生成 `https://域名或IP/reset` 密码重置地址，不在公开地址中暴露主服务监听端口。初始化完成后日常管理转由 Web 页面，CLI 保留非交互式状态和自动化能力。
|
||
- **状态：**`[x]` 已完成配置模型和交互式基础流程，第三方邮箱真实适配尚未完成。
|
||
|
||
3. **用户补充：**配置 DNS API 并进行验证测试。
|
||
- **实现说明：**初始化配置必须记录 DNS 服务商、凭据引用和验证状态；验证未通过时不得将 `setup_ready` 标记为完成。明文密钥应进入加密凭据存储，不直接写入普通配置文件。
|
||
- **状态：**`[x]` 已完成状态门禁；真实 provider 连通性测试为后续任务。
|
||
|
||
4. **用户补充：**配置 SSL 证书部署位置，默认使用 `/ssl/{域名}`，用户可以自定义。
|
||
- **实现说明：**配置模型保存证书根目录，证书任务根据域名和证书类型生成子目录；默认 Linux 根目录为 `/ssl`，Windows 默认根目录为安装目录下的 `Scert\ssl`。
|
||
- **状态：**`[x]` 已完成根目录配置基础能力；证书类型子目录和版本化落盘待证书模块实现。
|
||
|
||
5. **用户补充：**提示用户配置 Web 页面域名；没有域名时允许使用公网 IP。
|
||
- **实现说明：**Web 初始化目标只能二选一：域名或公网 IP。域名支持单域名、泛域名或 SAN；公网 IP 只按单 IP 标识处理，不支持把 IP 当作泛域名。
|
||
- **状态：**`[x]` 已完成配置校验基础能力；IP ACME 证书能力需单独验证后实现。
|
||
|
||
6. **用户补充：**DNS API 配置完成且测试通过后再申请证书。
|
||
- **实现说明：**初始化状态机顺序固定为：配置凭据 → DNS API 验证 → 申请 Web 证书 → 部署和校验 → 开放服务端口 → 标记初始化完成。
|
||
- **状态：**`[x]` 已写入流程约束；真实申请、部署和校验尚未完成。
|
||
|
||
7. **用户补充：**SSL 申请成功后开放用户指定端口，并提示用户在安全组放行自定义端口。
|
||
- **实现说明：**初始化程序自动检查并放行 Scert 主服务 TCP 端口。Windows 10/11 使用 Windows Defender 防火墙，Linux 支持已启用的 UFW 和 firewalld；规则名称固定、可追踪并支持重复执行。`Scert-admin` 不监听任何 TCP/UDP 端口，因此不创建额外防火墙规则。云厂商安全组不作为跨厂商自动修改对象，初始化完成后仍明确提示用户只需手动放行主服务端口。
|
||
- **失败处理：**本机防火墙权限不足、命令执行失败或规则创建失败时，初始化必须返回中文错误，不得静默标记成功；如果配置保存失败，只回滚本次初始化新建的规则，不删除初始化前已经存在的规则。防火墙未启用时返回“无需创建规则”的明确状态，不主动启用系统防火墙。
|
||
- **状态：**`[x]` 已完成核心适配层、Web/CLI 初始化接入和自动回滚；Windows 10/11、Ubuntu 22.04/24.04、CentOS/Rocky Linux 实机安装流程仍需随安装器复审。
|
||
|
||
### 29.2 图形系统安装流程
|
||
|
||
1. **用户补充：**图形安装包点击安装时，同时安装 Scert 本体和 `Scert-admin`。
|
||
- **实现说明：**Windows 桌面安装包必须将两个可执行文件、配置模板、服务注册组件和卸载组件作为一个安装产物交付。
|
||
- **状态：**`[ ]` 安装包尚未实现。
|
||
|
||
2. **用户补充：**安装完成后第一次启动时，显示与 CLI 等价的超级管理员配置向导。
|
||
- **实现说明：**Wails 桌面端复用同一套初始化服务和校验规则，不复制业务逻辑；向导完成后可启动核心服务。`Scert-admin` 不随桌面端或系统自动启动，只有用户明确进入超级管理员密码重置流程时，才允许通过受控本地方式启动，并在操作结束后停止。
|
||
- **状态：**`[ ]` Wails 向导尚未实现。
|
||
|
||
3. **用户补充：**桌面端增加“是否开启 Web 页面”按钮。
|
||
- **实现说明：**`web.enabled` 是持久化配置，关闭时桌面端仍可运行本地控制能力，但不启动 Web 管理监听；重新开启必须记录审计日志并重新检查端口和证书状态。
|
||
- **状态：**`[x]` 已完成配置字段和 CLI 参数；桌面端按钮尚未实现。
|
||
|
||
### 29.3 双服务和安全边界
|
||
|
||
1. **用户补充：**Scert 与 `Scert-admin` 同包交付。
|
||
- **实现说明：**`Scert` 负责证书管理、Web API、`/reset` 路由和任务调度；`Scert-admin` 是不监听网络端口的临时入口激活器，只负责生成一次性校验码并维护短时激活租约。
|
||
- **状态：**`[x]` 已完成独立 Go 入口、无网络监听控制器和主服务 `/reset` 路由；完整密码修改接口尚未实现。
|
||
|
||
2. **实现约束：**`Scert-admin` 不监听任何 TCP/UDP 端口；Scert 主服务固定注册 `/reset`，但仅在 `Scert-admin` 运行并持有有效租约时显示重置页面，未激活、停止或租约过期时统一返回 `404`。
|
||
- **说明：**启动 `Scert-admin` 时生成一次性校验码，状态文件只保存校验码的 SHA-256 摘要。租约有效期为 90 秒，每 30 秒刷新；正常停止时立即失效，异常退出后最迟在租约过期时失效。systemd 将单次运行最长时间限制为 30 分钟。
|
||
- **状态：**`[x]` 已完成 `/reset` 临时入口、租约、一次性校验码摘要和安全响应头；密码提交、校验码消费、密码摘要更新、频率限制及审计尚未实现。
|
||
|
||
3. **用户补充：**Linux 上的 `Scert-admin` 不允许开机自启动，只能通过 `systemctl start Scert-admin` 和 `systemctl stop Scert-admin` 进行日常启停控制，其他控制命令不作为支持入口。
|
||
- **实现说明：**`Scert-admin.service` 不提供 `[Install]` 段，不配置自动重启和 `ExecReload`；安装器不得执行 `systemctl enable`、`systemctl start` 或 `systemctl restart Scert-admin`。安装或升级阶段仅允许为加载新 unit 执行一次 `systemctl daemon-reload`，日常运维文档只提供 `start` 和 `stop`。
|
||
- **安全边界：**systemd 无法阻止 root 或等效权限操作者调用其他管理命令，因此同时依靠无独立网络监听、短时租约、30 分钟运行上限、未激活时返回 `404`、`Restart=no` 和 `Scert` 运行用户降低暴露面；不能宣称对 root 的所有 systemd 命令具有绝对阻断能力。
|
||
- **状态：**`[x]` 已新增 systemd 单元和服务管理说明，安装器及 Linux 实机复审仍待完成。
|
||
|
||
### 29.4 本轮暂不视为完成
|
||
|
||
- `[!]` 真实 `go-acme/lego` 申请和 Web 证书部署。
|
||
- `[!]` DNS API provider 的凭据加密存储和在线验证。
|
||
- `[!]` Windows/Linux 安装器、Windows Service、Linux systemd 注册；本轮已完成 `Scert-admin` 手动启停单元草案，尚未完成安装器注册和 Linux 实机复审。
|
||
- `[!]` Scert-admin 的完整密码重置协议和审计。
|
||
- `[x]` 本机防火墙自动配置已完成代码和自动化测试；安装器提权与各目标系统实机复审待完成。
|
||
- `[!]` 云安全组自动配置不纳入当前自动修改范围，继续由初始化界面提示用户手动放行。
|
||
- `[!]` 公网 IP 证书在目标 CA 和 `lego` 版本上的兼容性验证。
|
||
|
||
## 三十、本轮 DNS 授权范围与 SSH 推送测试范围补充（2026-08-29）
|
||
|
||
本节记录本轮用户补充内容，保留前文历史测试记录，便于对照追踪。
|
||
|
||
### 30.1 阿里云 RAM DNS 授权范围
|
||
|
||
- **用户补充：**本轮测试使用的阿里云 RAM 账号只允许控制以下 DNS 根域名：
|
||
- `epwn.uno`
|
||
- `zedyj.cn`
|
||
- `szqh.uno`
|
||
- **实现说明：**测试代码、示例配置和文档不得保存 AccessKeyId、AccessKeySecret 或其他敏感凭据；DNS 测试应验证授权边界，禁止将操作扩展到未授权域名。
|
||
- **状态：**`[x]` 已记录最新授权域名范围，真实 API 读取验证待在授权环境执行。
|
||
|
||
### 30.2 SSH 推送测试服务器
|
||
|
||
- **用户补充：**在已有 `192.168.2.3` 测试机基础上，增加 `192.168.2.4` 作为证书推送测试机。
|
||
- **实现说明：**测试范围同时覆盖 `192.168.2.3` 和 `192.168.2.4`；测试配置不得硬编码到生产配置，且每台服务器必须单独配置 SSH 用户、端口、私钥引用、主机指纹和远程证书路径。
|
||
- **状态：**`[x]` 已更新测试范围说明，实际连接、证书推送和服务重载验证待执行。
|
||
|
||
### 30.3 SSH 密钥配置引导
|
||
|
||
- **用户补充：**为不熟悉 SSH 密钥生成的用户提供从生成密钥到粘贴公钥的完整指导，并支持更省事的操作方式。
|
||
- **实现说明：**服务器配置页面增加 Windows、Linux/macOS 命令切换；支持复制密钥生成命令、复制公钥安装命令、选择本机私钥文件导入、私钥口令显示/隐藏，以及 Linux 和 Windows OpenSSH 授权位置说明。私钥只在页面内存中读取，保存时由后端加密存储。
|
||
- **状态：**`[x]` 已完成前端引导和中文说明文档，待前端构建和真实浏览器页面复审。
|