Files

T

Nexus Agent ac17f91106 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

2.6 KiB

Raw Blame History

凭据轮询 / pending servers — 生产与健康检查验证

日期: 2026-06-06
关联: 2026-06-06-frontend-14p-contract-audit.md

生产 API

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 端口转发 / 网络策略问题，与凭据轮询代码无关。

建议本机恢复路径：

docker compose up -d nexus --build — API 走容器内 mysql 主机名；或
修复宿主机→Docker MySQL 3306 转发后，对齐 .env 中 NEXUS_DATABASE_URL 与 docker-compose 卷内实际密码；或
NEXUS_TEST_ADMIN_PASSWORD=… python3 scripts/seed_local_admin.py 后重跑 bash scripts/local_verify.sh

待用户终验（需登录生产控制台）

凭据页：密码/SSH 预设填写 username 并保存
服务器页：「快速添加」输入测试 IP → 成功 toast 或失败弹窗 + 失败列表
失败列表：重试 / 删除

未提交工作区（文档 + 类型）

契约审计报告、功能指南 §12、附录 J、types/api.ts 共享类型
代码功能已在 4ba45ab 合入；上述为审计收尾文档

2.6 KiB Raw Blame History Unescape Escape