Issue #3 第一阶段:管理员首次运行自检
本文记录 Issue #3 的 P1 首次运行自检交付。后续 #14 已另行实现 TOTP、一次性恢复码,以及 MFA 管理操作的当次密码和现有因素验证,详见账号二次验证与恢复。这不表示全部敏感配置均已增加近期认证,也不包含 WebAuthn/Passkey。JWT 多密钥轮换、邮件投递诊断历史、授权趋势及接入沙盒等仍需分别验收,不能据此关闭整个 Issue #3。
使用与验收
管理员进入「系统设置 → 首次运行自检」,点击「运行自检」。配置修改后可以重新运行,结果只保留在当前页面;失败重试会清除旧结果。
POST /api/v1/admin/setup-check 复用登录会话、CSRF 和 settings:write 权限。返回 data.checked_at 与 data.checks;每项包含 id、name、status、message,适用的渠道另有 callback_url。状态为 passed、warning、failed、skipped。每次完成检查写入 setup.check / system 审计,审计写入失败则返回 503。
| 项目 | 检查内容 | 仍需实际验收 |
|---|---|---|
| PostgreSQL / Redis | 分别以最多 2 秒进行 Ping | 服务持续可用性 |
| SMTP | 已保存配置可解密,主机、端口、邮箱、TLS 与凭据满足现有校验 | SMTP 连通、服务器接收、真实邮箱收件 |
| S3 | 启用存储的目标格式及凭据完整,未启用时提示 | 存储页面连接测试、真实上传与下载权限 |
| 支付渠道 | 启用渠道必填字段齐全、配置可解密 | 密钥有效性、支付与退款、回调验签 |
| 三方登录 | 启用渠道标识与密钥齐全、配置可解密 | 平台登记、授权及登录流程 |
| 站点地址 | APP_ORIGIN 格式,HTTP/本机地址提示上线前更换,生成实际路由对应回调地址 | 公网 HTTPS 可达性、渠道后台回调地址一致性 |
自检不向 SMTP、S3 或支付/登录平台发请求,不发送邮件、上传文件或创建交易。字段完整不等于渠道可用。银行转账不显示回调地址。未启用的渠道标记为跳过。
接口使用固定诊断消息,不返回配置原值、密文、凭据、连接串或底层错误;带用户名、密码、查询参数或路径的异常 APP_ORIGIN 不回显。回调地址来自服务端配置。
数据库和 Redis 也是登录验证依赖,服务不可用导致无法验证身份时会返回 503,不能绕过身份验证获取报告;数据库无法保存审计时同样返回 503。单次报告使用 10 秒上下文期限。
本机运行与验证记录
遵循根目录 AGENTS.md,应用直接在 Windows 运行。现有容器已检查:Postgres18 健康、映射 127.0.0.1:5432;RedisPwd 健康、映射 127.0.0.1:6379。没有创建、重建或修改容器,没有使用 MYSQL8 或历史测试容器。凭据只从忽略的本地配置读取。
后端启动:./scripts/run-local.ps1 -Mode api;前端在 web 目录设置 API_URL=http://127.0.0.1:13141 后 npm run dev。本次页面测试使用已有 13140 开发服务;新后端通过本机 Go HTTP 路由集成测试验证,并已将本项目 13141 后端重启为本机构建的 .local/auth-center.exe。健康检查返回 ready,未登录自检请求返回 401。无需数据库迁移。
已通过:
./scripts/run-local.ps1 -Mode test:Go 单元测试和go vet。默认未配置集成测试变量时集成用例跳过。- 设置
TEST_DATABASE_URL、TEST_REDIS_URL为本地已有服务连接后,在 server 目录运行go test ./internal/app -run TestSetup -count=1 -v:本次新增集成测试实际通过,在 Postgres18 新建随机临时 schema 并清理,不写业务表;Redis 仅 Ping。覆盖匿名/无权限/CSRF 拒绝、默认配置、完整与损坏配置、缺少密钥、回调、脱敏、审计及审计失败。 ./scripts/run-local.ps1 -Mode build:后端编译。- web 目录
npm run build:前端构建及 TypeScript 检查。 - 根目录
node scripts/setup-check-ui-check.cjs:使用 Playwright(必要时通过 NODE_PATH 指向已安装包),在已有本机前端以 API fixtures 验证 1440/390 像素布局、权限隐藏、执行、失败清除旧结果和重试;不修改真实账号。
未执行:SMTP、S3、支付及三方登录真实渠道联调;已有全套写入式 HTTP 业务测试。本次没有把配置检查或模拟页面测试表述为外部渠道验收成功。