BISHENG F036 实战：知识空间子项列表 ReBAC 逐项评估优化，P50 从 22 秒压到亚秒级-平芜编程栈

BISHENG F036 实战：知识空间子项列表 ReBAC 逐项评估优化，P50 从 22 秒压到亚秒级

【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng

本文是 BISHENG 开源 LLM DevOps 平台 v2.6.0 中F036-rebac-eval-cost-optim（ReBAC 逐项权限评估成本优化）特性的压测与落地报告解读。文章以 loadtest-report.md 为主体，结合 spec.md、design.md、code-review-report.md 及仓库源码，完整还原一次典型的"并发性能瓶颈定位 → 方案取舍 → 等价性验证 → 压测对比 → 落地固化"全过程。读者读完可掌握：如何定位 ReBAC 列表接口的 per-item 评估瓶颈、为什么"继承快速通道 + bindings 索引"能在不改任何可见性语义的前提下把 CPU 开销从"随页内项数线性增长"降为"多数项 O(1) 套用"，以及如何用真实数据 diff + 单测 oracle 守住"优化不越权"这条安全红线。

1. 背景与定位：并发下 P50 22–24s 的"幽灵"瓶颈

F036 特性源于 109 环境的一次压测发现：知识空间的「子项列表 / 站内搜索」接口在并发下P50 升至 22–24s，而单请求实测只有0.6s。这个巨大的反差说明瓶颈不在单个请求的绝对耗时，而在并发下的资源竞争。

1.1 压测环境与被测接口

项目	内容
日期	2026-06-15
环境	109（`192.168.106.109`，达梦 DM + OpenFGA-on-DM）
被测接口	`GET /api/v1/knowledge/space/57/children`
分支	`worktree-feat+2.6.0+036-rebac-eval-cost-optim`（从`feat/2.6.0-beta4`切出）
部署方式	把改动的两个文件`docker cp`进`bisheng-backend-dm`容器（原文件备份为`.f036bak`），`docker restart`加载；压测后已还原为原始代码

1.2 逐项归因：单点都不慢，慢在"每项都算一遍"

对压测期间各组件开销的实测数据（见 spec.md 前置说明）：

单请求仅0.6s；
达梦 DM 查询 1–11ms、OpenFGA 单次 Check 8–15ms，均不慢；
并发下backend CPU 打满（~704%），OpenFGA 146%、Milvus 15%。

根因非常清晰：_filter_visible_child_items对页内每个子项做一次完整的细粒度 ReBAC 评估——逐项read_tuples（OpenFGA I/O 扇出）+ 逐 tuple 线性扫描整份 bindings（CPU）+ 每项 2 次get_*_permission_level。开销随页内项数线性增长，并发一上来 CPU 立刻打满。这正对应 design.md §5 中的反直觉事实 1：单请求只 0.6s，瓶颈只在并发——如果误判成"DB 慢"去加索引，就白费力气了。

定位方法提醒：压测时观察docker stats中各容器 CPU 占比是快速归因的关键手段。本案例中 backend 704% 直接锁定 CPU 型热点，与 DM（1–11ms）、OpenFGA（8–15ms）的低延迟形成鲜明对比。

1.3 与 F027 的承接关系

F036 是 F027 ReBAC 列表性能优化的延续：F027 解决「扫多少项」（cursor 分页去掉 count / 深翻页），F036 解决「每项评估多贵」。F036 直接在 F027 引入的_scan_visible_child_itemscursor 扫描循环内部改造，依赖 F004（ReBAC core）、F008（resource-rebac-adaptation），属于P0优先级——并发下常用列表不可用级慢，影响所有租户。

2. 优化方案：① 继承快速通道 + ③ bindings 索引，② 批量预取为何不可行

本次落地两项请求内优化（① ③），并经过论证否决了第三项（②）。三者均在单请求内完成，无任何跨请求状态、无开关默认启用（初版曾用环境变量开关做 A/B 压测，详见第 6 节）。

