HarborGuard分布式部署深度解析Dashboard Sensor MinIO高可用容器扫描架构完整教程【免费下载链接】HarborGuardModern image vulnerability scanning patching platform with multi-tool integration.项目地址: https://gitcode.com/gh_mirrors/ha/HarborGuardHarborGuard 是一款现代化的镜像漏洞扫描与修补平台集成 Trivy、Grype、Syft、Dockle、OSV、Dive 六大安全工具提供统一的 Web 界面来管理和可视化容器扫描结果。当单机资源不足以支撑大规模镜像扫描时本文带你快速掌握 HarborGuard 的分布式部署方案将「Dashboard 控制面 Sensor 扫描节点 MinIO 对象存储」拆分为独立容器实现可水平扩展的高可用容器扫描架构。为什么需要分布式部署单体模式下扫描器、Web 界面、数据库都运行在同一个容器里。镜像越扫描、并发越高CPU 与内存压力越大且扫描器依赖Buildah、Docker CLI 等会显著增大镜像体积。分布式架构将职责彻底分离组件职责特点DashboardWeb 界面、任务调度、结果展示轻量不含任何扫描器与 BuildahSensor实际执行容器漏洞扫描挂载 Docker Socket可任意扩缩容MinIO存储扫描大文件原始报告、SBOMS3 兼容避免数据库膨胀PostgreSQL存储扫描记录、漏洞、Agent 状态带健康检查就绪后 Dashboard 才启动Dashboard 专用镜像在 Dockerfile.distributed 中构建注释明确写着no scanners, no Buildah, no Docker CLI只保留 Web 服务与 Chromium用于生成 PDF 报告因此启动快、占用小、可放心多副本部署。一键部署Docker Compose 完整流程整个分布式架构由一份 docker-compose.distributed.yml 定义包含 5 个服务dashboard、sensor、db、minio、minio-init。部署步骤获取代码如本地没有仓库git clone https://gitcode.com/gh_mirrors/ha/HarborGuard cd HarborGuard启动全部服务docker compose -f docker-compose.distributed.yml up -d打开浏览器访问http://localhost:3456即进入分布式模式的 Dashboard。几个关键设计细节依赖顺序Dashboard 通过depends_on等待 PostgreSQL 健康检查通过、MinIO 启动后才启动杜绝“连接被拒绝”类启动失败。MinIO 自动初始化minio-init服务使用mc客户端自动创建harborguard存储桶无需手动建桶。统一 API KeyDashboard 与 Sensor 共享HG_API_KEY环境变量默认值仅用于演示生产环境务必修改认证机制下文详述。本地缓存Sensor 挂载sensor-cache卷到/workspace/cache扫描器漏洞数据库可跨重启复用省去重复下载。横向扩容一行命令增加扫描吞吐Sensor 是无状态的扫描 Worker扩容只需调整副本数docker compose -f docker-compose.distributed.yml up -d --scale sensor3多个 Sensor 会竞争领取任务队列中的扫描任务扫描吞吐随之线性提升。任务领取采用「原子认领」机制——只有任务仍处于PENDING状态时才会被标记为ASSIGNED因此多个节点并发轮询也不会出现重复扫描。核心机制Sensor 如何与 Dashboard 协同整个协同链路围绕 API Key 认证展开密钥以hg_ak_前缀生成服务端只保存其 SHA-256 哈希见 src/lib/agent/api-keys.ts即使数据库泄露也无法还原明文密钥。完整工作流注册Sensor 启动后携带 API Key 调用/api/agent/register上报主机名、OS、架构、扫描器版本等能力信息src/app/api/agent/register/route.ts心跳周期性调用/api/agent/heartbeat更新lastSeenAt与当前活跃扫描数Dashboard 据此判断节点在线状态ACTIVE/DISCONNECTED领任务Dashboard 创建扫描请求后写入agent_jobs任务表Sensor 轮询/api/agent/jobs每次最多领取 5 个待处理任务回传结果扫描完成后Sensor 将标准化结果信封ScanEnvelope包含漏洞、包清单、合规、效率四类发现项及聚合风险评分上传至/api/scans/uploadDashboard 将其落库并刷新页面展示。模式切换是全自动的src/lib/scanner/SensorBridge.ts 中的detectScanMode()优先检测是否存在已注册的远程 Agentagent-dispatch否则回退到本地内置的 Sensor CLIlocal-sensor。这意味着同一套代码既支持单体模式也支持分布式模式注册了 Sensor 后任务自动改走远程派发。数据模型定义在 prisma/migrations/20260322000000_add_agent_models/migration.sqlagents与agent_jobs两张表及索引为任务队列的高并发查询做了优化。MinIO 对象存储大文件不进数据库扫描会产生大量原始 JSON 报告与 SBOM 文件直接塞进 PostgreSQL 的 JSONB 字段会让数据库迅速膨胀。分布式模式下Sensor 将envelope.json结果信封、各扫描器的原始报告、sbom.cdx.json上传到 MinIO 的scans/{scanId}/前缀下数据库的scan_metadata表只记录一个s3Prefix指针Dashboard 读取报告时优先走 S3src/lib/storage/s3.ts失败则回退到 JSONB 字段双保险保证数据可读。MinIO 控制台默认映射到9002端口可随时打开查看存储对象。生产环境只需修改S3_ACCESS_KEY/S3_SECRET_KEY并替换为独立的 MinIO 集群即可获得高可用存储。关键环境变量速查变量配置在说明DATABASE_URLDashboardPostgreSQL 连接串示例中连接 compose 内的db服务S3_ENDPOINT/S3_BUCKETDashboardMinIO 地址与存储桶http://minio:9000/harborguardHG_API_KEYDashboard Sensor节点认证密钥两端必须一致HG_DASHBOARD_URLSensorDashboard 的内网地址http://dashboard:3000HG_AGENT_NAMESensor节点名称多节点部署时建议区分命名便于排查MAX_CONCURRENT_SCANSDashboard控制并发扫描上限默认 3完整变量说明可参考仓库根目录 README.md 的Environment Variables章节。常见问题排查Sensor 一直无法领取任务检查两端HG_API_KEY是否一致密钥不匹配时注册接口会返回 401。扫描失败提示 S3 错误确认minio-init已完成建桶docker compose logs minio-init以及 Dashboard 的S3_ENDPOINT指向http://minio:90009000 是 S3 API 端口9001/9002 是 Web 控制台。Sensor 扫不到本地镜像Sensor 容器必须挂载/var/run/docker.sock这是分布式 compose 文件已默认配置好的。扩容后任务分布不均属正常现象任务按创建时间先进先出分配负载高时自然趋于均衡。总结HarborGuard 的分布式部署通过三个关键设计实现高可用的容器扫描平台职责分离——轻量 Dashboard 独立 Sensor各取所需、独立扩展任务队列——基于数据库的原子认领机制天然支持多节点负载均衡对象存储解耦——MinIO 承载大文件数据库只存结构化结果与指针。只需一份 Compose 文件与一行--scale命令你就能把单机扫描工具升级为企业级多节点扫描集群从容应对成百上千个镜像的日常安全巡检。【免费下载链接】HarborGuardModern image vulnerability scanning patching platform with multi-tool integration.项目地址: https://gitcode.com/gh_mirrors/ha/HarborGuard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考