Linux Harbor 的镜像仓库安全扫描与 RBAC 配置模板

harbor扫描器未启动因服务未注册或健康检查失败，需配置harbor.yml的scan_mode和scanner区块并重装；rbac权限无法细分删除操作，ldap用户需正确映射ldap_uid字段；trivy漏报源于db滞后或os识别偏差，须手动更新db并调优超时参数。

Harbor 扫描器没启动，clair 或 trivy 显示 “scanner not available”

Harbor 默认不自动启用扫描器，即使你装了 trivy 或配了 clair，UI 上也会灰显“Scan”按钮。根本原因是扫描器服务未注册或健康检查失败。

实操建议：

• 确认 harbor.yml 中 scan_mode 设为 native（Trivy）或 clair，且 scanner 区块已取消注释
• 运行 ./install.sh --with-trivy（非 upgrade）——升级时不会重装 scanner 容器，必须手动拉起 harbor-trivy 并检查日志：docker logs harbor-trivy
• Trivy 启动后需约 90 秒完成数据库初始化，期间 API 返回 503；可 curl http://localhost:8080/api/v2.0/scanners 看 status 是否为 healthy
• 若用自建 Trivy Server（非 Harbor 内置），注意 harbor.yml 中 endpoint 必须带 /api/v1 后缀，否则注册失败

RBAC 权限颗粒度不够，用户能删别人项目的镜像

Harbor 的项目级权限模型默认只控制“推/拉/管理”，但 project-admin 角色实际拥有 delete 全量镜像权限，且无法按镜像名、标签或仓库路径细分——这是设计限制，不是配置错误。

实操建议：

• 避免给普通用户分配 project-admin；改用 developer（可 push/pull）+ 单独授予 guest 用户 pull 权限
• 如需禁止删除，只能靠外部手段：在 nginx 反向代理层拦截 DELETE /v2/* 请求，或用 registry 的 storage.delete.enabled=false（但会影响 Harbor GC）
• 项目设置里勾选 “Prevent vulnerability scanning from being disabled” 不影响 RBAC，只防扫描开关被关，别混淆
• 成员继承关系只有一层：用户加入项目 → 继承项目角色；不继承用户组角色，组策略需在项目内单独添加

harbor.yml 配置 RBAC 后，LDAP 用户登录报 “user not found”

不是 LDAP 连接失败，而是 Harbor 在同步用户时默认只拉取 uid 和 mail 属性，而 RBAC 规则依赖的 username 字段如果 LDAP 中是 sAMAccountName（AD 常见）或 cn，就会匹配不上。

实操建议：

• 修改 harbor.yml 的 auth_mode: ldap 区块，显式指定 ldap_search_dn 和 ldap_search_password，并设 ldap_uid 为实际用户名字段名，例如：ldap_uid: sAMAccountName
• 测试命令：ldapsearch -x -H ldaps://your-ldap -D "bind-dn" -W -b "base-dn" "(sAMAccountName=username)" uid mail，确保返回值含预期字段
• 改完必须执行 prepare 脚本（./prepare）再重启，仅 docker-compose down && up -d 不生效
• 首次登录的 LDAP 用户会自动创建本地记录，但角色需手动在 UI 分配；自动映射角色功能（ldap_group_attribute_name）仅支持 OpenLDAP，AD 需用 Group DN 白名单

Trivy 扫描结果不准，漏报 CVE 或标错严重等级

Trivy 的 DB 更新滞后、OS 包识别偏差、或镜像分层解析异常都会导致误判。Harbor 内置 Trivy 默认每周更新一次 DB，且不校验签名，容易用到陈旧数据。

实操建议：

• 手动更新 DB：docker exec -it harbor-trivy /bin/sh -c "trivy --download-db-only --db-repository ghcr.io/aquasecurity/trivy-db"，然后重启容器
• 扫描时加 --skip-update 参数（通过 Harbor UI 的“高级设置”勾选）可跳过每次扫描前的网络请求，但需确保 DB 已最新
• Alpine 镜像常漏报：Trivy 对 apk 包的 CVE 映射弱于 debian/ubuntu，建议用 trivy image --security-checks vuln,config --format json 对比原生输出
• 扫描超时默认 5 分钟，大镜像（>2GB）可能中断；调高 harbor.yml 中 trivy.timeout（单位秒），但别超过 1800，否则 Harbor 任务直接失败

RBAC 和扫描不是开关一开就稳的组合。权限继承链、LDAP 字段映射、Trivy DB 生命周期——这三个点，任何一个卡住，都会让策略看起来“没生效”。调的时候盯日志，别信 UI 状态栏。