2.1 ① 继承快速通道：多数项 O(1) 套用，少数项才完整评估

这是消除 CPU 的主收益。核心洞察来自 ReBAC 的nearest_binding_wins语义：如果某个子项的 lineage（自身 + 各级父文件夹 + 空间）里不存在任何文件/文件夹级绑定，那么它的有效权限恒等于「祖先/空间继承 + membership + public」，与逐项完整评估的结果逐位等价。

基于此，快速通道把页内子项分流为三类（spec.md 范围边界 + design.md 决策 1）：

叶级命中「有绑定资源集」→ 走完整逐项评估（nearest-wins，与既有一致）；
item.user_id == 当前用户（owner）→ 直接可见（owner 是加性裸 tuple，永远可见，见坑 8）；
其余→ 继承「父链决策」_chain_effective_permission_ids，每条祖先链只算一次、请求内 memo 缓存。

这个设计有两条安全前提必须讲清楚（见 design.md 决策 1 的备选方案对比）：

不能做"用户对空间有 view 就放行全部"（备选 B）——文件/文件夹可以被单独授权且严于空间，直接放行会越权泄露，该方案已被否决；
任何无法确定"是否有更近绑定"的情形必须回落完整评估（fail-closed），不得放行；
绑定恰好落在祖先文件夹时，项自身无绑定也必须走完整评估（坑 3），lineage 命中判定必须覆盖各级父文件夹，而非仅项自身。

「有绑定资源集」直接由本请求已加载的 bindings 清单（CONFIG 表中一份 JSON）在内存派生，判定 O(1)/项，不额外查库。

2.2 ③ bindings 索引：从"逐 tuple 线性扫全表"到 O(1) 命中

原实现_resolve_binding_for_tuple对每个 tuple 都线性扫描整份 bindings 列表，是隐蔽的 CPU 热点（坑 5）。F036 新增build_binding_index(bindings)，把 bindings 预处理为dict[(resource_type, str(resource_id))] → list[binding]（保序）的分组查表：

_resolve_binding_for_tuple/_permission_ids_from_bindings只遍历触及该资源的绑定组，复杂度从 O(全量 bindings) 降为 O(该资源绑定数)；
保序 ⇒ "首个匹配 wins" 语义不变，结果与线性扫描逐位等价；
索引每请求构建一次、随 context 下传，请求结束即弃，不跨请求。

需要说明：在 109 环境中 bindings 仅 42 条，③ 单独贡献有限（压测显示 FLAG OFF ≈ 原始基线）；它真正的价值是零风险的 O(1) 解析，在 bindings 规模更大的租户上收益会更明显。

2.3 ② 整页批量预取 tuple：经核实不可行，已并入 ①

最初设想是"一次批量读页内项 + 祖先 + 空间的 tuple 灌入tuple_cache"，但经核实不可行（design.md 决策 2）：

OpenFGA/read只能按单个object过滤，没有多对象批量原语——源码见 core/openfga/client.py 的read_tuples(user, relation, object)签名，无法在一次调用中读取一组对象；
② 想省的"逐项read_tuplesI/O 扇出"本质上已被 ① 覆盖：继承快速通道让无更近 binding 的项整项跳过评估（连它自己的read_tuples都不发），祖先/空间的 tuple 仍由既有请求级tuple_cache去重。

因此 ② 没有独立落点，被否决并并入 ① 的覆盖范围。

2.4 明确排除：不引入跨请求缓存（关键取舍）

曾考虑过"跨请求缓存 models/bindings/部门路径/用户主体 + 写时 epoch 失效"，但最终被砍（design.md 决策 4）。理由很实际：

