docs(audit): 14 页 API 契约审计与凭据轮询 SSOT 收尾

记录凭据轮询/pending 契约对照与生产验证，更新功能指南与附录 J，并将 pending 相关类型集中到 api.ts。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-06 23:50:05 +08:00
parent 9ee5c8a708
commit ac17f91106
8 changed files with 447 additions and 29 deletions
@@ -0,0 +1,68 @@
+# 凭据轮询 / pending servers — 生产与健康检查验证
+
+**日期**: 2026-06-06  
+**关联**: [2026-06-06-frontend-14p-contract-audit.md](2026-06-06-frontend-14p-contract-audit.md)
+
+## 生产 API
+
+```bash
+curl -sf https://api.synaglobal.vip/health
+# → ok
+
+curl -sf https://api.synaglobal.vip/openapi.json | jq '.paths | keys[] | select(test("pending|add-by-ip"))'
+```
+
+| 路径 | OpenAPI |
+|------|---------|
+| `/api/servers/add-by-ip` | ✓ |
+| `/api/servers/pending` | ✓ |
+| `/api/servers/pending/{pending_id}/retry` | ✓ |
+| `/api/servers/pending/{pending_id}` | ✓ |
+
+`AddByIpRequest` 字段：`domain`, `port`, `name`, `agent_port`, `target_path`, `category`, `platform_id`, `node_id`。
+
+## 生产前端（SPA）
+
+构建产物已与本地 `vite build` 一致（主包 `index-o0-2k-vI.js` 哈希相同）。
+
+| 分块 | 关键字探测 |
+|------|------------|
+| `ServersPage-Z2EpNr-B.js` | `add-by-ip`, `servers/pending`, `快速添加`, `matched_preset` |
+| `CredentialsPage-Cf9BpH3x.js` | `username`（24 处） |
+
+**结论**: 后端与前端均已部署到生产，无需本轮再跑 `deploy-frontend.sh`（本地 SSH 别名 `nexus` 亦不可解析）。
+
+## 单元 / 静态门控
+
+| 检查 | 结果 |
+|------|------|
+| `pytest tests/test_credential_poller.py` | 7 passed |
+| `ruff check server/ --select F` | All checks passed |
+| `cd frontend && npx vite build` | ✓ built |
+
+## 本地 `local_verify.sh`
+
+**未通过** — 根因：宿主机进程无法完成 MySQL 握手（`OperationalError 2013`），但：
+
+- Docker 内 `mysql` 服务名连接正常（`docker run --network nexus_default mysql:8.4 mysql -h mysql …` → OK）
+- 容器 `docker exec nexus-mysql-1` 内查询正常
+- 宿主机 `127.0.0.1:3306` / 桥接 IP `172.18.0.3:3306` 均 2013
+
+属本机 Docker 端口转发 / 网络策略问题，与凭据轮询代码无关。
+
+**建议本机恢复路径**：
+
+1. `docker compose up -d nexus --build` — API 走容器内 `mysql` 主机名；或  
+2. 修复宿主机→Docker MySQL 3306 转发后，对齐 `.env` 中 `NEXUS_DATABASE_URL` 与 `docker-compose` 卷内实际密码；或  
+3. `NEXUS_TEST_ADMIN_PASSWORD=… python3 scripts/seed_local_admin.py` 后重跑 `bash scripts/local_verify.sh`
+
+## 待用户终验（需登录生产控制台）
+
+1. 凭据页：密码/SSH 预设填写 `username` 并保存  
+2. 服务器页：「快速添加」输入测试 IP → 成功 toast 或失败弹窗 + 失败列表  
+3. 失败列表：重试 / 删除
+
+## 未提交工作区（文档 + 类型）
+
+- 契约审计报告、功能指南 §12、附录 J、`types/api.ts` 共享类型  
+- 代码功能已在 `4ba45ab` 合入；上述为审计收尾文档