这是 HTML 正文。
", - "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 路由和处理器实现为准。 \ No newline at end of file +# Scert 后端接口说明文档 + +> 本文档用于完整说明 Scert 证书管理系统当前所有 HTTP API 路由、请求参数、返回契约及权限约束。 +> 核对基准：当前代码分支 main（版本： 1.52.5）。 + +--- + +## 1. 架构原则与通用调用约定 + +### 1.1 基础地址与反向代理 +- 生产环境默认管理地址：https://odacm.cn +- 服务默认本地监听：127.0.0.1:8080（通过 Nginx 进行 TLS 终止及反向代理） + +### 1.2 认证模式与安全边界 +1. **会话认证（Session-Based）**： + - 登录成功后通过 Set-Cookie 写入 HttpOnly 会话凭据 scert_session。 + - 所有写入请求（POST / PUT / DELETE）均经过同源保护检查（Same-Origin Check），严格校验 Origin 与 Referer。 +2. **三级权限控制**： + - **普通用户（user）**：仅可访问被授权参与的项目、查看项目内域名/服务器/证书、发起证书申请与部署。 + - **管理员（admin）**：具备其管理分组/项目范围内的成员管理、项目资源调配权限，可查看全局只读统计。 + - **超级管理员（super_admin）**：拥有全局最高权限，唯一具备系统配置（SMTP、默认 DNS 凭据、续期策略）、用户账号增删改查权限。 +3. **敏感凭据脱敏**： + - DNS AccessKeySecret、SSH 登录密码等敏感数据入库加密，查询接口一律返回脱敏标识（如掩码或布尔指示），禁止明文泄露。 + +### 1.3 统一响应契约 +所有 JSON 接口统一遵循以下响应规范： +- 200 OK / 201 Created：请求成功处理。 +- 400 Bad Request：参数校验未通过或业务前置条件不满足。 +- 401 Unauthorized：未登录或会话已过期。 +- 403 Forbidden：权限不足（如非超管访问系统设置）。 +- 404 Not Found：请求资源不存在。 +- 409 Conflict：资源冲突（如域名/账号已存在）。 +- 500 Internal Server Error：服务端内部异常。 + +--- + +## 2. 系统初始化接口 (Bootstrap API) + +在系统首次启动且未完成向导配置时生效，初始化完成后自动关闭。 + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /readyz | 公开 | 就绪状态探针，返回服务初始化状态及就绪信息 | +| GET | /healthz | 公开 | 健康检查探针 | +| GET | /api/v1/setup/status | 公开 | 获取当前向导初始化进度、数据库驱动及支持清单 | +| GET | /api/v1/setup/dns/providers | 公开 | 获取支持的 DNS 服务商列表（如 Aliyun） | +| POST | /api/v1/setup/dns/test | 初始化临时会话 | 测试 DNS 服务商凭据连通性与 API 权限 | +| POST | /api/v1/setup | 初始化临时会话 | 提交并应用系统首次初始化配置（超管、数据库、凭据） | + +--- + +## 3. 认证与会话管理 (Auth API) + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /api/v1/status | 公开 | 获取系统运行时状态与版本号（如 v1.52.5） | +| GET | /api/v1/auth/session | 公开 | 获取当前会话状态及登录用户信息（账号、角色等） | +| POST | /api/v1/auth/login | 公开 (需同源) | 账号密码登录，成功后写入会话 Cookie | +| POST | /api/v1/auth/logout | 已登录 (需同源) | 退出登录并销毁当前服务端会话与 Cookie | +| POST | /api/v1/auth/password | 已登录 | 修改当前已登录账号的登录密码 | +| POST | /api/v1/password-reset/resolve | 公开 | 密码重置指引接口（本地 IPC 引导保护） | + +--- + +## 4. 用户与权限管理 (Users API) + +仅超级管理员具备用户完全管理权限；普通用户与管理员受限于其组织权限。 + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /api/v1/users | 已登录 | 获取系统用户列表（普通用户受限查看） | +| POST | /api/v1/users | 超级管理员 | 创建新用户（支持设置账号名、密码、邮箱、初始角色） | +| GET | /api/v1/users/:id | 已登录 | 获取指定用户的详细资料 | +| PUT | /api/v1/users/:id | 超级管理员 | 更新指定用户的账号状态、所属角色或重置密码 | +| DELETE | /api/v1/users/:id | 超级管理员 | 删除指定用户（主超级管理员不可删除） | + +--- + +## 5. 项目与成员协作 (Project Management API) + +支持多项目隔离管理，项目可独立绑定成员、域名、DNS 凭据和部署服务器。 + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /api/v1/projects | 已登录 | 获取当前账号可见的项目列表（分页） | +| POST | /api/v1/projects | 超管 / 权限账户 | 创建新项目（填写项目名称、项目说明） | +| PUT | /api/v1/projects/:projectID | 项目管理员 | 修改项目资料（更新名称与说明） | +| DELETE | /api/v1/projects/:projectID | 项目管理员 | 删除项目（默认项目不可删除，有资产关联时不可删除） | +| GET | /api/v1/projects/:projectID/members | 项目成员 | 查询指定项目的成员列表及被赋予的项目角色 | +| POST | /api/v1/projects/:projectID/members | 项目管理员 | 为项目成员授予角色（项目管理员、普通操作者、只读用户） | +| DELETE | /api/v1/projects/:projectID/members/:userID/roles/:role | 项目管理员 | 撤销成员在项目中的指定角色 | +| GET | /api/v1/audit-logs | 已登录 | 查询当前项目与全局的操作审计流水 | + +--- + +## 6. 托管域名与证书生命周期管理 (Domains & Certificate API) + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /api/v1/domains | 项目授权 | 获取当前上下文下的托管域名列表 | +| POST | /api/v1/domains | 项目授权 | 添加托管域名（支持单域名、泛域名、多级子域名配置） | +| PUT | /api/v1/domains/:id | 项目授权 | 修改托管域名参数（环境、自动续期开关、部署配置） | +| DELETE | /api/v1/domains/:id | 项目授权 | 删除托管域名配置 | +| POST | /api/v1/domains/:id/issue | 项目授权 | 触发申请/签发 Let's Encrypt 证书任务 | +| POST | /api/v1/domains/:id/deploy | 项目授权 | 手动触发证书向关联部署服务器的推送部署任务 | +| POST | /api/v1/domains/:id/certificate/validate | 项目授权 | 手动触发针对已部署证书与 HTTPS 连通性的端到端校验 | +| POST | /api/v1/domains/:id/certificate/import | 项目授权 | 手工导入外部证书文件（证书 fullchain、私钥 key、中间证书） | +| GET | /api/v1/domains/:id/certificate/versions | 项目授权 | 获取该域名历史证书版本归档记录 | +| POST | /api/v1/domains/:id/certificate/versions/:version/restore | 项目授权 | 回滚恢复并激活指定的历史证书版本 | +| GET | /api/v1/certificates | 项目授权 | 查询系统当前所有活跃证书基本信息与到期日 | +| GET | /api/v1/certificates/:id | 项目授权 | 查看指定证书详情（SAN 列表、签发机构、有效期、指纹） | + +--- + +## 7. 部署服务器与绑定管理 (Servers API) + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /api/v1/servers | 项目授权 | 获取可用的远程部署服务器列表 | +| POST | /api/v1/servers | 项目授权 | 添加新的部署服务器（IP/主机名、SSH 端口、认证方式、证书路径） | +| GET | /api/v1/servers/:id | 项目授权 | 查看指定部署服务器详细信息 | +| PUT | /api/v1/servers/:id | 项目授权 | 更新部署服务器配置（Web 服务类型、重载命令等） | +| DELETE | /api/v1/servers/:id | 项目授权 | 删除部署服务器（清理关联绑定） | +| GET | /api/v1/domains/:id/servers | 项目授权 | 获取指定域名已绑定的目标部署服务器列表 | +| PUT | /api/v1/domains/:id/servers | 项目授权 | 批量更新并替换指定域名关联的部署服务器列表 | +| GET | /api/v1/servers/:id/domains | 项目授权 | 查询特定服务器关联的所有托管域名 | + +--- + +## 8. DNS 账户与提供商管理 (DNS Accounts API) + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /api/v1/dns/providers | 已登录 | 获取系统支持的 DNS 服务商驱动列表 | +| GET | /api/v1/dns/accounts | 项目授权 | 获取可见的已配置 DNS 账户列表（脱敏） | +| POST | /api/v1/dns/accounts | 项目授权 | 新建 DNS 账户（填入提供商、AccessKeyId、AccessKeySecret、归属项目） | +| GET | /api/v1/dns/accounts/:id | 项目授权 | 查看特定 DNS 账户详细信息与校验状态 | +| PUT | /api/v1/dns/accounts/:id | 项目授权 | 重命名或修改 DNS 账户基础信息（包括调整归属项目） | +| PUT | /api/v1/dns/accounts/:id/status | 项目授权 | 启用或停用指定的 DNS 账户 | +| PUT | /api/v1/dns/accounts/:id/credentials | 项目授权 | 轮换/更新 DNS 账户的 API 访问凭据（Secret） | +| POST | /api/v1/dns/accounts/:id/verify | 项目授权 | 在线测试并校验 DNS 账户凭据在服务商处的 API 鉴权有效性 | +| GET | /api/v1/domains/:id/dns-account | 项目授权 | 查询特定域名当前绑定的专用 DNS 账户 | +| PUT | /api/v1/domains/:id/dns-account | 项目授权 | 为特定域名指定或切换所使用的 DNS 账户 | + +--- + +## 9. 异步任务与执行审计 (Tasks API) + +证书的签发、远程推送部署、回环 HTTPS 校验均为异步任务执行引擎驱动。 + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /api/v1/tasks | 项目授权 | 获取异步任务列表（支持按域名、任务类型、状态过滤） | +| GET | /api/v1/tasks/:id | 项目授权 | 获取指定任务的当前阶段、执行状态、结果消息 | +| DELETE | /api/v1/tasks/:id | 项目授权 | 取消处于等待中（pending）或运行中的任务 | +| POST | /api/v1/tasks/:id/retry | 项目授权 | 对执行失败（failed）的任务发起重新执行 | +| GET | /api/v1/tasks/:id/attempts | 项目授权 | 查询该任务的所有执行尝试流水记录与重试日志 | +| GET | /api/v1/tasks/:id/deployment-results| 项目授权 | 查询部署任务针对各台目标服务器的详细推送结果与执行状态 | +| GET | /api/v1/tasks/:id/validation-results| 项目授权 | 查询证书校验任务对各节点的 HTTPS 握手与证书链详细诊断数据 | + +--- + +## 10. 系统全局设置与超级管理 (Settings & Admin API) + +全部接口仅限超级管理员角色访问。 + +| 方法 | 路径 | 权限要求 | 说明 | +| :--- | :--- | :--- | :--- | +| GET | /api/v1/settings | 超级管理员 | 获取系统全局配置（邮件通知设置、默认 DNS、证书续期策略） | +| PUT | /api/v1/settings | 超级管理员 | 保存/更新系统配置（分项独立更新） | +| POST | /api/v1/dns/test | 超级管理员 | 验证系统默认 DNS API 凭据连通性 | +| POST | /api/v1/notification/test | 超级管理员 | 实时测试 SMTP 邮件发信连通性，发送测试邮件验证配置 | +| POST | /api/v1/dns/aliyun/check | 超级管理员 | 深度校验阿里云 RAM 凭据对特定域名的操作授权（解析记录读写权） | +| POST | /api/v1/renewal/run | 超级管理员 | 立即手动触发全局证书自动续期巡检引擎 | diff --git a/frontend/src/views/Dashboard/DashboardLayout.css b/frontend/src/views/Dashboard/DashboardLayout.css index 37094f4..0419d41 100644 --- a/frontend/src/views/Dashboard/DashboardLayout.css +++ b/frontend/src/views/Dashboard/DashboardLayout.css @@ -51,6 +51,7 @@ } .dashboard-workspace { + box-sizing: border-box; display: grid; grid-template-columns: minmax(0, 1fr) 200px; grid-template-areas: "main submenu"; @@ -86,15 +87,20 @@ } .dashboard-content > .panel, +.dashboard-content .panel, .dashboard-content :deep(.user-management), .dashboard-content :deep(.project-management), -.dashboard-content :deep(.dns-accounts-panel) { +.dashboard-content :deep(.dns-accounts-panel), +.dashboard-content :deep(.panel) { + box-sizing: border-box; + width: 100%; margin: 0; min-height: 100%; padding: 24px; - border: none; - box-shadow: none; - border-radius: 0; + border: none !important; + box-shadow: none !important; + border-radius: 0 !important; + background: transparent; } .overview-section { diff --git a/frontend/src/views/ProjectManagement/ProjectManagement.css b/frontend/src/views/ProjectManagement/ProjectManagement.css index 0854109..5c51b71 100644 --- a/frontend/src/views/ProjectManagement/ProjectManagement.css +++ b/frontend/src/views/ProjectManagement/ProjectManagement.css @@ -1,10 +1,12 @@ .project-management { - padding: 24px; + box-sizing: border-box; + width: 100%; + padding: 0; color: #1e293b; - border: 1px solid #e2e8f0; - border-radius: 20px; - background: #ffffff; - box-shadow: 0 4px 20px -2px rgba(15, 23, 42, 0.05); + border: none; + border-radius: 0; + background: transparent; + box-shadow: none; } .project-heading { @@ -35,8 +37,9 @@ .project-layout { display: grid; grid-template-columns: 280px minmax(0, 1fr); - gap: 28px; - align-items: start; + gap: 24px; + align-items: stretch; + width: 100%; } .project-directory { @@ -45,8 +48,9 @@ padding: 18px; background: #f8fafc; border: 1px solid #e2e8f0; - border-radius: 16px; + border-radius: 14px; min-width: 0; + box-sizing: border-box; } .project-members {