实测瓶颈是每项评估（98 项 × 完整评估 × 线性扫 bindings），不是每请求一次的上下文构建（约 5~8 条小查询 + 2 次 JSON parse）；
跨请求缓存只省"每请求构建一次上下文"的边际成本，却要把失效逻辑挂进授权/部门 CRUD/用户组/SSO-LDAP 同步等其它领域的写路径，挂点多而散、漏一处即越权，跨域耦合过重；
砍掉它，"上传/删文件夹/改部门如何让缓存失效"这个问题根本不存在。

design.md 同时预留了后路：若将来 profiling 证明"每请求上下文构建"成为新瓶颈，引入缓存也不得用写时 epoch-bump，必须改用读侧从数据自身版本派生 key的解耦方式（bindings/models 用 CONFIG 行update_time、部门树用MAX(update_time) per tenant等，零写侧挂点）。

3. 前置不变量与安全红线：等价性如何保证

优化可成立依赖一条已用真实数据验证的前置不变量：

每一个对 file/folder 的"非 owner 授权"都必须写入一条 binding。

也就是说，owner/parent属于"裸 tuple"，为加性/结构性授权，不影响可见集（owner 由item.user_id短路、parent 是结构边）；而真实存在的非 owner 授权 100% 有 binding 对应。109 环境实测：file/folder 上非 owner 的真实授权裸 tuple 数 = 0。

这条不变量是 spec.md 中 AC-01~AC-04 与 INV-7（列表 UI 不可见的 file，其 chunk/文件名/来源不得出现在任何 AI 问答可检索路径）能否成立的根基。设计上同时守住两条安全原则：

存疑必回落：任何无法确定"是否有更近绑定"的情形，必须回落完整逐项评估（fail-closed），不得放行；
owner 短路不可省：如果漏掉 owner 短路，owner 会看不到自己刚上传的文件（false-negative）——因为 owner 经ownertuple 在叶级 nearest-wins，永远可见。

4. 正确性验证：真实数据等价校验（安全红线的实战检验）

对用户 sarah（user 1）/ space 57，分别在flag OFF（完整逐项）与flag ON（快速通道）下抓取/children的 4 个变体，比较返回的文件 id 集合：

变体	OFF count	ON count	id 集合
`page_size=500`	98	98	完全一致
`&file_status=2`	98	98	完全一致
`&file_type=1`	98	98	完全一致
`&file_type=0`	0	0	一致

→FINGERPRINT 逐位相等：快速通道与原路径返回相同可见集。

本次校验的局限也需要如实记录：sarah 为 admin、space 57 文件均无 binding（走继承/owner 分支）；叶级 binding 分支由单测覆盖，未在 109 用"有 binding 的空间 + 非 admin 用户"做端到端 diff。这一缺口在后续轮次已通过新增单测补齐（见第 6 节）。

5. 性能结果：P50 提升 ~14.5 倍，稳定亚秒级

压测口径：20 并发 × 6 轮 = 120 请求，接口/children?page_size=20。

配置	p50	p95	p99	min	max
原始基线（未改造，早前实测）	~4.5s（20并发）/ 22–24s（Locust 持续）	—	—	—	—
FLAG OFF（③ + 完整逐项）	4.898s	5.038s	5.105s	4.151s	5.121s
FLAG ON（①③ 快速通道）	0.338s	0.587s	0.615s	0.155s	0.644s

关键结论：

① 快速通道：p50 提升 ~14.5×（4.898 → 0.338s）、p95 提升 ~8.6×，并发下稳定在亚秒级；
③ 单独贡献有限：FLAG OFF ≈ 原始基线，因为本环境 bindings 仅 42 条，线性扫描本就不是瓶颈；
真正消除 704% CPU 的是 ①：多数项不再做逐项评估 + 不再每项 2 次get_*_permission_level；
对照原始 Locust 持续压测的 22–24s，①③ 把同口径接口压到亚秒级，满足 AC-08 的"P50 较改造前下降 ≥70%"基准。

6. 源码级解读：快速通道与索引的实现落点

6.1 快速通道：`_filter_visible_child_items`

