统一 frontend、backend、test、test-log 和 out 目录,更新构建、部署及测试入口;纳入配置管理兼容与首次安全引导修复;排除本机配置、密钥和测试产物。
This commit is contained in:
1 parent
28cd9d3406
commit
f60d3b0880
603 files changed
+2351
-660
No files matched your search
+11
-11
@@ -20,7 +20,7 @@
|
||||
| 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` 为准。
|
||||
当前路由注册以 `backend/listen/http_server/http_server.go` 为准,接口处理逻辑以 `backend/controllers` 和 `backend/controllers/email` 为准。
|
||||
|
||||
## 2. 通用调用约定
|
||||
|
||||
@@ -756,15 +756,15 @@ Content-Disposition: attachment; filename="attachment"; filename*=UTF-8''report.
|
||||
|
||||
本次对照使用以下当前代码位置作为实现依据:
|
||||
|
||||
- 路由注册:`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`
|
||||
- 路由注册:`backend/listen/http_server/http_server.go`
|
||||
- 请求上下文、登录态和 CSRF 校验:`backend/listen/http_server/https_server.go`
|
||||
- 登录:`backend/controllers/login.go`
|
||||
- 分组:`backend/controllers/group.go`
|
||||
- 密码修改:`backend/controllers/settings.go`
|
||||
- 附件:`backend/controllers/attachments.go`
|
||||
- 邮件列表:`backend/controllers/email/list.go`
|
||||
- 邮件详情:`backend/controllers/email/detail.go`
|
||||
- 邮件发送:`backend/controllers/email/send.go`
|
||||
- 统一 JSON 响应:`backend/dto/response/response.go`
|
||||
|
||||
原版对照来源为 PMail Wiki 的《后端接口文档》。原版文档仅作为历史兼容性参考,接口是否可调用以当前 Smail 路由和处理器实现为准。
|
||||
+14
-14
@@ -196,10 +196,10 @@ flowchart LR
|
||||
| T-10 | 跨账号、跨用途、跨邮箱或跨浏览器上下文复用挑战 | HMAC 绑定账号、用途、邮箱、资源 ID;浏览器上下文只保存摘要;错误上下文不消费有效挑战 | `verification.TestServiceBindsVerificationToResource`;`verification.TestStoreRejectsDifferentBrowserContextWithoutConsumingChallenge`;`recovery.TestRecoveryBindsChallengeAndTicketToBrowserContext` |
|
||||
| T-11 | 密码或邮箱凭据变更后继续使用旧恢复流程 | `session_version`、外部邮箱 `credential_version` 和统一 `InvalidateUser`;密码重置撤销恢复码、密保问题和 WebAuthn | `recovery.TestRecoveryTicketRejectsChangedSessionVersion`;`controllers.TestPasswordChangeRevokesOfflineCredentialsAtomically`;`adminreset.TestResetSuperAdminOnlyRevokesTargetSessionsAndCredentials` |
|
||||
| T-12 | 恢复流程状态跳跃或直接调用完成接口 | begin/verify/complete 分离;complete 只接受服务端内存票据和浏览器上下文;无票据、过期票据和错误上下文拒绝 | `controllers.TestRecoveryBrowserContextCookieIsRequiredForCompletion`;`recovery.TestRecoveryRejectsCrossUserVerificationAndConsumesTicketOnce` |
|
||||
| T-13 | 未验证、已停用或他人外部邮箱被用于恢复/登录 | 查询只接受 verified 状态;资源 ID 和 UserID 双重绑定;停用时失效验证码、恢复票据和登录状态 | `externalemail.TestRepositoryBindsVerifiesAndScopesByUser`;`externalemail.TestRepositoryAbandonsOnlyOwnedPendingBinding`;`server/controllers/security.go` 中 `DisableExternalEmail` 的状态失效代码审查 |
|
||||
| T-13 | 未验证、已停用或他人外部邮箱被用于恢复/登录 | 查询只接受 verified 状态;资源 ID 和 UserID 双重绑定;停用时失效验证码、恢复票据和登录状态 | `externalemail.TestRepositoryBindsVerifiesAndScopesByUser`;`externalemail.TestRepositoryAbandonsOnlyOwnedPendingBinding`;`backend/controllers/security.go` 中 `DisableExternalEmail` 的状态失效代码审查 |
|
||||
| T-14 | 数据库读取者通过运营数据还原账号、邮箱或 IP | 运营字段使用独立 HMAC 指纹;限流维度键哈希;不保存完整值;按期限清理 | `verification.TestEventStorePersistsOnlyOperationalFingerprintsAndCleansAfterRetention`;`verification.TestPersistentRateLimiterDoesNotPersistSensitiveValues` |
|
||||
| T-15 | 主服务重启后旧验证码或恢复流程被恢复使用 | 验证码 Store 的临时密钥和任务只在内存;恢复票据、诱饵挑战和 WebAuthn ceremony 不从数据库恢复 | `verification.TestStoreRestartInvalidatesAllChallenges`;`recovery.TestRecoveryStoresOnlyTicketDigestAndLimitsCapacity`;`webauthn.TestCeremonySessionCapacityAndExpiredPruning` |
|
||||
| T-16 | 超级管理员通过 Web、外部邮箱或恢复码重置自身密码 | 恢复用户加载明确拒绝 `super_admin`;部署端重置单独走 IPC;没有 Web 路由调用 `ResetSuperAdmin` | `recovery.TestRecoveryDeniesSuperAdministrator`;`controllers.TestRecoveryRejectsWhenDisabled`;路由审计:`server/listen/http_server/http_server.go` 未注册网络超级管理员重置入口 |
|
||||
| T-16 | 超级管理员通过 Web、外部邮箱或恢复码重置自身密码 | 恢复用户加载明确拒绝 `super_admin`;部署端重置单独走 IPC;没有 Web 路由调用 `ResetSuperAdmin` | `recovery.TestRecoveryDeniesSuperAdministrator`;`controllers.TestRecoveryRejectsWhenDisabled`;路由审计:`backend/listen/http_server/http_server.go` 未注册网络超级管理员重置入口 |
|
||||
| T-17 | 恶意请求超过协议帧、JSON 或 SMTP 头字段限制 | IPC 最大帧 16 KiB、JSON unknown field 拒绝;邮箱和 SMTP Host/From 禁止换行和非法格式;HTTP JSON 单值解析 | `adminreset.TestProtocolRejectsOversizedFrame`;`controllers.TestDecodeJSONRequestRejectsUnsafeBodies`;`verification.TestSMTPHostValidation` |
|
||||
| T-18 | 外部错误把数据库细节或秘密返回给调用方 | IPC 统一返回 `RESET_FAILED`;HTTP 使用稳定业务错误;日志只记录内部错误上下文,不拼接密码、验证码和完整邮箱 | `adminreset.TestWindowsNamedPipeReturnsSafeHandlerFailure`;`controllers.TestSecurityHandlersRejectUnauthenticatedRequests`;安全响应形状测试 |
|
||||
|
||||
@@ -207,18 +207,18 @@ flowchart LR
|
||||
|
||||
| 能力 | 主要代码 | 主要测试 |
|
||||
|---|---|---|
|
||||
| IPC 协议和 nonce | `server/services/adminreset/protocol.go`、`client.go`、`transport_unix.go`、`transport_windows.go` | `server/services/adminreset/protocol_test.go`、`transport_windows_test.go`、`doctor_linux_test.go` |
|
||||
| 超级管理员事务 | `server/services/adminreset/reset.go` | `server/services/adminreset/reset_test.go` |
|
||||
| 验证码内存仓库 | `server/services/verification/store.go`、`service.go`、`runtime.go` | `store_test.go`、`service_test.go`、`cleanup_test.go` |
|
||||
| SMTP 投递 | `server/services/verification/delivery.go` | `delivery_test.go` |
|
||||
| 限流和运营事件 | `server/services/verification/rate_limit.go`、`event_store.go` | `rate_limit_test.go`、`event_store_test.go`、`event_cleanup_test.go` |
|
||||
| 外部邮箱加密和生命周期 | `server/services/externalemail/vault.go`、`repository.go` | `vault_test.go`、`repository_test.go` |
|
||||
| 密保和离线恢复码 | `server/services/credentials/service.go` | `service_test.go` |
|
||||
| 密码恢复状态机 | `server/services/recovery/service.go` | `service_test.go`、`webauthn_recovery_test.go` |
|
||||
| 登录二次验证 | `server/controllers/login_verification.go`、`login.go` | `login_security_test.go`、安全控制器测试 |
|
||||
| WebAuthn ceremony | `server/services/webauthn`、`server/controllers/webauthn.go` | WebAuthn service tests、recovery WebAuthn tests |
|
||||
| HTTP 公开边界 | `server/controllers/security.go`、`server/listen/http_server/http_server.go` | `security_reset_entry_test.go`、`security_public_response_test.go`、`security_authentication_test.go` |
|
||||
| 密码重置后的状态失效 | `server/controllers/security.go`、`server/services/recovery`、`server/services/adminreset` | `password_reset_permissions_test.go`、`reset_test.go`、recovery invalidation tests |
|
||||
| IPC 协议和 nonce | `backend/services/adminreset/protocol.go`、`client.go`、`transport_unix.go`、`transport_windows.go` | `backend/services/adminreset/protocol_test.go`、`transport_windows_test.go`、`doctor_linux_test.go` |
|
||||
| 超级管理员事务 | `backend/services/adminreset/reset.go` | `backend/services/adminreset/reset_test.go` |
|
||||
| 验证码内存仓库 | `backend/services/verification/store.go`、`service.go`、`runtime.go` | `store_test.go`、`service_test.go`、`cleanup_test.go` |
|
||||
| SMTP 投递 | `backend/services/verification/delivery.go` | `delivery_test.go` |
|
||||
| 限流和运营事件 | `backend/services/verification/rate_limit.go`、`event_store.go` | `rate_limit_test.go`、`event_store_test.go`、`event_cleanup_test.go` |
|
||||
| 外部邮箱加密和生命周期 | `backend/services/externalemail/vault.go`、`repository.go` | `vault_test.go`、`repository_test.go` |
|
||||
| 密保和离线恢复码 | `backend/services/credentials/service.go` | `service_test.go` |
|
||||
| 密码恢复状态机 | `backend/services/recovery/service.go` | `service_test.go`、`webauthn_recovery_test.go` |
|
||||
| 登录二次验证 | `backend/controllers/login_verification.go`、`login.go` | `login_security_test.go`、安全控制器测试 |
|
||||
| WebAuthn ceremony | `backend/services/webauthn`、`backend/controllers/webauthn.go` | WebAuthn service tests、recovery WebAuthn tests |
|
||||
| HTTP 公开边界 | `backend/controllers/security.go`、`backend/listen/http_server/http_server.go` | `security_reset_entry_test.go`、`security_public_response_test.go`、`security_authentication_test.go` |
|
||||
| 密码重置后的状态失效 | `backend/controllers/security.go`、`backend/services/recovery`、`backend/services/adminreset` | `password_reset_permissions_test.go`、`reset_test.go`、recovery invalidation tests |
|
||||
|
||||
## 8. 已知边界、剩余风险和后续任务
|
||||
|
||||
|
||||
+19
-19
@@ -25,8 +25,8 @@
|
||||
|
||||
| 任务编号 | 优先级 | 审核状态 | 结论 | 关键证据 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| SEC-001 | P0 | 未通过 | 不通过 | `server/listen/smtp_server/smtp.go:28` 在 587 端口设置 `AllowInsecureAuth = true` |
|
||||
| SEC-002 | P0 | 未通过 | 不通过 | `server/listen/smtp_server/action.go:68,92,96` 记录用户名、密码和完整用户对象 |
|
||||
| SEC-001 | P0 | 未通过 | 不通过 | `backend/listen/smtp_server/smtp.go:28` 在 587 端口设置 `AllowInsecureAuth = true` |
|
||||
| SEC-002 | P0 | 未通过 | 不通过 | `backend/listen/smtp_server/action.go:68,92,96` 记录用户名、密码和完整用户对象 |
|
||||
| SEC-003 | P0 | 未通过 | 不通过 | `setup_server.go:27-29,52-58` 暴露初始化服务;业务拦截只按 `/api/setup` 放行 |
|
||||
| SEC-004 | P0 | 未通过 | 不通过 | `http_server.go:69-90` 在关闭 HTTPS 时仍注册业务路由和会话 |
|
||||
| SEC-005 | P1 | 未通过 | 不通过 | `group.go:123-126` 只校验邮件所属用户,未校验目标分组所属用户 |
|
||||
@@ -38,7 +38,7 @@
|
||||
| SEC-011 | P1 | 未通过 | 不通过 | 缺少统一安全响应头;插件 iframe 未设置 `sandbox` |
|
||||
| SEC-012 | P1 | 未通过 | 不通过 | SSL 初始化仅 `os.Stat` 用户路径并直接写入配置,未做受控目录和匹配校验 |
|
||||
| SEC-013 | P1 | 未通过 | 不通过 | `utils/smtp/smtp.go:80` 设置 `InsecureSkipVerify = true` |
|
||||
| SEC-014 | P1 | 未通过 | 不通过 | `server/main_test.go:35-36` 删除真实配置和数据库 |
|
||||
| SEC-014 | P1 | 未通过 | 不通过 | `backend/main_test.go:35-36` 删除真实配置和数据库 |
|
||||
| SEC-015 | P2 | 未通过 | 不通过 | 配置、证书和公钥文件使用 `0666`,配置目录使用 `0755` |
|
||||
| SEC-016 | P2 | 未通过 | 不通过 | `services/auth/auth.go:45` 生成 1024 位 RSA DKIM 密钥 |
|
||||
| SEC-017 | P2 | 未通过 | 不通过 | 附件下载使用错误的 `ContentType` 响应头,文件名直接拼接到响应头 |
|
||||
@@ -56,7 +56,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/listen/smtp_server/smtp.go:28` 将 587 端口的 `AllowInsecureAuth` 设置为 `true`。当前配置会使 SMTP 服务器可能在 TLS 升级前声明并接受认证能力,与任务清单要求的“仅 STARTTLS 成功后认证”不一致。
|
||||
`backend/listen/smtp_server/smtp.go:28` 将 587 端口的 `AllowInsecureAuth` 设置为 `true`。当前配置会使 SMTP 服务器可能在 TLS 升级前声明并接受认证能力,与任务清单要求的“仅 STARTTLS 成功后认证”不一致。
|
||||
|
||||
**优化要求:**
|
||||
|
||||
@@ -69,7 +69,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/listen/smtp_server/action.go:68` 使用日志输出用户名和明文密码;`action.go:92` 在认证成功时输出完整用户对象,`action.go:96` 在认证失败时再次输出用户名和密码。该问题属于凭据直接泄漏,必须优先处理。
|
||||
`backend/listen/smtp_server/action.go:68` 使用日志输出用户名和明文密码;`action.go:92` 在认证成功时输出完整用户对象,`action.go:96` 在认证失败时再次输出用户名和密码。该问题属于凭据直接泄漏,必须优先处理。
|
||||
|
||||
**优化要求:**
|
||||
|
||||
@@ -81,7 +81,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/listen/http_server/setup_server.go:27-29` 将初始化 API 挂载到初始化 HTTP 服务,`setup_server.go:52-58` 直接监听端口。`server/listen/http_server/https_server.go:135-137` 在未初始化时仅按路径 `/api/setup` 放行,没有发现一次性初始化令牌、失败次数限制、速率限制或受控来源校验。
|
||||
`backend/listen/http_server/setup_server.go:27-29` 将初始化 API 挂载到初始化 HTTP 服务,`setup_server.go:52-58` 直接监听端口。`backend/listen/http_server/https_server.go:135-137` 在未初始化时仅按路径 `/api/setup` 放行,没有发现一次性初始化令牌、失败次数限制、速率限制或受控来源校验。
|
||||
|
||||
**优化要求:**
|
||||
|
||||
@@ -94,7 +94,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/listen/http_server/http_server.go:69-90` 在 `HttpsEnabled == 2` 时直接注册完整业务路由,并通过 `session.Instance.LoadAndSave(mux)` 启用会话。当前未见统一的 HTTPS 强制策略、Cookie `Secure`、`HttpOnly`、`SameSite`、HSTS 以及安全响应头配置。
|
||||
`backend/listen/http_server/http_server.go:69-90` 在 `HttpsEnabled == 2` 时直接注册完整业务路由,并通过 `session.Instance.LoadAndSave(mux)` 启用会话。当前未见统一的 HTTPS 强制策略、Cookie `Secure`、`HttpOnly`、`SameSite`、HSTS 以及安全响应头配置。
|
||||
|
||||
**优化要求:**
|
||||
|
||||
@@ -109,7 +109,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/services/group/group.go:123-126` 的更新语句只通过 `email_id` 和 `user_id` 限制被更新的邮件,但直接使用请求传入的 `groupId`,没有先确认目标分组属于 `ctx.UserID`。攻击者可以尝试引用其他用户的分组 ID。
|
||||
`backend/services/group/group.go:123-126` 的更新语句只通过 `email_id` 和 `user_id` 限制被更新的邮件,但直接使用请求传入的 `groupId`,没有先确认目标分组属于 `ctx.UserID`。攻击者可以尝试引用其他用户的分组 ID。
|
||||
|
||||
**优化要求:**先查询并锁定目标分组的 `id + user_id`,不存在或不属于当前用户时拒绝操作;再在同一事务内更新邮件,并增加双用户隔离回归测试。
|
||||
|
||||
@@ -117,7 +117,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/services/group/group.go:88` 的 `update user_email set group_id=0 where group_id in (...)` 没有附加 `user_id` 条件,存在跨用户修改邮件分组的风险。分组统计查询也存在按 `group_id` 查询而未统一附带用户条件的路径。
|
||||
`backend/services/group/group.go:88` 的 `update user_email set group_id=0 where group_id in (...)` 没有附加 `user_id` 条件,存在跨用户修改邮件分组的风险。分组统计查询也存在按 `group_id` 查询而未统一附带用户条件的路径。
|
||||
|
||||
**优化要求:**删除分组、清理邮件和统计查询均必须同时带当前用户条件;删除和清理操作必须在同一事务中完成,并增加失败回滚测试。
|
||||
|
||||
@@ -125,7 +125,7 @@
|
||||
|
||||
**审核结果:不通过,且与既定整改原则直接冲突。**
|
||||
|
||||
`server/utils/password/encode.go` 使用两次 MD5 和固定字符串盐。当前登录、初始化、改密、管理员重置和 SMTP 登录仍使用旧 `password.Encode` 路径;HTTP 临时令牌也依赖 MD5 计算。项目没有 Argon2id、统一 `PasswordService` 或 `CredentialValidator`。
|
||||
`backend/utils/password/encode.go` 使用两次 MD5 和固定字符串盐。当前登录、初始化、改密、管理员重置和 SMTP 登录仍使用旧 `password.Encode` 路径;HTTP 临时令牌也依赖 MD5 计算。项目没有 Argon2id、统一 `PasswordService` 或 `CredentialValidator`。
|
||||
|
||||
**优化要求:**
|
||||
|
||||
@@ -155,7 +155,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/dto/parsemail/email.go:122,129,132,140-141` 允许全局 `style`、`img` 的 `style`、`a` 的 `style` 及 `<style>` 元素,并允许远程图片。`fe/src/views/EmailDetailView.vue:52` 使用 `v-html` 将邮件 HTML 直接插入主页面 DOM。虽然已有 bluemonday 和 XSS 测试基础,但当前策略仍过宽,且缺少邮件展示专用隔离环境。
|
||||
`backend/dto/parsemail/email.go:122,129,132,140-141` 允许全局 `style`、`img` 的 `style`、`a` 的 `style` 及 `<style>` 元素,并允许远程图片。`frontend/src/views/EmailDetailView.vue:52` 使用 `v-html` 将邮件 HTML 直接插入主页面 DOM。虽然已有 bluemonday 和 XSS 测试基础,但当前策略仍过宽,且缺少邮件展示专用隔离环境。
|
||||
|
||||
**优化要求:**严格收紧 HTML 白名单,默认禁止脚本、事件属性、危险 URL、远程资源和 CSS 行为;优先使用邮件专用受限 iframe,配合 `sandbox` 和邮件专用 CSP;补充 CSS、URL、SVG、表单和重定向测试。
|
||||
|
||||
@@ -163,7 +163,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
当前 HTTP 拦截器主要设置 `Content-Type`,未发现统一设置 CSP、`X-Content-Type-Options`、`Referrer-Policy`、`Permissions-Policy` 等安全响应头。`fe/src/components/PluginSettings.vue:12` 的 iframe 没有 `sandbox`,也没有明确的来源、权限和通信边界。
|
||||
当前 HTTP 拦截器主要设置 `Content-Type`,未发现统一设置 CSP、`X-Content-Type-Options`、`Referrer-Policy`、`Permissions-Policy` 等安全响应头。`frontend/src/components/PluginSettings.vue:12` 的 iframe 没有 `sandbox`,也没有明确的来源、权限和通信边界。
|
||||
|
||||
**优化要求:**建立统一安全响应头中间件;插件 iframe 使用最小权限 `sandbox`,限制来源和可用能力,避免访问主应用 Cookie、DOM 和敏感 API。
|
||||
|
||||
@@ -171,7 +171,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/controllers/setup.go:148-162` 只使用 `os.Stat` 检查用户提交的证书和私钥路径,`server/services/setup/ssl/ssl.go:54-77` 直接把路径写入配置。未发现受控目录、路径穿越、符号链接逃逸、文件类型和证书私钥匹配校验。
|
||||
`backend/controllers/setup.go:148-162` 只使用 `os.Stat` 检查用户提交的证书和私钥路径,`backend/services/setup/ssl/ssl.go:54-77` 直接把路径写入配置。未发现受控目录、路径穿越、符号链接逃逸、文件类型和证书私钥匹配校验。
|
||||
|
||||
**优化要求:**使用受控证书目录和 `filepath.Clean`,拒绝目录、符号链接逃逸和工作区外路径;解析证书与私钥并验证公钥匹配,错误信息不得泄漏敏感路径内容。
|
||||
|
||||
@@ -179,7 +179,7 @@
|
||||
|
||||
**审核结果:不通过。**
|
||||
|
||||
`server/utils/smtp/smtp.go:79-82` 设置 `InsecureSkipVerify: true`,出站 SMTPS 默认跳过证书链和主机名校验,容易遭受中间人攻击。
|
||||
`backend/utils/smtp/smtp.go:79-82` 设置 `InsecureSkipVerify: true`,出站 SMTPS 默认跳过证书链和主机名校验,容易遭受中间人攻击。
|
||||
|
||||
**优化要求:**默认启用证书验证和主机名校验;如确有企业自签证书场景,使用显式受控 CA 配置,不提供无条件跳过校验的默认路径。
|
||||
|
||||
@@ -187,7 +187,7 @@
|
||||
|
||||
**审核结果:不通过,且本轮未执行全量测试。**
|
||||
|
||||
`server/main_test.go:35-36` 在 `TestMain` 中直接删除 `config/config.json` 和 `config/smail_temp.db`,并以当前工作目录启动主服务。为遵守“未经同意不删除任何文件”的约束,本轮没有执行 `go test ./...`。
|
||||
`backend/main_test.go:35-36` 在 `TestMain` 中直接删除 `config/config.json` 和 `config/smail_temp.db`,并以当前工作目录启动主服务。为遵守“未经同意不删除任何文件”的约束,本轮没有执行 `go test ./...`。
|
||||
|
||||
**优化要求:**测试使用临时目录、测试专用配置和测试端口;通过依赖注入或测试启动器隔离数据库和配置。整改后在隔离环境执行 `go test ./...`,并验证测试前后工作区文件校验和不变。
|
||||
|
||||
@@ -208,11 +208,11 @@
|
||||
|
||||
| 验证项 | 命令 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 前端构建 | `cd fe; npm.cmd run build` | 通过;Vite 构建成功,但存在单个 JavaScript 包超过 500 kB 的性能警告,建议后续代码分包。 |
|
||||
| 前端构建 | `cd frontend; npm.cmd run build` | 通过;Vite 构建成功,但存在单个 JavaScript 包超过 500 kB 的性能警告,建议后续代码分包。 |
|
||||
| 后端重点包测试 | `go test ./utils/password ./dto/parsemail ./utils/address ./utils/utf7 ./services/rule/match` | 通过。 |
|
||||
| 静态检查 | `cd server; go vet ./...` | 失败;发现 7 处未命名结构体字段问题。 |
|
||||
| Go 全量测试 | `cd server; go test ./...` | 未执行;`server/main_test.go` 会删除真实配置和数据库,需先隔离测试环境。 |
|
||||
| Go 依赖模块枚举 | `cd server; go list -m all` | 可执行;仅证明模块可解析,不等同于漏洞扫描。 |
|
||||
| 静态检查 | `cd backend; go vet ./...` | 失败;发现 7 处未命名结构体字段问题。 |
|
||||
| Go 全量测试 | `cd backend; go test ./...` | 未执行;`backend/main_test.go` 会删除真实配置和数据库,需先隔离测试环境。 |
|
||||
| Go 依赖模块枚举 | `cd backend; go list -m all` | 可执行;仅证明模块可解析,不等同于漏洞扫描。 |
|
||||
| Go 漏洞扫描 | `govulncheck ./...` | 未执行;当前环境未安装 `govulncheck`。 |
|
||||
| 前端依赖审计 | `npm audit` 或 `yarn audit` | 未形成可复现流程;前端锁文件和包管理器尚未统一。 |
|
||||
|
||||
|
||||
+79
-79
@@ -43,28 +43,28 @@
|
||||
|
||||
| 任务编号 | 优先级 | 风险主题 | 主要位置 | 状态 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| SEC-001 | P0 | SMTP 587 在 STARTTLS 前允许认证 | `server/listen/smtp_server/smtp.go` | [✓] |
|
||||
| SEC-002 | P0 | SMTP 日志记录明文密码 | `server/listen/smtp_server/action.go` | [✓] |
|
||||
| SEC-003 | P0 | 初始化接口缺少访问保护 | `server/listen/http_server/`、`server/controllers/setup.go` | [✓] |
|
||||
| SEC-004 | P0 | 明文 HTTP 承载完整登录会话 | `server/listen/http_server/http_server.go` | [✓] |
|
||||
| SEC-005 | P1 | 邮件移动未验证目标分组归属 | `server/controllers/email/move.go`、`server/services/group/group.go` | [✓] |
|
||||
| SEC-006 | P1 | 删除分组后的邮件更新缺少用户条件 | `server/services/group/group.go` | [✓] |
|
||||
| SEC-007 | P1 | 密码使用 MD5 和固定盐 | `server/utils/password/encode.go` | [✓] |
|
||||
| SEC-008 | P1 | 请求体读取没有统一大小限制 | `server/controllers/` | [✓] |
|
||||
| SEC-001 | P0 | SMTP 587 在 STARTTLS 前允许认证 | `backend/listen/smtp_server/smtp.go` | [✓] |
|
||||
| SEC-002 | P0 | SMTP 日志记录明文密码 | `backend/listen/smtp_server/action.go` | [✓] |
|
||||
| SEC-003 | P0 | 初始化接口缺少访问保护 | `backend/listen/http_server/`、`backend/controllers/setup.go` | [✓] |
|
||||
| SEC-004 | P0 | 明文 HTTP 承载完整登录会话 | `backend/listen/http_server/http_server.go` | [✓] |
|
||||
| SEC-005 | P1 | 邮件移动未验证目标分组归属 | `backend/controllers/email/move.go`、`backend/services/group/group.go` | [✓] |
|
||||
| SEC-006 | P1 | 删除分组后的邮件更新缺少用户条件 | `backend/services/group/group.go` | [✓] |
|
||||
| SEC-007 | P1 | 密码使用 MD5 和固定盐 | `backend/utils/password/encode.go` | [✓] |
|
||||
| SEC-008 | P1 | 请求体读取没有统一大小限制 | `backend/controllers/` | [✓] |
|
||||
| SEC-009 | P1 | 缺少统一 CSRF 防护 | Cookie 会话状态修改接口 | [✓] |
|
||||
| SEC-010 | P1 | 邮件 HTML 清理策略较宽松 | `server/dto/parsemail/email.go`、`fe/src/views/EmailDetailView.vue` | [✓] |
|
||||
| SEC-011 | P1 | 缺少统一安全响应头,插件 iframe 未隔离 | `server/listen/http_server/`、`fe/src/components/PluginSettings.vue` | [✓] |
|
||||
| SEC-012 | P1 | 初始化 SSL 路径校验不足 | `server/controllers/setup.go` | [✓] |
|
||||
| SEC-013 | P1 | 出站 SMTPS 跳过证书校验 | `server/utils/smtp/smtp.go` | [✓] |
|
||||
| SEC-014 | P1 | 测试可能删除真实配置和数据库 | `server/main_test.go` | [✓] |
|
||||
| SEC-015 | P2 | 敏感文件权限过宽 | `server/services/auth/`、`server/services/setup/ssl/`、`server/config/` | [✓] |
|
||||
| SEC-016 | P2 | DKIM RSA 密钥长度只有 1024 位 | `server/services/auth/auth.go` | [✓] |
|
||||
| SEC-017 | P2 | 附件下载响应头和文件名处理不规范 | `server/controllers/attachments.go` | [✓] |
|
||||
| SEC-018 | P2 | Windows 路径处理不完整 | `server/config/config.go` | [✓] |
|
||||
| SEC-019 | P2 | 插件进程信任边界较宽 | `server/hooks/base.go` | [✓] |
|
||||
| SEC-020 | P2 | IMAP 未使用辅助函数缺少 UID 用户隔离 | `server/services/detail/detail.go` | [✓] |
|
||||
| SEC-010 | P1 | 邮件 HTML 清理策略较宽松 | `backend/dto/parsemail/email.go`、`frontend/src/views/EmailDetailView.vue` | [✓] |
|
||||
| SEC-011 | P1 | 缺少统一安全响应头,插件 iframe 未隔离 | `backend/listen/http_server/`、`frontend/src/components/PluginSettings.vue` | [✓] |
|
||||
| SEC-012 | P1 | 初始化 SSL 路径校验不足 | `backend/controllers/setup.go` | [✓] |
|
||||
| SEC-013 | P1 | 出站 SMTPS 跳过证书校验 | `backend/utils/smtp/smtp.go` | [✓] |
|
||||
| SEC-014 | P1 | 测试可能删除真实配置和数据库 | `backend/main_test.go` | [✓] |
|
||||
| SEC-015 | P2 | 敏感文件权限过宽 | `backend/services/auth/`、`backend/services/setup/ssl/`、`backend/config/` | [✓] |
|
||||
| SEC-016 | P2 | DKIM RSA 密钥长度只有 1024 位 | `backend/services/auth/auth.go` | [✓] |
|
||||
| SEC-017 | P2 | 附件下载响应头和文件名处理不规范 | `backend/controllers/attachments.go` | [✓] |
|
||||
| SEC-018 | P2 | Windows 路径处理不完整 | `backend/config/config.go` | [✓] |
|
||||
| SEC-019 | P2 | 插件进程信任边界较宽 | `backend/hooks/base.go` | [✓] |
|
||||
| SEC-020 | P2 | IMAP 未使用辅助函数缺少 UID 用户隔离 | `backend/services/detail/detail.go` | [✓] |
|
||||
| SEC-021 | P2 | 依赖漏洞审计和锁文件审计尚未建立 | Go、前端依赖管理 | [✓] |
|
||||
| SEC-022 | P2 | `go vet` 现有问题降低静态检查效果 | `server/dto/parsemail/email.go`、`server/controllers/group.go` | [✓] |
|
||||
| SEC-022 | P2 | `go vet` 现有问题降低静态检查效果 | `backend/dto/parsemail/email.go`、`backend/controllers/group.go` | [✓] |
|
||||
|
||||
---
|
||||
|
||||
@@ -76,7 +76,7 @@
|
||||
- **风险等级**:P0 / 高风险
|
||||
- **关联问题**:SMTP 明文认证导致凭据泄漏。
|
||||
- **关联文件**:
|
||||
- `server/listen/smtp_server/smtp.go`
|
||||
- `backend/listen/smtp_server/smtp.go`
|
||||
- SMTP 认证和 STARTTLS 相关测试文件
|
||||
|
||||
### 整改要求
|
||||
@@ -107,7 +107,7 @@
|
||||
- **风险等级**:P0 / 高风险
|
||||
- **关联问题**:Debug 日志输出认证密码。
|
||||
- **关联文件**:
|
||||
- `server/listen/smtp_server/action.go`
|
||||
- `backend/listen/smtp_server/action.go`
|
||||
- 其他 SMTP 认证日志调用点
|
||||
|
||||
### 整改要求
|
||||
@@ -137,9 +137,9 @@
|
||||
- **风险等级**:P0 / 高风险
|
||||
- **关联问题**:攻击者可能在管理员之前抢先完成初始化。
|
||||
- **关联文件**:
|
||||
- `server/listen/http_server/setup_server.go`
|
||||
- `server/listen/http_server/https_server.go`
|
||||
- `server/controllers/setup.go`
|
||||
- `backend/listen/http_server/setup_server.go`
|
||||
- `backend/listen/http_server/https_server.go`
|
||||
- `backend/controllers/setup.go`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -171,10 +171,10 @@
|
||||
- **风险等级**:P0 / 高风险
|
||||
- **关联问题**:HTTP 模式下可能窃听登录请求和会话 Cookie。
|
||||
- **关联文件**:
|
||||
- `server/listen/http_server/http_server.go`
|
||||
- `server/listen/http_server/https_server.go`
|
||||
- `backend/listen/http_server/http_server.go`
|
||||
- `backend/listen/http_server/https_server.go`
|
||||
- 会话 Cookie 配置
|
||||
- `server/config/config*.json`
|
||||
- `backend/config/config*.json`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -203,8 +203,8 @@
|
||||
- **风险等级**:P1 / 中高风险
|
||||
- **关联问题**:用户可以引用其他用户的分组 ID。
|
||||
- **关联文件**:
|
||||
- `server/controllers/email/move.go`
|
||||
- `server/services/group/group.go`
|
||||
- `backend/controllers/email/move.go`
|
||||
- `backend/services/group/group.go`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -228,7 +228,7 @@
|
||||
- **风险等级**:P1 / 中高风险
|
||||
- **关联问题**:删除用户 A 的分组可能影响用户 B 的邮件元数据。
|
||||
- **关联文件**:
|
||||
- `server/services/group/group.go`
|
||||
- `backend/services/group/group.go`
|
||||
- 分组删除相关测试
|
||||
|
||||
### 整改要求
|
||||
@@ -259,7 +259,7 @@ where group_id in (...)
|
||||
- **风险等级**:P1 / 中风险
|
||||
- **关联问题**:MD5、固定盐、无独立随机盐。
|
||||
- **关联文件**:
|
||||
- `server/utils/password/encode.go`
|
||||
- `backend/utils/password/encode.go`
|
||||
- 用户创建、登录、修改密码流程
|
||||
- 数据库用户表结构
|
||||
|
||||
@@ -294,14 +294,14 @@ where group_id in (...)
|
||||
- **风险等级**:P1 / 中风险
|
||||
- **关联问题**:多个接口直接使用无上限 `io.ReadAll`。
|
||||
- **关联范围**:
|
||||
- `server/controllers/login.go`
|
||||
- `server/controllers/setup.go`
|
||||
- `server/controllers/user.go`
|
||||
- `server/controllers/settings.go`
|
||||
- `server/controllers/rule.go`
|
||||
- `server/controllers/plugin.go`
|
||||
- `server/controllers/group.go`
|
||||
- `server/controllers/email/`
|
||||
- `backend/controllers/login.go`
|
||||
- `backend/controllers/setup.go`
|
||||
- `backend/controllers/user.go`
|
||||
- `backend/controllers/settings.go`
|
||||
- `backend/controllers/rule.go`
|
||||
- `backend/controllers/plugin.go`
|
||||
- `backend/controllers/group.go`
|
||||
- `backend/controllers/email/`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -353,8 +353,8 @@ where group_id in (...)
|
||||
- **风险等级**:P1 / 中风险
|
||||
- **关联问题**:邮件正文使用 `v-html`,允许较宽的 HTML 和外链能力。
|
||||
- **关联文件**:
|
||||
- `server/dto/parsemail/email.go`
|
||||
- `fe/src/views/EmailDetailView.vue`
|
||||
- `backend/dto/parsemail/email.go`
|
||||
- `frontend/src/views/EmailDetailView.vue`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -382,8 +382,8 @@ where group_id in (...)
|
||||
- **风险等级**:P1 / 中风险
|
||||
- **关联问题**:缺少统一安全响应头,插件 iframe 未使用 `sandbox`。
|
||||
- **关联文件**:
|
||||
- `server/listen/http_server/`
|
||||
- `fe/src/components/PluginSettings.vue`
|
||||
- `backend/listen/http_server/`
|
||||
- `frontend/src/components/PluginSettings.vue`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -410,8 +410,8 @@ where group_id in (...)
|
||||
- **风险等级**:P1 / 中风险
|
||||
- **关联问题**:客户端可以直接指定 SSL 路径。
|
||||
- **关联文件**:
|
||||
- `server/controllers/setup.go`
|
||||
- `server/services/setup/ssl/`
|
||||
- `backend/controllers/setup.go`
|
||||
- `backend/services/setup/ssl/`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -438,7 +438,7 @@ where group_id in (...)
|
||||
- **风险等级**:P1 / 中风险
|
||||
- **关联问题**:出站 SMTP 使用 `InsecureSkipVerify: true`。
|
||||
- **关联文件**:
|
||||
- `server/utils/smtp/smtp.go`
|
||||
- `backend/utils/smtp/smtp.go`
|
||||
- 出站 SMTP 配置和测试
|
||||
|
||||
### 整改要求
|
||||
@@ -463,7 +463,7 @@ where group_id in (...)
|
||||
- **风险等级**:P1 / 测试安全与可靠性
|
||||
- **关联问题**:测试会删除工作区配置和临时数据库。
|
||||
- **关联文件**:
|
||||
- `server/main_test.go`
|
||||
- `backend/main_test.go`
|
||||
- 依赖运行时配置的测试包
|
||||
|
||||
### 整改要求
|
||||
@@ -512,7 +512,7 @@ where group_id in (...)
|
||||
- **状态**:[✓] 复审通过
|
||||
- **风险等级**:P2 / 低风险
|
||||
- **关联文件**:
|
||||
- `server/services/auth/auth.go`
|
||||
- `backend/services/auth/auth.go`
|
||||
- DKIM 生成和轮换逻辑
|
||||
|
||||
### 整改要求
|
||||
@@ -534,7 +534,7 @@ where group_id in (...)
|
||||
|
||||
- **状态**:[✓] 复审通过
|
||||
- **风险等级**:P2 / 低风险
|
||||
- **关联文件**:`server/controllers/attachments.go`
|
||||
- **关联文件**:`backend/controllers/attachments.go`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -561,7 +561,7 @@ where group_id in (...)
|
||||
|
||||
- **状态**:[✓] 复审通过
|
||||
- **风险等级**:P2 / 低风险
|
||||
- **关联文件**:`server/config/config.go`
|
||||
- **关联文件**:`backend/config/config.go`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -581,7 +581,7 @@ Windows 和 Linux 下的配置路径解析结果一致且符合预期,路径
|
||||
|
||||
- **状态**:[✓] 复审通过:生产模式默认强制操作系统级隔离;不具备隔离能力的平台拒绝启动插件
|
||||
- **风险等级**:P2 / 低至中风险
|
||||
- **关联文件**:`server/hooks/base.go`
|
||||
- **关联文件**:`backend/hooks/base.go`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -606,7 +606,7 @@ Windows 和 Linux 下的配置路径解析结果一致且符合预期,路径
|
||||
|
||||
- **状态**:[✓] 复审通过
|
||||
- **风险等级**:P2 / 未来回归风险
|
||||
- **关联文件**:`server/services/detail/detail.go`
|
||||
- **关联文件**:`backend/services/detail/detail.go`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -658,8 +658,8 @@ Windows 和 Linux 下的配置路径解析结果一致且符合预期,路径
|
||||
- **状态**:[✓] 复审通过
|
||||
- **风险等级**:P2 / 工程质量
|
||||
- **关联文件**:
|
||||
- `server/dto/parsemail/email.go`
|
||||
- `server/controllers/group.go`
|
||||
- `backend/dto/parsemail/email.go`
|
||||
- `backend/controllers/group.go`
|
||||
|
||||
### 整改要求
|
||||
|
||||
@@ -740,27 +740,27 @@ go vet ./...
|
||||
|
||||
| 任务编号 | 修改提交 | 修改文件 | 验证命令或链接 | 验证结果 | 复审日期 | 复审人 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| SEC-001 | 未提交(工作区) | `server/listen/smtp_server/` | `go test ./listen/smtp_server/...` | STARTTLS 前不提供 AUTH,相关测试通过 | 2026-08-24 | Codex |
|
||||
| SEC-002 | 未提交(工作区) | `server/listen/smtp_server/` | `gosec ./...` | 无密码明文日志,扫描 0 issues | 2026-08-24 | Codex |
|
||||
| SEC-003 | 未提交(工作区) | `server/listen/http_server/`、`server/controllers/setup.go` | `go test ./listen/http_server/... ./controllers/...` | 初始化令牌、来源和重复初始化边界已验证 | 2026-08-24 | Codex |
|
||||
| SEC-004 | 未提交(工作区) | `server/listen/http_server/`、`server/session/` | HTTP/HTTPS 测试、`go test ./...` | HTTP 不承载业务会话,Cookie 和安全响应头已加固 | 2026-08-24 | Codex |
|
||||
| SEC-005 | 未提交(工作区) | `server/controllers/email/move.go`、`server/services/group/` | `go test ./services/group/... ./controllers/email/...` | 跨用户目标分组被拒绝 | 2026-08-24 | Codex |
|
||||
| SEC-006 | 未提交(工作区) | `server/services/group/group.go` | `go test ./services/group/...` | 删除分组更新包含用户条件 | 2026-08-24 | Codex |
|
||||
| SEC-007 | 未提交(工作区) | `server/utils/password/`、认证及第三方配置流程 | `go test ./utils/password/... ./services/auth/...` | 统一使用 Argon2id;不保留旧算法兼容分支 | 2026-08-24 | Codex |
|
||||
| SEC-008 | 未提交(工作区) | `server/controllers/`、`server/listen/http_server/` | `go test ./...` | 请求体、附件和 RPC 均有限制 | 2026-08-24 | Codex |
|
||||
| SEC-009 | 未提交(工作区) | `server/utils/csrf/`、`server/listen/http_server/` | `go test ./utils/csrf/... ./listen/http_server/...` | 状态修改请求执行来源和 CSRF 校验 | 2026-08-24 | Codex |
|
||||
| SEC-010 | 未提交(工作区) | `server/dto/parsemail/`、`fe/src/views/EmailDetailView.vue` | `go test ./dto/parsemail/...`、前端构建 | 邮件 HTML 白名单清理和前端隔离已验证 | 2026-08-24 | Codex |
|
||||
| SEC-011 | 未提交(工作区) | `server/listen/http_server/https_server.go`、`fe/src/components/PluginSettings.vue` | 前端 ESLint、构建、HTTP 响应头测试 | 安全响应头和插件 iframe 隔离已验证 | 2026-08-24 | Codex |
|
||||
| SEC-012 | 未提交(工作区) | `server/services/setup/ssl/`、`server/controllers/setup.go` | `go test ./services/setup/ssl/...` | 路径、证书和私钥匹配校验通过 | 2026-08-24 | Codex |
|
||||
| SEC-013 | 未提交(工作区) | `server/utils/smtp/smtp.go` | `go test ./utils/smtp/...` | 出站 TLS 校验主机名和证书 | 2026-08-24 | Codex |
|
||||
| SEC-014 | 未提交(工作区) | `server/main_test.go` | `go test -count=1 ./...` | 测试副作用边界已修复,未删除真实配置 | 2026-08-24 | Codex |
|
||||
| SEC-015 | 未提交(工作区) | `server/config/`、`server/services/auth/`、`server/services/setup/ssl/` | `go test ./...`、文件权限测试 | 敏感文件和目录权限已收紧 | 2026-08-24 | Codex |
|
||||
| SEC-016 | 未提交(工作区) | `server/services/auth/auth.go` | `go test ./services/auth/...` | DKIM RSA 密钥至少 2048 位 | 2026-08-24 | Codex |
|
||||
| SEC-017 | 未提交(工作区) | `server/controllers/attachments.go`、附件测试 | `go test ./controllers/... ./services/attachments/...` | 文件名和响应头注入场景已覆盖 | 2026-08-24 | Codex |
|
||||
| SEC-018 | 未提交(工作区) | `server/config/config.go`、路径校验测试 | `go test ./...` | Windows/Linux 路径边界已覆盖 | 2026-08-24 | Codex |
|
||||
| SEC-019 | 未提交(工作区) | `server/hooks/` | `go test ./hooks/...`、Linux 跨平台编译、插件边界测试 | Linux 生产隔离和 Windows 生产失败关闭已验证;开发兼容模式不计入生产结论 | 2026-08-24 | Codex |
|
||||
| SEC-020 | 未提交(工作区) | `server/services/detail/`、IMAP 查询入口 | `go test ./services/detail/... ./listen/imap_server/...` | UID 查询包含用户隔离 | 2026-08-24 | Codex |
|
||||
| SEC-021 | 未提交(工作区) | `.github/workflows/security.yml`、`fe/yarn.lock`、`server/go.mod` | `govulncheck ./...`、`yarn.cmd audit --groups dependencies` | 未发现可达漏洞;记录 `openpgp` 不可达模块级告警 | 2026-08-24 | Codex |
|
||||
| SEC-001 | 未提交(工作区) | `backend/listen/smtp_server/` | `go test ./listen/smtp_server/...` | STARTTLS 前不提供 AUTH,相关测试通过 | 2026-08-24 | Codex |
|
||||
| SEC-002 | 未提交(工作区) | `backend/listen/smtp_server/` | `gosec ./...` | 无密码明文日志,扫描 0 issues | 2026-08-24 | Codex |
|
||||
| SEC-003 | 未提交(工作区) | `backend/listen/http_server/`、`backend/controllers/setup.go` | `go test ./listen/http_server/... ./controllers/...` | 初始化令牌、来源和重复初始化边界已验证 | 2026-08-24 | Codex |
|
||||
| SEC-004 | 未提交(工作区) | `backend/listen/http_server/`、`backend/session/` | HTTP/HTTPS 测试、`go test ./...` | HTTP 不承载业务会话,Cookie 和安全响应头已加固 | 2026-08-24 | Codex |
|
||||
| SEC-005 | 未提交(工作区) | `backend/controllers/email/move.go`、`backend/services/group/` | `go test ./services/group/... ./controllers/email/...` | 跨用户目标分组被拒绝 | 2026-08-24 | Codex |
|
||||
| SEC-006 | 未提交(工作区) | `backend/services/group/group.go` | `go test ./services/group/...` | 删除分组更新包含用户条件 | 2026-08-24 | Codex |
|
||||
| SEC-007 | 未提交(工作区) | `backend/utils/password/`、认证及第三方配置流程 | `go test ./utils/password/... ./services/auth/...` | 统一使用 Argon2id;不保留旧算法兼容分支 | 2026-08-24 | Codex |
|
||||
| SEC-008 | 未提交(工作区) | `backend/controllers/`、`backend/listen/http_server/` | `go test ./...` | 请求体、附件和 RPC 均有限制 | 2026-08-24 | Codex |
|
||||
| SEC-009 | 未提交(工作区) | `backend/utils/csrf/`、`backend/listen/http_server/` | `go test ./utils/csrf/... ./listen/http_server/...` | 状态修改请求执行来源和 CSRF 校验 | 2026-08-24 | Codex |
|
||||
| SEC-010 | 未提交(工作区) | `backend/dto/parsemail/`、`frontend/src/views/EmailDetailView.vue` | `go test ./dto/parsemail/...`、前端构建 | 邮件 HTML 白名单清理和前端隔离已验证 | 2026-08-24 | Codex |
|
||||
| SEC-011 | 未提交(工作区) | `backend/listen/http_server/https_server.go`、`frontend/src/components/PluginSettings.vue` | 前端 ESLint、构建、HTTP 响应头测试 | 安全响应头和插件 iframe 隔离已验证 | 2026-08-24 | Codex |
|
||||
| SEC-012 | 未提交(工作区) | `backend/services/setup/ssl/`、`backend/controllers/setup.go` | `go test ./services/setup/ssl/...` | 路径、证书和私钥匹配校验通过 | 2026-08-24 | Codex |
|
||||
| SEC-013 | 未提交(工作区) | `backend/utils/smtp/smtp.go` | `go test ./utils/smtp/...` | 出站 TLS 校验主机名和证书 | 2026-08-24 | Codex |
|
||||
| SEC-014 | 未提交(工作区) | `backend/main_test.go` | `go test -count=1 ./...` | 测试副作用边界已修复,未删除真实配置 | 2026-08-24 | Codex |
|
||||
| SEC-015 | 未提交(工作区) | `backend/config/`、`backend/services/auth/`、`backend/services/setup/ssl/` | `go test ./...`、文件权限测试 | 敏感文件和目录权限已收紧 | 2026-08-24 | Codex |
|
||||
| SEC-016 | 未提交(工作区) | `backend/services/auth/auth.go` | `go test ./services/auth/...` | DKIM RSA 密钥至少 2048 位 | 2026-08-24 | Codex |
|
||||
| SEC-017 | 未提交(工作区) | `backend/controllers/attachments.go`、附件测试 | `go test ./controllers/... ./services/attachments/...` | 文件名和响应头注入场景已覆盖 | 2026-08-24 | Codex |
|
||||
| SEC-018 | 未提交(工作区) | `backend/config/config.go`、路径校验测试 | `go test ./...` | Windows/Linux 路径边界已覆盖 | 2026-08-24 | Codex |
|
||||
| SEC-019 | 未提交(工作区) | `backend/hooks/` | `go test ./hooks/...`、Linux 跨平台编译、插件边界测试 | Linux 生产隔离和 Windows 生产失败关闭已验证;开发兼容模式不计入生产结论 | 2026-08-24 | Codex |
|
||||
| SEC-020 | 未提交(工作区) | `backend/services/detail/`、IMAP 查询入口 | `go test ./services/detail/... ./listen/imap_server/...` | UID 查询包含用户隔离 | 2026-08-24 | Codex |
|
||||
| SEC-021 | 未提交(工作区) | `.github/workflows/security.yml`、`frontend/yarn.lock`、`backend/go.mod` | `govulncheck ./...`、`yarn.cmd audit --groups dependencies` | 未发现可达漏洞;记录 `openpgp` 不可达模块级告警 | 2026-08-24 | Codex |
|
||||
| SEC-022 | 未提交(工作区) | `.github/workflows/security.yml`、Go 静态检查相关文件 | `go vet ./...`、`gosec ./...` | `go vet` 通过,gosec 0 issues | 2026-08-24 | Codex |
|
||||
|
||||
---
|
||||
@@ -774,7 +774,7 @@ go vet ./...
|
||||
- SEC-019 已完成生产模式的插件隔离整改:Linux 使用独立用户、临时根目录、网络命名空间和资源限制;Windows 及其他不具备可靠隔离能力的平台生产模式默认拒绝插件启动。开发模式的兼容启动不计入生产安全结论。
|
||||
- 前端构建存在大于 500 kB 的 JS chunk 性能警告,不属于本轮发现的明显安全漏洞。
|
||||
- 当前工作区已有大量未提交变更;本轮未执行提交、推送、`git reset`、`git clean` 或文件删除。
|
||||
- `server/utils/validation/test.tmp` 为此前调试遗留文件,当前仍保留,删除前需获得明确授权。
|
||||
- `backend/utils/validation/test.tmp` 为此前调试遗留文件,当前仍保留,删除前需获得明确授权。
|
||||
|
||||
## SEC-019 复审结论(2026-08-24)
|
||||
|
||||
@@ -839,7 +839,7 @@ go vet ./...
|
||||
|
||||
- **本轮状态**:`[x] 已完成,等待复审`
|
||||
- **执行任务**:继续复审配置回滚票据的代次冲突、一次性消费、并发执行、失败重试及错误响应边界。
|
||||
- **修改文件**:`server/config/manager.go`、`server/config/manager_v2.go`、`server/config/manager_v2_test.go`、`server/controllers/config_error.go`、`server/controllers/config_error_test.go`。
|
||||
- **修改文件**:`backend/config/manager.go`、`backend/config/manager_v2.go`、`backend/config/manager_v2_test.go`、`backend/controllers/config_error.go`、`backend/controllers/config_error_test.go`。
|
||||
- **实施摘要**:回滚票据增加执行中状态,防止同一票据被并发请求重复执行;请求取消或运行时快照暂时不可用时恢复票据的可重试状态;实际回滚已提交但审计写入失败时销毁票据,避免重复提交;新增 `CONFIG_ROLLBACK_IN_PROGRESS` 稳定错误码和中文提示。
|
||||
- **测试命令**:`go test ./config ./controllers -run 'Test(ConfigManagerRollbackTicket|ConfigErrorDetailsMapsRollbackInProgress)' -count=1`、`go test ./... -count=1 -timeout 30m`、`go vet ./...`、`git diff --check`。
|
||||
- **测试结果**:回滚票据专项测试、服务端全量测试和 `go vet ./...` 通过;前端 ESLint 与生产构建在上一轮已通过。
|
||||
@@ -867,7 +867,7 @@ go vet ./...
|
||||
- **状态**:`[x] 已完成,等待真实客户端和部署环境复审`。
|
||||
- **实施内容**:为 `user_email` 增加持久化 `is_deleted` 标志和版本 14 数据库迁移;`SELECT`、UID/序列号 `FETCH` 和 `STORE` 统一返回或更新 `\Seen`、`\Deleted`;普通 `EXPUNGE` 仅清除当前邮箱中已标记删除的邮件,`UID EXPUNGE` 仅清除指定 UID 集合中已标记删除的邮件。
|
||||
- **边界加固**:所有查询和更新同时限制当前用户与当前邮箱;修复 UID FETCH 返回错误序列号的问题;按序列号降序发送 EXPUNGE 响应;支持 `*` 和 `n:*` 动态 UID 范围,限制单次最多展开 10000 个 UID,防止超大范围占用资源。
|
||||
- **修改范围**:`server/models/user_email.go`、`server/db/migration/imap_flags.go`、`server/services/list/list.go`、`server/services/del_email/del_email.go`、`server/listen/imap_server/session_*.go` 及相关测试。
|
||||
- **修改范围**:`backend/models/user_email.go`、`backend/db/migration/imap_flags.go`、`backend/services/list/list.go`、`backend/services/del_email/del_email.go`、`backend/listen/imap_server/session_*.go` 及相关测试。
|
||||
- **自动化验证**:`go test ./services/list ./listen/imap_server ./db/migration ./services/del_email -count=1 -timeout 10m` 已通过;本轮最终提交前继续执行服务端全量测试、竞态测试、`go vet`、前端 ESLint 和生产构建。
|
||||
- **开放项**:HSTS 与 Nginx 反向代理的实际上线行为、真实 IMAP 客户端兼容性、Ubuntu/Windows 部署和真实 MySQL/PostgreSQL 迁移仍需实机复审,不据此升级为最终发布通过。
|
||||
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
# 安全引导与设置提示修复验收
|
||||
|
||||
日期:2026-09-05
|
||||
|
||||
## 本次范围
|
||||
|
||||
- [✓] 首次登录显示密保问题、外部安全邮箱、安全密钥引导,包含超级管理员。
|
||||
- [✓] 引导确认状态按账号持久化,确认失败保留弹窗并允许重试。
|
||||
- [✓] 强制修改密码页面不显示引导,进入邮箱后再提示。
|
||||
- [✓] 设置标签页按需加载,未启用安全密钥时显示状态说明。
|
||||
- [✓] 旧版配置模式先读取配置管理状态,不继续请求分区、备份、审计。
|
||||
- [✓] 退出时销毁会话和 CSRF Cookie,避免下一次登录被残留会话阻断。
|
||||
- [!] 现有主服务替换及完整 setup 向导重新验收未完成。
|
||||
- [!] Git 推送因远程认证失败未完成;用户已授权先本地修复。
|
||||
|
||||
## 引导语义
|
||||
|
||||
新增数据库迁移 15,为用户增加 `security_setup_acknowledged`,默认值为零。
|
||||
新账号与尚未确认过新引导的旧账号均显示一次引导。
|
||||
只有点击引导中的确认或前往设置按钮,并且服务端成功持久化后,才停止自动提示。
|
||||
未确认时刷新仍显示,避免页面刚加载或请求失败就丢失引导。
|
||||
多标签页已经显示的弹窗不会实时同步关闭,确认接口可重复安全调用。
|
||||
|
||||
`POST /api/v1/security/setup/acknowledge` 只处理当前会话用户,不接受目标账号切换。
|
||||
接口使用正式会话、请求来源、CSRF 与强制改密校验链路。
|
||||
确认引导不代表已完成任何安全设置,也不会修改密码或安全版本。
|
||||
|
||||
普通账号离线恢复码仍可在安全设置内生成,旧恢复码组件文件保留但不再全局自动弹出。
|
||||
超级管理员不开放网页密码恢复或离线恢复码入口,部署端本机 IPC 安全边界保持不变。
|
||||
|
||||
## 浏览器实测
|
||||
|
||||
隔离服务地址:`https://localhost:15443/`,采用临时自签名证书。
|
||||
服务使用独立空 SQLite、正式迁移器、真实登录/会话/CSRF/配置控制器,以及最新前端构建。
|
||||
测试账号由夹具创建,并非完整 setup 向导创建;未使用当前业务库。
|
||||
|
||||
1. 超级管理员通过登录表单进入收件箱,出现三项安全引导。
|
||||
2. 未带 CSRF 的确认请求返回业务错误,不能确认引导。
|
||||
3. 点击开始设置,确认成功后进入密保问题页,无配置管理请求和错误通知。
|
||||
4. 点击安全密钥,显示服务器未启用说明,不发送凭据列表请求。
|
||||
5. 切到配置管理,只请求一次状态,显示旧版配置迁移说明,无重复错误通知。
|
||||
6. 刷新后用户信息成功返回,`showSecuritySetupPrompt=false`,保持登录且不再弹窗。
|
||||
7. 退出重登实测发现原实现保留会话 Cookie;改为销毁后,在干净隔离浏览器上下文重测,登录成功且不再弹窗。
|
||||
|
||||
隔离夹具不启动 SMTP/IMAP/POP 或管理员 IPC,不构成完整服务部署验收。
|
||||
当前旧后端仍需要由具备相应权限的部署人员切换至新版本。
|
||||
旧版配置迁移及 WebAuthn 服务启用本身不在此次自动操作范围,不能将状态提示当成功能已启用。
|
||||
|
||||
## 验证与产物
|
||||
|
||||
- 后端全套 `go test ./...` 已运行通过;部分外部数据库或管理员权限相关测试按原有条件跳过。
|
||||
- 新增迁移默认值/幂等、账号隔离、匿名拒绝、HTTP 方法/CSRF、退出 Cookie 销毁回归测试。
|
||||
- 前端新增引导与配置请求行为测试;执行 `npm test` 与 `npm run build`。
|
||||
- 前端构建仍有大型分包警告,不影响本次构建成功。
|
||||
- 本地后端产物:`backend/.tmp-smail-security-setup.exe`。
|
||||
- 真实业务 SQLite、现有 DKIM 改动未修改或提交;测试数据保留在忽略目录中。
|
||||
|
||||
隔离浏览器夹具需显式设置 `SMAIL_BROWSER_FIXTURE=1`、新的 `SMAIL_BROWSER_ROOT`、
|
||||
`SMAIL_BROWSER_PASSWORD`、`SMAIL_BROWSER_DIST`,然后仅运行
|
||||
`TestSecuritySetupBrowserFixture`。默认跳过,启用后最长运行 30 分钟。
|
||||
不要给夹具指定真实数据目录,也不要把测试密码写入版本控制。
|
||||
@@ -0,0 +1,60 @@
|
||||
# 开发启动权限说明
|
||||
|
||||
## 需求与任务
|
||||
|
||||
- [x] 开发阶段不因管理员密码重置通道要求提升整个后端权限。
|
||||
- [x] 保留当前配置、数据库与 HTTPS 行为,不清空数据。
|
||||
- [x] 正式部署默认保留 Windows 命名管道和 Linux 本机套接字的严格检查。
|
||||
- [x] 开发时关闭重置入口,而不是取消入口鉴权。
|
||||
- [✓] 普通权限启动与后端回归测试验收。
|
||||
- [!] 自动停止并重启验收:本次执行工具拦截了停止命令,未完成重启验证。
|
||||
|
||||
## 使用当前数据库进行开发
|
||||
|
||||
在普通 PowerShell 中运行:
|
||||
|
||||
```powershell
|
||||
Set-Location D:\Desktop\Smail
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/build.ps1
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/start-dev.ps1 -Service backend
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/start-dev.ps1 -Service frontend
|
||||
```
|
||||
|
||||
此参数只停用本机超级管理员密码重置通道,不改变配置文件选择,仍读取 `config/config.json`。账号、数据库、HTTPS、Cookie 和 CSRF 策略均沿用原配置。开发日志会明确提示重置通道已停用。
|
||||
|
||||
2026-09-05 配置管理修复后,当前 `config/config.json` 已迁移为分区根配置。必须先执行上面的编译命令,再运行新二进制;不要直接运行迁移前保留的旧程序。备份和本次验收边界见《配置管理接入修复验收》。后续修复期间已成功普通权限停止旧后端并启动新后端,下方早期停止受阻记录仅反映当时状态。
|
||||
|
||||
启动脚本以普通权限在后台运行服务,并输出进程编号;停止时先核对进程路径,再使用 `Stop-Process -Id <进程编号>`。日志位于 `test-log/runtime/`,二进制位于 `out/backend/`。脚本显式设置 `SMAIL_ROOT` 指向 `backend/`,避免在 `out/` 下生成另一份配置或数据库。其他端口占用、文件权限或系统限制仍需分别处理,此参数不保证绕过所有操作系统权限问题。
|
||||
|
||||
## 原有开发模式
|
||||
|
||||
```powershell
|
||||
Set-Location D:\Desktop\Smail\backend
|
||||
go run . dev
|
||||
```
|
||||
|
||||
末尾 `dev` 仍读取 `config/config.dev.json` 并启用项目原有开发行为,现在也会停用管理员重置通道。该文件可能使用另一份数据库,不应为解决权限问题直接切换过去。开发模式下不再使用 `SMAIL_ADMIN_CONTROL_PATH` 创建重置通道。
|
||||
|
||||
## 正式部署
|
||||
|
||||
- 移除 `--dev-disable-admin-reset`,不要以末尾 `dev` 启动。
|
||||
- Windows 保持受保护命名管道及管理员客户端校验;Linux 保持受保护本机套接字及对端身份校验。
|
||||
- 通道创建或运行失败仍会让正式后端启动失败或退出,不静默降级。
|
||||
- 没有新增 HTTP、局域网或公网重置接口。
|
||||
- 启动参数属于部署主机权限边界,不能由网页请求切换。不要把开发启动命令复制进正式服务配置。
|
||||
|
||||
开发模式不能用于验收真实管理员恢复功能;该功能需在对应系统的正式权限条件下单独验收。
|
||||
|
||||
## 本次验证记录
|
||||
|
||||
2026-09-05 在 Windows 普通权限会话中验证:
|
||||
|
||||
- 当前进程管理员角色检查为 `False`。
|
||||
- 使用上述独立开发参数启动最新编译后端,日志显示开发通道停用和邮箱服务就绪。
|
||||
- 后端监听 80、443、25、465、587、110、993、995 端口。
|
||||
- 后端 `/api/ping`、前端 15173 端口代理 `/api/ping` 均返回 200。
|
||||
- 前端使用 `Accept: text/html` 请求首页返回 200,并包含 Vite 客户端。
|
||||
- `go test ./res_init ./services/adminreset` 和 `go test ./...` 均通过。
|
||||
- 正式模式创建失败、空通道和运行失败仍上报错误的自动测试通过;没有把这些单元测试当作 Linux 或 Windows 正式部署验收。
|
||||
- 没有清空真实数据库,没有重置账号或修改密钥;本次未进行浏览器业务流程回归。
|
||||
- 自动停止命令被执行工具策略拦截,没有绕过限制;后端保持运行,不宣称重启验收通过。
|
||||
@@ -0,0 +1,80 @@
|
||||
# 文件目录整理说明
|
||||
|
||||
## 需求确认
|
||||
|
||||
按本次要求将独立测试代码、脚本集中到 `test/`,测试记录集中到 `test-log/`,编译输出集中到 `out/`;不改动真实配置、账号库、证书或业务逻辑。
|
||||
|
||||
## 整理后的结构
|
||||
|
||||
```text
|
||||
Smail/
|
||||
├── frontend/ # 前端源码与依赖
|
||||
├── backend/ # 后端源码、必要的同包测试与运行配置
|
||||
├── plugins/ # 插件源码与文档
|
||||
├── deploy/ # 构建、开发启动及正式部署工具
|
||||
├── test/ # 独立测试源码、脚本和统一测试入口
|
||||
│ ├── frontend/
|
||||
│ ├── manual/
|
||||
│ ├── plugins/
|
||||
│ └── tools/
|
||||
├── test-log/ # 本地证据,不进入版本库
|
||||
│ ├── archive/ # 历史日志、浏览器数据、配置备份
|
||||
│ ├── fixtures/ # 历史初始化测试数据
|
||||
│ ├── reports/ # 审查报告和移动、清理清单
|
||||
│ ├── runtime/ # 前后端开发日志
|
||||
│ └── screenshots/ # 截图及测试 Logo 图
|
||||
├── out/ # 编译输出,不进入版本库
|
||||
│ ├── frontend/
|
||||
│ ├── backend/
|
||||
│ ├── plugins/
|
||||
│ ├── test-tools/
|
||||
│ └── archive/ # 尚需保留的旧编译产物
|
||||
└── docs/ # 项目文档
|
||||
```
|
||||
|
||||
`out/package/` 和 `out/release/` 分别供 Makefile 打包及 CI 发布使用。开发日志由 `deploy/start-dev.ps1` 写入 `test-log/runtime/`,测试入口为 `node test/run.mjs all`。
|
||||
|
||||
## 必须保留的例外
|
||||
|
||||
1. Go 同包测试保留在 `backend/`:依赖包私有符号,直接搬离会破坏测试,统一入口负责集中执行。
|
||||
2. `backend/listen/http_server/dist/` 和 Telegram 插件的 `hook/dist/` 是 Go 嵌入中间目录:Go 不允许跨模块向上嵌入,不能直接指向 `out/`。前端正式输出在 `out/`,构建后自动同步必需的嵌入文件。
|
||||
3. 运行 Logo、文档图片、源代码静态资源、依赖目录、模型及训练工具不属于测试垃圾。
|
||||
4. `backend/config/` 是现有服务的数据根目录,配置、SQLite、密钥及迁移备份原位保留。根目录 `ssl/` 和用途尚未确认的空数据库也保留,不凭文件名删除。
|
||||
|
||||
## 构建与启动
|
||||
|
||||
```powershell
|
||||
Set-Location D:\Desktop\Smail
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/build.ps1
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/start-dev.ps1 -Service backend
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/start-dev.ps1 -Service frontend
|
||||
```
|
||||
|
||||
开发后端为 `out/backend/smail-dev.exe`。脚本固定 `SMAIL_ROOT=backend/`,不在 `out/` 下创建新账号库。编译前应停止正在运行的同名二进制,停止前核对进程号和路径。正式部署仍需使用发行入口 `cmd/smail`,保留本机管理员恢复通道的权限保护。
|
||||
|
||||
两个新增 PowerShell 脚本使用 UTF-8 BOM,使 Windows PowerShell 5 正确解析中文;其他源文件沿用其原编码。没有用脚本替换中文文字。
|
||||
|
||||
## 清理与安全边界
|
||||
|
||||
- 历史 `artifacts/` 中的记录、浏览器资料和配置备份移入 `test-log/archive/artifacts/`,二进制另归档到 `out/archive/`。
|
||||
- 历史测试资料中的配置引用不自动重写;目录变更后它们只作为证据保留,不保证能够直接重放。
|
||||
- 清理候选仅限已确认的空目录和校验哈希相同的重复归档编译文件,至少保留一份。本次删除命令被执行环境策略拦截,未执行物理删除;文件已集中归档,并保存待清理清单,不绕过策略。
|
||||
- `make clean` 不再直接递归删除文件,必须先审查清单。
|
||||
- 构建打包不复制本机真实配置、证书或密钥,首次正式部署应使用初始化流程。
|
||||
- `test-log/` 可能含浏览器 Cookie、测试凭据和配置备份,不能公开上传或提交;`out/` 和历史工具归档同样不提交。
|
||||
|
||||
本轮任务点和实际验证结果见本文件末尾的验收记录;未做真实发信、模型运行或跨平台部署的项目,不算验收通过。
|
||||
|
||||
## 本次验收记录
|
||||
|
||||
- [✓] 前端自动测试、独立密码检查工具、SMTP 和模型测试脚本已迁入 `test/`;178 个 Go 同包测试原位保留。
|
||||
- [✓] 历史日志、截图、测试数据库及配置备份完成归档,移动记录位于 `test-log/reports/organization-moves.csv`。
|
||||
- [✓] 前端及后端开发程序、管理和配置工具输出到 `out/`;Telegram 前端及 Windows 插件构建通过。
|
||||
- [✓] 归档期间 `backend/config/` 下 79 个文件逐一哈希校验未改变,未清空数据库。
|
||||
- [✓] `node test/run.mjs all -- -count=1 ./...` 通过,Go 测试未使用结果缓存;随后新增构建路径约束测试,最终前端及构建约束共 19 项全部通过。
|
||||
- [✓] 从新目录启动前后端,443 和 15173 监听正常;后端与前端代理探活返回 200。
|
||||
- [✓] 浏览器 MCP 忽略缓存刷新后仍显示收件箱,无登录框或错误提示;配置状态、基础配置、备份、审计读取均返回 200。
|
||||
- [✓] 新脚本语法及 YAML 解析检查通过,`out/`、`test-log/` 和历史脚本归档均被 Git 忽略。
|
||||
- [✓] Windows 正式入口程序及微信、垃圾邮件和 Telegram 插件均成功编译到 `out/`,未启动正式服务或执行插件业务操作。
|
||||
- [!] 物理删除未完成:发现 2 个哈希完全相同的重复二进制候选,约 201.75 MiB;文件仍保留,见 `duplicate-binaries-retained.csv`,空目录清单见 `empty-directories-retained.csv`。
|
||||
- [!] 本次未验收模型推断、真实 SMTP 发信、全平台发布或 Linux/Windows 正式安装;未重新执行清库初始化流程,避免破坏用户现有账号与配置。
|
||||
+24
-24
@@ -10,7 +10,7 @@
|
||||
| 编写日期 | 2026-08-25 |
|
||||
| 需求依据 | `docs/超级管理员重置与邮箱验证码需求文档.md` 0.3 |
|
||||
| 关联文档 | `docs/配置系统重构需求文档.md`、`docs/配置系统重构技术设计.md`、`docs/配置系统重构实施任务清单.md` |
|
||||
| 适用目录 | `server`、`fe`、`docs` 及后续安装脚本目录 |
|
||||
| 适用目录 | `server`、`frontend`、`docs` 及后续安装脚本目录 |
|
||||
| 任务总数 | 66 |
|
||||
|
||||
本文档用于把超级管理员部署端重置、外部邮箱验证码、登录二次验证和分角色密码恢复拆分为可实施、可测试、可复审、可追踪的任务。本文档只建立执行计划,不代表任何功能已经实现。
|
||||
@@ -100,7 +100,7 @@
|
||||
2. **Linux 正式入口**:唯一可写入口为 `systemctl start smail-admin`;`smail-admin` 是执行一次受控重置事务后退出的短时服务,不是常驻网络服务;
|
||||
3. **安全密码交互**:使用 `systemd-ask-password` 或等效短时受保护本机凭据交互;无可用密码代理时安全拒绝,禁止参数、环境变量、文件、日志、标准输入和标准输出传递密码;
|
||||
4. **权限矩阵**:超级管理员可重置管理员和普通用户,管理员只可重置普通用户,普通用户仅可重置本人,部署端 `smail-admin` 只可重置超级管理员自身;
|
||||
5. **源码入口**:独立程序入口固定为 `server/cmd/smail-admin/main.go`;
|
||||
5. **源码入口**:独立程序入口固定为 `backend/cmd/smail-admin/main.go`;
|
||||
6. **持久化边界**:验证码及校验值只存在于签发认证进程内存;非敏感运营数据允许持久化并每 14 天执行一次清理;
|
||||
7. **验收边界**:systemd 安全交互、本机 IPC、Windows/Ubuntu 适配、三数据库、真实浏览器和安全负向测试均未完成前不得最终验收。
|
||||
|
||||
@@ -190,7 +190,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:AD-001、AD-002、AD-003
|
||||
- **需求映射**:第 21、22、24 章
|
||||
- **修改范围**:`server` 测试、`fe` 测试、跨平台测试说明、CI
|
||||
- **修改范围**:`server` 测试、`frontend` 测试、跨平台测试说明、CI
|
||||
- **实施步骤**:把需求条款映射到单元、集成、并发、故障注入、浏览器、安装升级和跨平台测试;标记 MySQL、PostgreSQL、SQLite 覆盖范围。
|
||||
- **安全要求**:不得以手工说明代替可自动化的关键安全测试;平台缺口必须阻塞验收。
|
||||
- **测试要求**:检查每条验收项和 17 条阻塞条件至少映射一个测试或人工审计步骤。
|
||||
@@ -216,7 +216,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:AD-001
|
||||
- **需求映射**:第 3.1、6.1、22.1 章
|
||||
- **修改范围**:`server/cmd/smail/main.go`、固定入口 `server/cmd/smail-admin/main.go`、构建配置
|
||||
- **修改范围**:`backend/cmd/smail/main.go`、固定入口 `backend/cmd/smail-admin/main.go`、构建配置
|
||||
- **实施步骤**:将主服务入口和管理程序入口分离;输出 `smail`、`smail-admin` 及 Windows 对应程序;共享版本信息但不共享不必要初始化逻辑。
|
||||
- **安全要求**:`smail-admin` 不加载插件、HTTP 服务、邮件监听器、数据库配置或主密钥。
|
||||
- **测试要求**:独立构建、依赖检查、启动副作用检查和二进制符号检查。
|
||||
@@ -230,7 +230,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:AD-006、AD-001
|
||||
- **需求映射**:第 8.1 章
|
||||
- **修改范围**:`server/cmd/smail-admin` 命令解析和测试
|
||||
- **修改范围**:`backend/cmd/smail-admin` 命令解析和测试
|
||||
- **实施步骤**:只实现 `version`、`doctor` 等只读辅助命令;正式重置只能由 `systemctl start smail-admin` 触发;未知参数和任何密码参数均拒绝;输出稳定退出码。
|
||||
- **安全要求**:禁止 `--password`、环境变量密码、脚本化明文标准输入和调试泄露。
|
||||
- **测试要求**:参数模糊测试、危险参数负向测试、退出码和帮助文本测试。
|
||||
@@ -330,7 +330,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:AD-012、AD-015、AD-009
|
||||
- **需求映射**:第 3.1、8.3、21.2、22.2 章
|
||||
- **修改范围**:建议 `server/internal/adminipc` Linux 适配、运行目录和测试
|
||||
- **修改范围**:建议 `backend/internal/adminipc` Linux 适配、运行目录和测试
|
||||
- **实施步骤**:使用 `/run/smail/admin-control.sock`;安全创建和清理 socket;验证目录、所有者、模式和对端 UID/进程凭据;拒绝符号链接和非常规文件。
|
||||
- **安全要求**:权限位不能替代服务端对端身份验证;不得监听 TCP 或注册 HTTP Router。
|
||||
- **测试要求**:root、普通用户、Smail 用户、错误所有者、socket 抢占、符号链接、主程序重启和并发连接测试。
|
||||
@@ -344,7 +344,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:AD-012、AD-015、AD-010
|
||||
- **需求映射**:第 3.1、8.3、21.2、22.2 章
|
||||
- **修改范围**:建议 `server/internal/adminipc` Windows 适配、ACL 和测试
|
||||
- **修改范围**:建议 `backend/internal/adminipc` Windows 适配、ACL 和测试
|
||||
- **实施步骤**:使用 `\\.\pipe\smail-admin-control`;设置仅 Administrators/SYSTEM 的 ACL;服务端模拟客户端并验证访问令牌、管理员组和会话身份。
|
||||
- **安全要求**:ACL 不能替代服务端令牌验证;拒绝远程管道、普通用户、Smail 服务账户和匿名身份。
|
||||
- **测试要求**:管理员、UAC 非提权令牌、普通用户、SYSTEM、服务账户、ACL 篡改和并发客户端测试。
|
||||
@@ -383,7 +383,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-029、AD-003
|
||||
- **需求映射**:第 3.1、8.5、8.6、22.2 章
|
||||
- **修改范围**:`server/utils/password`、认证服务、管理控制服务和测试
|
||||
- **修改范围**:`backend/utils/password`、认证服务、管理控制服务和测试
|
||||
- **实施步骤**:抽取主程序统一密码校验、策略检查和 Argon2id 哈希接口;本机控制服务只调用该接口;统一 Web、管理员强制重置和部署端重置的密码验证结果。
|
||||
- **安全要求**:不保留旧算法、弱算法或失败后的兼容回退;管理程序不得自行哈希。
|
||||
- **测试要求**:密码长度、复杂度、拒绝列表、Argon2id 参数、错误处理和跨入口一致性测试。
|
||||
@@ -439,7 +439,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:AD-002
|
||||
- **需求映射**:第 3.2、5.1、13.4、17、18.2、20.1 章
|
||||
- **修改范围**:`server/controllers`、HTTP Router、`fe` 登录和安全页面、测试
|
||||
- **修改范围**:`backend/controllers`、HTTP Router、`frontend` 登录和安全页面、测试
|
||||
- **实施步骤**:公共恢复流程识别超级管理员后统一拒绝创建任务;禁止 Web 修改超级管理员密码;确认未注册需求列出的三个禁止接口;前端不展示可用恢复入口。
|
||||
- **安全要求**:不能只靠前端隐藏;响应不得泄露账号存在、角色和恢复方式。
|
||||
- **测试要求**:路由枚举、直接 API 调用、角色篡改、localhost 请求、存在与不存在账号响应一致性测试。
|
||||
@@ -479,7 +479,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:AD-002、AD-004、CG-032
|
||||
- **需求映射**:第 11、15.3 章
|
||||
- **修改范围**:`server/models`、迁移、仓储及 MySQL/PostgreSQL/SQLite 测试
|
||||
- **修改范围**:`backend/models`、迁移、仓储及 MySQL/PostgreSQL/SQLite 测试
|
||||
- **实施步骤**:保存邮箱密文、邮箱指纹、验证时间、状态、类型和凭据版本;支持主要与备用邮箱;建立用户归属和数量约束。
|
||||
- **安全要求**:不得保存验证码任务;不得用明文邮箱建立索引;数据库约束与服务端校验同时存在。
|
||||
- **测试要求**:三数据库迁移、回滚、唯一性、并发绑定、数量上限和异常数据测试。
|
||||
@@ -561,7 +561,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:AD-026
|
||||
- **需求映射**:第 14.2、15.1、21.3 章
|
||||
- **修改范围**:建议 `server/services/verification` 内存仓库、索引和测试
|
||||
- **修改范围**:建议 `backend/services/verification` 内存仓库、索引和测试
|
||||
- **实施步骤**:保存需求定义字段;按用户、用途和任务 ID 建立受控索引;设置全局容量、每用户容量和内存预算;达到上限安全拒绝。
|
||||
- **安全要求**:任务只存在于签发实例;不得为每个任务创建无限 goroutine;内存转储风险纳入运维控制。
|
||||
- **测试要求**:容量边界、并发创建、索引一致性、内存增长、随机淘汰禁止和压力测试。
|
||||
@@ -713,7 +713,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:AD-036
|
||||
- **需求映射**:第 15.2、19、21.3、22.3 章
|
||||
- **修改范围**:`server/listen/cron_server` 或独立调度服务、租约、告警和测试
|
||||
- **修改范围**:`backend/listen/cron_server` 或独立调度服务、租约、告警和测试
|
||||
- **实施步骤**:首次安装默认启用;每 14 天运行;启动时补执行错过任务;失败每 6 小时重试;同环境单实例执行;每批最多删除 1000 条;记录脱敏结果。
|
||||
- **安全要求**:不删除活动窗口和调查保留数据;清理失败不影响登录、邮件或内存验证码;清理器不读取验证码内存仓库。
|
||||
- **测试要求**:周期、补执行、重试、租约竞争、分批、失败恢复、调查保留和服务可用性测试。
|
||||
@@ -754,7 +754,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-027、AD-035
|
||||
- **需求映射**:第 2、12.1、21.4 章
|
||||
- **修改范围**:`server/controllers/login.go`、认证服务、规范化和测试
|
||||
- **修改范围**:`backend/controllers/login.go`、认证服务、规范化和测试
|
||||
- **实施步骤**:用户名和完整 Smail 邮箱进入同一账号解析、密码校验、角色和二次验证策略;密码错误时不创建验证码任务、不发送邮件。
|
||||
- **安全要求**:两种登录标识错误响应和时间边界一致;不允许旧认证路径绕过验证码策略。
|
||||
- **测试要求**:用户名、完整邮箱、大小写、未知账号、错误密码、锁定账号和策略一致性测试。
|
||||
@@ -894,7 +894,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:AD-004、AD-035、CG-048
|
||||
- **需求映射**:第 17、20 章
|
||||
- **修改范围**:`server/controllers`、DTO、响应、CSRF、Session 和限流中间件
|
||||
- **修改范围**:`backend/controllers`、DTO、响应、CSRF、Session 和限流中间件
|
||||
- **实施步骤**:为验证码、外部邮箱、恢复和管理员接口定义稳定 DTO 与错误码;统一执行能力、对象归属、Session、CSRF、限流和请求大小检查。
|
||||
- **安全要求**:默认拒绝未知用途、角色和字段;禁止批量赋值;公共恢复响应防枚举。
|
||||
- **测试要求**:越权、CSRF、字段注入、超长请求、未知枚举、错误码稳定性和敏感响应测试。
|
||||
@@ -961,7 +961,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:AD-050
|
||||
- **需求映射**:第 18.1 章
|
||||
- **修改范围**:`fe/src/views`、认证状态、路由守卫和浏览器测试
|
||||
- **修改范围**:`frontend/src/views`、认证状态、路由守卫和浏览器测试
|
||||
- **实施步骤**:实现密码登录后的验证码输入、脱敏邮箱、倒计时、重发、过期、失败提示和 WebAuthn 替代入口;刷新后按安全状态恢复或失效事务。
|
||||
- **安全要求**:不在 localStorage、sessionStorage、URL 或前端日志保存验证码和重置授权;前端不能自行升级 Session。
|
||||
- **测试要求**:桌面、移动、低高度视口;重发、过期、刷新、后退、并发标签页和无障碍测试。
|
||||
@@ -975,13 +975,13 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:AD-050、AD-002
|
||||
- **需求映射**:第 13、18.2 章
|
||||
- **修改范围**:`fe` 忘记密码视图、恢复方式组件和测试
|
||||
- **修改范围**:`frontend` 忘记密码视图、恢复方式组件和测试
|
||||
- **实施步骤**:允许用户名或完整邮箱;始终显示统一提交结果;按后端签发事务展示可用的 WebAuthn、密保+恢复码或外部邮箱流程;启用功能并配置有效域名或 IP 后,通过大小写敏感的 `/Reset` 固定入口加载独立恢复页面。
|
||||
- **安全要求**:超级管理员不能看到或调用可用 Web 恢复路径;页面不得泄露账号存在、角色、邮箱绑定和投递结果。
|
||||
- **测试要求**:三角色、不存在账号、无恢复方式、SMTP 失败、直接路由、刷新和浏览器存储检查;覆盖域名、IPv4、IPv6、关闭开关、`GET` 方法限制和路径大小写。
|
||||
- **验收标准**:视觉和网络响应均无法可靠区分账号是否存在。
|
||||
- **回退方式**:关闭忘记密码入口。
|
||||
- **验收证据**:`fe/src/views/RecoveryView.vue`、`fe/src/views/LoginView.vue`、`server/listen/http_server/reset_entry_test.go`、`server/controllers/security_reset_entry_test.go`;2026-08-27 `go test ./...`、`go vet ./...`、`yarn.cmd build` 通过。恢复页面和登录弹窗统一为单页面表单,使用“切换验证方式”按钮切换安全密钥与外部邮箱验证码,并在切换时清理另一方式的验证码会话和输入状态。真实浏览器和三角色完整流程仍待 AD-064 复审。
|
||||
- **验收证据**:`frontend/src/views/RecoveryView.vue`、`frontend/src/views/LoginView.vue`、`backend/listen/http_server/reset_entry_test.go`、`backend/controllers/security_reset_entry_test.go`;2026-08-27 `go test ./...`、`go vet ./...`、`yarn.cmd build` 通过。恢复页面和登录弹窗统一为单页面表单,使用“切换验证方式”按钮切换安全密钥与外部邮箱验证码,并在切换时清理另一方式的验证码会话和输入状态。真实浏览器和三角色完整流程仍待 AD-064 复审。
|
||||
|
||||
- [x] 已完成,等待复审:域名/IP 配置与功能开关共同控制 `/Reset` 页面和恢复 API;关闭时页面返回 404,API 安全拒绝。
|
||||
- [x] 已完成,等待复审:新增独立恢复页面,验证码、恢复票据不写入 URL、localStorage 或 sessionStorage。
|
||||
@@ -994,7 +994,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:AD-049、AD-041
|
||||
- **需求映射**:第 18.3 章
|
||||
- **修改范围**:`fe/src/components/SecuritySettings.vue` 或独立安全页面
|
||||
- **修改范围**:`frontend/src/components/SecuritySettings.vue` 或独立安全页面
|
||||
- **实施步骤**:管理主要和备用外部邮箱;显示脱敏地址、验证状态和最近发送时间;设置登录邮箱二次验证;关联离线恢复码和 WebAuthn 管理入口。
|
||||
- **安全要求**:更换和删除前要求近期重新认证;完整邮箱和敏感票据不进入页面状态快照和错误报告。
|
||||
- **测试要求**:绑定、更换、删除、重认证过期、双邮箱上限、角色差异和 XSS 测试。
|
||||
@@ -1008,7 +1008,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:AD-051、AD-059
|
||||
- **需求映射**:第 18.4、19 章
|
||||
- **修改范围**:`fe` 管理安全页面、配置表单、统计和审计列表
|
||||
- **修改范围**:`frontend` 管理安全页面、配置表单、统计和审计列表
|
||||
- **实施步骤**:配置开关、Relay 引用、发件人、限流和角色策略;发送测试邮件;展示脱敏状态、投递统计、审计和清理任务状态。
|
||||
- **安全要求**:不显示 SMTP 密码、验证码、完整邮箱、恢复授权和删除审计入口;敏感配置修改要求近期重新认证或 WebAuthn。
|
||||
- **测试要求**:权限、CSRF、脱敏、审计分页、配置校验、失败告警和浏览器缓存检查。
|
||||
@@ -1320,7 +1320,7 @@ AD-065 + CG-053~CG-056 → AD-066 → CG-057
|
||||
- **日期**:2026-08-27
|
||||
- **执行任务**:AD-004 建立敏感字段、日志和持久化禁止清单
|
||||
- **开始状态**:未开始
|
||||
- **修改文件**:`server/config/sensitive.go`、`server/config/sensitive_test.go`、`server/controllers/config.go`、`server/controllers/config_error_test.go`、`server/services/access/authorize.go`、`server/services/access/capability.go`、`server/services/access/catalog.go`、`server/services/access/access_test.go`、`server/services/access/matrix_test.go`、`server/listen/http_server/http_server.go`、`server/listen/http_server/config_route_test.go`
|
||||
- **修改文件**:`backend/config/sensitive.go`、`backend/config/sensitive_test.go`、`backend/controllers/config.go`、`backend/controllers/config_error_test.go`、`backend/services/access/authorize.go`、`backend/services/access/capability.go`、`backend/services/access/catalog.go`、`backend/services/access/access_test.go`、`backend/services/access/matrix_test.go`、`backend/listen/http_server/http_server.go`、`backend/listen/http_server/config_route_test.go`
|
||||
- **实施摘要**:扩展敏感字段目录和持久化禁止策略;增加公共脱敏能力;将配置、审计和回滚 API 纳入能力目录;恢复配置更新 `PUT` 路由;统一授权错误的稳定错误码并防止内部错误文本进入响应;增加配置路由、授权矩阵和敏感响应负向测试。
|
||||
- **测试命令**:`go test ./services/access ./config ./controllers ./listen/http_server`、`go test ./...`、`go vet ./...`、`git diff --check`
|
||||
- **测试结果**:定向测试、全量测试和 `go vet ./...` 通过;`git diff --check` 未发现空白错误。
|
||||
@@ -1417,10 +1417,10 @@ AD-065 + CG-053~CG-056 → AD-066 → CG-057
|
||||
|
||||
### 当前实现证据
|
||||
|
||||
- 管理程序与本机控制通道:`server/cmd/smail-admin`、`server/services/adminreset`、`deploy/systemd`。
|
||||
- 外部邮箱与验证码:`server/services/externalemail`、`server/services/verification`。
|
||||
- 恢复和强认证:`server/services/recovery`、`server/services/webauthn`、`server/services/totp`、`server/services/credentials`。
|
||||
- API 与前端:`server/controllers/security.go`、`server/controllers/webauthn.go`、`server/listen/http_server/api_v1_compat.go`、`fe/src/views` 下登录验证、密码恢复、账户安全和强制改密页面。
|
||||
- 管理程序与本机控制通道:`backend/cmd/smail-admin`、`backend/services/adminreset`、`deploy/systemd`。
|
||||
- 外部邮箱与验证码:`backend/services/externalemail`、`backend/services/verification`。
|
||||
- 恢复和强认证:`backend/services/recovery`、`backend/services/webauthn`、`backend/services/totp`、`backend/services/credentials`。
|
||||
- API 与前端:`backend/controllers/security.go`、`backend/controllers/webauthn.go`、`backend/listen/http_server/api_v1_compat.go`、`frontend/src/views` 下登录验证、密码恢复、账户安全和强制改密页面。
|
||||
- 自动化复核:服务端全量、竞态和静态检查以及前端 ESLint、生产构建在本轮最终提交前统一执行并记录。
|
||||
|
||||
### 发布结论
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
|
||||
| 需求范围 | 测试或审计入口 | 当前结果 | 仍需补充 |
|
||||
|---|---|---|---|
|
||||
| AD-001~AD-004 | `server/cmd/smail-admin/main_test.go`、`services/adminreset/*_test.go`、安全威胁模型 | 自动化通过 | Ubuntu、Windows 交互实机审计 |
|
||||
| AD-001~AD-004 | `backend/cmd/smail-admin/main_test.go`、`services/adminreset/*_test.go`、安全威胁模型 | 自动化通过 | Ubuntu、Windows 交互实机审计 |
|
||||
| AD-005 | 本文件、配置系统测试基线、CI 安全工作流 | 自动化通过 | 将本矩阵接入发布检查 |
|
||||
| AD-006~AD-008 | 管理程序命令、危险参数、受信进程和密码代理测试 | 自动化通过 | 真实 systemd 和 Windows 令牌 |
|
||||
| AD-009、AD-010 | `deploy/systemd/*`、安装脚本和平台适配测试 | 部分通过 | Ubuntu 22.04/24.04、Windows Service 和 ACL |
|
||||
@@ -60,9 +60,9 @@
|
||||
|
||||
| 环境 | 命令或检查 | 当前状态 |
|
||||
|---|---|---|
|
||||
| Windows 开发环境 | `cd server; go test ./... -count=1` | 通过 |
|
||||
| Windows 开发环境 | `cd server; go vet ./...` | 通过 |
|
||||
| Windows 开发环境 | `cd fe; yarn.cmd build` | 通过 |
|
||||
| Windows 开发环境 | `cd backend; go test ./... -count=1` | 通过 |
|
||||
| Windows 开发环境 | `cd backend; go vet ./...` | 通过 |
|
||||
| Windows 开发环境 | `cd frontend; yarn.cmd build` | 通过 |
|
||||
| SQLite | 迁移、事务、并发和恢复测试 | 通过 |
|
||||
| MySQL | `SMAIL_TEST_MYSQL_DSN` 集成测试 | 未配置,未验证 |
|
||||
| PostgreSQL | `SMAIL_TEST_POSTGRES_DSN` 集成测试 | 未配置,未验证 |
|
||||
@@ -74,4 +74,4 @@
|
||||
|
||||
## 5. 发布判定
|
||||
|
||||
在 MySQL、PostgreSQL、Ubuntu 22.04、Ubuntu 24.04、Windows 生产服务、真实 SMTP 和真实浏览器证据补齐前,AD-065、AD-066 以及配置系统的最终验收不得标记为复审通过。自动化测试通过只说明当前代码在隔离测试环境下满足已覆盖的行为,不代表跨平台和生产边界已经闭合。
|
||||
在 MySQL、PostgreSQL、Ubuntu 22.04、Ubuntu 24.04、Windows 生产服务、真实 SMTP 和真实浏览器证据补齐前,AD-065、AD-066 以及配置系统的最终验收不得标记为复审通过。自动化测试通过只说明当前代码在隔离测试环境下满足已覆盖的行为,不代表跨平台和生产边界已经闭合。
|
||||
@@ -153,8 +153,8 @@ smail-admin
|
||||
推荐源码入口:
|
||||
|
||||
```text
|
||||
server/cmd/smail/main.go
|
||||
server/cmd/smail-admin/main.go
|
||||
backend/cmd/smail/main.go
|
||||
backend/cmd/smail-admin/main.go
|
||||
```
|
||||
|
||||
Windows 构建产物为:
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
# 配置管理接入修复验收
|
||||
|
||||
## 本次需求
|
||||
|
||||
修复配置管理标题被挤成两行,以及旧版配置无法接入在线配置管理的问题。保留现有数据库、账号和证书,不以隐藏错误代替修复。
|
||||
|
||||
## 任务与结果
|
||||
|
||||
- [✓] 标题与说明改为上下排列,标题独立显示一行。
|
||||
- [✓] 修正配置管理器根目录,避免重复拼接 `config/config`。
|
||||
- [✓] 为旧业务启动提供分区配置只读兼容快照,保留当前 SQLite 数据库引用。
|
||||
- [✓] 禁止旧版写入接口覆盖分区根文件。
|
||||
- [✓] 停机备份、预演迁移、真实配置迁移及新后端重启。
|
||||
- [✓] 脱敏备份列表使用配置读取权限,回滚预览、票据及执行仍要求近期认证。
|
||||
- [✓] 备份与审计错误局部显示,不阻挡成功加载的配置编辑区。
|
||||
- [✓] 修复卡片最小内容宽度造成的右侧导航遮挡,确认文字允许换行。
|
||||
- [✓] 前端测试、生产构建及后端全量测试通过。
|
||||
- [✓] 浏览器刷新保持登录,五个配置分区均可读取,卡片不与右侧导航重叠。
|
||||
|
||||
## 原因
|
||||
|
||||
旧配置尚未迁移,管理器不能启用;原启动代码又把配置目录当成服务根目录传入加载器,重复拼接路径。只生成分区文件仍不足以修复,旧业务还需要正确读取新的数据库与证书引用。
|
||||
|
||||
迁移后发现另一个独立问题:备份列表读取使用了高风险回滚权限,现有会话的近期认证过期时返回 `403 / RECENT_AUTH_REQUIRED`。前端又把附属请求失败提升为整页不可用。
|
||||
|
||||
现在只有脱敏代次列表读取改用 `config.read`,普通用户仍被拒绝。回滚的三个操作均有自动测试确认近期认证要求没有放松。
|
||||
|
||||
## 本机配置与备份
|
||||
|
||||
- 当前读取:`backend/config/config.json`,已经是分区根配置,代次为 `1`。
|
||||
- 当前数据库仍为 `backend/config/smail_temp.db`,未清空、重建或重置账号。
|
||||
- 停机配置目录备份已归档至:`test-log/archive/artifacts/config-migration-backup-20260905-175927/config`。
|
||||
- 原始配置迁移备份位于 `backend/config/migration-backups/`,并保留 `backend/config/config.json.legacy`。
|
||||
- 以上目录含真实配置或凭据,仅限本机保管,不能提交或对外分享。
|
||||
|
||||
## 后续开发启动
|
||||
|
||||
必须重新编译当前源码再启动,不能继续运行迁移前遗留的旧后端二进制:
|
||||
|
||||
```powershell
|
||||
Set-Location D:\Desktop\Smail
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/build.ps1
|
||||
powershell -NoProfile -ExecutionPolicy Bypass -File deploy/start-dev.ps1 -Service backend
|
||||
```
|
||||
|
||||
编译前先停止同名运行进程;同时只能有一个后端占用服务端口。目录整理后的运行文件为 `out/backend/smail-dev.exe`,启动脚本显式指定配置根目录 `backend/`。前端开发地址为 `http://127.0.0.1:15173`。
|
||||
|
||||
开发参数只停用本机管理员重置通道,不改用另一份数据库,不放宽线上接口鉴权。正式部署需移除此参数,保留 Windows 命名管道或 Linux 本机套接字保护。
|
||||
|
||||
## 其他旧部署的显式迁移
|
||||
|
||||
以下命令只适用于尚未迁移的旧部署,本机已迁移完成,不应重复执行:
|
||||
|
||||
```powershell
|
||||
Set-Location D:\Desktop\Smail
|
||||
& .\out\backend\smail-config.exe --root D:\Desktop\Smail\backend
|
||||
# 先停止后端并备份配置目录,再执行以下命令。
|
||||
& .\out\backend\smail-config.exe --root D:\Desktop\Smail\backend --apply
|
||||
```
|
||||
|
||||
默认命令仅做旧字段检查,不是完整迁移预演;完整校验及备份迁移发生在 `--apply`。命令本身不检测运行中的后端,停机必须由部署人员确认。
|
||||
|
||||
## 验收边界
|
||||
|
||||
- 本次浏览器通过现有登录会话及 Vite 代理访问最新后端,验证的是配置读取和桌面布局;生产前端产物也已构建并复制到后端嵌入目录。
|
||||
- 未在真实账号库执行保存配置、回滚、数据库迁移或重置初始化,避免改变现有业务数据。
|
||||
- 不代表所有旧版设置写入接口均已迁移;旧写接口对分区根文件会明确拒绝,不能绕过保护。
|
||||
- 当前真实迁移只验收 SQLite 与现有证书引用。MySQL、PostgreSQL、自动 DNS 证书及正式 Linux/Windows 部署未做本次端到端验收。
|
||||
- 前端构建仍有大于 500 kB 的包体积警告,不影响本次构建成功,未在本任务内扩大重构范围。
|
||||
- 浏览器截图已直接复审;工具限制了指定磁盘路径的截图写入,不声称截图已保存至项目目录。
|
||||
+60
-60
@@ -11,7 +11,7 @@
|
||||
| 需求依据 | `docs/配置系统重构需求文档.md` 0.7、`docs/超级管理员重置与邮箱验证码需求文档.md` 0.3 |
|
||||
| 技术依据 | `docs/配置系统重构技术设计.md` 0.5 |
|
||||
| 详细子任务 | `docs/超级管理员重置与邮箱验证码实施任务清单.md` 0.3 |
|
||||
| 适用目录 | `server`、`fe`、`plugins`、`docs` |
|
||||
| 适用目录 | `server`、`frontend`、`plugins`、`docs` |
|
||||
|
||||
本文档用于按任务点实施、测试、复审和标记配置系统重构进度。除文档任务外,所有编码任务初始状态均为“未开始”;不得因为已有相似代码就直接标记为“已完成”。
|
||||
|
||||
@@ -127,7 +127,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-001
|
||||
- **设计映射**:第 3、13、28 章
|
||||
- **修改范围**:`server/services/access`、`server/config`、相关测试和安全文档
|
||||
- **修改范围**:`backend/services/access`、`backend/config`、相关测试和安全文档
|
||||
- **实施步骤**:列出所有 Secret 字段;定义三级角色能力;定义高风险操作和二次确认要求;允许能力策略声明 `requiresRecoveryCode`;建立 API 到能力映射。
|
||||
- **安全要求**:能力必须默认拒绝;敏感字段不允许通过通用反射自动输出;`requiresRecoveryCode` 只检查管理员和普通用户,超级管理员明确豁免;角色变更必须按照变更后的目标角色检查目标用户是否需要有效恢复码。
|
||||
- **测试要求**:为每个管理 API 建立最少一条允许和一条拒绝用例;覆盖管理员和普通用户缺少有效恢复码、超级管理员豁免、角色变更目标用户缺少恢复码及稳定错误码 `RECOVERY_CODE_REQUIRED`。
|
||||
@@ -141,7 +141,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-001
|
||||
- **设计映射**:第 11.4、24.1 章
|
||||
- **修改范围**:`server/db`、新增迁移目录和测试
|
||||
- **修改范围**:`backend/db`、新增迁移目录和测试
|
||||
- **实施步骤**:创建 `schema_migration`;实现迁移发现、校验和、数据库锁、事务执行和版本检查;限制生产环境继续依赖无版本 `Sync2`。
|
||||
- **安全要求**:检测迁移文件篡改;并发启动只能有一个迁移执行者;失败时停止业务服务。
|
||||
- **测试要求**:MySQL、PostgreSQL、SQLite 的首次迁移、重复执行、校验和冲突和中途失败测试。
|
||||
@@ -155,7 +155,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-001
|
||||
- **设计映射**:第 29 章
|
||||
- **修改范围**:`server` 测试目录、`fe` 测试配置、`docs`
|
||||
- **修改范围**:`server` 测试目录、`frontend` 测试配置、`docs`
|
||||
- **实施步骤**:记录当前 Go 和前端测试结果;建立新增测试分类;定义跨数据库和跨平台验证命令;准备无真实凭据的测试配置。
|
||||
- **安全要求**:测试夹具不得包含真实密钥;失败日志不得打印 Secret。
|
||||
- **测试要求**:运行当前完整测试并记录既有失败,避免把历史失败误归因于重构。
|
||||
@@ -181,17 +181,17 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-001
|
||||
- **设计映射**:第 6 章
|
||||
- **修改范围**:`server/config/model.go`、`root.go`、`smtp.go`、`email.go`、`ssl.go`、`plugins.go`
|
||||
- **修改范围**:`backend/config/model.go`、`root.go`、`smtp.go`、`email.go`、`ssl.go`、`plugins.go`
|
||||
- **实施步骤**:定义 `RootConfig`、四个分区模型、`SectionRef`、`SectionMeta`、`SetupState`、固定文件名映射和 MySQL、PostgreSQL、SQLite 结构化数据库模型;MySQL/PostgreSQL 使用主机、端口、用户名、加密密码和数据库名称,SQLite 使用后端生成的 `localRef`。
|
||||
- **安全要求**:API 和配置内容不能覆盖分区实际路径;枚举使用白名单;DSN 只允许连接工厂在内存临时构造,不进入配置、API、日志和审计。
|
||||
- **测试要求**:模型序列化、三种数据库条件字段、默认端口、非法枚举、任意 SQLite 路径拒绝和固定路径测试。
|
||||
- **验收标准**:模型能表达需求文档字段且不继续增加旧聚合 `Config` 字段。
|
||||
- **回退方式**:新模型暂不接入启动流程。
|
||||
- **验收证据**:
|
||||
1. `server/config/model.go` 已建立 `DatabaseType` 白名单,支持 `mysql`、`postgresql`、`sqlite`;MySQL 和 PostgreSQL 在端口为空时分别补充 `3306`、`5432`,SQLite 不生成网络默认端口。
|
||||
1. `backend/config/model.go` 已建立 `DatabaseType` 白名单,支持 `mysql`、`postgresql`、`sqlite`;MySQL 和 PostgreSQL 在端口为空时分别补充 `3306`、`5432`,SQLite 不生成网络默认端口。
|
||||
2. `DatabaseConfig` 已按数据库类型表达条件字段:MySQL/PostgreSQL 使用主机、端口、用户名、加密密码和数据库名称;SQLite 仅使用后端引用格式的 `localRef`,并拒绝绝对路径、Windows 路径、UNC 路径、目录分隔符、上级目录、网络字段和密码字段。
|
||||
3. `server/config/sections.go` 已固定分区到 `config.json`、`smtp.json`、`email.json`、`ssl.json`、`plugins.json`,并通过 `SectionRef`、`SectionMeta`、代次和 SHA-256 摘要校验阻止任意路径映射;`server/config/sections_test.go` 覆盖固定文件名、未知分区、路径篡改、Schema、代次和摘要异常。
|
||||
4. `server/config/model_database_test.go` 覆盖三种数据库条件字段、默认端口、非法及旧 PostgreSQL 枚举、SQLite 任意路径拒绝和 `localRef` JSON 序列化;`go test ./config -count=1` 通过。
|
||||
3. `backend/config/sections.go` 已固定分区到 `config.json`、`smtp.json`、`email.json`、`ssl.json`、`plugins.json`,并通过 `SectionRef`、`SectionMeta`、代次和 SHA-256 摘要校验阻止任意路径映射;`backend/config/sections_test.go` 覆盖固定文件名、未知分区、路径篡改、Schema、代次和摘要异常。
|
||||
4. `backend/config/model_database_test.go` 覆盖三种数据库条件字段、默认端口、非法及旧 PostgreSQL 枚举、SQLite 任意路径拒绝和 `localRef` JSON 序列化;`go test ./config -count=1` 通过。
|
||||
5. 全量验证:在 `server` 目录执行 `go test ./... -count=1`、`go vet ./...` 均通过;`git diff --check` 未发现空白错误。MySQL/PostgreSQL 真实数据库连接、跨平台部署和启动流程仍未在本机完成集成验收,不能据此视为生产验收通过。
|
||||
|
||||
### CG-006 实现严格 JSON 解析器
|
||||
@@ -200,13 +200,13 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-005
|
||||
- **设计映射**:第 8.2 章
|
||||
- **修改范围**:`server/config/parser.go`、测试
|
||||
- **修改范围**:`backend/config/parser.go`、测试
|
||||
- **实施步骤**:限制大小和深度;拒绝未知字段、重复键、BOM、无效 UTF-8、尾随内容和范围溢出。
|
||||
- **安全要求**:错误不得回显 Secret 值和绝对路径。
|
||||
- **测试要求**:覆盖嵌套重复键、大小写相近字段、超大数值、多个 JSON 值和畸形输入。
|
||||
- **验收标准**:全部恶意配置夹具被稳定拒绝,正常配置无兼容性回退。
|
||||
- **回退方式**:保留旧解析器但不在生产开关中启用新路径。
|
||||
- **验收证据**:`server/config/parser.go` 已实现配置大小限制、最大嵌套深度、Token 级重复键检测、`DisallowUnknownFields`、BOM 拒绝、无效 UTF-8 拒绝、尾随 JSON 内容拒绝、`UseNumber` 数值解析和精确字段形状校验;超大数值、大小写相近字段、嵌套未知字段、控制字符、畸形输入均使用固定错误,不回显 Secret 或绝对路径。`server/config/parser_test.go`、`server/config/parser_security_test.go` 覆盖重复键、嵌套重复键、未知字段、数值溢出、多个 JSON 值、深度和大小限制,以及错误信息脱敏;`go test ./config -count=1` 已通过。
|
||||
- **验收证据**:`backend/config/parser.go` 已实现配置大小限制、最大嵌套深度、Token 级重复键检测、`DisallowUnknownFields`、BOM 拒绝、无效 UTF-8 拒绝、尾随 JSON 内容拒绝、`UseNumber` 数值解析和精确字段形状校验;超大数值、大小写相近字段、嵌套未知字段、控制字符、畸形输入均使用固定错误,不回显 Secret 或绝对路径。`backend/config/parser_test.go`、`backend/config/parser_security_test.go` 覆盖重复键、嵌套重复键、未知字段、数值溢出、多个 JSON 值、深度和大小限制,以及错误信息脱敏;`go test ./config -count=1` 已通过。
|
||||
|
||||
### CG-007 实现配置验证器
|
||||
|
||||
@@ -214,13 +214,13 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-005、CG-006
|
||||
- **设计映射**:第 8.3、8.4 章
|
||||
- **修改范围**:`server/config/validator.go`、`server/utils/validation`、测试
|
||||
- **修改范围**:`backend/config/validator.go`、`backend/utils/validation`、测试
|
||||
- **实施步骤**:实现结构、本地语义、跨分区、路径、域名、端口和插件 ID 校验;将外部连接测试与保存校验分离。
|
||||
- **安全要求**:保存配置不得隐式连接任意用户输入目标;路径必须限制在受控目录。
|
||||
- **测试要求**:端口冲突、路径逃逸、域名冲突、插件能力越权和状态机条件测试。
|
||||
- **验收标准**:无效候选配置不能进入磁盘事务或运行时快照。
|
||||
- **回退方式**:关闭新配置更新入口,不绕过验证器保存。
|
||||
- **验收证据**:`server/config/validator.go` 已实现日志级别、HTTP/HTTPS 端口、SMTP Relay 主机/端口/发件域/加密模式、邮箱端口和登录验证策略、SSL 受控相对路径及证书私钥成对引用、插件逻辑 ID/文件名/网络白名单/凭据格式校验;远程 SMTP 明文 Relay、路径逃逸、绝对路径、非法域名、重复插件网络目标和不安全插件网络目标均被拒绝。`server/config/runtime_validator.go` 已实现分区元数据、代次、域名唯一性、端口冲突、插件能力与网络目标、ready 状态和生产降级状态校验。`server/config/validator_security_test.go` 覆盖非法日志级别、HTTP/HTTPS 端口、ready 缺少 Web 域名、域名重复、SMTP 非法主机及远程明文、SSL 路径逃逸和证书私钥不成对、邮箱策略、插件重复/危险网络目标;`SnapshotStore` 和 `ConfigManager` 测试证明无效候选不会改变活动快照、活动代次、待重启状态或磁盘分区文件。已通过 `go test ./config ./controllers ./listen/http_server -count=1`、`go test ./... -count=1` 和 `go vet ./...`。本证据未覆盖真实数据库、真实 SMTP 投递、证书链/私钥匹配、插件进程沙箱和生产部署环境,相关验收保持开放。
|
||||
- **验收证据**:`backend/config/validator.go` 已实现日志级别、HTTP/HTTPS 端口、SMTP Relay 主机/端口/发件域/加密模式、邮箱端口和登录验证策略、SSL 受控相对路径及证书私钥成对引用、插件逻辑 ID/文件名/网络白名单/凭据格式校验;远程 SMTP 明文 Relay、路径逃逸、绝对路径、非法域名、重复插件网络目标和不安全插件网络目标均被拒绝。`backend/config/runtime_validator.go` 已实现分区元数据、代次、域名唯一性、端口冲突、插件能力与网络目标、ready 状态和生产降级状态校验。`backend/config/validator_security_test.go` 覆盖非法日志级别、HTTP/HTTPS 端口、ready 缺少 Web 域名、域名重复、SMTP 非法主机及远程明文、SSL 路径逃逸和证书私钥不成对、邮箱策略、插件重复/危险网络目标;`SnapshotStore` 和 `ConfigManager` 测试证明无效候选不会改变活动快照、活动代次、待重启状态或磁盘分区文件。已通过 `go test ./config ./controllers ./listen/http_server -count=1`、`go test ./... -count=1` 和 `go vet ./...`。本证据未覆盖真实数据库、真实 SMTP 投递、证书链/私钥匹配、插件进程沙箱和生产部署环境,相关验收保持开放。
|
||||
|
||||
### CG-008 实现统一 SecretChange 和 CredentialVault 适配
|
||||
|
||||
@@ -228,13 +228,13 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-002、CG-005
|
||||
- **设计映射**:第 3.3、10.3 章
|
||||
- **修改范围**:`server/config/secret.go`、`server/config/sections.go`、`server/config/manager_v2.go`、`server/config/runtime_validator.go`、`server/controllers/config.go`、`server/utils/credential` 和相关测试
|
||||
- **修改范围**:`backend/config/secret.go`、`backend/config/sections.go`、`backend/config/manager_v2.go`、`backend/config/runtime_validator.go`、`backend/controllers/config.go`、`backend/utils/credential` 和相关测试
|
||||
- **实施步骤**:实现 `keep`、`replace`、`clear`;统一数据库、SMTP、插件等凭据的加密、解密、脱敏和版本字段;插件 Secret 使用 `plugins.<逻辑ID>.secret` 变更路径,并在分区载荷中保留已有密文。
|
||||
- **安全要求**:不支持旧弱算法回退;密钥文件权限不合格时拒绝启动;Secret 不进入日志。
|
||||
- **测试要求**:密文篡改、错误密钥、版本不支持、三种更新语义和 JSON 脱敏测试。
|
||||
- **验收标准**:所有第三方配置使用同一输入和存储边界,查询接口不返回原文。
|
||||
- **回退方式**:不迁移已有凭据,只关闭 V2 写接口;不得回退成明文。
|
||||
- **验收证据**:`StoredSecret`、`SecretChange`、`SecretPolicy` 和 `CredentialVault` 已统一接入数据库密码、SMTP Relay 密码和插件 Secret;插件支持 `replace`、`keep`、`clear`,未知插件、非法路径、直接提交密文均被拒绝;插件 Secret 经过同一套版本与密文格式校验,公共配置响应仅返回 `secretStatus`,不返回明文、密文或 Secret 输入值。`server/config/secret_test.go` 覆盖三种语义、密文篡改、错误密钥、版本不支持和 JSON 脱敏;`server/config/manager_v2_test.go` 覆盖插件 Secret 全流程及非法请求;`server/controllers/config_public_response_test.go` 覆盖插件公共响应脱敏。测试结束清理仅匹配 `server/.codex-smail-*` 的临时文件。已通过 `go test ./... -count=1`、`go vet ./...`、`git diff --check`,并验证 `mingw32-make clean_codex_test_artifacts` 只清理目标临时文件。真实数据库、SMTP 投递、插件进程沙箱、Ubuntu/Windows 部署和生产环境仍未完成集成验收。
|
||||
- **验收证据**:`StoredSecret`、`SecretChange`、`SecretPolicy` 和 `CredentialVault` 已统一接入数据库密码、SMTP Relay 密码和插件 Secret;插件支持 `replace`、`keep`、`clear`,未知插件、非法路径、直接提交密文均被拒绝;插件 Secret 经过同一套版本与密文格式校验,公共配置响应仅返回 `secretStatus`,不返回明文、密文或 Secret 输入值。`backend/config/secret_test.go` 覆盖三种语义、密文篡改、错误密钥、版本不支持和 JSON 脱敏;`backend/config/manager_v2_test.go` 覆盖插件 Secret 全流程及非法请求;`backend/controllers/config_public_response_test.go` 覆盖插件公共响应脱敏。测试结束清理仅匹配 `backend/.codex-smail-*` 的临时文件。已通过 `go test ./... -count=1`、`go vet ./...`、`git diff --check`,并验证 `mingw32-make clean_codex_test_artifacts` 只清理目标临时文件。真实数据库、SMTP 投递、插件进程沙箱、Ubuntu/Windows 部署和生产环境仍未完成集成验收。
|
||||
|
||||
### CG-009 实现不可变运行时快照
|
||||
|
||||
@@ -242,13 +242,13 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-005、CG-007、CG-008
|
||||
- **设计映射**:第 9 章
|
||||
- **修改范围**:`server/config/snapshot.go`、调用方和竞态测试
|
||||
- **修改范围**:`backend/config/snapshot.go`、调用方和竞态测试
|
||||
- **实施步骤**:使用 `atomic.Pointer` 发布快照;深复制映射和切片;为旧 `config.Instance` 增加只读兼容适配。
|
||||
- **安全要求**:调用方不能修改已发布快照;快照不包含加密主密钥和不必要明文 Secret。
|
||||
- **测试要求**:并发读取、连续更新、竞态检测、深复制和旧快照生命周期测试。
|
||||
- **验收标准**:业务请求不再从磁盘读取配置,竞态测试无数据竞争。
|
||||
- **回退方式**:切回旧读取适配层,不删除新快照代码。
|
||||
- **验收证据**:`server/config/snapshot.go` 使用 `atomic.Pointer[RuntimeConfig]` 和 CAS 发布;发布前对根配置、分区 map、插件 map、插件权限切片、网络目标切片和 `json.RawMessage` 深复制;拒绝低于当前活动代次的候选快照;`server/config/runtime_access.go` 为旧 `config.Instance` 提供只读深拷贝适配;覆盖旧配置的切片和 map 字段;`server/config/snapshot_test.go` 覆盖无效候选拒绝、输入和读取结果深拷贝、并发读取与连续更新、旧快照生命周期、旧代次并发发布;`server/config/manager_v2_test.go` 覆盖 `Snapshot`、`UpdateResult.Candidate` 和 `ApplyResult.Snapshot` 返回值隔离;已通过 `go test ./config -count=1` 和 `go test -race ./config -count=1`;本证据未覆盖真实生产进程切换、Ubuntu/Windows 部署和真实运行时长期观测,相关验收保持开放。
|
||||
- **验收证据**:`backend/config/snapshot.go` 使用 `atomic.Pointer[RuntimeConfig]` 和 CAS 发布;发布前对根配置、分区 map、插件 map、插件权限切片、网络目标切片和 `json.RawMessage` 深复制;拒绝低于当前活动代次的候选快照;`backend/config/runtime_access.go` 为旧 `config.Instance` 提供只读深拷贝适配;覆盖旧配置的切片和 map 字段;`backend/config/snapshot_test.go` 覆盖无效候选拒绝、输入和读取结果深拷贝、并发读取与连续更新、旧快照生命周期、旧代次并发发布;`backend/config/manager_v2_test.go` 覆盖 `Snapshot`、`UpdateResult.Candidate` 和 `ApplyResult.Snapshot` 返回值隔离;已通过 `go test ./config -count=1` 和 `go test -race ./config -count=1`;本证据未覆盖真实生产进程切换、Ubuntu/Windows 部署和真实运行时长期观测,相关验收保持开放。
|
||||
|
||||
### CG-010 实现 ConfigManager 核心接口
|
||||
|
||||
@@ -256,7 +256,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-006、CG-007、CG-008、CG-009
|
||||
- **设计映射**:第 7 章
|
||||
- **修改范围**:`server/config/manager.go`、`loader.go`、测试
|
||||
- **修改范围**:`backend/config/manager.go`、`loader.go`、测试
|
||||
- **实施步骤**:实现 `Load`、`Snapshot`、`Status`、`Validate`、`Update`、`Apply`、`Rollback`;统一错误模型。
|
||||
- **安全要求**:写操作串行化;读取只返回快照;所有入口执行固定分区检查。
|
||||
- **测试要求**:空配置、正常加载、分区损坏、摘要错误、代次不一致和并发更新测试。
|
||||
@@ -270,7 +270,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-010
|
||||
- **设计映射**:第 10.1、10.2 章
|
||||
- **修改范围**:`server/config/transaction.go`、`storage.go`、`server/utils/atomicfile`、测试
|
||||
- **修改范围**:`backend/config/transaction.go`、`storage.go`、`backend/utils/atomicfile`、测试
|
||||
- **实施步骤**:实现候选目录、事务清单、分区提交、主入口最后提交、目录同步和启动恢复。
|
||||
- **安全要求**:拒绝符号链接和非常规文件;临时文件权限与正式配置一致;崩溃后不得混合代次启动。
|
||||
- **测试要求**:在每个事务阶段模拟失败;验证完成提交或恢复旧代次;执行竞态和文件替换测试。
|
||||
@@ -284,7 +284,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-011、CG-002
|
||||
- **设计映射**:第 10.4、10.5 章
|
||||
- **修改范围**:`server/config/backup.go`、`audit.go`、Controller 和测试
|
||||
- **修改范围**:`backend/config/backup.go`、`audit.go`、Controller 和测试
|
||||
- **实施步骤**:每 7 天创建并验证配置备份;清理超过 30 天的备份;超过 4 份时删除最旧备份;始终保留至少一个已验证有效版本;实现超级管理员回滚预览、一次性票据和回滚生成新 generation。
|
||||
- **安全要求**:新备份成功并验证后才能清理;新备份失败不得删除已有有效备份;回滚要求近期重新认证和审计;备份不含明文 Secret;不删除旧数据库、用户文件或当前唯一有效备份。
|
||||
- **测试要求**:备份失败不清理、30 天边界、最多 4 份、唯一有效备份保护、备份篡改、不可解密、回滚预览票据、代次冲突、应用失败和审计失败测试。
|
||||
@@ -298,7 +298,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-010、CG-012、CG-003
|
||||
- **设计映射**:第 7.3、11.7、11.8、26、27 章
|
||||
- **修改范围**:`server/dto/response`、配置 Controller、数据库名称迁移服务、审计查询和导出服务、受控服务管理器、前端请求层和测试
|
||||
- **修改范围**:`backend/dto/response`、配置 Controller、数据库名称迁移服务、审计查询和导出服务、受控服务管理器、前端请求层和测试
|
||||
- **实施步骤**:实现稳定英文错误码、中文公开消息、字段错误、请求 ID、待重启服务和降级原因;实现仅限同类型同服务器同账户的数据库名称迁移服务;实现配置审计筛选、详情和脱敏导出;实现 Windows Service/systemd 固定服务重启适配器。
|
||||
- **安全要求**:迁移仅限超级管理员并保留旧数据库;数据库名称迁移和配置回滚对超级管理员不检查离线恢复码,但必须要求近期重新认证或 WebAuthn 二次确认、能力授权、审计和事务保护;审计至少保留 365 天且普通 Web API 不可删除单条记录;重启不接受任意命令或服务名;响应不包含绝对路径、底层数据库错误、第三方正文或 Secret。
|
||||
- **测试要求**:错误码、HTTP 状态、字段脱敏、数据库复制失败和原子切换、审计差异脱敏与导出、回滚预览票据、固定服务重启、命令注入拒绝、日志错误链和前端显示测试。
|
||||
@@ -325,7 +325,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-010、CG-011、CG-003
|
||||
- **设计映射**:第 11 章
|
||||
- **修改范围**:`server/config/migrate.go`、迁移测试和示例配置
|
||||
- **修改范围**:`backend/config/migrate.go`、迁移测试和示例配置
|
||||
- **实施步骤**:检测旧结构;生成迁移计划;映射基础、SSL、SMTP、插件字段;重新封装凭据;完整验证后提交新主入口。
|
||||
- **安全要求**:迁移前备份;未知字段必须报告;无法安全解密的凭据要求重新设置;不删除旧文件。
|
||||
- **测试要求**:当前配置、缺失字段、未知字段、损坏密文、重复执行和迁移中断测试。
|
||||
@@ -339,7 +339,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-014、CG-007
|
||||
- **设计映射**:第 6、8、11.6、12、30 章
|
||||
- **修改范围**:`server/config/ssl.go`、`server/services/setup/ssl`、`server/listen/http_server`、测试
|
||||
- **修改范围**:`backend/config/ssl.go`、`backend/services/setup/ssl`、`backend/listen/http_server`、测试
|
||||
- **实施步骤**:实现 `managed_default` 默认受控目录和 `managed_upload` 自定义上传后托管双模式;导入证书到候选目录并生成内部引用;完成证书链、私钥匹配和域名校验后原子切换;接入快照和应用结果。
|
||||
- **安全要求**:API 不接受服务器绝对路径;限制大小和 PEM 类型;拒绝路径逃逸、符号链接、重解析点和硬链接;检查私钥权限;生产环境不得因证书错误自动回退到公网 HTTP。
|
||||
- **测试要求**:默认目录、自定义上传、自动证书、路径输入拒绝、路径逃逸、符号链接、重解析点、硬链接、权限、域名不匹配和更新回滚测试。
|
||||
@@ -360,7 +360,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-005、CG-002
|
||||
- **设计映射**:第 21.1 章
|
||||
- **修改范围**:`server/services/plugin/catalog.go`、`server/hooks/registry.go`、测试
|
||||
- **修改范围**:`backend/services/plugin/catalog.go`、`backend/hooks/registry.go`、测试
|
||||
- **实施步骤**:固定 `spam_block`、`wechat_push`、`telegram_push`;建立跨平台可执行文件映射和插件能力元数据。
|
||||
- **安全要求**:不接受客户端路径;拒绝未知插件 ID、重复 Hook 名和未登记可执行文件。
|
||||
- **测试要求**:路径注入、大小写冲突、重复 ID、未知文件和平台映射测试。
|
||||
@@ -374,7 +374,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-008、CG-016、CG-002
|
||||
- **设计映射**:第 13.3、14.4、21.2~21.5 章
|
||||
- **修改范围**:`server/config/plugins.go`、`server/services/plugin/config.go`、`user_setting.go`、`secret.go`、数据库迁移、模型和测试
|
||||
- **修改范围**:`backend/config/plugins.go`、`backend/services/plugin/config.go`、`user_setting.go`、`secret.go`、数据库迁移、模型和测试
|
||||
- **实施步骤**:实现非敏感全局插件 DTO、`plugin_user_setting`、`plugin_secret`、按插件验证器、本人设置服务、跨用户设置服务、批量预览与执行服务;插件 Secret 使用统一 SecretChange 加密存数据库;Telegram 用户设置只存数据库;预留能力授权接口但暂不开放写路由。
|
||||
- **安全要求**:主密钥不能存入同一数据库;插件文件和配置备份不得包含 Token、Secret、API Key;本人服务只从 Session 获取用户 ID;跨用户服务校验目标角色;批量服务只接受短时一次性预览票据、明确覆盖策略和逐用户版本;正式路由在 CG-025 完成前保持关闭。
|
||||
- **测试要求**:三角色策略、IDOR、批量目标篡改、预览票据重放、版本冲突、数据库密文篡改、密钥分离、Secret 脱敏、Telegram 用户设置归属和并发更新测试。
|
||||
@@ -388,7 +388,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-016、CG-017、CG-009
|
||||
- **设计映射**:第 21.4、22 章
|
||||
- **修改范围**:`server/services/plugin`、`server/hooks/base.go`、`server/hooks/framework`、测试
|
||||
- **修改范围**:`backend/services/plugin`、`backend/hooks/base.go`、`backend/hooks/framework`、测试
|
||||
- **实施步骤**:增加 `/Capabilities`、`/ValidateConfig`、`/Configure`、`/Health`;生成单插件裁剪 DTO;只在内存解密并下发该插件所需 Secret;实现目标主机、端口和协议强制白名单;将 Web Push 纳入插件能力;在健康检查后注册 Hook。
|
||||
- **安全要求**:插件只获取自身配置和当前事件必要用户设置;RPC 有认证、大小、超时和并发限制;网络默认拒绝且不存在任意外网开关;每次 DNS 解析、重定向和连接均校验白名单;失败立即注销 Hook。
|
||||
- **测试要求**:伪造插件、超大响应、超时、崩溃、重复 Hook、错误能力、Secret 泄露、主机和端口绕过、DNS 重绑定、跨白名单重定向、私网访问和 Web Push 越权测试。
|
||||
@@ -444,7 +444,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-014、CG-009
|
||||
- **设计映射**:第 6、8、30 章
|
||||
- **修改范围**:`server/config/smtp.go`、`email.go`、SMTP/IMAP/POP3 服务和测试
|
||||
- **修改范围**:`backend/config/smtp.go`、`email.go`、SMTP/IMAP/POP3 服务和测试
|
||||
- **实施步骤**:迁移监听、DKIM、垃圾邮件、Relay 和邮箱策略字段;按热更新或重启分类;业务服务改读快照。
|
||||
- **安全要求**:SMTP 密码统一加密;DKIM 私钥限制受控目录;连接测试执行 SSRF 防护。
|
||||
- **测试要求**:端口冲突、DKIM 路径、Relay 凭据、策略边界、应用失败和服务重启测试。
|
||||
@@ -474,7 +474,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-003、CG-001
|
||||
- **设计映射**:第 14.1、24.1、24.2 章
|
||||
- **修改范围**:`server/models/User.go`、数据库迁移、用户服务和测试
|
||||
- **修改范围**:`backend/models/User.go`、数据库迁移、用户服务和测试
|
||||
- **实施步骤**:增加 `role`、`must_change_password`、`security_version`、密码时间字段;迁移现有 `is_admin`;保留兼容输出。
|
||||
- **安全要求**:无法唯一确定首个超级管理员时停止迁移;至少保留一个未禁用超级管理员。
|
||||
- **测试要求**:零管理员、一个管理员、多个管理员、禁用管理员和重复迁移测试。
|
||||
@@ -488,7 +488,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-002、CG-023
|
||||
- **设计映射**:第 13.1~13.4 章
|
||||
- **修改范围**:新增 `server/services/access`、上下文和测试
|
||||
- **修改范围**:新增 `backend/services/access`、上下文和测试
|
||||
- **实施步骤**:定义角色、能力、默认矩阵、资源引用和目标用户策略;将插件启停与插件重启拆分为 `plugin.control` 和 `plugin.restart`;在请求上下文中装载后端能力。
|
||||
- **安全要求**:默认拒绝;不得通过角色字符串排序;目标资源和目标角色必须同时检查。
|
||||
- **测试要求**:三角色能力矩阵、管理员仅重启明确授权插件、未知角色、角色变化、禁用用户和目标用户边界测试。
|
||||
@@ -502,7 +502,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-024、CG-017
|
||||
- **设计映射**:第 13.3~13.5、23 章
|
||||
- **修改范围**:`server/controllers/plugin.go`、`user.go`、`settings.go`、`group.go`、`rule.go` 和路由测试
|
||||
- **修改范围**:`backend/controllers/plugin.go`、`user.go`、`settings.go`、`group.go`、`rule.go` 和路由测试
|
||||
- **实施步骤**:逐接口替换布尔管理员判断;增加对象级策略;分离角色变更 DTO;保护最后一个超级管理员;角色变更时按照变更后的目标角色检查有效恢复码;启用已完成授权接入的本人、跨用户和批量插件设置路由。
|
||||
- **安全要求**:直接调用隐藏接口仍拒绝;角色变更和高风险配置要求二次确认;目标角色为管理员或普通用户时必须已经配置有效恢复码,否则返回稳定错误码 `RECOVERY_CODE_REQUIRED`;目标角色为超级管理员时明确豁免恢复码检查;管理员不能管理管理员;普通用户不能访问含目标用户 ID 的插件接口;批量插件接口仅限超级管理员。
|
||||
- **测试要求**:接口级权限矩阵、IDOR、批量操作、管理员和普通用户恢复码前置条件、超级管理员豁免、稳定错误码、并发降级最后超级管理员和旧 Session 测试。
|
||||
@@ -516,7 +516,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-003、CG-023
|
||||
- **设计映射**:第 14.2、15.1、15.2 章
|
||||
- **修改范围**:`server/models/user_email.go`、数据库迁移、`server/services/auth/identifier.go`、测试
|
||||
- **修改范围**:`backend/models/user_email.go`、数据库迁移、`backend/services/auth/identifier.go`、测试
|
||||
- **实施步骤**:增加邮箱规范化字段和唯一索引;实现用户名或完整邮箱精确解析;移除截断域名逻辑。
|
||||
- **安全要求**:冲突绑定必须停止迁移或拒绝登录;邮箱不存在时保持防枚举和耗时一致。
|
||||
- **测试要求**:用户名、完整邮箱、域名大小写、本地部分、重复邮箱、未验证邮箱、多个 `@` 和超长输入测试。
|
||||
@@ -530,7 +530,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-026、CG-024
|
||||
- **设计映射**:第 15.3 章
|
||||
- **修改范围**:`server/services/auth`、SMTP、IMAP、POP3 登录处理和测试
|
||||
- **修改范围**:`backend/services/auth`、SMTP、IMAP、POP3 登录处理和测试
|
||||
- **实施步骤**:实现统一 `Authenticator`;接入四个通道;复用标识解析、密码验证、用户状态和审计。
|
||||
- **安全要求**:统一虚假哈希;账户、IP、组合限流;协议层不得复制密码校验或账号截断。
|
||||
- **测试要求**:同一用户通过两种标识在四通道登录;错误耗时、禁用用户、限流和协议差异测试。
|
||||
@@ -544,7 +544,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-027、CG-023
|
||||
- **设计映射**:第 15.1、15.4、15.5 章
|
||||
- **修改范围**:`server/controllers/login.go`、`server/session`、`fe/src/views/LoginView.vue`、Store 和测试
|
||||
- **修改范围**:`backend/controllers/login.go`、`backend/session`、`frontend/src/views/LoginView.vue`、Store 和测试
|
||||
- **实施步骤**:将请求字段迁移到 `identifier`;返回角色、能力和安全引导状态;Session 绑定版本;支持临时密码限制。
|
||||
- **安全要求**:`account` 兼容字段有冲突时拒绝;Session 固定防护、CSRF 和安全 Cookie 保持有效。
|
||||
- **测试要求**:旧新 DTO 冲突、登录成功响应、角色变化、密码变化、临时密码和 Session 撤销测试。
|
||||
@@ -558,7 +558,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-027
|
||||
- **设计映射**:第 16.1、16.2 章
|
||||
- **修改范围**:`server/services/auth/password.go`、`server/utils/password`、安全设置接口和测试
|
||||
- **修改范围**:`backend/services/auth/password.go`、`backend/utils/password`、安全设置接口和测试
|
||||
- **实施步骤**:统一新密码策略;封装 Argon2id;实现 `NeedsRehash`;管理员和普通用户修改密码时递增 Session 版本,撤销包括当前会话在内的全部旧 Session,成功响应后清除当前 Session Cookie,并要求使用新密码重新登录;Web 接口显式拒绝超级管理员。
|
||||
- **安全要求**:不随机选择算法;不保留旧算法无限回退;密码不出现在日志、URL 和审计;超级管理员不能通过任何 Web 路由修改或恢复密码。
|
||||
- **测试要求**:弱密码、同密码、超长输入、参数升级、并发修改、事务失败和超级管理员直接调用 Web 改密接口测试。
|
||||
@@ -586,7 +586,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-029、CG-023、AD-006~AD-020、AD-062、AD-063
|
||||
- **设计映射**:第 16.4 章
|
||||
- **修改范围**:`server/cmd/smail-admin/main.go`、专用重置通道服务、systemd unit、Windows 服务适配、Windows Named Pipe、Unix Domain Socket 和测试
|
||||
- **修改范围**:`backend/cmd/smail-admin/main.go`、专用重置通道服务、systemd unit、Windows 服务适配、Windows Named Pipe、Unix Domain Socket 和测试
|
||||
- **实施步骤**:随主程序安装独立 `smail-admin`;Linux 唯一正式可写入口固定为显式 `systemctl start smail-admin`,`systemctl stop smail-admin` 仅用于终止正在运行的短时事务;禁止开机自启动、自动重启、reload、restart、try-restart 和依赖拉起进入重置流程;由短时一次性 systemd 服务执行一个受控重置事务后退出;使用 `systemd-ask-password` 或等效受保护本机密码代理获取不回显的新密码;经 Unix Domain Socket 调用主程序统一密码服务;Windows 使用等价服务启动语义和 Named Pipe;使用 `closed -> open -> consumed` 或 `closed -> open -> expired` 状态机;成功、超时、失败达到阈值或管理进程退出后自动关闭通道。
|
||||
- **安全要求**:不监听公网、局域网或 localhost TCP;不注册普通 HTTP Router;不能由 Web、公共 API、环境变量、普通配置、插件、开发模式、开机目标、服务依赖或非 start systemd Job 开启;没有安全密码代理时拒绝执行;密码不得通过命令参数、标准输入、标准输出、环境变量、文件、服务名或日志传递;Unix Socket 权限和对端身份必须校验,Windows Named Pipe 仅允许受信系统身份;失败不得降级为普通 Web 重置流程。`status`、`show`、`is-active` 等只读命令只允许观察状态,不创建重置会话。
|
||||
- **测试要求**:在 Windows、Ubuntu 22.04 和 Ubuntu 24.04 验证正式服务入口和平台适配器;执行无开机自启动、start、stop、restart、try-restart、reload、依赖拉起、只读状态查询、TCP/HTTP 暴露扫描、systemd 安全密码代理缺失、Named Pipe 和 Unix Socket 权限与对端身份、维护会话重放、跨进程复用、通道超时、管理进程退出、失败阈值、参数/标准输入输出/环境变量/文件/日志泄漏、普通 Web API 尝试开启通道、开发模式自动开放、Session 与安全版本撤销测试。
|
||||
@@ -617,7 +617,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-003、CG-023
|
||||
- **设计映射**:第 14.3、17~20、24 章
|
||||
- **修改范围**:数据库迁移、`server/models`、`server/services/auth` 仓储和测试
|
||||
- **修改范围**:数据库迁移、`backend/models`、`backend/services/auth` 仓储和测试
|
||||
- **实施步骤**:创建密保、恢复码、WebAuthn、密码重置和安全审计通用数据表;建立唯一索引、外键、版本字段和过期查询;为 AD-022~AD-025、AD-035~AD-037 提供三数据库迁移基础,但外部邮箱和验证码非敏感运营数据的详细字段由对应 AD 任务实现。
|
||||
- **安全要求**:答案、恢复码和票据只保存不可逆值;WebAuthn credential ID 全局唯一;不得创建可持久化验证码、验证码校验值、内存验证码任务或进程临时密钥的字段和表。
|
||||
- **测试要求**:三种数据库建表、重复迁移、约束冲突、时间字段、禁止验证码秘密字段和事务回退测试。
|
||||
@@ -631,7 +631,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-032、CG-029
|
||||
- **设计映射**:第 17 章
|
||||
- **修改范围**:`server/services/auth/security_question.go`、Controller、前端接口和测试
|
||||
- **修改范围**:`backend/services/auth/security_question.go`、Controller、前端接口和测试
|
||||
- **实施步骤**:实现问题设置、答案固定规范化、Argon2id 哈希、独立随机盐、算法与规范化版本、修改验证、限流和恢复阶段验证;规范化固定为去除首尾空格、Unicode 规范化、英文转小写、合并连续空白,并保留标点和特殊字符。
|
||||
- **安全要求**:答案不可逆保存;密保问答不能单独重置密码;不使用模糊匹配、随机算法或可逆加密;问题和答案不得写日志。
|
||||
- **测试要求**:大小写混淆、Unicode 等价、首尾和连续空白、标点保留、版本升级、错误答案、防枚举、限流、修改撤销恢复会话和单因素绕过测试。
|
||||
@@ -645,7 +645,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-032、CG-029
|
||||
- **设计映射**:第 18.1~18.4 章
|
||||
- **修改范围**:`server/services/auth/recovery_code.go`、安全接口、前端状态和测试
|
||||
- **修改范围**:`backend/services/auth/recovery_code.go`、安全接口、前端状态和测试
|
||||
- **实施步骤**:使用安全随机源生成一组代码;保存不可逆校验值;一次返回明文;实现状态和剩余数量接口。
|
||||
- **安全要求**:要求近期重新认证;响应 `no-store`;明文不进入数据库、日志、审计、Store 持久化或 URL。
|
||||
- **测试要求**:随机源失败、事务失败、响应缓存头、重复查看、重新生成和前端存储检查。
|
||||
@@ -673,7 +673,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-032、CG-028
|
||||
- **设计映射**:第 19.1~19.3、19.5 章
|
||||
- **修改范围**:`server/services/auth/webauthn.go`、Controller、前端组件和测试
|
||||
- **修改范围**:`backend/services/auth/webauthn.go`、Controller、前端组件和测试
|
||||
- **实施步骤**:生成注册 Challenge;绑定用户、Session、RP ID、Origin 和有效期;验证注册响应;实现列表、重命名和撤销。
|
||||
- **安全要求**:Challenge 一次性;credential ID 全局唯一;校验用户验证标志;生产只允许配置的 HTTPS Origin。
|
||||
- **测试要求**:Challenge 重放、跨用户绑定、错误 Origin、错误 RP ID、过期、取消、签名数据篡改和撤销测试。
|
||||
@@ -701,7 +701,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-033、CG-035、CG-037、CG-029
|
||||
- **设计映射**:第 20 章
|
||||
- **修改范围**:`server/services/auth/recovery.go`、恢复 Controller、路由和测试
|
||||
- **修改范围**:`backend/services/auth/recovery.go`、恢复 Controller、路由和测试
|
||||
- **实施步骤**:实现统一恢复状态机和路径 A:开始、密保问题验证、离线恢复码或 WebAuthn 验证、票据签发、新密码设置、完成和过期;建立路径 B 的正式状态、接口和事务边界,供 AD-043~AD-047 完整实现外部安全邮箱验证码恢复;任一路径成功后撤销全部旧会话和未完成恢复票据;功能启用且配置有效域名或 IP 时注册固定 `/Reset` 页面入口,并由同一后端开关保护全部恢复 API。
|
||||
- **安全要求**:仅管理员和普通用户使用;路径 A 必须为密保问答加恢复码或 WebAuthn;路径 B 必须完成验证码服务、SMTP 投递、外部邮箱验证、限流、审计和清理并通过安全验收后才能启用,配置错误或投递失败时安全拒绝且不得降级绕过;票据高熵、短期、一次性且只存哈希。
|
||||
- **测试要求**:路径 A 全部合法流程、阶段跳过、阶段回退、票据重放、并发流程、防枚举和超级管理员禁用;路径 B 覆盖默认关闭、完整启用、配置错误、投递失败、验证码错误或过期、跨用途重放和并发消费,关闭或失败时不能创建有效重置票据。
|
||||
@@ -748,7 +748,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-028、CG-025
|
||||
- **设计映射**:第 25.2、25.3 章
|
||||
- **修改范围**:`fe/src/stores`、`fe/src/router`、`fe/src/utils/axios.js`、测试
|
||||
- **修改范围**:`frontend/src/stores`、`frontend/src/router`、`frontend/src/utils/axios.js`、测试
|
||||
- **实施步骤**:新增认证 Store;保存角色、能力和安全状态;实现路由守卫和操作级能力组件;统一 401、403 和二次认证处理。
|
||||
- **安全要求**:前端守卫不替代后端;不持久化 Secret、Challenge 和恢复票据;不在控制台打印敏感请求。
|
||||
- **测试要求**:三角色路由、直接输入 URL、角色变化、Session 过期、403 和 Store 清理测试。
|
||||
@@ -762,7 +762,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-013、CG-040
|
||||
- **设计映射**:第 11.7、11.8、23.2、25.1、25.2、26 章
|
||||
- **修改范围**:`fe/src/components`、配置 Store、路由和测试
|
||||
- **修改范围**:`frontend/src/components`、配置 Store、路由和测试
|
||||
- **实施步骤**:实现配置状态、基础、SMTP、邮箱策略、SSL、数据库名称迁移和超级管理员配置审计页面;显示 generation、验证结果、应用方式和待重启状态;实现回滚预览、脱敏 CSV/JSON 导出和“重启 Smail”按钮。
|
||||
- **安全要求**:Secret 只显示“已配置”;差异中的 Secret 只显示已设置、已修改、已清除;保存和回滚使用明确操作及近期重新认证;冲突时不得自动覆盖;迁移页不接收主机、账户、密码或 DSN;重启页不接收命令和服务名。
|
||||
- **测试要求**:加载、编辑、验证、代次冲突、连接测试、数据库迁移阶段、应用失败、审计筛选和详情、导出审计、回滚预览票据、受控重启、权限拒绝和响应脱敏测试。
|
||||
@@ -776,7 +776,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-017、CG-021、CG-040
|
||||
- **设计映射**:第 21、23.3、25.5 章
|
||||
- **修改范围**:`fe/src/components/PluginSettings.vue`、`UserManagement.vue`、Store 和测试
|
||||
- **修改范围**:`frontend/src/components/PluginSettings.vue`、`UserManagement.vue`、Store 和测试
|
||||
- **实施步骤**:按能力展示全局、普通用户和自己的设置;使用 Schema 驱动中文表单;显示插件健康状态和脱敏测试结果。
|
||||
- **安全要求**:不渲染插件任意 HTML;不信任前端 `userId`;Secret 不回填;测试请求限制目标。
|
||||
- **测试要求**:三角色页面矩阵、篡改用户 ID、隐藏按钮直调、Secret 浏览器存储和插件失败测试。
|
||||
@@ -790,13 +790,13 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-029、CG-036、CG-040、AD-054
|
||||
- **设计映射**:第 25.1、25.4 章
|
||||
- **修改范围**:`fe/src/components/SecuritySettings.vue`、新增安全子组件和测试
|
||||
- **修改范围**:`frontend/src/components/SecuritySettings.vue`、新增安全子组件和测试
|
||||
- **实施步骤**:拆分登录密码、密保问题、离线恢复码、WebAuthn 安全密钥、外部安全邮箱管理和登录会话;实现外部邮箱绑定、验证、更换、删除、脱敏状态和近期重新认证交互;超级管理员不显示恢复码管理入口和恢复码首次提示,密码区域只显示“必须通过部署端重置服务开启专用通道”的中文说明,不提供或调用任何 Web 改密和密码恢复入口;验证码功能关闭时展示受控停用状态,但页面和后端功能仍须完成本轮实现与验收。
|
||||
- **安全要求**:敏感操作前重新认证;恢复码明文不持久化;安全密钥操作不允许管理员代办。
|
||||
- **测试要求**:每个子页面的成功、取消、过期、权限、Session 撤销和错误提示测试;覆盖外部邮箱绑定、验证、更换、删除、发送和脱敏状态;验证验证码默认关闭时不存在可用发送或恢复入口,启用并配置有效时完整流程可用。
|
||||
- **验收标准**:管理员和普通用户可管理自己的密码、密保、恢复码、WebAuthn 和会话;超级管理员只能在 Web 管理自己的 WebAuthn 与会话,页面只展示部署端专用通道说明,不存在可调用的 Web 改密、恢复码或密码恢复入口;所有角色都不能访问其他用户安全凭据。
|
||||
- **回退方式**:保留修改密码和退出功能,暂时关闭未完成子页面。
|
||||
- **验收证据**:账户恢复页面和登录忘记密码弹窗已统一为单页面验证方式切换交互,详见 `fe/src/views/RecoveryView.vue` 和 `fe/src/views/LoginView.vue`;2026-08-27 `yarn.cmd build` 通过。账户安全完整功能和真实浏览器验收仍待后续任务。
|
||||
- **验收证据**:账户恢复页面和登录忘记密码弹窗已统一为单页面验证方式切换交互,详见 `frontend/src/views/RecoveryView.vue` 和 `frontend/src/views/LoginView.vue`;2026-08-27 `yarn.cmd build` 通过。账户安全完整功能和真实浏览器验收仍待后续任务。
|
||||
|
||||
### CG-044 实现登录后离线恢复码首次提示
|
||||
|
||||
@@ -845,7 +845,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-010、CG-023
|
||||
- **设计映射**:第 12 章
|
||||
- **修改范围**:`server/services/setup`、`server/main.go`、HTTP 和邮件服务启动代码、测试
|
||||
- **修改范围**:`backend/services/setup`、`backend/main.go`、HTTP 和邮件服务启动代码、测试
|
||||
- **实施步骤**:实现 `new`、`bootstrap`、`ready`、`degraded`;建立合法转换;按状态启动受限服务;增加三数据库、主域名、SSL 和 HTTPS 切换完整预检。
|
||||
- **安全要求**:无有效超级管理员、主域名或有效 SSL 不能进入 `ready`;配置损坏不得启动完整邮件服务;SSL 成功前 HTTP 只允许受控初始化范围,成功后生产管理后台强制 HTTPS;降级状态不回退公网明文管理。
|
||||
- **测试要求**:所有状态转换、非法回退、服务矩阵、配置损坏、三种数据库失败、主域名和 SSL 未完成、HTTPS 切换及恢复测试。
|
||||
@@ -859,7 +859,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-046、CG-029
|
||||
- **设计映射**:第 6.2、11.6、12.3 章
|
||||
- **修改范围**:`server/listen/http_server/setup_security.go`、Setup Controller、数据库初始化服务、SSL 初始化服务、前端初始化页和测试
|
||||
- **修改范围**:`backend/listen/http_server/setup_security.go`、Setup Controller、数据库初始化服务、SSL 初始化服务、前端初始化页和测试
|
||||
- **实施步骤**:使用短期初始化授权并绑定来源和有效期;MySQL/PostgreSQL 只收集主机、用户名、密码及可选高级端口,SQLite 只选择类型;后端自动创建数据库和表结构;创建首个超级管理员;继续完成主域名和 SSL 双模式配置;全部成功后立即撤销匿名初始化能力。
|
||||
- **安全要求**:初始化令牌不进入 URL 和日志;请求不接受数据库名称、表名、DSN、SQL、SQLite 路径或 SSL 服务器绝对路径;重复创建必须拒绝;只允许受控来源访问未初始化接口。
|
||||
- **测试要求**:三数据库自动创建、权限不足、部分建库失败、令牌过期、重放、跨来源、并发创建、主域名和 SSL 校验、初始化完成后访问和请求体超限测试。
|
||||
@@ -873,7 +873,7 @@
|
||||
- **优先级**:P1
|
||||
- **依赖**:CG-013、CG-025、CG-038、CG-018
|
||||
- **设计映射**:第 23、27 章
|
||||
- **修改范围**:`server/listen/http_server`、Controller、前端 API 封装和测试
|
||||
- **修改范围**:`backend/listen/http_server`、Controller、前端 API 封装和测试
|
||||
- **实施步骤**:注册 `/api/v1`;拆分本人、跨用户、批量插件设置路由;增加配置审计筛选、详情和脱敏导出,配置回滚预览与执行,数据库名称迁移预览、创建和状态查询以及受控重启预览与执行;为 AD-048~AD-051 提供正式外部安全邮箱、验证码、登录二次验证和密码恢复路由的通用守卫与注册基础;为旧登录字段和只读响应提供短期兼容;对旧写接口设置停用计划和使用统计。
|
||||
- **安全要求**:兼容层不能跳过新授权、严格解析、CSRF、Secret 处理或审计;冲突字段拒绝;数据库迁移接口只接收目标名称;重启接口不接受任意命令或服务名;验证码相关路由在完整实现和安全验收前保持关闭,但不得以关闭为由省略实现,也不得在校验成功前创建恢复票据。
|
||||
- **测试要求**:新旧路由对照、本人接口不接受用户 ID、跨用户权限矩阵、批量和回滚预览票据、审计导出权限、数据库迁移参数白名单、固定服务重启、验证码功能关闭与受控启用、错误码、方法限制、请求大小和废弃告警测试。
|
||||
@@ -956,7 +956,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-052
|
||||
- **设计映射**:第 6~11、28.1 章
|
||||
- **修改范围**:`server/config`、`server/utils/credential`、配置 API 和审计
|
||||
- **修改范围**:`backend/config`、`backend/utils/credential`、配置 API 和审计
|
||||
- **实施步骤**:审查唯一磁盘入口、结构化三数据库配置、严格 JSON、路径安全、代次、事务、7 天/30 天/4 份备份、回滚、数据库名称迁移、完整配置审计、受控重启、连接测试和 Secret 生命周期。
|
||||
- **安全要求**:重点验证旧算法回退、明文落盘、日志泄露、SSRF、符号链接、审计删除和泄密、迁移越界、重启命令注入及崩溃混合代次漏洞不存在。
|
||||
- **测试要求**:使用恶意夹具和故障注入复现每个风险点,检查 API、文件、日志和内存暴露边界。
|
||||
@@ -984,7 +984,7 @@
|
||||
- **优先级**:P0
|
||||
- **依赖**:CG-052
|
||||
- **设计映射**:第 21~22、28.3 章
|
||||
- **修改范围**:`plugins`、`server/services/plugin`、`server/hooks` 和插件 API
|
||||
- **修改范围**:`plugins`、`backend/services/plugin`、`backend/hooks` 和插件 API
|
||||
- **实施步骤**:逐个审查三个插件源码;检查旧 PMail 依赖、磁盘读取、数据库 Secret、裁剪 RPC、强制网络白名单、Web Push、用户映射、Hook 生命周期和异常隔离。
|
||||
- **安全要求**:插件不得读取主配置、DSN、主数据库、其他插件数据或主加密密钥;不得通过 HTML 设置页影响主页面;网络不能跳过主机、端口和协议白名单;管理员不得启停插件或重启未授权实例;批量用户配置只允许超级管理员按已确认预览执行。
|
||||
- **测试要求**:恶意插件、配置和 Secret 泄露、SSRF、DNS 重绑定、跨白名单重定向、私网访问、Web Push 越权、超时、超限、崩溃、重复 Hook、越权重启、本人和跨用户设置混用、批量目标篡改、预览票据重放、越权用户设置和沙箱不可用测试。
|
||||
@@ -1097,7 +1097,7 @@ CG-053~CG-056 → AD-066 → CG-057
|
||||
- **日期**:2026-08-27
|
||||
- **执行任务**:CG-002 建立敏感字段和安全能力清单
|
||||
- **开始状态**:未开始
|
||||
- **修改文件**:`server/config/sensitive.go`、`server/config/sensitive_test.go`、`server/services/access/authorize.go`、`server/services/access/capability.go`、`server/services/access/catalog.go`、`server/services/access/access_test.go`、`server/services/access/matrix_test.go`、`server/controllers/config.go`、`server/controllers/config_error_test.go`、`server/listen/http_server/http_server.go`、`server/listen/http_server/config_route_test.go`
|
||||
- **修改文件**:`backend/config/sensitive.go`、`backend/config/sensitive_test.go`、`backend/services/access/authorize.go`、`backend/services/access/capability.go`、`backend/services/access/catalog.go`、`backend/services/access/access_test.go`、`backend/services/access/matrix_test.go`、`backend/controllers/config.go`、`backend/controllers/config_error_test.go`、`backend/listen/http_server/http_server.go`、`backend/listen/http_server/config_route_test.go`
|
||||
- **实施摘要**:扩展敏感字段目录,明确四类持久化策略和公共脱敏能力;补充配置、审计和回滚 API 的能力映射;恢复配置分区 `PUT` 路由;统一配置授权错误的稳定错误码并避免回显内部错误文本;补充配置路由、能力目录、角色恢复码和敏感响应测试。
|
||||
- **测试命令**:`go test ./services/access ./config ./controllers ./listen/http_server`、`go test ./...`、`go vet ./...`、`git diff --check`
|
||||
- **测试结果**:定向测试和全量测试通过;`go vet ./...` 通过;`git diff --check` 未发现空白错误。
|
||||
@@ -1114,7 +1114,7 @@ CG-053~CG-056 → AD-066 → CG-057
|
||||
- **日期**:2026-08-27
|
||||
- **执行任务**:CG-003 引入显式数据库迁移框架
|
||||
- **开始状态**:未开始
|
||||
- **修改文件**:`server/db/migration/dialect.go`、`server/db/migration/migration.go`、`server/db/migration/registry.go`、`server/db/migration/runner.go`、`server/db/migration/schema.go`、相关测试文件、`server/db/init.go`、`server/db/init_migration_test.go`
|
||||
- **修改文件**:`backend/db/migration/dialect.go`、`backend/db/migration/migration.go`、`backend/db/migration/registry.go`、`backend/db/migration/runner.go`、`backend/db/migration/schema.go`、相关测试文件、`backend/db/init.go`、`backend/db/init_migration_test.go`
|
||||
- **实施摘要**:建立显式迁移注册表和连续版本校验;为 SQLite、MySQL、PostgreSQL 提供方言 SQL 或自定义迁移;记录迁移版本、名称、校验和、执行时间和耗时;增加数据库级并发锁、事务执行、失败回滚、重复执行跳过、未知版本拒绝和当前版本查询;生产环境不再默认依赖无版本 `Sync2`,兼容模式仅在显式配置并满足开发或测试条件时启用;补充默认迁移注册表的连续性和三数据库方言完整性测试。
|
||||
- **测试命令**:`go test ./db/migration ./db`、`go test ./db/migration -run 'Test(Default|SQLite|Normalize|Runner|Unknown|Legacy|Custom)' -count=1`、`go test ./...`、`go vet ./...`、`git diff --check`
|
||||
- **测试结果**:迁移专项测试和 `db` 测试通过;新增默认迁移连续性、名称和三数据库方言覆盖测试通过。MySQL/PostgreSQL 集成测试通过环境变量启用,当前环境未配置 `SMAIL_TEST_MYSQL_DSN` 和 `SMAIL_TEST_POSTGRES_DSN`,因此按测试设计跳过;不能据此宣称 MySQL/PostgreSQL 真实环境已验收。
|
||||
@@ -1150,7 +1150,7 @@ CG-053~CG-056 → AD-066 → CG-057
|
||||
| 2026-08-28 | CG-009 | 未开始 | 已完成,等待复审 | 使用 `atomic.Pointer` 和 CAS 发布不可变运行时快照;补齐深拷贝、旧代次拒绝、并发读取/发布和 ConfigManager 返回值隔离测试;配置包竞态测试通过;真实生产进程切换和跨平台部署仍待验收 |
|
||||
| 2026-08-28 | CG-009 | 已完成,等待复审 | 复审通过 | 独立复审确认 `atomic.Pointer` CAS 发布、深复制边界、旧代次冲突保护、返回值隔离和配置包竞态测试;`go test ./... -count=1`、`go vet ./...`、`git diff --check` 通过;仅本机自动化复审通过,真实生产进程切换、Ubuntu/Windows 部署及长期观测仍未覆盖 |
|
||||
| 2026-08-28 | CG-008 | 已完成,等待复审 | 复审通过 | 复核插件 Secret 的 keep 保留、replace 加密、clear 确认、非法路径和直接密文拒绝逻辑;配置、控制器全量测试和 `go vet` 均通过,临时文件定向清理验证通过;真实数据库、SMTP、插件沙箱、Ubuntu/Windows 和生产环境边界继续保留为未验收项 |
|
||||
| 2026-08-28 | CG-008 | 未开始 | 已完成,等待复审 | 完成统一 SecretChange 与 CredentialVault 适配;数据库、SMTP Relay 和插件 Secret 使用统一加密、版本、脱敏和更新语义;补齐插件 Secret 的 keep/replace/clear、非法路径与公共响应脱敏测试;Makefile 增加仅清理 `server/.codex-smail-*` 的测试收尾逻辑;真实数据库、SMTP、插件沙箱、Ubuntu/Windows 和生产环境仍待集成验收 |
|
||||
| 2026-08-28 | CG-008 | 未开始 | 已完成,等待复审 | 完成统一 SecretChange 与 CredentialVault 适配;数据库、SMTP Relay 和插件 Secret 使用统一加密、版本、脱敏和更新语义;补齐插件 Secret 的 keep/replace/clear、非法路径与公共响应脱敏测试;Makefile 增加仅清理 `backend/.codex-smail-*` 的测试收尾逻辑;真实数据库、SMTP、插件沙箱、Ubuntu/Windows 和生产环境仍待集成验收 |
|
||||
| 2026-08-27 | CG-005 | 未开始 | 已完成,等待复审 | 完成配置模型、三数据库条件字段、默认端口、SQLite `localRef` 约束和固定分区映射测试;自动化验证通过,真实数据库集成、跨平台部署和启动流程仍待验收 |
|
||||
| 2026-08-27 | CG-002 | 未开始 | 已完成,等待复审 | 完成敏感字段目录、持久化策略、管理 API 能力映射、配置 PUT 路由和授权负向测试;自动化检查通过,真实平台和生产观测仍待验收 |
|
||||
| 2026-08-27 | CG-003 | 未开始 | 已完成,等待复审 | 完成显式迁移框架、版本和校验和校验、三数据库方言定义、数据库锁、事务回滚和生产 `Sync2` 兼容边界;SQLite 自动化测试通过,MySQL/PostgreSQL 因未配置 DSN 未执行真实集成验收 |
|
||||
@@ -1205,7 +1205,7 @@ CG-053~CG-056 → AD-066 → CG-057
|
||||
|
||||
- **本轮状态**:`[✓] 复审通过`
|
||||
- **涉及任务**:CG-016、CG-017、CG-018、CG-019、CG-020、CG-021。
|
||||
- **修改文件**:`server/plugins/catalog/catalog.go`、`server/plugins/catalog/catalog_test.go`、`server/hooks/framework/framework.go`、`server/hooks/base.go`、`server/hooks/base_test.go`、`server/hooks/spam_block/`、`server/hooks/wechat_push/`、`plugins/pmail_telegram_push/hook/`。
|
||||
- **修改文件**:`backend/plugins/catalog/catalog.go`、`backend/plugins/catalog/catalog_test.go`、`backend/hooks/framework/framework.go`、`backend/hooks/base.go`、`backend/hooks/base_test.go`、`backend/hooks/spam_block/`、`backend/hooks/wechat_push/`、`plugins/pmail_telegram_push/hook/`。
|
||||
- **实施摘要**:补齐插件目录中的逻辑 ID、可执行文件、权限能力、握手能力和设置字段声明;插件启动握手严格校验 ID、协议版本、能力集合和设置字段集合;运行时配置增加非零配置代次,主程序只向已启用且能力匹配的插件下发专属配置;插件继续只从受控 Secret 服务取得自身密钥,并拒绝旧密钥字段、未知能力、未知设置和未授权网络目标。
|
||||
- **测试命令**:`go test ./... -count=1`(`server`)、`go test ./... -count=1`(`plugins/pmail_telegram_push`)、`go test -race ./hooks/... ./plugins/catalog ./services/plugin -count=1`(`server`)、`go test -race ./hook -count=1`(`plugins/pmail_telegram_push`)、`go vet ./...`、`git diff --check`。
|
||||
- **当前测试结果**:本轮 `server` 全量测试、Telegram 插件全量测试、服务端 `go vet ./...`、服务端插件配置链路竞态测试和 Telegram 插件竞态测试均通过;目录声明专项测试通过;`git diff --check` 通过。
|
||||
@@ -1226,7 +1226,7 @@ CG-053~CG-056 → AD-066 → CG-057
|
||||
|
||||
- **本轮状态**:`[x] 已完成,等待复审`
|
||||
- **执行任务**:继续实施 CG-013,补齐配置审计详情与正式导出、受控重启预览、数据库名称迁移安全基础链路及定向测试。
|
||||
- **修改文件**:`server/config/audit_query.go`、`server/config/audit_export.go`、`server/config/audit_query_test.go`、`server/config/audit_store.go`、`server/controllers/config_audit.go`、`server/controllers/config_audit_query_test.go`、`server/controllers/database_migration.go`、`server/controllers/restart.go`、`server/listen/http_server/http_server.go`、`server/listen/http_server/api_v1_compat.go`、`server/listen/http_server/api_v1_compat_test.go`、`server/services/access/catalog.go`、`server/services/dbmigration/`、`server/services/restart/`。
|
||||
- **修改文件**:`backend/config/audit_query.go`、`backend/config/audit_export.go`、`backend/config/audit_query_test.go`、`backend/config/audit_store.go`、`backend/controllers/config_audit.go`、`backend/controllers/config_audit_query_test.go`、`backend/controllers/database_migration.go`、`backend/controllers/restart.go`、`backend/listen/http_server/http_server.go`、`backend/listen/http_server/api_v1_compat.go`、`backend/listen/http_server/api_v1_compat_test.go`、`backend/services/access/catalog.go`、`backend/services/dbmigration/`、`backend/services/restart/`。
|
||||
- **实施摘要**:配置审计事件支持稳定 ID、详情查询和正式 JSON/CSV 导出;导出响应设置禁止缓存并保留敏感字段脱敏边界;受控重启预览只返回固定 Smail 目标,不接受服务名、命令、脚本或参数;数据库迁移仅允许同类型、同服务器、同端口、同账户下的数据库名称或 SQLite 本地引用变更,采用短期一次性预览票据和按迁移 ID 隔离的状态机,失败时保留旧配置。
|
||||
- **定向测试**:`go test ./services/dbmigration -count=1`、`go test -race ./services/dbmigration -count=1`、`go test ./config -count=1`、`go test ./controllers ./services/restart ./listen/http_server -count=1` 均通过。
|
||||
- **安全检查**:修复迁移状态读取的并发访问边界;拒绝状态倒退;票据只保存哈希且执行后立即失效;审计详情和导出不返回密码、密钥、票据或底层错误;新路由已纳入能力目录和方法限制测试。
|
||||
@@ -1251,7 +1251,7 @@ CG-053~CG-056 → AD-066 → CG-057
|
||||
- **本轮状态**:`[x] 已完成,等待复审`
|
||||
- **执行任务**:继续实施配置系统回滚票据的并发消费、临时失败重试和稳定错误映射。
|
||||
- **开始状态**:配置回滚票据已具备操作者绑定和成功后失效能力,但临时失败会提前消耗票据,并发执行状态缺少明确错误边界。
|
||||
- **修改文件**:`server/config/manager.go`、`server/config/manager_v2.go`、`server/config/manager_v2_test.go`、`server/controllers/config_error.go`、`server/controllers/config_error_test.go`。
|
||||
- **修改文件**:`backend/config/manager.go`、`backend/config/manager_v2.go`、`backend/config/manager_v2_test.go`、`backend/controllers/config_error.go`、`backend/controllers/config_error_test.go`。
|
||||
- **实施摘要**:增加票据 `InFlight` 状态;在回滚执行前原子标记执行中,避免并发重复消费;对上下文取消和运行时快照暂不可用保留票据并允许在有效期内重试;通过已应用标志区分审计失败与未提交失败;新增 `CONFIG_ROLLBACK_IN_PROGRESS` 中文错误响应。
|
||||
- **测试命令**:`go test ./config ./controllers -run 'Test(ConfigManagerRollbackTicket|ConfigErrorDetailsMapsRollbackInProgress)' -count=1`、`go test ./... -count=1 -timeout 30m`、`go vet ./...`、`git diff --check`。
|
||||
- **测试结果**:配置管理器回滚票据专项测试通过;服务端全量测试通过;`go vet ./...` 和差异检查通过;前端 ESLint、生产构建已在上一轮复核通过。
|
||||
@@ -1293,14 +1293,14 @@ CG-053~CG-056 → AD-066 → CG-057
|
||||
|
||||
### 过时记录修正
|
||||
|
||||
旧记录中“真实数据库复制执行器尚未接入”的结论已经过时。当前已存在 `server/services/dbmigration/sql_executor.go`、`sqlite_executor.go`、运行时执行器工厂、复制校验、配置切换和相关测试。该修正只表示代码已接入,不表示真实 MySQL/PostgreSQL 数据复制、失败回滚和原子切换已经实机通过。
|
||||
旧记录中“真实数据库复制执行器尚未接入”的结论已经过时。当前已存在 `backend/services/dbmigration/sql_executor.go`、`sqlite_executor.go`、运行时执行器工厂、复制校验、配置切换和相关测试。该修正只表示代码已接入,不表示真实 MySQL/PostgreSQL 数据复制、失败回滚和原子切换已经实机通过。
|
||||
|
||||
### 当前实现证据
|
||||
|
||||
- 配置核心:`server/config/model.go`、`parser.go`、`validator.go`、`secret.go`、`snapshot.go`、`manager.go`、`manager_v2.go`、`transaction.go`、`storage.go`。
|
||||
- 备份、审计和迁移:`server/config/manager_backups.go`、`audit_store.go`、`audit_query.go`、`database_migration.go`。
|
||||
- 数据库复制与切换:`server/services/dbmigration/service.go`、`sql_executor.go`、`sqlite_executor.go`。
|
||||
- 受控重启和接口:`server/services/restart`、`server/controllers/config.go`、`config_audit.go`、`database_migration.go`、`restart.go`。
|
||||
- 配置核心:`backend/config/model.go`、`parser.go`、`validator.go`、`secret.go`、`snapshot.go`、`manager.go`、`manager_v2.go`、`transaction.go`、`storage.go`。
|
||||
- 备份、审计和迁移:`backend/config/manager_backups.go`、`audit_store.go`、`audit_query.go`、`database_migration.go`。
|
||||
- 数据库复制与切换:`backend/services/dbmigration/service.go`、`sql_executor.go`、`sqlite_executor.go`。
|
||||
- 受控重启和接口:`backend/services/restart`、`backend/controllers/config.go`、`config_audit.go`、`database_migration.go`、`restart.go`。
|
||||
- 自动化复核:服务端全量测试、竞态检测、`go vet`、前端 ESLint 和生产构建在本轮最终提交前统一执行并记录。
|
||||
|
||||
### 发布结论
|
||||
|
||||
+21
-21
@@ -10,7 +10,7 @@
|
||||
| 编写日期 | 2026-08-25 |
|
||||
| 上游文档 | `docs/配置系统重构需求文档.md` 0.7、`docs/超级管理员重置与邮箱验证码需求文档.md` 0.3 |
|
||||
| 适用项目 | Smail |
|
||||
| 适用目录 | `server`、`fe`、`plugins`、`docs` |
|
||||
| 适用目录 | `server`、`frontend`、`plugins`、`docs` |
|
||||
|
||||
本文档将已经确认的产品和安全需求转换为可实施的后端、前端、数据库、插件和测试设计。本文档不代表功能已经完成,所有实现状态以实施任务清单、代码审查和测试结果为准。
|
||||
|
||||
@@ -65,7 +65,7 @@
|
||||
|
||||
### 3.7 平滑迁移
|
||||
|
||||
优先保留现有 `server/config` 导入路径,在包内部逐步替换 `Config` 和 `Instance`。兼容字段只能用于短期响应兼容,不得继续作为授权或配置决策依据。
|
||||
优先保留现有 `backend/config` 导入路径,在包内部逐步替换 `Config` 和 `Instance`。兼容字段只能用于短期响应兼容,不得继续作为授权或配置决策依据。
|
||||
|
||||
---
|
||||
|
||||
@@ -76,14 +76,14 @@
|
||||
当前主要实现位于:
|
||||
|
||||
```text
|
||||
server/config/config.go
|
||||
server/config/storage.go
|
||||
server/services/auth/auth.go
|
||||
server/controllers/login.go
|
||||
server/controllers/plugin.go
|
||||
server/hooks/
|
||||
server/db/init.go
|
||||
server/models/User.go
|
||||
backend/config/config.go
|
||||
backend/config/storage.go
|
||||
backend/services/auth/auth.go
|
||||
backend/controllers/login.go
|
||||
backend/controllers/plugin.go
|
||||
backend/hooks/
|
||||
backend/db/init.go
|
||||
backend/models/User.go
|
||||
```
|
||||
|
||||
主要差距:
|
||||
@@ -104,7 +104,7 @@ server/models/User.go
|
||||
|
||||
1. 配置目录和文件类型检查;
|
||||
2. 配置文件原子写入;
|
||||
3. `server/utils/credential` 凭据加密能力;
|
||||
3. `backend/utils/credential` 凭据加密能力;
|
||||
4. Argon2id 密码哈希;
|
||||
5. 登录限流和虚假密码验证;
|
||||
6. Session 版本撤销;
|
||||
@@ -149,10 +149,10 @@ server/models/User.go
|
||||
|
||||
### 5.2 后端模块边界
|
||||
|
||||
建议在现有 `server/config` 包内平滑增加:
|
||||
建议在现有 `backend/config` 包内平滑增加:
|
||||
|
||||
```text
|
||||
server/config/
|
||||
backend/config/
|
||||
├── manager.go
|
||||
├── model.go
|
||||
├── root.go
|
||||
@@ -175,7 +175,7 @@ server/config/
|
||||
认证和授权建议增加:
|
||||
|
||||
```text
|
||||
server/services/auth/
|
||||
backend/services/auth/
|
||||
├── authenticator.go
|
||||
├── identifier.go
|
||||
├── password.go
|
||||
@@ -184,7 +184,7 @@ server/services/auth/
|
||||
├── security_question.go
|
||||
└── webauthn.go
|
||||
|
||||
server/services/access/
|
||||
backend/services/access/
|
||||
├── role.go
|
||||
├── capability.go
|
||||
├── authorizer.go
|
||||
@@ -194,7 +194,7 @@ server/services/access/
|
||||
插件管理建议增加:
|
||||
|
||||
```text
|
||||
server/services/plugin/
|
||||
backend/services/plugin/
|
||||
├── manager.go
|
||||
├── catalog.go
|
||||
├── config.go
|
||||
@@ -1899,7 +1899,7 @@ INDEX database_name_migration(status, created_at)
|
||||
|
||||
### 25.1 页面结构
|
||||
|
||||
在当前 `fe/src/components/HomeHeader.vue` 设置抽屉基础上,逐步拆分为路由或独立组件:
|
||||
在当前 `frontend/src/components/HomeHeader.vue` 设置抽屉基础上,逐步拆分为路由或独立组件:
|
||||
|
||||
```text
|
||||
系统设置
|
||||
@@ -1930,10 +1930,10 @@ INDEX database_name_migration(status, created_at)
|
||||
建议增加:
|
||||
|
||||
```text
|
||||
fe/src/stores/useAuthStore.js
|
||||
fe/src/stores/useConfigStore.js
|
||||
fe/src/stores/useSecurityStore.js
|
||||
fe/src/stores/usePluginStore.js
|
||||
frontend/src/stores/useAuthStore.js
|
||||
frontend/src/stores/useConfigStore.js
|
||||
frontend/src/stores/useSecurityStore.js
|
||||
frontend/src/stores/usePluginStore.js
|
||||
```
|
||||
|
||||
状态原则:
|
||||
|
||||
+5
-5
@@ -6,7 +6,7 @@
|
||||
- **工作目录**:`D:\Desktop\Smail`
|
||||
- **当前验证平台**:Windows 开发环境
|
||||
- **后端模块**:`server`
|
||||
- **前端模块**:`fe`
|
||||
- **前端模块**:`frontend`
|
||||
- **测试原则**:只使用临时目录、内存数据或测试数据库;不读取、不提交、不打印真实密码、私钥、数据库连接串、SMTP 凭据或配置主密钥。
|
||||
|
||||
本文件记录当前可重复执行的自动化基线,不代表 Ubuntu、Windows 生产服务、真实 SMTP、真实 MySQL、真实 PostgreSQL、多实例部署或最终发布验收已经完成。
|
||||
@@ -16,7 +16,7 @@
|
||||
在 PowerShell 中执行:
|
||||
|
||||
```powershell
|
||||
Set-Location D:\Desktop\Smail\server
|
||||
Set-Location D:\Desktop\Smail\backend
|
||||
go test ./... -count=1
|
||||
go vet ./...
|
||||
go test ./db/migration ./db -count=1
|
||||
@@ -37,7 +37,7 @@ go test ./db/migration -run 'Test(MySQL|Postgres)Integration' -count=1
|
||||
在 PowerShell 中执行:
|
||||
|
||||
```powershell
|
||||
Set-Location D:\Desktop\Smail\fe
|
||||
Set-Location D:\Desktop\Smail\frontend
|
||||
yarn.cmd build
|
||||
```
|
||||
|
||||
@@ -47,7 +47,7 @@ yarn.cmd build
|
||||
yarn.cmd eslint . --ext .vue,.js,.jsx,.cjs,.mjs --ignore-path .gitignore
|
||||
```
|
||||
|
||||
前端构建产生的 `fe/dist` 属于忽略目录,不应据此覆盖、提交或删除用户已有的配置、密钥和可执行文件。
|
||||
前端构建产生的 `frontend/dist` 属于忽略目录,不应据此覆盖、提交或删除用户已有的配置、密钥和可执行文件。
|
||||
|
||||
## 4. 测试分类
|
||||
|
||||
@@ -82,7 +82,7 @@ yarn.cmd eslint . --ext .vue,.js,.jsx,.cjs,.mjs --ignore-path .gitignore
|
||||
- 测试 DSN 只通过临时环境变量注入,文档只保留占位符。
|
||||
- 测试失败信息不应包含完整 SQL、密码、私钥、密文、恢复码、验证码或数据库连接串。
|
||||
- 迁移测试夹具使用临时 SQLite 文件和临时目录,不操作项目配置目录。
|
||||
- 真实的 `server/config/dkim/dkim.priv`、`server/config/ssl/private.key` 和已有可执行文件不属于测试输入,不得被测试覆盖、删除或提交。
|
||||
- 真实的 `backend/config/dkim/dkim.priv`、`backend/config/ssl/private.key` 和已有可执行文件不属于测试输入,不得被测试覆盖、删除或提交。
|
||||
- MySQL/PostgreSQL 集成测试必须使用一次性测试数据库或测试 schema,并在独立环境中清理;清理动作不得指向生产数据库。
|
||||
|
||||
## 7. 当前未完成项
|
||||
|
||||
Reference in new issue
Block a user