完善证书管理与邮件通知流程

This commit is contained in:
xuans committed 2026-08-28 15:23:23 +08:00
1 parent c74372284a
commit b2833b761d
60 files changed
+7340 -254

No files matched your search

+1 -1
View File
@@ -926,7 +926,7 @@ imported 外部导入
- **状态:**`[x]` 已完成基础服务入口,安装器和服务注册尚未完成。
2. **用户补充:**命令行安装启动时,只进行初始化配置:超级管理员用户名、密码、第三方邮箱和 Scert 主服务端口;密码重置功能不再配置独立端口。
- **实现说明:**`scert init` 使用交互式向导保存上述字段;系统根据 Web 管理域名或公网 IP 与主服务端口自动生成密码重置地址。主端口为 `443` 时地址为 `https://域名或IP/reset`,其他端口为 `https://域名或IP:主端口/reset`。初始化完成后日常管理转由 Web 页面,CLI 保留非交互式状态和自动化能力。
- **实现说明:**`scert init` 使用交互式向导保存上述字段;系统根据 Web 管理域名或公网 IP 自动生成 `https://域名或IP/reset` 密码重置地址,不在公开地址中暴露主服务监听端口。初始化完成后日常管理转由 Web 页面,CLI 保留非交互式状态和自动化能力。
- **状态:**`[x]` 已完成配置模型和交互式基础流程,第三方邮箱真实适配尚未完成。
3. **用户补充:**配置 DNS API 并进行验证测试。
+139 -5
View File
@@ -50,7 +50,7 @@
### 2.3 ACME 和证书
- [x] 第一阶段使用 Let’s Encrypt。
- [x] 使用 `go-acme/lego`,不使用 `acme.sh`。
- [x] 使用 `go-acme/lego` 作为唯一 ACME 客户端实现。
- [x] 支持 Let’s Encrypt Production 和 Staging。
- [x] 支持 DNS-01 验证。
- [x] 第一阶段支持单域名、泛域名和多域名 SAN 证书。
@@ -200,7 +200,7 @@ Windows:
阶段验收标准:
- 需求文档、技术架构文档和任务清单没有互相矛盾的基础决策。
- 代码开发不再使用已废弃的 `acme.sh` 方案。
- 代码开发统一使用已确认的 `go-acme/lego` 方案。
- MySQL 5.7 和 MySQL 8.0 的用途明确区分。
---
@@ -1869,14 +1869,14 @@ Linux amd64 可以交叉编译
- [✓] 密码重置服务取消独立监听端口,初始化流程只配置 Scert 主服务端口。
- [✓] 根据 Web 管理域名或公网 IP 自动生成 `/reset` 地址。
- [✓] 主服务端口为 `443` 时省略端口号,其他端口继续使用主服务端口,不增加新的防火墙或云安全组端口。
- [✓] `/reset` 公开地址始终使用 `https://域名或IP/reset`,不暴露主服务监听端口,也不增加新的防火墙或云安全组端口。
- [✓] `Scert-admin` 默认不启动,不允许开机自启动,日常控制仍只支持 `systemctl start Scert-admin` 和 `systemctl stop Scert-admin`。
- [✓] `/reset` 只在 `Scert-admin` 显式启动并持有有效租约时临时开放,其他时间隐藏为 `404`。
### 43.2 开发任务状态
- [✓] 删除配置模型、初始化 API、CLI 和 Web 初始化向导中的独立重置主机与端口字段。
- [✓] 配置模型新增 `ResetURL()`,支持域名、IPv4、IPv6、`443` 省略端口和非 `443` 主端口。
- [✓] 配置模型新增 `ResetURL()`,支持域名、IPv4 和 IPv6,并统一生成不带主服务端口的 `https://域名或IP/reset`。
- [✓] 将 `scert-admin` 从独立 HTTP 服务改为无网络监听的短时租约控制器。
- [✓] 启动时生成一次性校验码,状态文件只保存 SHA-256 摘要,不保存明文校验码。
- [✓] 租约有效期设置为 90 秒,每 30 秒刷新;正常停止立即失效,异常退出后自动过期。
@@ -1962,4 +1962,138 @@ Linux amd64 可以交叉编译
### 45.4 当前状态
- [!] 本轮视觉修改已完成,等待用户确认参考效果。
- [!] 当前仅完成初始化向导界面优化,不代表 Scert 完整产品的 ACME/lego 签发、自动续期、远程部署和正式 HTTPS 生产验收已完成。
- [!] 当前仅完成初始化向导界面优化,不代表 Scert 完整产品的 ACME/lego 签发、自动续期、远程部署和正式 HTTPS 生产验收已完成。
## 四十六、全量开发清单阶段复审记录(2026-08-27)
### 46.1 本轮需求清单
- [x] 执行开发清单中当前可以在本机独立完成的代码、测试、构建和安全复审任务。
- [x] 修复 CLI 恢复流程中的备份覆盖、源目标相同、目标类型和失败回滚边界。
- [x] 复审 SQLite 连接可靠性、MySQL DSN 脱敏、证书本地完整性校验和 CLI 备份安全。
- [x] 复审前端目录拆分、用户可见文字和 HTML 实体问题。
- [x] 重新执行后端、前端和 Windows/Linux amd64 构建验证。
- [x] 更新本清单,区分本地复审通过项、已实现但待实机验收项和当前阻塞项。
### 46.2 本轮开发任务状态
- [x] `backend/internal/cli/operations.go` 的 `restore` 增加恢复输入规范化、当前配置校验、备份数据库普通文件校验、恢复源与目标相同保护、目标类型校验和恢复前备份。
- [x] 恢复 SQLite 数据库失败时,增加配置和数据库的回滚尝试,并返回明确中文错误。
- [x] 恢复文件判断改用不跟随符号链接的普通文件检查,避免把符号链接当作安全恢复目标。
- [x] 补充 CLI 备份、恢复输入、排他复制和路径规范化测试。
- [x] 保留配置和数据库恢复前备份,不覆盖已有备份文件。
- [x] 修复 Dashboard 服务器重载命令占位文本中的 HTML 换行实体,改为普通中文界面可读形式。
- [x] 保留页面公共组件和按页面目录拆分结构:`src/views/components/AccessShell` 与各页面目录分离管理。
### 46.3 自动化复审结果
- [✓] `go test ./...` 通过。
- [✓] `go test -race ./...` 通过。
- [✓] `go vet ./...` 通过。
- [✓] `go mod verify` 通过。
- [✓] `npm.cmd run build` 通过。
- [✓] Windows amd64、`CGO_ENABLED=0` 的 `review-scert-windows-amd64.exe` 和 `review-scert-admin-windows-amd64.exe` 构建通过。
- [✓] Linux amd64、`CGO_ENABLED=0` 的 `review-scert-linux-amd64` 和 `review-scert-admin-linux-amd64` 构建通过。
- [✓] `git diff --check` 通过。
- [✓] 后端 Go 源码和前端源码未发现中文 HTML 实体、Unicode 转义、乱码或旧重置入口类名。
- [✓] 代码、文档和配置源文件未发现 UTF-8 BOM。
- [✓] Git 差异未发现删除文件或重命名文件;本轮未执行 Git 提交、推送、重置或清理。
- [✓] 新构建产物使用 `review-` 前缀,未覆盖 `build` 目录中已有构建文件。
### 46.4 已实现但必须继续进行真实环境验收的任务
以下任务已有代码或测试基础,但不能仅凭本机自动化测试标记为复审通过:
- [x] `go-acme/lego`、Let’s Encrypt Production/Staging、DNS-01 Provider 和 CNAME 委派的代码接入边界已保留。
- [x] 证书本地文件、私钥匹配、完整证书链、有效期、域名覆盖和 SAN 覆盖校验已实现。
- [x] SSH 私钥加密存储、远程部署工作流、远程证书目录模板和失败回滚的基础能力已实现。
- [x] HTTP 通知、第三方邮件接口配置、事件模式、认证方式、重试和脱敏配置基础能力已实现。
- [x] SQLite、MySQL 5.7 和 MySQL 8.0 的数据访问与迁移分支已保留,SQLite 已通过本地专项验证。
- [x] 需要真实环境继续验证:Let’s Encrypt 申请、各 DNS 服务商 API、CNAME 委派、真实 SSH/SFTP、远程 Windows 10/11、Ubuntu 22.04/24.04、Debian、CentOS/Rocky Linux、Nginx、Caddy、Apache、MySQL 5.7/8.0 实例和云安全组。
- [x] 需要真实环境继续验证:Linux systemd、Windows Service、本机防火墙真实放行、核心 HTTPS 终止、高级反向代理 HTTPS、Wails 桌面版和浏览器视觉验收。
### 46.5 当前阻塞或未完成任务
- [!] 真实 Let’s Encrypt 和 DNS Provider 连通性未使用用户生产凭据执行,不能宣称证书申请已经成功。
- [!] 真实服务器部署和部署后的公网 HTTPS 在线校验尚未完成,不能宣称多服务器部署已经完成。
- [!] Scert 核心服务生产级 HTTPS 终止、高级反向代理内部 HTTPS 和公开端口独立配置仍需继续开发与实机验证。
- [!] `Scert-admin` 一次性密码重置仍需受保护的本地校验码呈现机制;不能把标准输出中的校验码方式作为生产方案。
- [!] Wails 桌面安装器、Windows Service、Linux systemd 安装和跨平台防火墙适配仍需继续开发或实机验收。
- [!] MySQL 5.7 基础实例连接、MySQL 8.0 兼容迁移和升级回滚尚未完成实机验收。
- [!] 原清单中仍有大量规划阶段 `[ ]` 条目,不能因为局部代码和自动化测试通过而整体改为 `[✓]`。
### 46.6 复审结论
本轮已完成当前工作区内可以独立验证的开发、修复和自动化复审,后端测试、竞态检查、静态检查、依赖校验、前端构建和双平台 amd64 构建均通过。恢复流程的安全边界已补强,前端源码中的遗留 HTML 实体已处理。
本项目当前结论为:**本地开发复审通过,尚未达到完整产品发布和需求总验收条件**。后续应优先完成真实 ACME/DNS、真实远程部署、正式 HTTPS、认证安全、安装服务、Wails 和 MySQL 双版本实机验收。原有章节中的历史状态和未完成项保留,不进行机械批量改标。
## 四十七、Lego DNS Provider 集成与离线复审记录(2026-08-28)
### 47.1 本轮需求清单
- [x] 继续使用 `go-acme/lego` 作为 ACME 和 DNS-01 实现。
- [x] 接入第一批已确认的 DNS Provider 工厂。
- [x] 保留 CNAME 委派和其他服务商扩展占位,不虚构尚未完成的适配器。
- [x] 修正旧测试中将阿里云 DNS 错误标记为未开放的问题。
- [x] 单元测试不得因伪造凭据访问真实云 API。
### 47.2 本轮开发任务状态
- [x] 接入 Cloudflare、阿里云 DNS、DNSPod、华为云、腾讯云、AWS Route 53 和 Google Cloud DNS 的 lego Provider 构造工厂。
- [x] 为新增 lego Provider 补齐 Go 模块依赖和校验和。
- [x] 为已接入 Provider 增加构造级测试。
- [x] 保留 CNAME 委派和其他服务商的类型化未开放错误。
- [x] 华为云测试改为无效区域校验,避免单元测试触发真实鉴权请求。
- [x] Google Cloud 测试使用格式错误的服务账号 JSON 验证已接入且错误可识别。
### 47.3 本轮验证状态
- [✓] `go test ./internal/dnsprovider` 通过。
- [✓] `go test -race ./internal/dnsprovider` 通过。
- [✓] `go vet ./internal/dnsprovider` 通过。
- [✓] `go test ./...` 通过。
- [✓] `go test -race ./...` 通过。
- [✓] `go vet ./...` 通过。
- [✓] `go mod verify` 通过。
- [✓] `npm.cmd run build` 通过。
- [✓] `git diff --check` 通过;换行格式提示不属于差异错误。
### 47.4 当前边界
- [x] Provider 工厂和凭据字段映射已完成本地代码级接入,等待真实环境验收。
- [!] 本轮未使用真实 DNS API 凭据,不能将 DNS 权限测试、记录创建清理和证书申请标记为生产验收通过。
- [!] 华为云 lego 构造过程可能在有效凭据下请求项目区域信息,真实测试必须放在集成测试或用户明确授权的环境中。
- [!] CNAME 委派和其他服务商仍属于扩展占位,未接入自动创建、检查和清理流程。
### 47.5 复审结论
本轮完成了第一批 lego DNS Provider 的工厂接入、依赖锁定和离线测试修正。全量后端测试、竞态检查、静态检查、模块校验和前端构建均通过。真实 DNS 服务商权限、DNS-01 记录生命周期和 Let’s Encrypt 证书签发仍需在受控真实环境中继续验收。
## 四十八、HTTP 邮件通知会话认证与中文编码修复记录(2026-08-28)
### 48.1 本轮需求清单
- [✓] 使用 UTF-8 编码发送登录请求和邮件通知请求。
- [✓] HTTP 通知请求声明 `application/json; charset=utf-8`。
- [✓] 检查邮件服务统一响应中的 `errorNo`,不能只依据 HTTP 200 判断成功。
- [✓] 会话认证收到 HTTP 401、403 或对应业务错误码时,重试前重新登录。
- [✓] 保留会话认证密码原文,不因校验而修改合法密码内容。
- [✓] 初始化向导支持“账号登录会话”和自定义登录路径。
- [✓] CLI 支持修改 `notification.http_login_path`。
- [✓] 增加中文 UTF-8、业务失败和会话刷新回归测试。
### 48.2 本轮验证状态
- [✓] `go test ./...` 通过。
- [✓] `go test -race ./...` 通过。
- [✓] `go vet ./...` 通过。
- [✓] `go mod verify` 通过。
- [✓] `npm.cmd run build` 通过。
- [✓] `git diff --check` 通过。
- [!] 临时邮件服务此前由 Windows PowerShell 默认编码发送的旧邮件已经乱码,无法在服务端原地修复;该邮件已保留作为问题记录。
- [✓] 使用明确 UTF-8 请求重新发送唯一测试邮件,并通过邮件列表和详情接口确认标题、纯文本、HTML 正文均为正常中文,状态为成功且错误为空。
- [!] 本轮验证的是临时邮件服务的服务端列表与详情结果,尚未在最终收件邮箱客户端中完成到达、编码和渲染复核。
### 48.3 复审结论
本轮已完成 HTTP 邮件通知的 UTF-8 编码、业务响应判断、会话失效刷新和配置入口开发,并通过自动化验证;同时已通过临时邮件服务的接口详情确认修复后的中文内容正常。Scert 代码链路已经避免因客户端默认字符集导致的中文乱码,但最终收件邮箱客户端的到达和渲染仍需在发布环境继续复核。
+770
View File
@@ -0,0 +1,770 @@
# Smail 后端接口说明文档
> 本文档用于说明当前 Smail 后端 HTTP API 的实际调用方式,并对照原版 PMail《后端接口文档》核对接口是否仍然存在。
>
> 核对基准:当前代码分支 `main`,提交 `6ec4628`,核对日期:2026-08-27。
## 1. 文档范围和结论
原版 PMail 文档包含 9 个基础接口。当前 Smail 仍然保留其中 8 个接口的功能入口,但有以下路径或调用方式变化:
| 编号 | 原版接口 | 当前实际接口 | 当前状态 | 主要差异 |
|---|---|---|---|---|
| 1 | `/api/ping` | `/api/ping` | 存在 | 当前返回统一 JSON,不再是纯文本 `pong` |
| 2 | `/api/login` | `/api/login` | 存在 | 只接受 `POST`;使用会话 Cookie 和 CSRF Cookie,不使用原版文档所述的 `token` 请求头 |
| 3 | `/api/group` | `/api/group` | 部分兼容 | 当前只接受 `GET`,原版写的 `POST` 不再可用;另有 `/api/group/list` |
| 4 | `/api/email/list` | `/api/email/list` | 存在 | 只接受 `POST`,分页参数增加范围限制 |
| 5 | `/api/detail` | `/api/email/detail` | 路径已变更 | 原路径不存在,必须使用 `/api/email/detail` |
| 6 | `/api/email/send` | `/api/email/send` | 存在 | 只接受 `POST`,增加发件人校验、附件和收件人数限制 |
| 7 | `/api/settings/modify_password` | `/api/settings/modify_password` | 存在 | 当前需要同时提交 `current_password` 和 `password` |
| 8 | `/attachments/` | `/attachments/{邮件ID}/{内容标识}` | 存在 | 当前只接受 `GET`,用于内联展示附件内容 |
| 9 | `/attachments/download/` | `/attachments/download/{邮件ID}/{附件序号}` | 存在 | 当前只接受 `GET`,最后一段是附件序号,不是附件数据库 ID |
当前路由注册以 `server/listen/http_server/http_server.go` 为准,接口处理逻辑以 `server/controllers` 和 `server/controllers/email` 为准。
## 2. 通用调用约定
### 2.1 基础地址
以下示例使用:
```text
https://mail.example.com
```
请替换为实际的 Smail Web 地址。开发环境也可以使用:
```text
http://127.0.0.1:80
```
生产环境应优先使用 HTTPS。
### 2.2 通用响应格式
除附件内容下载接口外,JSON 接口统一返回以下结构:
```json
{
"errorNo": 0,
"errorMsg": "",
"data": {}
}
```
字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
| `errorNo` | number | `0` 表示成功;非 `0` 表示失败。常见值:`100` 参数错误、`403` 未登录、`405` 无权限、`500` 服务端错误 |
| `errorMsg` | string | 错误说明。生产环境不应依赖错误文本判断业务分支,应优先判断 `errorNo` |
| `data` | any | 成功数据或错误附加数据 |
请求方法不正确时,路由层返回 HTTP `405 Method Not Allowed`,并通过 `Allow` 响应头提示允许的方法;此时不一定返回上面的 JSON 结构。
### 2.3 登录态和 CSRF
除探活、登录和公开的密码恢复流程外,邮件、分组、密码修改等接口都需要登录态。
登录成功后,服务端会设置:
1. 会话 Cookie,用于识别登录用户;
2. `smail_csrf` Cookie,用于保存 CSRF Token;
3. 后续状态修改请求需要在 `X-CSRF-Token` 请求头中提交与 `smail_csrf` Cookie 相同的值。
对于携带登录会话 Cookie 的状态修改请求,还需要使用同源的 `Origin`;跨站请求或 CSRF Token 不匹配时会被拒绝。
建议使用浏览器或 HTTP 客户端的 Cookie Jar 保存登录后的 Cookie,不要手工复制会话 Cookie 到代码或日志中。
### 2.4 请求头
JSON 请求通常应携带:
```http
Content-Type: application/json
```
需要登录的状态修改请求示例:
```http
Cookie: 会话Cookie; smail_csrf=CSRF_TOKEN
X-CSRF-Token: CSRF_TOKEN
Origin: https://mail.example.com
```
`Lang` 请求头可以指定返回语言,例如:
```http
Lang: zh-CN
```
未指定时由服务端使用默认语言处理。
### 2.5 通用错误处理
调用方建议按以下顺序处理:
1. 先检查 HTTP 状态码;
2. 对 JSON 响应解析 `errorNo`、`errorMsg` 和 `data`;
3. 收到 `403` 或业务错误码表示登录失效时,重新登录;
4. 收到 `405` 时检查请求方法,不要重试相同方法;
5. 不要把密码、会话 Cookie、CSRF Token、完整邮箱地址写入日志。
## 3. 原版基础接口对照和调用说明
## 3.1 服务探活
### 接口信息
| 项目 | 内容 |
|---|---|
| 原版路径 | `/api/ping` |
| 当前路径 | `/api/ping` |
| 当前方法 | `GET`、`POST` 均可到达处理器;建议使用 `GET` |
| 是否需要登录 | 否 |
| 请求体 | 无 |
| 返回类型 | JSON |
### 调用示例
```bash
curl -X GET "https://mail.example.com/api/ping"
```
也可以使用:
```bash
curl -X POST "https://mail.example.com/api/ping"
```
### 返回示例
```json
{
"errorNo": 0,
"errorMsg": "",
"data": "pong"
}
```
### 与原版差异
原版文档把返回格式写成 `text`,示例为纯文本 `pong`。当前代码通过统一响应封装返回 JSON,实际数据位于 `data` 字段中。
## 3.2 用户登录
### 接口信息
| 项目 | 内容 |
|---|---|
| 原版路径 | `/api/login` |
| 当前路径 | `/api/login` |
| 方法 | `POST` |
| 是否需要登录 | 否 |
| 请求格式 | `application/json` |
| 返回类型 | JSON |
### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `identifier` | string | 否 | 登录标识。当前优先使用该字段,可填写账号或完整邮箱 |
| `account` | string | 否 | 兼容原版字段。当 `identifier` 为空时使用该字段 |
| `password` | string | 是 | 登录密码 |
`identifier` 和 `account` 至少提供一个。为了兼容原版客户端,可以继续提交 `account`;新客户端建议使用 `identifier`。
### 调用示例
兼容原版字段:
```bash
curl -X POST "https://mail.example.com/api/login" \
-H "Content-Type: application/json" \
-c cookies.txt \
-d '{
"account": "admin",
"password": "your-password"
}'
```
使用新的登录标识字段:
```bash
curl -X POST "https://mail.example.com/api/login" \
-H "Content-Type: application/json" \
-c cookies.txt \
-d '{
"identifier": "admin@example.com",
"password": "your-password"
}'
```
### 成功返回示例
普通登录直接完成时,返回:
```json
{
"errorNo": 0,
"errorMsg": "",
"data": {
"account": "admin",
"name": "管理员",
"role": "super_admin",
"is_admin": 1,
"domains": [
"example.com"
]
}
}
```
登录成功时,服务端同时通过 `Set-Cookie` 设置会话 Cookie 和 CSRF Cookie。客户端必须保存这两个 Cookie,后续接口才能继续调用。
### 二次验证情况
如果当前账号启用了登录二次验证,密码正确后可能返回一个待完成的验证数据,而不是直接建立完整登录态。客户端应根据返回的 `data` 调用登录验证接口:
```text
POST /api/security/login/verify
```
该流程不属于原版 PMail 基础接口,详细接口以本文第 4 节的当前安全接口表和前端调用为准。
### 失败返回示例
```json
{
"errorNo": 100,
"errorMsg": "参数错误",
"data": ""
}
```
为了防止账号枚举,登录失败、账号不存在、密码错误和登录限流通常使用相同的业务错误响应,调用方不要根据错误文本判断账号是否存在。
### 与原版差异
原版文档提到可以通过请求头 `token` 进行验签。当前代码路由和认证逻辑未发现该兼容方式,当前登录态以服务端会话 Cookie 为准,不应使用 `token` 请求头替代登录。
## 3.3 获取邮件分组树
### 接口信息
| 项目 | 内容 |
|---|---|
| 原版路径 | `/api/group` |
| 当前路径 | `/api/group` |
| 方法 | `GET` |
| 原版方法 | `POST/GET` |
| 是否需要登录 | 是 |
| 请求体 | 无 |
| 返回类型 | JSON |
当前 `/api/group` 只注册了 `GET`。使用原版文档中的 `POST` 调用会返回 HTTP `405`。
### 调用示例
```bash
curl -X GET "https://mail.example.com/api/group" \
-b cookies.txt
```
如果是浏览器外的状态修改场景,读取接口不需要提交 CSRF Token;但必须携带有效会话 Cookie。
### 返回示例
```json
{
"errorNo": 0,
"errorMsg": "",
"data": [
{
"label": "收件箱",
"tag": "{\"type\":0,\"status\":-1,\"group_id\":0}"
},
{
"label": "发件箱",
"tag": "{\"type\":1,\"status\":-1}"
},
{
"label": "草稿箱",
"tag": "{\"type\":0,\"status\":4}"
}
]
}
```
### 当前相关分组接口
| 方法 | 路径 | 说明 | 请求体 |
|---|---|---|---|
| `GET` | `/api/group` | 获取前端使用的分组树 | 无 |
| `GET` | `/api/group/list` | 获取默认分组和用户自定义分组列表 | 无 |
| `POST` | `/api/group/add` | 创建自定义分组 | `{"name":"项目邮件","parent_id":0}` |
| `POST` | `/api/group/del` | 删除自定义分组 | `{"id":1}` |
`POST /api/group/add` 和 `POST /api/group/del` 属于状态修改接口,需要登录态和 CSRF Token。
## 3.4 获取邮件列表
### 接口信息
| 项目 | 内容 |
|---|---|
| 路径 | `/api/email/list` |
| 方法 | `POST` |
| 是否需要登录 | 是 |
| 请求格式 | `application/json` |
| 返回类型 | JSON |
### 请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---:|---:|---|
| `keyword` | string | 否 | 空字符串 | 邮件搜索关键词,最多 512 字节 |
| `tag` | string | 否 | 全部邮件 | JSON 字符串形式的筛选条件 |
| `current_page` | integer | 否 | `1` | 当前页,从 `1` 开始,最大 `10000` |
| `page_size` | integer | 否 | `15` | 每页数量,最大 `100` |
`tag` 是一个字符串字段,内容需要再次编码为 JSON,例如:
```json
"{\"type\":0,\"status\":-1,\"group_id\":0}"
```
### 调用示例
```bash
curl -X POST "https://mail.example.com/api/email/list" \
-H "Content-Type: application/json" \
-b cookies.txt \
-H "X-CSRF-Token: CSRF_TOKEN" \
-H "Origin: https://mail.example.com" \
-d '{
"keyword": "验证码",
"tag": "{\"type\":0,\"status\":-1,\"group_id\":0}",
"current_page": 1,
"page_size": 15
}'
```
### 返回示例
```json
{
"errorNo": 0,
"errorMsg": "",
"data": {
"current_page": 1,
"total_page": 1,
"list": [
{
"id": 1,
"title": "邮件标题",
"desc": "邮件正文摘要",
"datetime": "2026-08-27 08:44:00",
"is_read": false,
"sender": {
"Name": "发件人",
"EmailAddress": "sender@example.com"
},
"to": [
{
"Name": "收件人",
"EmailAddress": "admin@example.com"
}
],
"dangerous": false,
"error": ""
}
]
}
}
```
### 分页说明
- 不提交分页参数时使用 `current_page=1`、`page_size=15`;
- `current_page` 小于 `1` 或大于 `10000` 会被拒绝;
- `page_size` 小于 `1` 或大于 `100` 会被拒绝;
- `keyword` 超过 512 字节会被拒绝;
- `total_page` 在没有邮件时为 `0`。
## 3.5 获取邮件详情
### 接口信息
| 项目 | 内容 |
|---|---|
| 原版路径 | `/api/detail` |
| 当前路径 | `/api/email/detail` |
| 方法 | `POST` |
| 是否需要登录 | 是 |
| 请求格式 | `application/json` |
| 返回类型 | JSON |
### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `id` | integer | 是 | 邮件 ID,必须大于 `0` |
### 调用示例
```bash
curl -X POST "https://mail.example.com/api/email/detail" \
-H "Content-Type: application/json" \
-b cookies.txt \
-H "X-CSRF-Token: CSRF_TOKEN" \
-H "Origin: https://mail.example.com" \
-d '{
"id": 1
}'
```
### 返回示例
```json
{
"errorNo": 0,
"errorMsg": "",
"data": {
"id": 1,
"type": 0,
"subject": "邮件标题",
"reply_to": "",
"from_name": "发件人",
"from_address": "sender@example.com",
"to": "[{\"Name\":\"收件人\",\"EmailAddress\":\"admin@example.com\"}]",
"bcc": "[]",
"cc": "[]",
"sender": "{\"Name\":\"发件人\",\"EmailAddress\":\"sender@example.com\"}",
"spf_check": 1,
"dkim_check": 1,
"status": 1,
"send_time": "2026-08-27 08:44:00",
"send_date": "2026-08-27 08:44:00",
"update_time": "2026-08-27 08:44:00",
"create_time": "2026-08-27 08:44:00",
"text": "纯文本正文",
"html": "<div>HTML正文</div>",
"error": "",
"attachments": [
{
"Filename": "report.pdf",
"ContentType": "application/pdf",
"Index": 0
}
]
}
}
```
### 与原版差异
原版文档使用 `/api/detail`。当前该路径没有注册,必须改为 `/api/email/detail`。邮件详情请求会标记邮件为已读,因此调用该接口不是纯读取操作;使用 `POST` 也符合当前路由约束。
## 3.6 发送邮件
### 接口信息
| 项目 | 内容 |
|---|---|
| 路径 | `/api/email/send` |
| 方法 | `POST` |
| 是否需要登录 | 是 |
| 请求格式 | `application/json` |
| 返回类型 | JSON |
| 请求体上限 | 40 MiB |
### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `reply_to` | array | 否 | 回复地址列表,每项包含 `name`、`email` |
| `from` | object | 否 | 发件人,包含 `name`、`email`;邮箱为空时使用当前账号地址 |
| `to` | array | 是 | 收件人列表,每项包含 `name`、`email` |
| `bcc` | array | 否 | 密送列表 |
| `cc` | array | 否 | 抄送列表 |
| `subject` | string | 是 | 邮件标题 |
| `text` | string | 否 | 纯文本正文 |
| `html` | string | 否 | HTML 正文 |
| `sender` | object | 否 | SMTP Envelope Sender;为空时使用 `from` |
| `read_receipt` | array | 否 | 已读回执地址列表 |
| `attrs` | array | 否 | 附件列表,每项包含 `name`、`data` |
`attrs[].data` 必须是 Data URL 格式的 Base64 数据,例如:
```text
data:application/pdf;base64,BASE64_DATA
```
### 调用示例
```bash
curl -X POST "https://mail.example.com/api/email/send" \
-H "Content-Type: application/json" \
-b cookies.txt \
-H "X-CSRF-Token: CSRF_TOKEN" \
-H "Origin: https://mail.example.com" \
-d '{
"from": {
"name": "管理员",
"email": "admin@example.com"
},
"to": [
{
"name": "收件人",
"email": "user@example.com"
}
],
"cc": [],
"bcc": [],
"subject": "测试邮件",
"text": "这是纯文本正文。",
"html": "<p>这是 HTML 正文。</p>",
"attrs": []
}'
```
### 成功返回
```json
{
"errorNo": 0,
"errorMsg": "",
"data": "操作成功"
}
```
接口返回成功表示邮件已经通过参数校验并创建发送任务。实际投递结果可能在异步处理后才确定,失败信息会写入邮件状态,调用方应通过邮件列表或详情接口检查最终状态。
### 当前限制
- `to` 至少包含一个收件人;
- `to`、`cc`、`bcc`、`reply_to` 合计最多 `100` 个地址;
- 附件最多 `20` 个;
- 单个附件最大 `10 MiB`;
- 附件总大小最大 `25 MiB`;
- 邮件正文最大约 `8 MiB`;
- `subject` 必填;
- 普通用户不能伪造未授权的内部发件人地址;
- 附件文件名会进行路径和控制字符清理。
## 3.7 修改当前账号密码
### 接口信息
| 项目 | 内容 |
|---|---|
| 原版路径 | `/api/settings/modify_password` |
| 当前路径 | `/api/settings/modify_password` |
| 方法 | `POST` |
| 是否需要登录 | 是 |
| 请求格式 | `application/json` |
| 返回类型 | JSON |
### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `current_password` | string | 是 | 当前密码 |
| `password` | string | 是 | 新密码,长度为 8 到 256 字节 |
### 调用示例
```bash
curl -X POST "https://mail.example.com/api/settings/modify_password" \
-H "Content-Type: application/json" \
-b cookies.txt \
-H "X-CSRF-Token: CSRF_TOKEN" \
-H "Origin: https://mail.example.com" \
-d '{
"current_password": "old-password",
"password": "new-password"
}'
```
### 成功返回
```json
{
"errorNo": 0,
"errorMsg": "",
"data": "操作成功"
}
```
修改成功后,当前账号的安全凭据和登录会话会按服务端策略刷新或撤销。调用方如果收到会话失效,应重新登录并重新获取 CSRF Token。
### 与原版差异
原版示例中的 `passowrd` 是拼写错误,当前代码使用正确字段 `password`。当前接口还要求提供 `current_password`,不能只提交新密码。
## 3.8 内联获取附件内容
### 接口信息
| 项目 | 内容 |
|---|---|
| 原版路径 | `/attachments/` |
| 当前路径 | `/attachments/{邮件ID}/{内容标识}` |
| 方法 | `GET` |
| 原版方法 | 文档写成 `POST`,但请求示例使用 `GET` |
| 是否需要登录 | 是 |
| 返回类型 | 附件原始内容 |
其中:
- `{邮件ID}` 是邮件 ID;
- `{内容标识}` 是邮件详情中附件的内容标识,通常对应内联资源的 Content-ID;
- 当前处理器会按路径读取这两个值,并检查当前用户是否有权访问该邮件附件。
### 调用示例
```bash
curl -X GET "https://mail.example.com/attachments/1/image001.png" \
-b cookies.txt \
-o image001.png
```
### 返回说明
成功时返回附件原始字节,并设置对应的 `Content-Type`,例如:
```http
Content-Type: image/png
```
失败时返回统一 JSON 错误响应。常见原因包括路径格式错误、附件不存在、附件不可用或当前用户无权访问。
## 3.9 下载附件
### 接口信息
| 项目 | 内容 |
|---|---|
| 原版路径 | `/attachments/download/` |
| 当前路径 | `/attachments/download/{邮件ID}/{附件序号}` |
| 方法 | `GET` |
| 是否需要登录 | 是 |
| 返回类型 | 文件流 |
其中 `{附件序号}` 是邮件详情 `attachments` 数组中的 `Index`,当前从 `0` 开始,不是附件数据库 ID。
### 调用示例
```bash
curl -X GET "https://mail.example.com/attachments/download/1/0" \
-b cookies.txt \
-o report.pdf
```
### 返回响应头
成功时服务端返回:
```http
Content-Type: application/octet-stream
X-Content-Type-Options: nosniff
Content-Disposition: attachment; filename="attachment"; filename*=UTF-8''report.pdf
```
服务端会清理文件名中的路径分隔符、换行符和控制字符,避免下载文件名被用于路径穿越或响应头注入。
## 4. 当前新增安全和账户接口
这些接口不在原版 PMail 的 9 个基础接口中,但已经注册在当前 Smail 路由中。它们属于当前前端登录、安全设置和密码恢复流程的一部分。
### 4.1 登录和恢复流程
| 方法 | 路径 | 是否公开 | 说明 |
|---|---|---:|---|
| `POST` | `/api/security/verification/request` | 否 | 请求验证信息 |
| `POST` | `/api/security/verification/verify` | 否 | 校验验证信息 |
| `POST` | `/api/security/login/verify` | 是 | 完成登录二次验证 |
| `POST` | `/api/security/recovery/begin` | 是 | 开始密码恢复流程 |
| `POST` | `/api/security/recovery/verify` | 是 | 校验密码恢复凭据 |
| `POST` | `/api/security/recovery/complete` | 是 | 完成密码恢复 |
| `POST` | `/api/security/recovery/webauthn/begin` | 是 | 开始 WebAuthn 恢复验证 |
| `POST` | `/api/security/recovery/webauthn/verify` | 是 | 完成 WebAuthn 恢复验证 |
| `POST` | `/api/logout` | 否 | 退出当前会话 |
### 4.2 WebAuthn 和恢复码
| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/api/security/webauthn/registration/begin` | 开始注册安全密钥 |
| `POST` | `/api/security/webauthn/registration/finish` | 完成注册安全密钥 |
| `GET` | `/api/security/webauthn/credentials` | 查询当前账号安全密钥 |
| `POST` | `/api/security/webauthn/credentials/rename` | 重命名安全密钥 |
| `POST` | `/api/security/webauthn/credentials/revoke` | 撤销安全密钥 |
| `POST` | `/api/security/webauthn/login/begin` | 开始登录安全密钥验证 |
| `POST` | `/api/security/webauthn/login/finish` | 完成登录安全密钥验证 |
| `GET` | `/api/security/credentials/recovery-codes` | 查询恢复码状态,不返回历史恢复码原文 |
| `POST` | `/api/security/credentials/recovery-codes/generate` | 生成新的恢复码 |
| `POST` | `/api/security/credentials/recovery-codes/revoke` | 撤销恢复码 |
| 未限制 | `/api/security/credentials/question` | 密保问题相关流程入口,实际方法由处理器判断 |
### 4.3 外部安全邮箱
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/security/external-email/list` | 获取当前账号外部安全邮箱状态 |
| `POST` | `/api/security/external-email/bind` | 绑定外部安全邮箱 |
| `POST` | `/api/security/external-email/verify` | 验证外部安全邮箱 |
| `POST` | `/api/security/external-email/disable` | 禁用外部安全邮箱 |
以上安全接口的请求参数和恢复状态机依赖当前安全设计,不应按照原版 PMail 的 `token` 模式调用。
## 5. 当前邮件和账户管理接口补充
| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/api/email/del` | 删除邮件 |
| `POST` | `/api/email/read` | 标记邮件已读 |
| `POST` | `/api/email/move` | 移动邮件到分组 |
| `POST` | `/api/rule/get` | 获取邮件规则 |
| `POST` | `/api/rule/add` | 新增邮件规则 |
| `POST` | `/api/rule/update` | 更新邮件规则 |
| `POST` | `/api/rule/del` | 删除邮件规则 |
| `POST` | `/api/user/create` | 创建用户,权限由当前角色控制 |
| `POST` | `/api/user/edit` | 编辑用户 |
| `POST` | `/api/user/info` | 获取用户信息 |
| `POST` | `/api/user/list` | 获取用户列表 |
| `GET` | `/api/plugin/list` | 获取插件列表 |
| `GET`、`POST` | `/api/plugin/settings/{插件名}/{操作}` | 读取或保存插件设置 |
配置管理接口使用 `/api/v1/config/` 和 `/api/v1/audits/config` 路径,属于新的配置系统,不属于原版 PMail 基础接口;调用时需要按当前配置授权、审计和 CSRF 规则处理。
## 6. 原版接口迁移清单
使用原版 PMail 客户端迁移到当前 Smail 时,至少需要修改以下内容:
| 原版调用 | 当前调用 |
|---|---|
| `POST /api/detail` | `POST /api/email/detail` |
| `POST /api/group` | `GET /api/group` |
| `POST /attachments/{邮件ID}/{附件标识}` | `GET /attachments/{邮件ID}/{附件标识}` |
| 仅提交 `password` 修改密码 | 同时提交 `current_password` 和 `password` |
| 使用 `token` 请求头认证 | 保存登录会话 Cookie,并在状态修改请求中提交 `X-CSRF-Token` |
| 将 `/api/ping` 当作纯文本读取 | 解析 JSON,并读取 `data` 中的 `pong` |
## 7. 代码核对位置
本次对照使用以下当前代码位置作为实现依据:
- 路由注册:`server/listen/http_server/http_server.go`
- 请求上下文、登录态和 CSRF 校验:`server/listen/http_server/https_server.go`
- 登录:`server/controllers/login.go`
- 分组:`server/controllers/group.go`
- 密码修改:`server/controllers/settings.go`
- 附件:`server/controllers/attachments.go`
- 邮件列表:`server/controllers/email/list.go`
- 邮件详情:`server/controllers/email/detail.go`
- 邮件发送:`server/controllers/email/send.go`
- 统一 JSON 响应:`server/dto/response/response.go`
原版对照来源为 PMail Wiki 的《后端接口文档》。原版文档仅作为历史兼容性参考,接口是否可调用以当前 Smail 路由和处理器实现为准。
+76
View File
@@ -0,0 +1,76 @@
# 邮件通知配置说明
## 1. 配置目的
Scert 的证书申请、续期、部署和校验任务完成后,可以通过第三方邮件服务 API 发送通知。SMTP、IMAP、POP3 协议仅作为外部邮件服务兼容性参考,Scert 不实现邮件服务器端;当前已接入 HTTP 邮件 API 通知。
## 2. HTTP 邮件服务配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| `email_http_enabled` | 是否启用 HTTP 邮件通知 | `false` |
| `email_provider` | 第三方服务标识 | 空 |
| `email_endpoint` | 第三方服务基础地址,必须使用 HTTP 或 HTTPS | 空 |
| `email_http_path` | 请求路径 | `/api/email/send` |
| `email_http_auth_mode` | `none`、`bearer`、`hmac_sha256` 或 `session` | `none` |
| `email_http_login_path` | 会话认证模式的登录请求路径 | `/api/login` |
| `email_http_credential_ref` | 凭据引用,不填写明文 Token 或密钥 | 空 |
| `email_http_headers` | 自定义请求头 JSON 对象 | `{}` |
`email_endpoint` 与 `email_http_path` 分开保存。例如 Smail 服务可以配置基础地址为 `https://mail.example.com`,请求路径使用 `/api/email/send`。
Bearer Token 或 HMAC-SHA256 的实际密钥必须由凭据存储管理,配置文件只保存 `secret://` 等形式的引用。自定义请求头不能覆盖 `Authorization`、`Cookie`、`Origin`、`Referer`、`Content-Type`、`Accept`、`X-CSRF-Token`、`X-Scert-Signature`、`X-Scert-Request-Id` 和 `X-Scert-Timestamp` 等安全请求头。
## 3. Smail 接口适配说明
Smail 的发送接口为:
```text
POST /api/email/send
Content-Type: application/json
```
请求体沿用 Smail 的英文字段名,包括 `from`、`to`、`cc`、`bcc`、`subject`、`text`、`html` 和 `attrs`。Scert 的通知发送器应将证书任务事件转换为邮件标题、纯文本正文和 HTML 正文。
Smail 当前接口需要登录会话 Cookie、`smail_csrf` Cookie、`X-CSRF-Token` 请求头和同源 `Origin` 请求头。Scert 的 `session` 认证模式会使用凭据存储中的账号和密码调用配置的登录路径,读取登录响应中的会话 Cookie,并在发送邮件时携带会话、CSRF 和同源请求头;密码不会写入请求日志、普通配置文件或错误信息。
## 4. 通知内容配置
| 配置项 | 说明 |
|---|---|
| `email_event_mode` | `detailed` 表示发送详细事件,`unified` 表示发送统一事件 |
| `email_include_deployment_details` | 是否包含服务器部署明细 |
| `email_include_certificate_serial` | 是否包含证书序列号 |
| `email_include_management_url` | 是否包含管理后台链接 |
| `email_sender_name` | 发件人名称,默认 `Scert` |
| `email_sender_email` | 发件人地址,留空时使用超级管理员绑定邮箱 |
| `recipients` | 收件人列表;未填写时自动使用超级管理员绑定邮箱 |
## 5. 超时与重试
| 配置项 | 说明 | 默认值 |
|---|---|---|
| `email_timeout_secs` | 单次通知请求超时时间 | `10` |
| `email_retry_count` | 失败后的重试次数 | `3` |
| `email_retry_intervals_secs` | 每次重试前等待的秒数 | `30,120,600` |
重试间隔数量必须与重试次数一致。HTTP 通知发送器应将所有 2xx 响应视为请求成功,其他状态码进入重试或失败流程,并记录请求 ID 和最终错误。
## 6. 当前实现边界
当前阶段已完成邮件通知配置的保存、校验、初始化接口、CLI/Web 表单接入和 HTTP 通知发送器。SMTP 发送器尚未接入;当前应优先使用 HTTP 邮件 API 方式配置邮件服务。Smail 登录会话可通过 `session` 认证模式自动建立和刷新。
## 7. 当前开发状态补充
当前版本已经接入 HTTP 邮件通知发送器,支持以下能力:
- 按证书申请、续期、导入和部署结果生成通知事件。
- 按 Smail `/api/email/send` 接口格式发送 JSON 请求。
- 支持 `none`、`bearer`、`hmac_sha256` 和 `session` 四种 HTTP 认证模式。
- `session` 模式支持配置登录路径;收到 HTTP 401、403 或对应业务错误码时,会在重试前重新登录并使用新会话发送。
- 使用加密凭据存储读取 Bearer Token 或 HMAC 签名密钥,配置文件只保存凭据引用。
- 使用 `X-Scert-Request-Id`、`X-Scert-Timestamp` 请求头,并禁止自定义请求头覆盖安全头。
- 将所有 2xx 响应视为成功,其他响应按重试配置处理。
- 证书工作流会在任务成功、失败或部署错误后触发通知;通知发送失败会写入 Scert 日志,不覆盖原证书任务结果。
SMTP 发送器仍未接入。初始化界面和 CLI 不再暴露 SMTP 开关,旧配置字段仅为兼容已有配置文件保留,并不会在初始化时启用。Smail 登录会话的自动适配已通过 `session` 模式接入,仍需在目标部署环境使用实际凭据进行上线前复核。