优化后的默认且唯一路径实现在 knowledge_space_service.py 的_filter_visible_child_items，其核心分发逻辑与文档描述一一对应：

async def can_view(item: KnowledgeFile) -> bool: object_type = "folder" if item.file_type == FileType.DIR.value else "knowledge_file" permission_id = "view_folder" if item.file_type == FileType.DIR.value else "view_file" if (object_type, str(item.id)) in bound_ff: # ① 叶级有绑定 → 完整逐项评估 ...return permission_id in effective_permissions item_owner = getattr(item, "user_id", None) if item_owner is not None and item_owner == user_id: # ① owner 短路 return True ancestor_ids = [int(p) for p in (item.file_level_path or "").split("/") if p] return permission_id in await chain_perms(ancestor_ids) # ① 继承父链决策（memo）

几个值得注意的实现细节：

bound_ff = {key for key in binding_index if key[0] in ("knowledge_file", "folder")}：由 bindings 索引直接派生的"有绑定资源集"，键统一为字符串形式的 resource_id，与str(item.id)查找对齐（test_f036_invariant.py 专门锁定了这一 stringify 约定）；
chain_cache: dict[tuple[int, ...], set[str]]：父链决策 memo，同一祖先链只算一次，且是请求内结构，不跨请求；
semaphore（_CHILD_PERMISSION_CHECK_CONCURRENCY）继续保留，控制完整评估的并发度；
旧的完整逐项路径_filter_visible_child_items_reference（L2463-L2490）不在热路径，仅作为等价测试 oracle / 文档化兜底保留。

6.2 索引构建与索引化解析：`FineGrainedPermissionService`

build_binding_index（fine_grained_permission_service.py）的实现非常精简：

index: dict[tuple[str, str], list[dict]] = {} for binding in bindings: key = (binding.get("resource_type"), str(binding.get("resource_id"))) index.setdefault(key, []).append(binding) return index

分组键(resource_type, str(resource_id))，组内保持原列表顺序——这是"首个匹配 wins"语义不变的关键；
每请求构建一次、随context下传，请求结束即弃。

_resolve_binding_for_tuple（L337 起）与_permission_ids_from_bindings（L278 起）在传入binding_index时只迭代binding_index.get((resource_type, str(resource_id)), [])命中组；内部原有的 resource_type/resource_id 校验被刻意保留，保证线性路径（binding_index=None）与索引路径逐字节等价——这正是 test_f036_binding_index.py 用"线性路径本身当 oracle"做行为保持验证的基础。

6.3 请求级数据结构全景

结构	形态	生命周期	用途
有绑定资源集（bound_ff）	`set[(resource_type, resource_id)]`，由本请求 bindings 派生	单请求	① 判定项 lineage 是否含更近绑定
bindings 索引	`dict[(resource_type, str(resource_id))] → list[binding]`（保序）	单请求	③ O(1) 解析
请求级`tuple_cache`	`dict[tuple_object → list[tuple]]`（既有，按对象去重；祖先/空间天然共享）	单请求	避免重复`read_tuples`（非批量预取）
父链决策（memo）	`dict[祖先 id 元组 → set[permission_id]]`	单请求	① 同一祖先链只算一次

对外契约零变化：/children、/search的 request/response 结构与语义不变（cursor 协议沿用 F027 的 INV-6）。

7. 测试与回归保障：四个测试文件守住四条线

F036 的等价性保障由四组测试构成，覆盖从"分发逻辑"到"真实评估"再到"不变量闭环"的完整层次：

测试文件	覆盖点
test/knowledge/test_f036_child_fastpath_equivalence.py	分发等价：owner 短路 / 叶级 binding 走完整评估不走链 / 否则走链；用 mock 的评估函数在同一 oracle 下断言`_filter_visible_child_items`==`_filter_visible_child_items_reference`；`test_owner_shortcircuit_required`守护"owner 链不可见也必须显示"的回归
test/knowledge/test_f036_real_eval_equivalence.py	真实 FGPS 评估（InMemoryOpenFGA + 真实 binding/model 解析）下，非 admin 用户 + "空间只授 view_space"受限场景，fast == reference 逐位相等——覆盖"空间 view ≠ 文件 view"、单独授权文件/文件夹、owner、继承不可见
test/permission/test_f036_binding_index.py	③ 索引与线性扫描逐位等价、保序（同键多条时"首个匹配 wins"顺序不变）、部门 include_children 前缀匹配
test/permission/test_f036_invariant.py	锁定"授权 binding ↔ fast-path bound_ff"闭环：被授权的 file/folder 必进 bound_ff、必走完整评估；空间级 binding 不进 bound_ff（由链评估处理）；resource_id 统一 stringify

其中test_f036_real_eval_equivalence.py正是补齐了压测报告"本次校验局限"中"有 binding 空间 + 非 admin 用户"的真实 eval 等价缺口，test_f036_invariant.py则把"非 owner 授权必有 binding"这条不变量从口头约定固化为可执行测试。

8. 结论与建议：优化如何从"开关"走向"默认唯一路径"

8.1 最终落地形态

① 是关键优化，且经真实数据验证可见集等价；已按决定去掉开关BS_REBAC_CHILD_FASTPATH，优化逻辑成为默认且唯一路径——完整逐项_filter_visible_child_items_reference保留作等价测试 oracle / 兜底。报告中"flag OFF/ON"是当时为 A/B 压测临时切换的方式，最终版本无开关。
已补测试缺口：① "有 binding 空间 + 非 admin 用户"真实 eval 等价（test_f036_real_eval_equivalence）；② "授权 binding ↔ fast-path bound_ff"闭环（test_f036_invariant）。
③ 保留（零风险、O(1) 解析），在 bindings 规模增大的租户上收益会更明显。
残留非阻断建议：authorize 写路径加 arch-guard 强制"非 owner 授权必带 model_id（⟹ 写 binding）"，把不变量从"测试守护"升级为"代码强制"。

8.2 对后续迭代的启示（design.md §8）

跨请求缓存仅当profiling 证明"每请求上下文构建"成为新瓶颈才考虑，且必须用读侧版本派生 key 的解耦方式；
count_folder（每文件夹一次聚合查询）本期未并入，若成新热点，下一步批量化为单查询GROUP BY 父路径；
不做"最终可见判定"级缓存（user×item）——失效复杂、越权风险高；
OpenFGA 服务端扩容 / 只读副本属于容量侧议题，另议。

附录：复现实命令骨架

压测报告附带的命令骨架可直接用于复现（20 并发 × 6 轮，取 p50/p95/p99/min/max）：

# 20 并发 × 6 轮，取 p50/p95/p99/min/max for r in $(seq 1 6); do for i in $(seq 1 20); do (curl -s -m120 -o /dev/null -w '%{time_total}\n' -H "Cookie: $TK" \ 'http://localhost:7865/api/v1/knowledge/space/57/children?page_size=20' >> /tmp/t) & done; wait; done sort -n /tmp/t | awk '{a[NR]=$1} END{print "p50="a[int(NR*.5)]" p95="a[int(NR*.95)]" max="a[NR]}' # flag 切换：sed 改 BS_REBAC_CHILD_FASTPATH 默认值 + docker restart bisheng-backend-dm

注意：命令骨架中的 flag 切换仅在当时的 A/B 压测版本有效；最终合入版本已移除开关，快速通道为默认且唯一路径。压测时用$TK环境变量携带 Cookie（压测报告特别注明不把字面 token 写入仓库），并通过docker stats观察 backend CPU 是否从 ~704% 显著回落来验证优化效果。

BISHENG F036 实战：知识空间子项列表 ReBAC 逐项评估优化，P50 从 22 秒压到亚秒级