本页目录展开
  1. 空间与页面树
    1. 个人空间与共享空间
    2. 目录树与删除语义
  2. 编辑、版本与冲突
    1. 两种协作模式
    2. 版本链:快照加反向 diff
    3. 三路合并
    4. 编辑锁、冲突草稿与 Yjs 种子
  3. 权限体系
  4. 评论与批注
  5. 检索与 AI
    1. 索引写入
    2. 混合检索与权限
    3. 文件知识源与模型配置
  6. CodeWiki
  7. 开放能力
  8. 其他内容与后台
  9. 面试速答

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
2
3
4
5
6
7
8
9
10
11
12
13
-- src/db/init.ts
CREATE TABLE IF NOT EXISTS pages (
id TEXT PRIMARY KEY,
space_id TEXT NOT NULL REFERENCES spaces(id) ON DELETE CASCADE,
parent_id TEXT REFERENCES pages(id) ON DELETE SET NULL,
title TEXT NOT NULL,
content TEXT NOT NULL DEFAULT '',
visibility TEXT NOT NULL DEFAULT 'public',
editor_id TEXT NOT NULL REFERENCES users(id),
updated_at TEXT NOT NULL,
published INTEGER NOT NULL DEFAULT 1
);
CREATE INDEX IF NOT EXISTS idx_pages_space ON pages(space_id);

拖拽移动后要调 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
2
3
4
5
6
7
8
9
10
11
12
13
-- src/db/init.ts
CREATE TABLE IF NOT EXISTS wiki_revision (
rev_id INTEGER PRIMARY KEY AUTOINCREMENT,
page_id TEXT NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
rev_no INTEGER NOT NULL,
is_snapshot INTEGER NOT NULL DEFAULT 0,
full_content BLOB NULL,
reverse_diff BLOB NULL,
config_snapshot TEXT NULL, -- 结构化页面(表格/流程图/PPT/画布)的配置
create_ts INTEGER NOT NULL,
expire_mark INTEGER NOT NULL DEFAULT 0,
UNIQUE(page_id, rev_no)
);

config_snapshot 必须和正文同版本落库。表格、PPT 的正文只是占位,真实数据在配置里;只存正文,回滚后格式会全丢。

三路合并

普通文档用 node-diff3 的 diff3Merge(ours, base, theirs):base 是打开时的基线,ours 是用户草稿,theirs 是线上最新。无冲突块直接拼接,冲突块包成 Git 风格标记,同时记录行号区间给前端逐块选择。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// src/services/collab/merge-service.ts
export function threeWayMerge(base: string, ours: string, theirs: string): MergeResult {
const chunks = diff3Merge(splitLines(ours), splitLines(base), splitLines(theirs));
const mergedLines: string[] = [];
const conflictList: ConflictItem[] = [];
let lineNo = 1;
for (const chunk of chunks) {
if ('ok' in chunk && chunk.ok) {
mergedLines.push(...chunk.ok); lineNo += chunk.ok.length; continue;
}
if ('conflict' in chunk && chunk.conflict) {
const { a, b } = chunk.conflict;
mergedLines.push(CONFLICT_START, ...a, CONFLICT_SEP, ...b, CONFLICT_END);
const blockLen = 1 + a.length + 1 + b.length + 1;
conflictList.push({ startLine: lineNo, endLine: lineNo + blockLen - 1, oursContent: [...a], theirsContent: [...b] });
lineNo += blockLen;
}
}
return { hasConflict: conflictList.length > 0, mergedText: joinLines(mergedLines), conflictList };
}

合并必须按行切,按字符切会让中文冲突区间错位,前端无法定位到块。另有一个 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// src/collab/yjs-server.ts
export function decideRoomSeed(input: {
storedBaseRevNo: number | null; snapshotText: string; hasSnapshot: boolean;
latestRevNo: number; latestText: string | null;
}): RoomSeedDecision {
if (input.latestText === null) return { action: 'refuse', baseRevNo: null, latestText: null };
if (!input.hasSnapshot) {
return { action: 'seed-from-chain', baseRevNo: input.latestRevNo, latestText: input.latestText };
}
const same = normalizeMarkdownContent(input.snapshotText) === normalizeMarkdownContent(input.latestText);
// 旧数据 base 可能为 null:靠正文归一化比对兜底
if (input.storedBaseRevNo === input.latestRevNo || same) {
return { action: 'trust-snapshot', baseRevNo: input.latestRevNo, latestText: input.latestText };
}
return { action: 'replace-with-chain', baseRevNo: input.latestRevNo, latestText: input.latestText };
}

快照可能落后于版本链(进程在落盘前崩了),不能无条件信任 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
2
3
4
5
6
7
8
9
10
11
12
13
// src/services/rag-index.ts
export async function indexPage(pageId: string, title: string, content: string): Promise<number> {
const readCurrent = () => db.prepare('SELECT title,content,latest_rev_no,deleted_at FROM pages WHERE id=?').get(pageId);
const source = readCurrent();
if (!source || source.deleted_at || !isRagVectorConfigured()) return 0;
const isCurrent = () => { const current = readCurrent();
return Boolean(current && !current.deleted_at && current.title === source.title
&& current.content === source.content && current.latest_rev_no === source.latest_rev_no); };
// 过期快照不能删掉更新的分块,也不能把旧内容写进共享索引
if (!isCurrent()) return 0;
deletePageRagChunks(pageId);
...
}

混合检索与权限

retrieveForQuestion 优先走向量,异常时降级 BM25 关键词,两条路共用同一套权限过滤。向量服务没配或临时挂了,不该让整个问答不可用,所以降级要静默,不能直接抛错。

1
2
3
4
5
6
7
8
9
10
11
// src/services/ai-rag.ts
export async function retrieveForQuestion(userId: string, question: string, options: RetrieveOptions = {}) {
if (isRagVectorConfigured()) {
try {
return await retrieveWithVectors(userId, question, options);
} catch (e) {
console.warn('[rag] vector retrieve failed, fallback keyword:', e);
}
}
return retrieveWithKeywords(userId, question, options);
}

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
2
3
4
5
6
7
8
9
10
// src/services/api-token.ts
export function createApiToken(userId: string, name: string, scope: ApiTokenScope = 'read-write') {
const active = db.prepare('SELECT COUNT(*) as c FROM api_tokens WHERE user_id = ? AND revoked_at IS NULL')
.get(userId) as { c: number };
if (active.c >= MAX_ACTIVE_TOKENS_PER_USER) {
throw new Error(`每个用户最多创建 ${MAX_ACTIVE_TOKENS_PER_USER} 个有效 Token,请先吊销不用的 Token`);
}
const token = `${API_TOKEN_PREFIX}${randomBytes(24).toString('hex')}`;
...
}

吊销只置 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:统一身份