Harbor 漏洞数据库“未就绪“提示机制详解：测试用例 10-04 的验证方法与前后端实现

Harbor 漏洞数据库"未就绪"提示机制详解：测试用例 10-04 的验证方法与前后端实现

【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor

本文基于 Harbor 仓库中 Group10 漏洞扫描测试用例 10-04，完整介绍"漏洞数据库可能尚未完全就绪"（Vulnerability database might not be fully ready）提示的验证场景、操作步骤与预期结果，并结合前端 i18n 资源、扫描器元数据接口与后端 scanner REST v1 协议，解析该提示在 Harbor 中的落地链路，帮助读者理解为什么新装实例会出现这一提示、它在哪里显示、以及"未就绪"状态在代码层面如何表达。

一、测试用例 10-04：验证目标与前置环境

测试用例 10-04-Clair-data-not-ready-hint.md 的完整内容如下（原文逐节继承）：

验证目的（Purpose）：验证当漏洞数据尚未就绪时，Harbor 会给出相应提示（"there will be a hint if vulnerability data is not ready"）。

参考文档：官方 User guide（用户指南）。

环境要求（Environment）：

1. 一个已运行且可访问的 Harbor 实例；
2. Harbor 安装时启用了 Trivy 扫描器（原文为 "Harbor is installed with trivy enable"）；
3. 一台安装了 Docker CLI 的 Linux 主机；
4. 关键前提：Harbor 安装完成后，将其带宽限制到 1Mbps 以下（"Limit the Harbor's bandwidth to less than 1Mbps after Harbor is installed"）。

测试步骤（Test Step）：

注意：原文特别强调 "This test need to be done as soon as possible after Harbor is installed"（该测试需要在 Harbor 安装后尽快执行）。

1. 以 admin 身份登录 Harbor；
2. 进入项目页面（Project 页面）；
3. 进入项目配置（Configuration）；
4. 点击 Vulnerability（漏洞扫描）选项卡。

预期结果（Expected Outcome）：

• 步骤 2 的项目页面应看到 "Vulnerability database might not be fully ready"（漏洞数据库可能尚未完全就绪）的提示；
• 步骤 4 的漏洞扫描配置中应看到一个警告符号（warning symbol）以及同样的 "Vulnerability database might not be fully ready" 提示。

可能的问题（Possible Problems）：无（None）。

为什么需要人为制造"未就绪"状态

这条用例最核心的设计点在于第 4 条环境约束：限带宽。Harbor 内置的扫描适配器（Trivy 或 Clair）在首次启动时需要从上游下载漏洞数据库，随后周期性更新。在正常网络下，这个过程通常在实例启动后很快完成，提示窗口极短，难以被测试捕捉到。而将实例带宽限制到 1Mbps 以下后，漏洞数据库的下载/同步会被拖慢，从而在新装实例的早期稳定复现"数据未就绪"这一中间态，让测试可以在项目页面和漏洞扫描配置页观察到对应的 UI 提示。这也解释了为什么原文要求"安装后尽快"执行测试——只有抓住数据库尚未完成初始同步的时间窗口，才能验证到提示。

从命名上看，该用例文件名为 "Clair"（Harbor 早期默认扫描器为 Clair），但正文环境描述中写的是启用 Trivy，这反映了用例随默认扫描器从 Clair 演进到 Trivy 的历史痕迹；其验证对象统一是"漏洞数据库未就绪时的提示"，与具体扫描器实现解耦。

二、提示文案的实现：CONFIG.SCANNING.DB_NOT_READY 国际化资源

预期结果中两处提示的文案，在仓库中对应 Portal 前端国际化资源里的CONFIG.SCANNING.DB_NOT_READY键，英文原文（en-us-lang.json）为：

"DB_NOT_READY": "Vulnerability database might not be fully ready!"

该键位于CONFIG命名空间下的SCANNING子节点（同节点还包含DB_REFRESH_TIME、SCAN_ALL、SCHEDULE_TO_SCAN_ALL等扫描配置相关文案），与"项目配置 → Vulnerability 选项卡"的页面区域一一对应。该文案在 10 种语言的资源文件中均有翻译，例如简体中文（zh-cn-lang.json）：

"DB_NOT_READY": "缺陷数据库可能没有完全准备好!"

以及繁体中文、韩语、日语以外的其余语种（德语、法语、西班牙语、葡萄牙语、俄语、土耳其语等），保证了不同语言环境下的用户都能看到语义一致的提示。

需要说明的边界：在当前仓库源码中，DB_NOT_READY键仅确认存在于上述 i18n 语言文件中，测试用例描述的"项目页提示 + 配置页警告符号"是该键对应的 UI 行为验收标准。也就是说，"两处显示"这一预期以测试用例文档为依据，文案本体以前端语言文件为依据，两者相互印证。

三、漏洞扫描配置页：提示与"数据库更新时间"共存的渲染逻辑

用例步骤 4 所指的页面，由 Portal 中的漏洞扫描配置组件实现（vulnerability-config.component.html）。该模板的关键结构如下：

