运维与故障排除¶
本章涵盖日常运维、故障模式及内网托管 CVE Intelligence Panel 的安全注意事项。
性能¶
无 NVD_API_KEY 时对多工具完整扫描可能需数分钟。请在维护窗口执行。排除 NVD 后监控模式应保持轻量。
常见问题¶
| 现象 | 可能原因 | 处理 |
|---|---|---|
Too many scan requests / RATE_LIMITED |
应用 middleware（scan 或 watch 桶） | 等待 retryAfterSec；关闭多余标签；在 .env 提高 RATE_LIMIT_*；重启服务 |
| NVD 结果为空 | NVD upstream 速率限制 | 添加 NVD_API_KEY、缩小栈、重试 |
| 源时间戳陈旧 | 拉取失败 | 检查网络；查看服务端日志 |
| 翻译卡住 | Provider 不可用 | 暂时关闭自动翻译；使用英文 UI |
| 误匹配 | 工具名启发式 | refine 栈命名；人工分拣 |
| 监控无新项 | knownIds 已含 CVE |
预期行为；用完整扫描验证 |
安全¶
- 勿在无认证情况下公网暴露 API。
GITHUB_TOKEN与NVD_API_KEY仅保存在服务端 env。- RSS 与外部 JSON 为不可信输入——服务端防御性解析。
升级¶
git pull 后执行 npm install、make build 并重启进程。若版本间 i18n 键变化，请清除浏览器缓存。v1.1.0 新增设置向导与按栈键的扫描缓存 — 现有栈自动迁移；新安装会走一次向导。
自动化测试¶
| 套件 | 命令 | 范围 |
|---|---|---|
| 单元 + API | make test |
tests/server/、tests/client/、tests/integration/ |
| 覆盖率 (CI) | npm run test:ci |
同上 + lcov 供 Codecov/Sonar |
| E2E (Playwright) | 先运行一次 npm run test:e2e:install，再 npm run test:e2e |
tests/e2e/ — CSV 导出、Live Watch、租户通知偏好（mock API） |
tests/integration/ 集成测试覆盖 NVD 分页、OSV bulk air-gap、GitLab mirror prefetch、multi-tenant API（multi-tenant-api.test.ts）。
测试覆盖率（CI 基线）¶
npm test 当前运行 257 个用例，覆盖服务端单元测试、客户端 helper 与集成镜像。CI 覆盖率（npm run test:ci）约为 94% 行、82% 分支、94% 函数（V8 lcov → Codecov/SonarCloud）。
| 领域 | 示例文件 |
|---|---|
| 通知 | tests/server/notifications.test.ts、notificationEmail.test.ts、notificationTelegram.test.ts |
| 中间件 | tenantContext.test.ts、scanTimeout.test.ts、securityHeaders.test.ts |
| 数据层 | pool.test.ts、tenants.test.ts、tenantsDb.integration.test.ts |
| 客户端 helper | exportVulns.test.ts、iconAssets.test.ts、scanCache.test.ts |
| 集成 | nvd-pagination.test.ts、osv-bulk-scan.test.ts、multi-tenant-api.test.ts、gitlab-mirror-prefetch.test.ts |
E2E：export.spec.ts、watch.spec.ts、tenant-prefs.spec.ts — 先运行 npm run test:e2e:install。
文档维护¶
产品变更应同步更新 全部六种 extended-docs/docs/content/{locale}/ 树、src/i18n/messages/*.ts 及必要时 legacy docs/。遵循 agent 规则 code-to-docs-sync（agent/rules/code-to-docs-sync.mdc）— 路径→文档映射、术语表与 scripts/check-extended-docs-locale-sync.sh。
audit、RBAC、租户、指标、airgap 与 Kubernetes 见 11 自托管。