本页目录展开
iWiki 是集市的企业知识库:用「空间 → 页面树 → 页面正文」组织文档,支持实时协同和普通文档两种写作方式,带版本回溯、按权限过滤的 AI 问答,还能把 Git 仓库转成文档、对外提供 MCP 服务。仓库是 monorepo:apps/iwiki-api(Express + SQLite)、apps/iwiki-web(Vue 3)、apps/iwiki-mcp、packages/sse-ui,后端约 3.7 万行 TypeScript。这篇按「内容怎么组织、协作怎么不打架、权限和检索怎么做对」三件事讲。
空间与页面树
个人空间与共享空间
用户注册后自动有个人空间,个人空间 ID 由用户 ID 派生(personalSpaceId(userId))。共享空间可以挂在其他空间下,形成多级知识库;spaces 表靠 parent_id 和 owner_id 表达这两件事。
发布走一条很窄的路径:只有「我的个人空间 → 共享空间」允许发布,逻辑在 src/services/page-publish.ts 的 publishPageToSpace。它校验源页面确实属于当前用户的个人空间,然后改写同一条 pages 记录的 space_id 和可见性,不复制数据——所以发布之后旧链接依然有效。
目录树与删除语义
页面树用 pages.parent_id 自引用。关键在删除行为:父页面被删时子页面不跟着删,而是上提为根,所以外键用 ON DELETE SET NULL;空间删除才用 ON DELETE CASCADE。
1 | -- src/db/init.ts |
拖拽移动后要调 invalidateCatalogAfterMove 让目录缓存失效,否则前端会继续拿到旧树。新建页面(src/services/page-create.ts)依次校验:空间存在(404)、有权在该空间建页(403)、父页面属于同一空间且可见。最后一条最容易漏——只校验父页面存在,就能把 A 空间的页面挂到 B 空间树下,目录渲染时泄露标题。
删除空间是级联操作:src/services/space-tree.ts 的 deleteSpaceCascade 先收集子树空间 ID 和页面 ID,再在一个事务里删 RAG 分块、删页面、删挂在空间上的收集记录,最后删空间。向量分块必须显式删,因为 SQLite 外键级联覆盖不到向量索引表,漏删会留下「搜得到但打不开」的孤儿向量。空间还有配额:space_quotas 记上限,space-quota.ts 在建页和上传时检查,根空间用 countVisiblePagesByRoot 汇总子树用量,超限返回 403 并带上当前用量。
编辑、版本与冲突
两种协作模式
pages.collab_mode 只有两个值:collab(默认,Yjs 实时协同,最后发布者为准)和 normal(单人编辑,保存时三路合并)。分两种模式是刻意的:长文档、多人同时改适合 CRDT;表格、PPT 这类结构化内容用单人编辑加合并,避免让 CRDT 去处理复杂属性。
草稿分两层:浏览器本地草稿保证刷新不丢,云草稿存 page_drafts,主键是 (page_id, user_id)。按「页面 + 用户」而不是只按页面存,否则两个人同时编辑会互相覆盖草稿。
版本链:快照加反向 diff
wiki_revision 每版一条记录。is_snapshot 标记全量快照,其余版本存 reverse_diff——从后一版回退到这一版的差分。回滚频率远低于前进,存反向 diff 让「从最新版退到任意历史版」变成顺序重放,不必先重建全量再算差。expire_mark 供清理任务识别可回收版本,另有 idx_rev_page_no 与 idx_rev_expire 两个索引。
1 | -- src/db/init.ts |
config_snapshot 必须和正文同版本落库。表格、PPT 的正文只是占位,真实数据在配置里;只存正文,回滚后格式会全丢。
三路合并
普通文档用 node-diff3 的 diff3Merge(ours, base, theirs):base 是打开时的基线,ours 是用户草稿,theirs 是线上最新。无冲突块直接拼接,冲突块包成 Git 风格标记,同时记录行号区间给前端逐块选择。
1 | // src/services/collab/merge-service.ts |
合并必须按行切,按字符切会让中文冲突区间错位,前端无法定位到块。另有一个 hasConflictMarkers 单独导出,用来判断用户手改的正文里是否残留 <<<<<<<,避免把冲突标记直接发布出去。
编辑锁、冲突草稿与 Yjs 种子
普通文档被他人编辑时提示「XX 正在编辑」。wiki_edit_lock 以 page_id 唯一,记录持有者和 expire_ts,拿不到锁进只读。锁必须有 TTL:浏览器崩溃不会发解锁请求,没有过期时间就等于把文档永久锁死。
合并到一半离开,草稿和冲突块存 wiki_temp_draft,按 (page_id, user_id) 唯一,带 base_rev_no、conflict_draft、conflict_json 和过期时间。base_rev_no 不能省——只存冲突文本,下次打开无法判断线上又前进了几版。
实时协同这边,服务端在 yjs_docs.ydoc_state 持有 Yjs 文档二进制,并用 base_rev_no 记录它对应哪个版本。开房前必须先决定种子来源:
1 | // src/collab/yjs-server.ts |
快照可能落后于版本链(进程在落盘前崩了),不能无条件信任 BLOB。另外 collab_mode='normal' 的文档不会给 editor 权限(return page.collabMode === 'normal' ? 'viewer' : 'editor'),避免 CRDT 和三路合并同时作用于一篇文档。
权限体系
可见性由几个来源合成:pages.visibility(公开/私密/指定成员/团队可见)、页级白名单 page_allowed_users、空间级白名单 space_allowed_users、团队可见(getAllowedPageTeams),再加空间上的 allow_all_edit 开关。白名单表要用 (page_id, user_id) 复合主键;只建自增 ID 时,重复授权会插入多行,权限查询结果集越滚越大。
目录、搜索、AI 问答都只返回「我可见」的内容。src/services/permission.ts 的 getAllowedUserIdsByPage(pageIds) 一次查多页白名单,避免逐页查库;SQLite 单语句占位符默认上限 999,所以传进来的 ID 列表要经 chunkIds 分批。分批不是为了更快,是因为不分批会直接报错。
团队加入有三态 teams.join_mode,分流逻辑在 src/services/team-join.ts 的 joinOrApply:open 直接建成员关系并通知,approval 建待审记录(已存在则复用),closed 拒绝。normalizeJoinMode 的默认值必须是 approval——历史数据缺字段时默认放行,等于把团队直接公开。访问申请则分两张表:access_requests 记录「谁申请了什么、理由、状态」,access_grants 记录最终给到的权限和期限,申请可以有多轮,授权是最终态。审计由 src/services/audit-log.ts 的 record(actorId, action, target, detail) 写入:audit_logs 追加记录操作者、动作、对象,管理台和 API 调用都记。
评论与批注
页面评论在 src/services/page-comments.ts,page_comments 单表带 parent_id 的两级结构;page_comment_settings 存每页的评论开关和数量上限。上限一定要有硬边界(MIN_MAX_COMMENTS / MAX_MAX_COMMENTS 等常量),只校验「不超过用户设的值」,用户设 1e9 就等于没有上限。
段评(批注)的难点是定位。page_annotations 不只存 start_offset / end_offset,还存选中的原文 quote 和前后文 prefix / suffix,外加结构化锚点 anchor_json。正文一改 offset 就失效,这时用 quote 加前后文重新找位置,属于锚点降级。startOffset 用 -1 表示未知,不能默认 0,否则所有降级批注都会堆到文档开头。批注可选带 comment_id,把「一条评论」和「一段文字」关联起来。
检索与 AI
索引写入
发布文档后,indexPage 负责切块、向量化入库。它先读当前页面,确认内容仍是最新版本;写入前再查一次,latest_rev_no 和正文都一致才继续,否则直接放弃。原因是并发索引同一页时,旧任务可能在新任务之后落库,把新分块删掉。
1 | // src/services/rag-index.ts |
混合检索与权限
retrieveForQuestion 优先走向量,异常时降级 BM25 关键词,两条路共用同一套权限过滤。向量服务没配或临时挂了,不该让整个问答不可用,所以降级要静默,不能直接抛错。
1 | // src/services/ai-rag.ts |
KNN 在 sqlite-vec 扩展上做(searchChunksKnn),候选集先按可见页集合过滤再算距离。反过来先全库搜再过滤,既浪费算力,又可能过滤后数量不够而漏召回。分块 ID 同样按 chunkIds 分批,绕开变量上限。
没有召回时,buildRagSystemPrompt 明确要求模型回答「知识库中没有找到相关内容」,可以建议换关键词,但不许编造。
文件知识源与模型配置
PDF、课件走 rag_files:以文件内容 SHA 为主键,同一份文件多次上传只索引一次;ocr_state / ocr_task / attempts 管理 OCR 队列与重试,扫描件转成文本后逐页存进 file_page_texts 再切块。attempts 是必要的,否则坏文件会无限重排。
模型与自定义端点由 ai-models.ts 和 ai-custom-endpoints.ts 管理,凭证加密在 secret-crypto.ts,密钥轮换时的存量迁移在 secret-migration.ts。
CodeWiki
用户贴 Git 地址、选模型、提交,系统拉仓库、过滤无关文件、按需探索、生成文档、审校后落盘。任务面用三张表:code_wikis(仓库、模型、状态、进度)、code_wiki_jobs(阶段任务)、code_wiki_files(产出文件),code_wiki_pro_usage 记用量;code-wiki-queue.ts 控并发,code-wiki-quota.ts 和 code_wiki_quota_requests 控配额与提额申请。
runCodeWikiPipeline(id, mode) 按阶段推进,mode 区分首次生成(generate)和增量更新(update),每步都写进度并打心跳供前端轮询。code-wiki-checkpoint.ts 把已完成阶段写入检查点,进程重启后从断点续跑,不重复拉仓库、不重复调模型——长任务的主要成本就是模型调用。
一个反直觉的细节:解析模型时用 resolveCodeWikiModelId(..., { bypassUserAccess: true })。任务可能在提交者失去模型权限之后才执行,不绕过权限,历史任务会因权限变更随机失败。探索阶段由 code-wiki-explore.ts 让模型决定读哪些文件,不全量塞入上下文;code-wiki-reviewer.ts 审校产出,code-wiki-filter.ts 过滤无关文件。
开放能力
API Token 在个人设置里创建,前缀 API_TOKEN_PREFIX 标识类型,随机 24 字节。每个用户最多 MAX_ACTIVE_TOKENS_PER_USER 个有效 Token,超出时报错并要求先吊销。
1 | // src/services/api-token.ts |
吊销只置 revoked_at、不删记录,保留审计线索;计数也只算未吊销的。MCP 服务由 src/mcp/server.ts 的 buildMcpServer(userId, ctx, scope) 按当前授权用户构造工具集,scope='read' 只挂只读工具,所有工具内部走同一套权限过滤。这里要记住:MCP 的权限边界就是 Token 所属用户,工具不做二次授权,Token 泄露等于该用户的全部文档权限。
上传走三段式:upload-validation.ts 校验类型和大小,upload-store.ts 落存储,upload-handler.ts 返回可访问 URL;image-bed.ts 对接图床服务。
其他内容与后台
作业用四张表拆开:assignment_collections(收集/作业)、assignment_submissions(提交)、space_assignment_roles(空间内作业角色)、assignment_reminders(提醒计划),提醒由 assignment-reminder.ts 定时扫描。收集和提交必须分表,否则截止时间、要求这类字段会在每条提交上重复,改一次要全表更新。表单、活动、公告、竞赛、讨论各自独立路由与表,共用权限和通知基础设施;研究空间以「项目 + 会议」组织,材料存 research-assets。
后台由 platform_admins 记录管理员,platform_settings 存全局开关,admin.ts 路由统一挂管理员校验。管理员身份单独建表,不要复用 users.role:用户表角色是业务概念,混进平台管理权限后,任何一次「改角色」都可能变成提权。
面试速答
- 协作双模式:
collab走 Yjs CRDT(yjs_docs+base_rev_no),normal走编辑锁加三路合并(wiki_edit_lock+wiki_temp_draft);普通文档不给 editor 权限,避免两套机制打架。 - 版本链:
wiki_revision存快照与反向 diff;config_snapshot与正文同版本,保住结构化页面的格式。 - 权限:页级白名单、空间白名单、团队可见三源合成;批量查询用
chunkIds分片,规避 SQLite 999 个变量上限。 - RAG:向量优先、BM25 降级;KNN 先按可见页过滤再算距离;索引写入前双重校验版本号,防止旧任务覆盖新分块。
- CodeWiki:主任务、阶段任务、结果文件三表;检查点按阶段落盘,模型解析绕过提交者权限,避免历史任务因权限变更失败。
- 开放能力:API Token 有前缀和数量上限,吊销保留记录;MCP 权限等价于 Token 所属用户。
→ 下一篇:UniSSO:统一身份





