WeKnora 文档权限控制完整指南：如何用 5 分钟配好 RBAC 角色与多租户数据隔离

WeKnora 文档权限控制完整指南如何用 5 分钟配好 RBAC 角色与多租户数据隔离【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora打开同一个知识库你能浏览、同事能编辑、而陌生人只会被 403 挡在门外——这就是 WeKnora 文档权限控制的日常。本指南从真实协作痛点出发带你用 6 个步骤走通 RBAC基于角色的访问控制与多租户数据隔离的完整链路让你 5 分钟内给自己空间配好权限。同一份文档不同的权利为什么需要权限控制想象这个场景你搭了一个团队共享的 WeKnora 知识库把产品文档、合同、周报都丢了进去。三个月后实习生误删了核心知识库外部合作方却能看到不该看的合同。问题不在进没进门而在进门之后能走到哪一层。WeKnora 把这套权限体系设计成类似小区管理的三层结构门禁卡认证确认你是谁。没有卡连小区大门都进不去工牌授权确认你能干什么。访客、住户、物业、业主工牌颜色不一样能开的门就不一样楼层分区数据隔离确认你在哪栋楼。A 栋住户永远摸不到 B 栋的门把手。接下来我们用一张表把这三件事钉死。一张对照表快速看懂认证、授权、数据隔离的分工层次生活类比回答的问题WeKnora 的实现方式出错时你看到什么认证门禁卡你是谁JWT Bearer 令牌网页登录或 X-API-Key脚本集成401 Unauthorized授权RBAC工牌你能干什么viewer / contributor / admin / owner 四级角色 资源归属creator_id403 Forbidden数据隔离楼层分区你在哪栋楼空间tenantID 注入请求上下文所有查询按 tenant_id 过滤404 或 TENANT_REQUIRED关键认知三层是串行关卡不是三选一。一个请求必须先刷门禁、再查工牌最后才允许进楼层。任何一层不通过请求都会被拦下且每一层的拦截行为你都能通过状态码区分401 是没登录403 是权限不够。跟着一个请求走完全程我们拿用户小赵打开知识库列表页当例子把整个链路走一遍。第 1 步登录换门禁卡。小赵在登录页提交邮箱密码后服务端发回一对令牌短期有效的 access_token 和长期有效的 refresh_token。access_token 就是他的门禁卡过期前可以反复刷。第 2 步请求带上卡片。之后每次请求前端都在请求头里带上这张卡。认证中间件会按固定顺序处理先查白名单登录、健康检查这类公开接口直接放行再验证 JWT// internal/middleware/auth.go 核心流程简化 if token, ok : bearerToken(c); ok { user, err : userService.ValidateToken(ctx, token) if err nil { applyAuthSession(c, session) // 用户空间角色写入上下文 c.Next() } } // JWT 无效时再尝试 X-API-Key最后都失败才返回 401第 3 步确认楼层。JWT 验证只是认出小赵还要确定这次操作属于哪个空间。判定优先级是X-Tenant-ID请求头 JWT 里的空间声明 小赵的第一个有效成员身份。这也是前端空间切换器能工作的前提——第 4 步查工牌。中间件在小赵要访问的空间里查成员表tenant_members解析出他的角色连同用户、空间一起挂进请求上下文。如果小赵在这个空间压根没有成员记录强制鉴权模式下直接 403。第 5 步数据层的自动过滤。到了业务层和数据库层空间 ID 已经躺在上下文里所有查询都会自动带上tenant_id ?条件——这就是多租户数据隔离落到代码里的样子不是每个开发手动记着加条件而是上下文一路带下来层层自动过滤。第 6 步留痕。如果小赵角色不足被拒这次拒绝会写进 audit_logs 审计表带 1 分钟去重防刷表事后可追溯。整个链路下来认证、授权、隔离三层各司其职谁也没越权。一张表看懂角色从只读到 Owner 的权限边界WeKnora 的空间角色是一个刻意保持精简的四级矩阵高角色自动继承低角色的全部权限角色身份比喻能读什么能改什么典型使用场景viewer 只读访客空间内全部内容什么都不能改只查阅、只提问的成员contributor 贡献者住户空间内全部内容自己创建的知识库、Agent 及其子资源上传文档、维护自己那一摊admin 管理员物业空间内全部内容空间内任意资源 管理成员空间运维、配置模型/存储/向量库owner 所有者业主全部admin 全部 可删除空间空间创建者每个空间至少一位这张表里最精巧的是 contributor 一行的加粗部分——归属模型。除了角色这一道闸WeKnora 还给每个知识库记了一个 creator_id 创建者。判定写权限的规则是我是这条资源的创建者或者我至少是 admin满足其一即可。于是Contributor 在自己的 KB 里像 Owner在别人的 KB 里像 Viewer就自然成立了子资源文档块、FAQ、标签则顺着归属链回溯到知识库的创建者。两个特殊身份值得你记住API Key 调用X-API-Key 认证的虚拟用户在所属空间内固定按 Admin 对待脚本集成不需要为角色操心跨空间超管开启跨空间访问后特定用户可用X-Tenant-ID切到任意空间按 Admin 权限操作。把权限调到既安全又顺手配置都在 config/config.yaml 里核心就三个开关tenant: enable_rbac: true # 强制鉴权false 进入只记录不拦截灰度 auth: registration_mode: invite_only # 关闭公开注册只走邀请链接 audit: retention_days: 90 # 审计日志保留天数给你四条可落地的建议灰度上线别硬切。担心升级后权限收紧伤到现有脚本先把enable_rbac设为 false 跑几天观察日志里已记录但未强制的拒绝项逐条修正成员角色后再切回 true。回滚只需改回 false 重启。企业部署关掉公开注册。默认 self_serve 允许任何人注册并自建空间适合个人学习团队环境改成 invite_only 后登录页注册入口会自动消失所有新成员必须通过管理员发出的邀请进入。人机分权。人用 JWT 登录走角色体系脚本用 API Key 走 Admin 通道。这样脚本挂了、Key 泄露的影响面和真人误操作的排查路径是两条线好查得多。审计日志是排障利器。每次成员增删、角色变更、越权拒绝都有记录保留 90 天起步安全事件倒查时它就是你最好的时间线。另外两个底层保障不用你操心但值得知道密码以强哈希存储且 API 响应里永远不序列化令牌支持 Logout 撤销refresh_token 过期需重新登录。新手最常踩的 4 个坑坑一升级后空间里找不到 Admin人人都是 Contributor回填逻辑会把最早活跃的用户选为 Owner其余统一成 Contributor。如果那个最早的用户是机器人或共用账号把机器人降级、真人提升即可每次调整都会进审计日志。坑二切到强制鉴权后某个脚本突然 403大概率是脚本对应的人类成员角色不够。两条出路把该用户提升为 Admin或者脚本改用 X-API-Key 调用Key 在所属空间固定 Admin。坑三共享空间会不会绕过空间 RBAC不会。共享空间是横向的协作通道空间 RBAC 是纵向的纵深防御任何跨空间的写操作要同时穿过两道闸口。哪怕 KB 被以可写共享过来若源空间里它属于仅 Admin 可写外空间成员也只能读。坑四审计表里怎么有的 403 找不到记录两种可能同一来源的拒绝在 1 分钟滑动窗口内只写一行防恶意探测刷表或者你还处在 enable_rbacfalse 的灰度模式此时不写拒绝记录。完整的逐条序列在应用日志里永远可见。现在轮到你了权限体系的最终目的不是锁死一切而是让谁能看、谁能改变成一件确定且可预期的事——门禁管住入口工牌划清边界楼层分区守住数据审计日志兜住底。下一步很具体打开成员管理页给你的第一位同事分配合适的角色然后观察一次 403 是如何被记录下来的。配置细节可对照 docs/RBAC说明.md 与 docs/共享空间说明.md权限链路的源码在 internal/middleware/auth.go 和 internal/handler/auth.go。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考