@if (onGettingUpdatedTimeStr || onGoing) { <span class="mt-1 ml-1 spinner spinner-inline"></span> } @if (!(onGettingUpdatedTimeStr || onGoing)) { <section class="form-block"> @if (updatedTimeStr) { <div class="mt-1 display-flex"> <label class="update-time">{{ 'CONFIG.SCANNING.DB_REFRESH_TIME' | translate }}</label> <span>{{ updatedTimeStr }} </span> </div> } ...

可以看到，配置页在正常状态下会展示CONFIG.SCANNING.DB_REFRESH_TIME（英文为 "Database updated on"）标签及其后的updatedTimeStr时间字符串，即"漏洞数据库上次更新时间"。这与DB_NOT_READY提示构成同一区域的一组状态反馈：数据库已完成更新时展示更新时间，尚未就绪时展示警示文案。加载中（onGettingUpdatedTimeStr或onGoing为真）则显示 spinner。

时间字符串的数据来源在组件 TS 文件中（vulnerability-config.component.ts）：

getScannerMetadata(uid: string) { this.scanningService .getScannerMetadata(uid) .pipe(finalize(() => (this.onGettingUpdatedTimeStr = false))) .subscribe(metadata => { if (metadata && metadata.properties) { for (let key in metadata.properties) { if ( key === DATABASE_UPDATED_PROPERTY && metadata.properties[key] ) { this.updatedTimeStr = new DatePipe( 'en-us' ).transform(metadata.properties[key], 'short'); } } } }); }

其中DATABASE_UPDATED_PROPERTY常量定义在 utils.ts：

export const DATABASE_UPDATED_PROPERTY = 'harbor.scanner-adapter/vulnerability-database-updated-at';

链路解读：组件先调用getScanners()找到is_default的默认扫描器，再请求该扫描器的 metadata（/scan-v2风格的 scanner metadata 接口），从properties中取harbor.scanner-adapter/vulnerability-database-updated-at属性，用DatePipe格式化为短日期后渲染。这正是"未就绪"提示的判定依据所在——扫描适配器只有在漏洞数据库完成下载/更新后才会上报该时间戳属性；在 1Mbps 限流的早期窗口内该属性缺失或过期，UI 侧就切换为DB_NOT_READY警示。同一常量也被 scanner-metadata.component.ts 用于扫描器元数据详情页的属性展示，说明该属性是扫描器 metadata 协议的通用字段，而非某一页面私有。

四、后端"未就绪"的另一层含义：ReportNotReadyError 与重试

除了 UI 层面的"数据库未就绪"提示，Harbor 后端在扫描流程中还有一层与"未就绪"直接相关的机制，值得区分理解。在 scanner REST v1 客户端模型中（models.go）：

// ReportNotReadyError is an error to indicate the scan report is not ready type ReportNotReadyError struct { // RetryAfter is a time hint indicating the time in seconds the client // should retry to get the scan report RetryAfter int } // Error for ReportNotReadyError func (rnr *ReportNotReadyError) Error() string { ... }

当 Harbor 轮询取回扫描报告而报告尚未生成完毕时，客户端会按上游返回的重试提示构造该错误（client.go）：

return nil, &ReportNotReadyError{RetryAfter: retryAfter}

随后扫描任务编排逻辑会依据RetryAfter重置退避计时并继续等待（job.go）：

if notReadyErr, ok := err.(*v1.ReportNotReadyError); ok { ... tm.Reset(time.Duration(notReadyErr.RetryAfter) * time.Second) myLogger.Infof("Report with mime type %s is not ready yet, retry after %d seconds", m, notReadyErr.RetryAfter)

对应的单测 client_test.go 通过TestClientGetScanReportNotReady验证了该分支：断言错误类型为*ReportNotReadyError且RetryAfter等于 10。

由此可以区分两个"未就绪"概念：

两者共同构成 Harbor 扫描子系统对"数据/结果尚未准备好"这一中间态的完整处理：前者向用户显式告知，避免把"扫描无结果"误读为"无漏洞"；后者在协议层用带重试提示的错误类型保证报告轮询不丢失、不空转。

五、复现验证清单与注意事项

综合测试用例与源码证据，验证该行为时可按以下清单操作：

1. 部署：安装/升级 Harbor 并确保启用内置扫描器（用例环境为 Trivy 启用；旧文档语境为 Clair，两者对该提示的验证是等价的）；
2. 限流：安装完成后立即将实例出口带宽限制到 1Mbps 以下，制造漏洞数据库同步延迟；
3. 及时登录：以 admin 尽快登录（提示窗口与数据库初始同步进度相关，过晚可能已就绪）；
4. 观察项目页：进入 Project 页面，确认出现 "Vulnerability database might not be fully ready" 提示；
5. 观察配置页：进入 Configuration → Vulnerability 选项卡，确认出现警告符号及同一文案（英文环境为 "Vulnerability database might not be fully ready!"）；
6. 收尾验证（可选）：待带宽恢复、数据库同步完成后，Vulnerability 选项卡应从警示状态恢复为展示 "Database updated on <时间>" 的DB_REFRESH_TIME区域，该时间值即来自扫描器 metadata 的harbor.scanner-adapter/vulnerability-database-updated-at属性。

适用前提与限制：本用例面向"带内置扫描器的 Harbor 实例 + 人为限流"的受控环境，属于对 UI 状态提示的功能验收，不涉及漏洞数据本身的内容正确性；文案断言以英文环境为准（i18n 各语言翻译见src/portal/src/i18n/lang/下各语言文件）。

六、小结

测试用例 10-04 用一个"限带宽 + 尽快验证"的巧妙设计，把漏洞扫描生命周期中极易被忽视的"冷启动中间态"固定成了可验收的行为：Harbor 不允许用户在新装实例上把"扫描不到漏洞"误当作"镜像没有漏洞"，而是通过项目页与漏洞扫描配置页的双处提示显式声明"漏洞数据库可能尚未完全就绪"。前端侧，该提示由CONFIG.SCANNING.DB_NOT_READY国际化键承载，与DB_REFRESH_TIME/vulnerability-database-updated-at元数据共同构成配置页的状态机；后端侧，ReportNotReadyError+RetryAfter的重试机制则保证了报告轮询在"结果未就绪"时以秒级退避继续收敛。理解这两条链路，就能完整回答"提示为什么出现、在哪里出现、何时消失"这三个问题。

【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor