OpenViking ACL 实战如何给共享资源目录授权用户组并用 restricted 模式切断继承【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking在多用户的 OpenViking account 中viking://resources/...共享资源目录默认向整个 account 开放。如果你只想让特定用户组读写某个共享目录并且希望某个子目录不再继承上级目录放开的权限需要用 OpenViking 的 ACL 功能给目录直接授权group:{group_id}再在子目录上切换到restricted模式。本文按「开启 ACL 开关 → 建组加人 → 授权 → 切断继承 → 核对有效权限」的顺序给出一条可照做的操作路径。以下内容基于 ACL 概念文档、ACL API 文档 和 Admin API 文档。示例中的 account、用户组和用户名acme、engineering、alice、bob沿用文档示例执行时替换为你环境中的实际值。先确认目标资源和操作身份在动手前核对两个前提它们决定命令能否执行成功ACL 只作用于共享资源viking://resources/...。个人私有区viking://user/{user_id}/resources/...不接受 ACLviking://resources本身是固定共享 scope不能设置直接 ACL授权从它下面的文件和目录开始。所有 ACL 修改接口都要求调用者对目标节点拥有manage权限共享资源由 accountADMIN隐式管理。权限分三级read读取、列目录、find/search/grep、write在read基础上可写入、创建、删除或移动文件、修改 tags、manage在write基础上可删除或移动目录、管理 ACL。高等级包含低等级能力。CLI 侧的调用身份来自~/.openviking/ovcli.conf{ url: http://localhost:1933, api_key: alice-user-key, root_api_key: your-root-api-key, ... }其中api_key是执行 ACL 数据命令ov acl ...所用身份root_api_key用于--sudo管理命令。--sudo仅适用于ov admin、ov system、ov reindex、ov task status/list等管理命令对普通数据命令使用会报错所以 ACL 授权本身用具有manage权限的api_key例如 account 管理员的 key执行即可。开启账号级 ACL 开关账号级acl.enabled默认为false。关闭时共享资源完全使用原有 URI namespace 可见性规则不解析或校验 ACL也不为新建内容写入 ACL。ROOT 可管理任意 accountADMIN 仅可管理自己所属的 account。CLI 方式需要root_api_keyov --sudo admin set-account-settings acme --acl-enabled trueHTTP 方式ROOT 或本 account 的 ADMIN 均可调用PATCH /api/v1/admin/accounts/{account_id}/settings Content-Type: application/json { acl: {enabled: true} }开启后需要注意文档明确的生效范围新建的共享文件、目录和add-resource根节点会给创建者直接manage并从父目录继承 ACL已有且未设置 ACL 的内容不会迁移或改权仍按公开规则访问重新关闭开关后已有 ACL 也不再参与访问判断覆盖已有配置前内核会先把设置备份到/local/{account_id}/_system/setting.backup.json。创建用户组并添加成员用户组属于单个 account用于通过一个 ACL principal 授权多个用户。group_id由调用者创建时指定使用与user_id相同的标识符规则是 account 内唯一且稳定的标识没有单独的组名。组内只能加入当前 account 已存在的用户不支持嵌套组也不支持group:*这种通配 principal。创建空组并向其中加入成员--sudo走root_api_key本 account 的 ADMIN 也有「管理用户组和成员」的权限ov --sudo admin create-group acme engineering ov --sudo admin add-group-member acme engineering alice成员添加是幂等的重复调用返回addedtrue移除成员重复调用返回removedfalse。成员关系从下一次请求开始生效服务端把它并入每次请求的RequestContext.group_ids不会重写资源 ACL 或 context 记录。用户被删除时会自动退出所有组用户组必须为空才能删除。可以用 Admin API 中列出的成员查询接口核对{account_id}、{group_id}替换为实际值key 用 ROOT 或本 account ADMIN 的curl http://localhost:1933/api/v1/admin/accounts/acme/groups/engineering/members \ -H X-API-Key: root-or-admin-key给共享目录授权用户组对目标目录执行grant把group:engineering的直接权限级别设为writeov acl grant viking://resources/project-a \ --principal group:engineering \ --level write该命令的语义是把engineering组在当前节点上的直接 level 设置为write如果该 principal 已有直接条目则更新该条目其他 principal 的条目不变。目录上的 ACL 授权会被所有后代继承所以该命令执行后project-a下的子目录和文件默认对组内成员可写。如果不想用 CLI等价路径是 HTTP 或 SDKcurl -X POST http://localhost:1933/api/v1/acl/grant \ -H Content-Type: application/json \ -H X-API-Key: your-key \ -d { uri: viking://resources/project-a, principal: group:engineering, level: write }report client.acl_grant( viking://resources/project-a, principalgroup:engineering, levelwrite, )这里的your-key必须是对目标节点有manage权限的调用者的 key。用 restricted 模式切断继承默认继承规则是「协作文档式」的普通节点合并 direct 与 inherited后代继承的是父节点当前的有效权限。如果project-a上层目录已经放开了某些权限project-a下的子目录也会一并继承。要切断继承把目标子目录切到restricted模式ov acl set viking://resources/project-a/sub \ --acl-mode restricted \ --entry group:engineeringwrite--entry完整替换当前节点的直接权限--acl-mode restricted表示该节点只使用直接权限。文档给出的行为要点公式上effective(node) direct(node) (acl_mode restricted ? empty : inherited(node))。restricted 节点只认 direct。inherited字段不会被删除即使节点处于 restricted 模式它仍保存并随父节点继续更新父目录的有效权限。恢复继承后立即使用最新 inherited。后代继承的是当前节点的有效权限因此不会绕过中间的 restricted 边界。restricted 节点即使没有直接权限也不会变公开其没有单独授权的后代同样不可访问account 管理员仍有隐式管理权。有manage权限的用户只能切换inherit/restricted不能直接设置none绕过父目录权限。概念文档中的例子可以帮你判断效果假如 Bob 在上层A上有read把A/B设为 restricted 后Bob 在A上的权限不会对A/B及其后代生效删除 restricted 后Bob 立即恢复从A继承的权限。只想切换模式、不改直接授权时# 恢复继承 ov acl set viking://resources/project-a/sub --acl-mode inherit验证有效权限验证用 GET 接口也可以在目标尚无 context 记录时返回结果此时direct_entries为空继承权限从已有祖先 context 计算curl http://localhost:1933/api/v1/acl?uriviking%3A%2F%2Fresources%2Fproject-a \ -H X-API-Key: your-keyreport client.acl_get(viking://resources/project-a)返回的 ACL report 分四组字段判断授权是否生效就看这里字段含义direct_entries只包含当前节点直接设置的条目inherited_entries父节点当前的有效权限restricted 期间也会继续更新effective_entriesinherit 时合并 direct 与 inheritedrestricted 时仅使用 directacl_modenone/inherit/restricted决定 inherited 是否参与有效权限文档给出的报告示例示例结果实际条目取决于你设置的授权{ uri: viking://resources/project-a, acl_mode: inherit, direct_entries: [ {principal: user:bob, level: read} ], inherited_entries: [ {principal: group:engineering, level: write} ], effective_entries: [ {principal: group:engineering, level: write}, {principal: user:bob, level: read} ] }对照检查点被授权的group:engineering出现在direct_entries授权目录本身或effective_entries继承它的后代节点中切了 restricted 的节点上acl_mode为restricted且effective_entries只包含直接授权。注意 accountADMIN的隐式manage不出现在这些列表中这是正常现象。常见报错与回退操作ACL 接口先校验manage再向已授权调用者确认 URI 是否存在。文档给出的错误对照场景错误URI 不在viking://resources/...INVALID_ARGUMENT调用者没有 managePERMISSION_DENIED已授权调用者访问不存在的 URINOT_FOUND修改 ACL 时 URI 尚无 context 记录INVALID_ARGUMENT需先完成索引principal格式非法或使用group:*INVALID_ARGUMENTlevel 不是read/write/manageINVALID_ARGUMENTacl_mode不是inherit/restricted或请求包含 inherited 等只读字段INVALID_ARGUMENT其中「URI 尚无 context 记录」是最容易踩到的一条对刚建出来还没有内容的空目录执行修改类 ACL 接口会失败需要先让目标完成索引再授权。回退操作按粒度选择# 只删除某个 principal 在当前节点上的直接授权从祖先继承的权限不受影响 ov acl revoke viking://resources/project-a --principal user:bob # 清空当前节点的直接 ACL 并退出 restricted不会删除已保存的 inherited也不删除后代节点的直接 ACL ov acl rm viking://resources/project-a清空后立即使用最新继承权限如果父目录也不受 ACL 控制acl_mode恢复为none。边界与限制ACL 不改变 account 隔离任何授权都只在当前 account 内生效。不支持group:*用户组是平铺结构。删除用户组后旧 principal 不再匹配请求除非重新创建同一个group_id。检索侧检索 target URI 只是搜索范围不要求调用者能够读取 target 节点本身用户即使不能读取中间目录也可以检索到深层单独授权给自己的文件而list、tree和批量结果仍逐个检查有效 ACL。共享区内部移动时节点自己的 direct ACL 和 restricted 状态随节点移动inherited 按新父节点重新计算个人资源移入共享区时不携带 ACL只继承目标目录权限共享资源移回个人区时清空 ACL。完成以上步骤后你的共享目录就处于「用户组按 direct 授权访问、指定子目录以 restricted 切断继承」的状态后续核对权限变化始终以 GET 接口返回的effective_entries为准。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考