企业官网建设流程全解析

Harbor DB 认证模式下系统管理员角色的项目成员搜索权限验证：Test 3-22 测试用例深度解析

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

导读

本文围绕 Harbor 开源仓库中的 RBAC 测试用例 3-22-DB-admin-role-user-search-project-members.md，详细讲解"在本地数据库（db_auth）认证模式下，一个被授予系统管理员角色的普通用户能否与内置 admin 用户一样搜索任意项目成员"这一核心场景。读完本文，你将掌握该测试的完整前置条件、执行步骤与预期结果，并能够结合 Harbor 源码（成员管理控制器、REST API 处理器、DAO 查询与 RBAC 策略）理解"系统管理员"与"内置 admin"在权限上的等价性，以及项目成员搜索功能在 UI 与 API 层的真实实现链路。

测试定位：Group3-RBAC 系列中的权限等价性验证

该测试属于 tests/testcases/Group3-RBAC 目录下的 RBAC（基于角色的访问控制）测试组。Group3 系列用例系统性地覆盖了 Harbor 中三类主体的权限行为：

3-22 与 3-12 形成对称关系：3-12 验证内置 admin 用户具备搜索任意项目成员的能力，而 3-22 验证被授予系统管理员角色的普通用户（非内置 admin）同样具备该能力。这实质上是在验证 Harbor 权限模型中"系统管理员角色"与"内置 admin 用户"在项目成员查询这一操作上的权限等价性。

测试目的（Purpose）

To verify that a user with system admin role can search members of a project when users are managed locally by Harbor (DB mode).

即：当 Harbor 采用本地数据库管理用户（DB 模式）时，验证一个拥有系统管理员角色的用户能够搜索项目的成员。该用例重点关注的是"权限角色"而非"具体账号"——只要用户被赋予了系统管理员角色，无论其是否为内置的admin账号，都应当获得跨项目的成员可见性。

环境前置条件（Environment）

要复现该测试，需要满足以下环境要求：

1. Harbor 实例正在运行且可访问；
2. 认证模式为本地数据库认证：即配置项auth_mode设置为db_auth，用户数据存储在 Harbor 本地数据库中。该常量定义于 src/common/const.go（DBAuth = "db_auth"），是 Harbor 支持的多种认证模式之一（其余包括ldap_auth、uaa_auth、http_auth、oidc_auth）；
3. 一台安装了 Docker CLI 的 Linux 主机（Docker 客户端），用于执行docker login、docker push、docker pull等操作（3-22 本身不直接涉及镜像操作，但这是整个 Group3 系列用例的公共环境要求）；
4. Harbor 中至少存在 5 个非管理员用户；
5. 至少存在一个项目 X，其成员数不少于 5 人，且 admin 用户不是该项目成员——该条件确保成员搜索发生在 admin 无直接项目身份的跨项目场景下，能够真正检验系统管理员的全局权限。

测试步骤详解（Test Steps）

原用例仅包含两个步骤，核心是"角色授予 + 复用既有用例"：

NOTE:The below non-admin user M should NOT be the same as the non-admin user in Test 3-12.

注意：用例中的非管理员用户 M不能与 Test 3-12 中使用的非管理员用户相同。这是为了保证两个用例各自独立、互不污染，避免因账号角色状态残留而影响断言结果。

1. 授予角色：将一个非管理员用户 M 赋予系统管理员角色（system admin role），此后以 M 的身份作为管理员用户执行操作。在 Harbor UI 中，这一操作在"用户管理"页面完成——管理员选中用户 M 并将其设置为系统管理员，从而使其脱离普通用户权限边界；
2. 复用 3-12：重复执行 3-12-DB-admin-user-search-project-members.md 中的全部步骤。

3-12 的完整步骤（本用例的复用对象）

为便于整体理解，这里完整列出 3-12 的核心执行步骤：

1. 以 admin 身份登录 Harbor UI；
2. 寻找一个 admin不是其成员、且至少拥有 5 名成员的既有项目 X；
3. 使用不同的搜索条件（关键词）搜索项目 X 的成员。

3-12 的预期结果是：第 3 步中，admin 应当能基于搜索关键词看到对应结果。3-22 将上述 admin 身份替换为"被授予系统管理员角色的用户 M"后重放，断言行为完全一致。

双浏览器会话注意点

尽管 3-12/3-22 本身只涉及单一管理员视角，但 Group3 系列的 3-03 等用例明确要求：

• 必须同时使用两种浏览器（例如 Chrome + Firefox，或 Chrome + Safari）以保证会话独立；
• 禁止在同一个浏览器的不同窗口/标签页中同时登录两个用户。

这是因为 Harbor 使用基于会话（Session）的认证，同一浏览器下多用户登录会造成会话串扰，导致角色验证不准确。3-22 的步骤 2 在复用 3-12 时同样应遵循这一会话隔离原则。

预期结果（Expected Outcome）

原用例的预期结果非常明确：

• 一个拥有系统管理员角色的用户，可以执行与 admin 用户完全相同的所有操作；
• 其余预期与 Test 3-12 保持一致（即：使用不同关键词搜索项目成员时，均应返回匹配的成员结果）。

这意味着从权限层面看，系统管理员角色与内置 admin 用户是等价的——它不需要是项目 X 的成员，也能够查看并搜索该项目全部成员列表。

源码级原理解析

1. 权限入口：API 层的成员列表处理器

在 Harbor 的 v2.0 API 实现中，项目成员列表由 src/server/v2.0/handler/member.go 的ListProjectMembers处理器提供。其关键逻辑是：

func (m *memberAPI) ListProjectMembers(ctx context.Context, params operation.ListProjectMembersParams) middleware.Responder { projectNameOrID := parseProjectNameOrID(params.ProjectNameOrID, params.XIsResourceName) if err := m.RequireProjectAccess(ctx, projectNameOrID, rbac.ActionList, rbac.ResourceMember); err != nil { return m.SendError(ctx, err) } entityName := lib.StringValue(params.Entityname) // ... total, err := m.ctl.Count(ctx, projectNameOrID, query) // ... members, err := m.ctl.List(ctx, projectNameOrID, entityName, query) // ... }

可以看到，搜索关键词（entityname参数）由 HTTP 请求传入，最终与分页参数（page、page_size）一起下发到控制器层。这里的关键是RequireProjectAccess权限检查：任何用户访问项目成员资源时，都要通过 RBAC 评估。对于普通用户，这一检查依赖其在项目内的角色；而对于系统管理员，RBAC 评估直接放行——这正是 3-22 断言"系统管理员能搜索非成员项目"的底层依据。

2. 业务层：成员控制器的 List 链路

权限检查通过后，请求进入 src/controller/member/controller.go 的List方法：

func (c *controller) List(ctx context.Context, projectNameOrID any, entityName string, query *q.Query) ([]*models.Member, error) { p, err := c.projectMgr.Get(ctx, projectNameOrID) // ... pm := models.Member{ ProjectID: p.ProjectID, Entityname: entityName, } return c.mgr.List(ctx, pm, query) }

控制器先将"项目 ID + 搜索关键词（实体名）"封装为models.Member查询条件，再交由成员管理器的 DAO 层执行数据库查询。该控制器同时定义了完整的成员管理能力：Get、Create、Delete、UpdateRole、List、Count、IsProjectAdmin，并实现了角色合法性校验（仅允许 projectAdmin、maintainer、developer、guest、limitedGuest 五种项目角色，见isValidRole，定义于 src/controller/member/controller.go）。

3. 数据层：成员搜索的 SQL 实现

成员搜索的最终落地是 src/pkg/member/dao/dao.go 中的 SQL 查询。其核心是一条UNION查询，将两类成员实体合并为统一的结果集：

• 用户组成员（entity_type = 'g'）：关联user_group与project_member表，取ug.group_name作为entity_name；
• 用户成员（entity_type = 'u'）：关联harbor_user与project_member表，取u.username作为entity_name。

当搜索关键词非空时，追加过滤条件and a.entity_name = ?（src/pkg/member/dao/dao.go），按关键词精确匹配成员的用户名或组名。成员的实体名字段在 src/pkg/member/models/member.go 中定义为entity_name（orm:"column(entity_name)"）。DAO 的查询结果按entity_name排序，并支持分页（orm.PaginationOnRawSQL）。

4. RBAC 策略：系统管理员与项目角色的差异

Harbor 的项目级权限通过 src/common/rbac/project/rbac_role.go 中定义的策略矩阵实现。五种项目角色及其对member资源的权限如下（从源码策略表可以确认）：

可以看出，普通项目角色（除 projectAdmin 外）只对自己所在项目的成员拥有只读可见性，并且RequireProjectAccess会先校验调用者是否为该项目成员。而**系统管理员（system admin）**走的是系统级 RBAC 评估路径，天然拥有全系统所有资源的全部权限，因此即使不是项目 X 的成员，也能搜索其成员——这正是 3-22 用例要验证并锁定的行为。

5. 项目角色常量与db_auth模式

成员表project_member.role存储的是角色数值，对应 src/common/const.go 中的常量：

RoleProjectAdmin = 1 RoleDeveloper = 2 RoleGuest = 3 RoleMaintainer = 4 RoleLimitedGuest = 5

而db_auth模式（DBAuth = "db_auth"，src/common/const.go）意味着用户账号、密码与角色数据全部由 Harbor 本地数据库（PostgreSQL，位于make/photon/db的迁移脚本维护）持久化管理，与 LDAP/OIDC 等外部目录服务的差异在于：系统管理员角色完全由 Harbor 内部授予和管理，这也正是本用例"将用户 M 提升为系统管理员"这一操作可行的前提。

测试用例间的关联与验证闭环

将 3-22 放入 Group3-RBAC 整体矩阵中可以看出 Harbor 测试设计的闭环思路：

1. 3-03验证普通用户只能在自己的项目内按角色搜索成员；
2. 3-12验证内置admin 用户可以搜索任意非成员项目的成员；
3. 3-21验证系统管理员角色用户能管理（增删改角色）项目成员；
4. 3-22（本文）验证系统管理员角色用户能搜索任意项目的成员——与 3-21 形成"管理 + 查询"的完整权限面，与 3-12 形成"内置 admin vs 被授权用户"的等价性闭环。

综合来看，当企业环境中存在多个被授权为系统管理员的运维人员时，他们可以像内置 admin 一样对任意项目执行成员搜索与审计，无需逐一加入各项目；而普通用户（guest/developer/maintainer）则只能搜索自己参与的项目。理解这一边界，是规划 Harbor 多租户权限策略与进行权限审计的关键。

可能遇到的问题（Possible Problems）

原用例标注 "None"。从复现角度看，若测试失败，通常可优先排查以下环节：

• 用户 M 是否真正获得了系统管理员角色（检查用户管理页面中的系统管理员标记是否生效）；
• auth_mode 是否为db_auth（可在 Harbor 配置或系统设置中核对）；
• 项目 X 是否满足"非 admin 成员且成员数 ≥ 5"，否则搜索结果的样本量不足以区分权限差异；
• 会话隔离是否被破坏（同一浏览器多账号登录导致权限上下文串扰）。

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