《WeKnora 深度技术解析》第 5 章 数据底座:多租户模型、仓储与迁移

《WeKnora 深度技术解析》第 5 章 数据底座:多租户模型、仓储与迁移

本章基于 WeKnora v0.9.0 的 PostgreSQL 与 SQLite 双迁移历史。所有表名、字段与索引均可在 migrations/ 与 internal/types/ 中对照。

WeKnora 的功能看起来是"上传文档、检索、问答、Agent、Wiki",但在这些能力之下,真正决定系统边界的是数据模型:哪些数据属于谁、以什么粒度隔离、哪些是事实来源、哪些只是派生索引、升级时如何演进。本章不讨论具体业务算法,而是把数据库这一层拆开,回答四个问题:

  1. 多租户在表结构、查询和上下文里分别怎样落地;
  2. 关系库与向量索引之间是什么关系,谁是权威、谁可重建;
  3. 仓储层提供了什么抽象,又刻意不提供什么保证;
  4. 迁移体系如何在 PostgreSQL 与 SQLite 两条历史上演进,失败时会发生什么。

后面的知识生命周期、检索、Agent 章节都会反复引用这里的表与约束。如果这一层理解错了,后面的很多"偶发问题"会被误判成算法问题。

5.1 数据底座的五个事实

在进入具体表之前,先给出五个贯穿全章的事实。它们不是概括,而是后续所有细节的锚点。

事实一:关系库是唯一权威。 知识库、文档、分块、会话、消息、权限、配置都以关系表为准。向量库里的 embedding 是派生数据:它可以被删除重建,重建的输入来自关系库中的分块文本。Lite 版把向量索引也放在同一个 SQLite 文件里,但这不改变"chunk 是权威、向量是索引"的关系。理解这一点,才能索引损坏时选择重建而不是恢复整库。

事实二:Schema 由 SQL 迁移定义,不由 GORM 自动生成。 项目大量使用 GORM 做 CRUD,但几乎不调用 AutoMigrate。表结构来自 migrations/versioned/*.sql 与 migrations/sqlite/*.sql,启动时由 golang-migrate 执行(internal/database/migration.go:101)。唯一的例外是 Lite 检索器在运行时创建的 lite_embeddings、FTS5 虚表和按维度划分的 vec_embeddings_* 表------它们属于检索索引,不属于业务 schema。

事实三:存在两套并行的迁移历史。 PostgreSQL 使用 migrations/versioned,当前有 138 个版本(276 个文件,含 up/down);SQLite 使用 migrations/sqlite,当前有 54 个版本(108 个文件)。SQLite 的历史是压缩过的:初始迁移一次性建了 47 张表(migrations/sqlite/000000_init.up.sql:3),而 PostgreSQL 的初始迁移只有 7 张表,其余表由后续 137 个版本逐步添加(migrations/versioned/000000_init.up.sql:11)。两边版本号不对应,不能互换,也没有跨方言迁移工具。

事实四:租户隔离靠应用层谓词,不靠数据库行级安全。 代码里没有 ROW LEVEL SECURITY,没有按租户的数据库角色,也没有为每个租户建 schema。隔离依赖三件事:认证中间件把租户写进上下文、服务层把租户传给仓储、仓储方法显式拼 tenant_id = ?。任何一层漏掉,隔离就出现缺口。

事实五:软删除是默认策略。 Tenant、User、KnowledgeBase、Knowledge、Chunk、Session、Message 等核心模型都带 gorm.DeletedAt(internal/types/tenant.go:132、internal/types/chunk.go:193)。删除通常是置位而非物理删除;查询默认过滤 deleted_at IS NULL,需要显式 Unscoped() 才能看到历史行。软删除保护了误删与审计,但也让唯一约束、统计和清理变得复杂。

5.1.1 表的四个家族

把 85 张 PostgreSQL 表按职责分组,可以看清系统的数据版图:

家族 代表表 职责
租户与身份 tenants、users、tenant_members、auth_tokens、tenant_invitations、tenant_api_keys、audit_logs 谁存在、属于哪个空间、能做什么
知识与检索 knowledge_bases、knowledges、chunks、chunk_revisions、knowledge_tags、embeddings、wiki_pages 知识如何被组织、切分、索引与引用
会话与 Agent sessions、messages、message_artifacts、custom_agents、agent_grants、agent_collaborations、automations 一次交互的历史、Agent 配置与运行状态
平台与集成 models、vector_stores、storage_backends、mcp_*、im_*、embed_channels、data_sources、system_settings、task_* 外部系统接入、部署级配置与异步任务

这个分组不是数据库 schema 的物理划分,而是理解依赖关系的地图。例如 messages 不直接带 tenant_id(internal/types/message.go:477),它通过 sessions 归属租户;chunks 同时带 tenant_id、knowledge_id、knowledge_base_id(internal/types/chunk.go:138),是为了让高频检索少做一次 join。

5.1.2 标识符的选择并不统一

系统里同时存在三种标识策略,各有原因:

  • 租户用自增整数 :tenants.id 是 SERIAL(migrations/versioned/000000_init.up.sql:12),并且初始迁移把序列起点调到 10000(migrations/versioned/000000_init.up.sql:34)。代码注释说明这是为了与早期内置/演示租户区分。整数主键让 tenant_id 在所有业务表里保持 4 字节(PostgreSQL INTEGER),索引紧凑。
  • 大多数业务实体用 UUID 字符串 :users.id、knowledge_bases.id、knowledges.id、chunks.id、sessions.id、messages.id 都是 VARCHAR(36)(internal/types/user.go:111)。
  • 分块额外有 seq_id :chunks.seq_id 是 BIGINT 加 PostgreSQL 序列默认值与唯一索引(migrations/versioned/000010_add_seq_id.up.sql:11),用于对外 API 的稳定数字标识(尤其是 FAQ)。UUID 适合内部关联,数字适合人工引用与外部系统对接。

混用带来一个实际约束:跨表关联时类型必须匹配。tenant_id 是整数,用户 ID 是字符串;messages.session_id 是字符串,sessions.tenant_id 是整数。写原生 SQL 时不能想当然地套用同一种类型,否则 PostgreSQL 会报操作符不存在,SQLite 则可能做隐式转换,导致"生产报错、Lite 正常"的差异。

5.1.3 JSON 列承担了"可变配置"

大量配置不是拆成独立表,而是放在 JSON/JSONB 列里:知识库的分块配置、图片处理配置、VLM 配置(internal/types/knowledgebase.go:79);租户的检索配置、存储配置、默认模型(internal/types/tenant.go:118);消息的引用、Agent 步骤、附件、用量(internal/types/message.go:485)。这样做的好处是演进成本低:新增一个配置项不需要 DDL,后端用结构体反序列化即可。

代价是数据库无法对这些字段做细粒度约束与索引。例如"所有知识库的 chunk_size 必须大于 0"只能由应用校验;按 JSON 内部字段过滤要么走表达式索引,要么退化为全表扫描。项目在需要检索的字段上单独建了列(如 parse_status、enable_status、file_hash),而不是依赖 JSON 查询,这是一种务实的分层:高频过滤字段列化,低频配置 JSON 化。

5.1.4 时间、时区与软删除

GORM 初始化时设置了(internal/container/container.go:1086):

go 复制代码
NowFunc: func() time.Time { return time.Now().UTC() },

因此 CreatedAt、UpdatedAt 由 GORM 写入 UTC。PostgreSQL 列类型是 TIMESTAMP WITH TIME ZONE,SQLite 存 DATETIME 文本。应用层展示时再按用户时区转换。这个约定避免了"服务器时区变了,数据含义变了"的问题,但也要求手写 SQL 时不要用 NOW() 与 Go 时间混比而不加时区说明。

软删除字段统一是 DeletedAt gorm.DeletedAt(internal/types/tenant.go:132),在 PostgreSQL 是 TIMESTAMP WITH TIME ZONE,在 SQLite 是 DATETIME。GORM 的默认 scope 会自动追加 deleted_at IS NULL,但原生 SQL、Joins 里的手写条件、以及 Unscoped() 查询都需要自己处理。后文会看到,正是这个差异导致了两套迁移在唯一索引上的不同写法。

5.2 租户:一行记录如何变成全系统的隔离边界

tenants 表最初只有名称、描述、配额等少数字段,随着功能增加,它逐渐变成了"工作空间配置聚合":检索配置、存储配置、默认模型、记忆开关、助手设置都挂在这一行上。

5.2.1 表结构与字段语义

Tenant 模型的关键字段可以分成四组:

身份与生命周期

  • ID uint64:自增主键,序列从 10000 开始(internal/types/tenant.go:88);
  • Name、Description、Business:展示与业务分类;
  • Status:默认 active,用于停用空间(internal/types/tenant.go:94);
  • DeletedAt:软删除标记,带索引(internal/types/tenant.go:132)。

容量与计量

  • StorageQuota int64:默认 10 GiB(10737418240 字节,internal/types/tenant.go:100);
  • StorageUsed int64:已用字节数,默认 0(internal/types/tenant.go:102)。

配额覆盖"向量、原始文件、文本、索引"等全部存储占用(字段注释明确列出)。它不是数据库层的硬约束,而是应用层计量与拦截的依据:写入前后更新 storage_used,超限时拒绝新上传。计量与真实对象存储之间可能漂移(删除失败、重复统计、外部直接写入),因此它更像"软配额"而非财务级账单。

检索与模型配置

  • RetrieverEngines:JSON 列,保存该租户启用的检索引擎组合(internal/types/tenant.go:96);
  • DefaultSettings:每类模型的默认绑定(internal/types/tenant.go:124);
  • RetrievalConfig:搜索/召回参数(internal/types/tenant.go:118);
  • ChatHistoryConfig:把聊天记录索引为可检索知识的配置(internal/types/tenant.go:116);
  • MemoryConfig:跨会话长期记忆开关(internal/types/tenant.go:120)。

GetEffectiveEngines() 的逻辑是:租户配置了引擎就用租户的,否则回退到 RETRIEVE_DRIVER 环境变量推导出的系统默认值(internal/types/tenant.go:141)。由此实现"部署级默认 + 租户级覆盖",但同一部署里不同租户可能走不同检索后端,排查检索问题须先确认当前租户的有效引擎。

外部依赖与安全配置

  • ParserEngineConfig:解析引擎覆盖(如 MinerU 端点与密钥,internal/types/tenant.go:108);
  • Credentials:第三方提供商凭据(如 WeKnoraCloud 的 AppID/AppSecret,internal/types/tenant.go:110);
  • StorageEngineConfig:本地、MinIO、COS 等存储参数(internal/types/tenant.go:112);
  • DefaultStorageBackendID:指向具体的存储实例(internal/types/tenant.go:114);
  • APIPrincipalConfig:X-API-Key 请求如何映射到终端主体(internal/types/tenant.go:126)。

这些字段里不少是敏感信息。它们以 JSONB 存储,读取时由服务层解密或直接使用;数据库备份因此等同于"配置 + 凭据"的备份,需要按敏感数据管理。

一个历史字段:初始迁移的 tenants.api_key VARCHAR(64) NOT NULL(migrations/versioned/000000_init.up.sql:15)在新模型中已不存在,租户 API Key 移到独立 tenant_api_keys 表(多把 Key、作用域、过期与撤销)。旧列可能仍在老库,但应用不再依赖;判断字段是否有效应以模型与仓储为准,而不是只看表结构。

5.2.2 租户 ID 从 10000 开始

初始迁移里有一段不常见的序列调整(migrations/versioned/000000_init.up.sql:28):

sql 复制代码
SELECT last_value INTO current_val FROM tenants_id_seq;
IF current_val < 10000 THEN
    ALTER SEQUENCE tenants_id_seq RESTART WITH 10000;
END IF;

它把自增起点推到 10000,让系统租户/演示租户与真实租户在数值上可区分。两个后果:

  • 任何"按 ID 范围判断是不是内置租户"的逻辑都依赖这个约定,导入外部数据时若带入小 ID,可能被误判;
  • 从其它系统迁移数据时,不能假设租户 ID 从 1 开始连续,分页、统计和导出都要以实际值为准。

SQLite 版本没有序列,tenants.id INTEGER PRIMARY KEY AUTOINCREMENT 从 1 开始(migrations/sqlite/000000_init.up.sql:4),因此 Lite 与标准版的租户 ID 分布不同。这不是 bug,但跨形态比较数据或写迁移脚本时必须意识到。

5.2.3 租户上下文:两个表面,一次写入

请求进入后,租户信息被写进 context.Context。这一步集中在 middleware.applyAuthSession(internal/middleware/auth_context.go:53),它同时写两个表面:

go 复制代码
set := func(key types.ContextKey, v any) {
    c.Set(key.String(), v)          // gin.Context,供 handler 用 c.Get 读取
    ctx = context.WithValue(ctx, key, v) // request.Context,供 service/repo 用
}

代码注释解释了为什么必须成对写入(internal/middleware/auth_context.go:61):项目里同时存在 c.Get(types.TenantIDContextKey.String()) 和 types.TenantIDFromContext(ctx) 两种读法,只写一个表面会造成"handler A 正常、handler B 拿不到租户"的隐蔽 bug。

写入条件是 TenantID != 0。零值表示 tenantless,既不写 TenantIDContextKey 也不写 TenantInfoContextKey;这类会话只能访问身份级接口(登录、改密码、列出自己的成员关系),需要租户的接口应在中间件或服务层拒绝。TenantIDFromContext(internal/types/context_helpers.go:26)返回 (0, false),调用方必须检查布尔值;MustTenantIDFromContext(internal/types/context_helpers.go:32)缺失时 panic,只适合上层已保证存在的内部路径。

角色也随会话写入:TenantRoleContextKey。若角色为空(tenantless),不会写入;读取方通过 TenantRoleFromContext(internal/types/context_helpers.go:219)取值时默认回退到 Viewer,这是 fail-closed 的设计------拿不到角色就按最低权限处理,而不是放行。

5.2.4 仓储不自动加租户条件

这是全章最需要记住的实现细节。以知识库仓储为例:

go 复制代码
// GetKnowledgeBaseByID gets a knowledge base by id
// (no tenant scope; caller must enforce isolation where needed)
func (r *knowledgeBaseRepository) GetKnowledgeBaseByID(ctx context.Context, id string) (*types.KnowledgeBase, error) {
    var kb types.KnowledgeBase
    if err := r.db.WithContext(ctx).Where("id = ?", id).First(&kb).Error; ...
}

同一个仓储里另有 GetKnowledgeBaseByIDAndTenant(internal/application/repository/knowledgebase.go:43),显式拼 id = ? AND tenant_id = ?;不带租户的版本就定义在 internal/application/repository/knowledgebase.go:31。两个方法并存说明租户隔离是调用方的选择而非仓储默认:面向用户的路径必须用带租户方法或先做访问校验,只有内部任务、跨租户管理与系统级扫描才可走不带租户的查询。

这样设计是为了灵活:后台迁移、统计、跨租户共享与系统管理都需要跨越租户边界,强制注入 tenant_id 会迫使这些路径绕开仓储或不断传"特权标记",反而更危险。代价是正确性依赖开发者纪律,因此关键资源上还有第二道防线:kb_access 在进入 handler 前校验归属,RBAC 中间件再校验角色。

排查"为什么 A 租户看到了 B 租户的数据"时,应沿着三层查:

  1. 该请求是否真的携带了租户(JWT、API Key、X-Tenant-ID 解析结果);
  2. 服务层调用的仓储方法是否带 tenant_id 条件;
  3. 是否存在跨租户共享/系统管理员的合法旁路。

只检查第 1 层,会漏掉"上下文正确但查询没带条件"的情况;只检查第 3 层,则会把设计内的共享误判为越权。

5.2.5 跨租户不是"关掉隔离",而是另一条受控路径

User.CanAccessAllTenants(internal/types/user.go:125)与 User.IsSystemAdmin(internal/types/user.go:127)是两个不同的概念:

  • CanAccessAllTenants 允许用户通过 X-Tenant-ID 切换到其它租户,但仍需在该租户有 active 成员关系,或在特定配置下允许跨租户访问;
  • IsSystemAdmin 是平台级管理员,独立于任何租户角色,用于系统设置、用户管理等接口。

认证中间件 resolveTargetTenant(internal/middleware/auth.go:324)会综合 JWT 里的租户声明、请求头、用户主租户与成员关系,决定本次请求的目标租户;随后 resolveTenantRole(internal/middleware/auth.go:795)解析角色。JWT 本身携带租户声明,但刷新令牌没有租户声明,需要从用户偏好或成员关系重新解析------这也是为什么"最后一次活跃租户"会存在用户偏好里。

这条受控路径的存在,意味着数据层不能假设"一个用户只有一个租户"。任何以 user.TenantID 作为唯一归属的判断都可能过时:用户可能切换过空间,TenantID 只是主租户;真正的权限来自 tenant_members 的 active 行。

5.2.6 删除租户时发生了什么

TenantService.DeleteTenant 走的是软删除(internal/application/repository/tenant.go:155):租户行置 deleted_at,同时把成员关系一并软删除(仓储测试明确验证"行还在,但被软删除")。业务数据(知识库、文档、会话)不会级联删除,这带来两个后果:

  • 误删租户后,理论上可以通过清空 deleted_at 恢复,但要注意成员关系与唯一索引;
  • 物理清理需要独立任务,按租户批量删除关联数据与对象存储文件,否则"删除"只释放了可见性,没有释放空间。

配额也不会因软删除自动回退:租户软删除后恢复,storage_used 仍是删除前的值;执行物理清理则需同步扣减。这是"软删除 + 配额"组合的固有成本。

5.3 身份表:账号、成员关系与令牌

身份数据分四层:账号(users)、凭证(auth_tokens)、空间成员关系(tenant_members)、邀请(tenant_invitations),以便准确表达"一个人属于多个空间""邀请尚未接受""账号存在但无空间"等状态。

5.3.1 users:账号本身不等于成员

User 模型的关键点:

  • ID string 是 UUID(internal/types/user.go:111),Username 与 Email 各有唯一索引(internal/types/user.go:113、internal/types/user.go:115);
  • TenantID uint64 记录"主租户"(internal/types/user.go:121),但允许为 0,表示 tenantless;
  • PasswordHash 只存哈希,JSON 序列化时 json:"-"(internal/types/user.go:117),不会通过 API 泄漏;
  • CanAccessAllTenants 与 IsSystemAdmin 是两个独立布尔;
  • Preferences UserPreferences 是 JSONB 列(internal/types/user.go:131),保存 UI 偏好、最后活跃租户、OIDC 标记等;
  • DeletedAt 软删除(internal/types/user.go:137)。

Preferences 用指针字段区分"客户端没传这个键"和"显式传了 false":部分更新时 nil 保留原值,非 nil 覆盖;LastActiveTenantID 还用 *0 作为"清空偏好"的哨兵值。这些语义只在应用层,数据库看到的只是一个 JSON 对象。新增偏好项不需要 DDL,但必须同步修改合并逻辑,否则部分更新会清空新字段。

唯一约束是普通唯一而非部分唯一:PostgreSQL 中被软删除的用户仍占用用户名与邮箱,重新注册同名账号会命中约束。系统没有"恢复用户"接口,删除账号基本等于永久放弃该用户名/邮箱;要支持复用,必须改成部分唯一索引,或在注册时检测软删除行并恢复。

5.3.2 auth_tokens:令牌也进了数据库

AuthToken 表保存访问令牌与刷新令牌(internal/types/user.go:144):

go 复制代码
accessTokenRecord := &types.AuthToken{
    UserID:    user.ID,
    Token:     accessToken,
    TokenType: "access_token",
    ExpiresAt: time.Now().Add(24 * time.Hour),
}
refreshTokenRecord := &types.AuthToken{
    UserID:    user.ID,
    Token:     refreshToken,
    TokenType: "refresh_token",
    ExpiresAt: time.Now().Add(7 * 24 * time.Hour),
}

Token 存令牌原文(internal/types/user.go:150),不是哈希:好处是校验/撤销可按令牌精确查找,代价是数据库读权限等同于"在有效期内可冒充任意用户",备份、只读副本与日志导出都属高敏感资产。令牌有效期 24 小时与 7 天,IsRevoked(internal/types/user.go:156)支持逐条撤销;但已签发的 JWT 过期前仍可能被其它校验路径接受,撤销范围取决于校验是否查库。

令牌与用户是弱关联:user_id 有索引但无外键级联(internal/types/user.go:148),删除用户不会自动删除令牌行,需显式清理,否则残留令牌在软删除后仍可能通过某些校验路径。这是后文清理任务存在的原因之一。

5.3.3 tenant_members:角色的真正来源

TenantMember 是 (user, tenant) 的成员关系(internal/types/tenant_member.go:86),字段包括:

  • 自增 ID;
  • UserID、TenantID;
  • Role(internal/types/tenant_member.go:95):owner、admin、contributor、viewer;
  • Status(internal/types/tenant_member.go:98):active、invited、suspended;
  • InvitedBy、JoinedAt;
  • 软删除(internal/types/tenant_member.go:106)。

角色有数值层级(internal/types/tenant_member.go:38),owner=40、admin=30、contributor=20、viewer=10,HasPermission(internal/types/tenant_member.go:59)用"等级大于等于所需等级"判断。层级间留 10 的间隔,便于插入新角色。代价是角色为"全序":若出现"能管理成员但不能改知识库"的横切角色,单靠等级无法表达,需要额外权限位。

成员关系的唯一性在两套迁移里写法不同(PostgreSQL 见 migrations/versioned/000043_tenant_rbac.up.sql:41,SQLite 见 migrations/sqlite/000000_init.up.sql:357):

  • PostgreSQL:
sql 复制代码
CREATE UNIQUE INDEX idx_tenant_members_user_tenant_unique
    ON tenant_members(user_id, tenant_id)
    WHERE deleted_at IS NULL;
  • SQLite:
sql 复制代码
CREATE UNIQUE INDEX idx_tenant_members_user_tenant_unique
    ON tenant_members(user_id, tenant_id);

PostgreSQL 的部分唯一索引允许软删除后重新添加同一成员;SQLite 不支持这种写法,唯一约束覆盖所有行,因此 Lite 版软删除成员后再邀请同一用户会命中约束,服务层必须恢复原行(清空 deleted_at)而非插入新行。这是"同一业务语义、两种数据库能力"的差异,5.11 会再讨论。

Status 与软删除是两个维度:invited 表示邀请已发出未接受,suspended 表示被管理员停用,两者都保留行;软删除表示关系被移除。认证中间件只认 active,查询必须同时过滤 status = 'active' 与 deleted_at IS NULL,漏掉任何一个都会把无效成员当成有效。

5.3.4 邀请与 tenantless

tenant_invitations 保存邀请令牌、目标租户、目标角色、过期时间与状态。邀请是"加入已有租户"的权威凭据:注册接口不接收目标租户,只有邀请 handler 能按令牌决定加入哪个空间、给什么角色;RegisterRequest.TenantProvisioning 标记为 json:"-"(internal/types/user.go:226),客户端无法通过 JSON 注入。

tenantless 是合法状态:账号存在但 users.tenant_id = 0,没有个人空间,适用于"先建身份、稍后由管理员邀请"的流程。此类用户登录后只能访问身份级接口;接受邀请或被分配成员关系后,登录解析会回填主租户:resolveFirstMembershipTenant 在有成员关系而主租户为零时,挑选最早加入的有效租户写回 users.tenant_id。

5.3.5 注册不是一次事务,而是一段补偿流程

公开注册在"创建个人空间"模式下要写三张表:tenants、users、tenant_members。代码(internal/application/service/user.go:135)没有把三者放进一个数据库事务,而是采用补偿:

  1. 先创建租户(internal/application/service/user.go:179);
  2. 创建用户(internal/application/service/user.go:201),失败则删除刚建的租户;
  3. 创建 Owner 成员关系,失败则删除用户与租户(internal/application/service/user.go:220)。

第三步上方的注释仍写着"失败只记录日志,由认证中间件的孤儿租户恢复路径在下次登录时重建成员关系"(internal/application/service/user.go:213),但紧随其后的代码实际执行了删除并返回错误。这是注释未跟上实现的历史残留,排错时应以代码为准:成员关系创建失败会让整个注册失败,不留用户与租户。

补偿式一致性适合跨服务/跨聚合流程,但并不原子:删除租户也失败会留下孤儿租户,进程在两步之间崩溃同样留下半成品,因此还需要后台清理与"孤儿恢复"。"注册偶尔失败后残留数据"是这套模型的已知边界,而非单纯的 bug。

下一节转向组织与共享:当知识不再只属于一个租户,organizations、organization_tenant_members、kb_shares 如何在不破坏隔离的前提下建立跨空间访问。

5.4 组织与共享:跨越租户边界的受控通道

租户模型解决"数据属于谁",却回答不了另一类问题:两家公司合作、集团下多个子公司、一个团队在同一部署里开了多个空间,知识需要被另一群人读到。直接的做法是"建一个超级租户,把所有人塞进去",但那会摧毁隔离:成员共享同一配额、同一套模型与成员管理权限,A 公司无法阻止 B 公司看到自己的全部知识库。

WeKnora 选择更窄的一条路:数据永远留在源租户,跨租户访问靠一条共享记录授权 。organizations 不是租户的上级,也不是"更大的租户",而是一张协作关系表;kb_shares、agent_shares 记录"某个租户把资源借给了某个协作组织"。共享不迁移、不复制、不改变数据归属,只改变"谁有资格读"。

5.4.1 为什么组织表里没有 tenant_id

organizations 的 DDL(migrations/versioned/000012_organizations.up.sql:6)没有 tenant_id 列,只有 owner_id 与后来的 owner_tenant_id,与几乎所有业务表都带 tenant_id 的习惯相反。因为成员本身就是多个租户:把组织挂在某个 tenant_id 下,查询、权限与生命周期都会退回"单租户所有"的语义。

组织的字段分三组:

身份与展示 :id(UUID)、name、description、avatar、searchable。searchable 决定组织是否出现在"可发现的协作空间"列表里,非成员可按名称或 ID 搜索并申请加入。

邀请与准入 :invite_code、invite_code_expires_at、invite_code_validity_days、require_approval、member_limit。邀请码是 16 位十六进制字符串(8 字节随机数的 hex),有效期只允许 0(永不过期)、1、7、30 天,默认 7 天。require_approval 决定"用邀请码/ID 加入"是立即生效还是转为待审批申请。

归属与生命周期 :owner_id、owner_tenant_id、created_at、updated_at、deleted_at。后文会解释 owner_tenant_id 为什么必须是"创建时快照",而不是每次从 owner 用户现算。

成员关系放在 organization_tenant_members(migrations/versioned/000045_org_tenant_members.up.sql:33),键是 (organization_id, tenant_id),值是 role 与 representative_user_id。角色枚举是 admin/editor/viewer,与租户内的 owner/admin/contributor/viewer 是两套独立层级。同一个人可能在自租户里是 owner、在协作组织里只是 viewer,两个身份在权限计算中相乘而非取其一。

5.4.2 Plan 3:成员从"用户"改成"租户"

早期实现是 organization_members(organization_id, user_id, tenant_id, role):一个用户加入组织,就在表里加一行。单用户场景下工作正常,但把"公司"当作协作单位后就有结构性缺陷。迁移文件 000045_org_tenant_members.up.sql 的开头写得很清楚(migrations/versioned/000045_org_tenant_members.up.sql:5):Alice 代表租户 T 加入组织 X 后,同事 Bob 在组织里没有任何记录,看不到任何共享给 X 的资源,"我们公司加入了这个组织"无法表达。

更棘手的是粒度不一致:tenant_disabled_shared_agents 已是租户粒度(主键含 tenant_id),组织成员却是用户粒度,同一个系统两套粒度会让"禁用某个共享 Agent"在不同租户成员之间表现不同。

Plan 3 新建 organization_tenant_members(migrations/versioned/000045_org_tenant_members.up.sql:33),键改为 (organization_id, tenant_id),保留 representative_user_id 仅用于展示与审计------注释明确说明权限检查只看 (org_id, tenant_id, role)。这一句就是迁移的设计原则:权限主体是租户,用户只是代表。

迁移过程有几个值得学习的细节:

第一,角色折叠采用"最高者胜" 。同一 (org, tenant) 下原来可能有多行用户记录,角色不一。迁移用 BOOL_OR(role = 'admin') 优先、其次 editor、否则 viewer 的 CASE 表达式折叠成一行(migrations/versioned/000045_org_tenant_members.up.sql:71)。因此原本是 viewer 的用户,会因为同租户里有人是 admin 而被"提升"为 admin。迁移在回填前用一段 RAISE NOTICE 循环把所有"多用户且角色冲突"的组合打印到日志,让运维在升级时能看到哪些租户被提升了权限。

第二,代表用户的选择是确定性的 。子查询按 created_at ASC, user_id ASC 排序取第一条,迁移重跑结果也一致;否则回滚再升级会得到不同的数据。

第三,旧表不删除,而是改名 。organization_members 重命名为 organization_members_pre_plan3(migrations/versioned/000045_org_tenant_members.up.sql:117),相关索引逐个改名(旧版 PostgreSQL 重命名表不会自动重命名索引),这样 down.sql 可以恢复旧表而不必重建数据。注释还说明,未来会有一个受 weknora.allow_destructive_migration 开关控制的破坏性迁移来删除它------先并存,再清理。

第四,加入申请的去重键同步升级 。旧模型下同一用户可以有多个 pending 申请;新模型下同一租户只能有一个。迁移先按 (org, tenant, request_type) 分区、保留最早一条,其余标记为 rejected 并写入系统审核消息 [Plan 3] superseded...,然后建立部分唯一索引(migrations/versioned/000045_org_tenant_members.up.sql:159):

sql 复制代码
CREATE UNIQUE INDEX IF NOT EXISTS uq_org_join_requests_pending_per_tenant
    ON organization_join_requests (organization_id, tenant_id, request_type)
    WHERE status = 'pending';

把"清理"写成带审计痕迹的状态变更,而不是物理删除,是这张表可以长期保留历史的前提。

5.4.3 owner_tenant_id:保护对象不能是移动靶

组织的"所有者"需要不可移除、不可降级的锚点,否则组织可能被成员清空、变成孤儿。早期规则是:owner 用户当前所属租户等于目标租户,则该租户是 owner 租户。问题在于 users.tenant_id 会变:owner 切换租户后,原来受保护的租户变成可移除,而 owner 新去、可能根本不在组织里的租户反而成了"不可触碰"的对象。

迁移 000046_org_owner_tenant_id.up.sql 的注释称其为"静默失效"(breaks silently)。修复方式是在创建组织时把 owner 当时的租户写入 organizations.owner_tenant_id(migrations/versioned/000046_org_owner_tenant_id.up.sql:27),此后不再改变。回填分三步:

  1. 从仍存在的 owner 用户的 tenant_id 推导(migrations/versioned/000046_org_owner_tenant_id.up.sql:31);
  2. owner 用户已被删除时,取该组织内最早的 admin 租户;
  3. 仍然无法解析的,用 RAISE EXCEPTION 让迁移失败(migrations/versioned/000046_org_owner_tenant_id.up.sql:62),而不是给一个 NOT NULL 列填假值(migrations/versioned/000046_org_owner_tenant_id.up.sql:70)。

第三点最关键。很多迁移在无法回填时用默认值蒙混过关,结果是权限判断对某些组织永久错误;这里宁可升级失败、要求手工处理,也不产生"看起来成功、实际权限错乱"的数据。错误信息甚至直接给出了排查 SQL:

sql 复制代码
SELECT id, name, owner_id FROM organizations
WHERE owner_tenant_id IS NULL AND deleted_at IS NULL;

服务层的 isOwnerTenant(internal/application/service/organization.go:609)对历史零值采取另一种 fail-closed:OwnerTenantID == 0 时返回 true(internal/application/service/organization.go:614),把所有租户都当成 owner,冻结成员表直到运维回填,避免真实 owner 反被移除且无法恢复。DeleteOrganization 单独保留 legacy 回退:OwnerTenantID == 0 且调用者用户 ID 等于 OwnerID 时仍允许删除(internal/application/service/organization.go:340)。两条路径策略不一致------删除有用户级回退,移除成员没有------这是迁移过渡期的妥协。

5.4.4 成员上限:默认值分裂与并发计数

member_limit 语义是"组织最多容纳多少个租户成员",0 表示不限,但两个默认值来源不同:

  • 数据库 DDL:member_limit INTEGER NOT NULL DEFAULT 50(migrations/versioned/000012_organizations.up.sql:17);
  • 服务层常量:DefaultMemberLimit = 200(internal/application/service/organization.go:22),创建组织时未指定就用它。

于是 API 创建的组织默认 200,绕过服务层直接 INSERT 的行默认 50;任何数据修复脚本都必须显式写 member_limit,不能依赖 DDL 默认。

上限检查放在仓储层事务里(internal/application/repository/organization.go:134),而非服务层"先 count 再 insert"。AddTenantMember 注释说明:并发加入时两个请求可能同时读到 count = limit - 1,然后都插入成功。PostgreSQL 分支先对组织行加 FOR UPDATE 锁(internal/application/repository/organization.go:145)再计数、插入;SQLite 分支跳过锁,因为没有行锁、写事务本身串行化,"读后升级为写"会失败而非静默放行。分支是为了正确性,不是性能。

修改上限还有一条约束:新上限不能低于当前成员数,否则已有成员"超限",后续加入都会失败而现有成员不受影响。服务层用 ErrOrgMemberLimitTooLow 拒绝。

5.4.5 加入组织的三条路径

成员关系只能由三种方式产生:

邀请码 。invite_code 上有部分唯一索引(migrations/versioned/000012_organizations.up.sql:23,仅对 invite_code IS NOT NULL AND deleted_at IS NULL 生效),多个组织可以都没有邀请码,但有码的组织之间不会撞码。查找时先按码取组织,再检查 invite_code_expires_at,过期返回 ErrInviteCodeExpired。过期判断在应用层、数据库不参与,所以把系统时间调回过去不能"复活"邀请码;反过来,应用服务器时钟漂移时过期判断也会漂移。

可搜索加入 。组织设 searchable = true 后出现在搜索列表里。非成员可按 ID 直接加入;若 require_approval = true 则转为 pending 申请,否则以 viewer 身份立即加入。SearchSearchableOrganizations 对每个结果统计成员数、共享知识库数、共享 Agent 数,并标记调用者租户是否已是成员------典型的列表页聚合查询,代价是每个组织若干次 COUNT,组织多时需改批量聚合。

审批加入/升级 。organization_join_requests 同时承载"新成员加入"(request_type = join)与"角色升级"(request_type = upgrade,带 prev_role)。pending 状态的部分唯一索引(migrations/versioned/000045_org_tenant_members.up.sql:159)保证同一租户对同一组织、同一类型只有一个待审请求。升级请求不允许申请不高于当前角色的等级,否则会产生"申请降级"的无意义记录。

三条路径最终都落到 AddTenantMember,成员上限、重复成员、角色合法性只在一处校验,不会在三个 handler 里各写一遍。

5.4.6 kb_shares:一条记录就是一份授权

共享知识库的核心表只有九个业务列(migrations/versioned/000012_organizations.up.sql:57):

  • knowledge_base_id:被共享的知识库;
  • organization_id:共享给哪个组织;
  • shared_by_user_id:谁执行的共享(审计与"原共享人"权限);
  • source_tenant_id(migrations/versioned/000012_organizations.up.sql:62):知识库所属租户;
  • permission:授予的权限等级(admin/editor/viewer);
  • 时间戳与软删除。

source_tenant_id 本可从 knowledge_bases.tenant_id 现查,冗余有三个理由:读取路径少一次 join(共享列表与权限判断高频使用);它是"共享来源"的语义,知识库日后转移时共享仍指向共享发生时的来源租户,否则历史授权被追溯性改变;跨租户执行需要它------读取共享知识库时 embedding 模型、向量索引、原始文件都在源租户下,执行上下文必须切到源租户,接收方配置不能替代。

PostgreSQL 迁移为 (knowledge_base_id, organization_id) 建了部分唯一索引(migrations/versioned/000012_organizations.up.sql:69),同一知识库对同一组织只有一条有效共享,软删除后可重新共享。SQLite 初始迁移只有单列索引(migrations/sqlite/000000_init.up.sql:629),唯一性由仓储 Create 的 count 检查保证(internal/application/repository/kbshare.go:28):

go 复制代码
Where("knowledge_base_id = ? AND organization_id = ? AND deleted_at IS NULL", ...).Count(&count)
if count > 0 { return ErrKBShareAlreadyExists }

"先查后插"并发不安全:标准版有数据库兜底,Lite 没有,两个请求同时共享可能产生两条有效行;服务层收到 ErrKBShareAlreadyExists 会转成"更新已有共享的权限",但两者都插入成功的情况绕过了这条路径。影响有限(权限取最高值、列表去重),但应在迁移里补齐。

权限字段复用 OrgMemberRole 枚举,语义却不同:成员角色是"你在组织里的身份",共享权限是"这份资源允许组织成员做到什么",两者在权限计算中取较小值。

5.4.7 权限算术:三维取最小

共享知识库的最终权限不是 kb_shares.permission 一个值,而是三个维度的最小值:

ini 复制代码
effective = min(share.permission, caller_tenant_org_role, tenant_role_cap)
  • share.permission:源租户愿意授予的最高权限;
  • caller_tenant_org_role:调用者租户在组织里的角色;
  • tenant_role_cap:调用者在自己租户内的角色上限。

MinOrgRole(internal/types/organization.go:47)约定任一参数为空时返回另一个,即"缺失维度不参与比较"。若成员查询失败却传零值,结果会退化为"只剩共享权限"而非拒绝;代码用"查询失败就 continue"避开,新增调用点须遵守同样纪律。

第三维 tenant_role_cap 由 applyTenantRoleCap(internal/application/service/kbshare.go:69)实现:调用者在自己租户内是 Viewer 时,无论组织给什么最高只能是 OrgRoleViewer,从而保证"在自己空间只读的人,不因共享在别人空间获得写权限";Contributor 及以上不受此帽限制,仍由前两维约束。

共享为 editor 只表示"上限",viewer 身份的租户成员依然只能读。

管理共享记录另有独立规则,集中在 canManageShare(internal/application/service/kbshare.go:236):

  1. 原共享人,且当前仍在源租户、租户角色至少 Contributor;
  2. 源租户的 Admin 及以上(即使原共享人已离职);
  3. 目标组织中角色为 admin 的租户的 Admin,但只能删除或降低权限,不能提高。

第三条注释解释:组织管理员若能把权限从 viewer 提到 editor,等于让组织里所有 editor 获得另一个租户知识库的写权限;允许降权或撤销是为了治理,如原共享人离职后仍能收回共享。这里用 role == OrgRoleAdmin 而非 HasPermission,editor 不行。

5.4.8 共享什么时候失效:主动撤销与读取兜底

一条共享记录存在,不代表它一定生效。系统在两层保证"源租户仍是组织成员":

写路径主动撤销 。租户离开组织或被移除时,RemoveTenantMember 调用 revokeTenantShares(internal/application/service/organization.go:432),按 (org, source_tenant) 软删除该租户在该组织下的所有知识与 Agent 共享。注释写明了动机:否则留下的人仍能读它的知识库、用它的模型跑 Agent。

读路径 JOIN 兜底 。所有共享查询都带一个固定的 JOIN(internal/application/repository/kbshare.go:109):

go 复制代码
const kbShareSourceMemberJoin = "JOIN organization_tenant_members src_member " +
    "ON src_member.organization_id = kb_shares.organization_id " +
    "AND src_member.tenant_id = kb_shares.source_tenant_id"

这条 JOIN 让"源租户已不在组织"的残留共享自动失效,覆盖旧版本遗留数据与撤销失败。CheckTenantKBPermission 还额外显式检查源租户成员关系,因为该路径通过 Preload("Organization") 取组织,不经过同一个 JOIN------权限判断不能依赖调用方恰好用了哪条查询。

组织的软删除也在读路径过滤:ListSharedKBsForTenant(internal/application/repository/kbshare.go:169)显式 JOIN organizations 并要求 deleted_at IS NULL;ListByOrganization(internal/application/repository/kbshare.go:130)只过滤知识库软删除,组织是否删除由调用方保证(组织删除时会先删共享)。DeleteOrganization 依次删除 KB 共享、Agent 共享,再软删除组织,每步失败只记日志、不中断,因为读路径 JOIN 会兜底------这是"尽力清理 + 读取兜底",不依赖级联。

5.4.9 一份数据、两个租户:执行租户与配额

读取共享知识库时系统面对两个租户:调用者租户(身份、RBAC)与源租户(数据、模型、存储),不能混用。检索必须用源租户的 embedding 模型向量化查询,因为索引由该模型建立;误用接收方模型会导致维度或语义空间不匹配,报错或结果失真。原始文件下载也走源租户的存储后端配置。

代码用 types.WithExecutionTenant(internal/types/caller.go:40)切换执行租户,同时保留调用者身份。access 包 README 说明:切换执行租户本身不授予访问权,授权必须先完成;grant 绑定 KB ID、所有者租户、调用者与解析出的权限,事后切换不能把 Viewer 变成 Editor,顺序反过来就是提权漏洞。

配额方向相反:共享不复制数据,接收方 storage_used 不增加;读取的计算与流量不计入源租户存储配额(配额只统计存储占用)。但接收方以 editor 权限写入时,新文档落在源租户并占用其配额------源租户可能因"别人往我的知识库写东西"而触顶,且无法从配额报表看出是谁写的。共享审计日志(AuditActionKBShareAdded 等)记录共享动作而非每次写入,定位需结合知识条目的创建者信息。

5.4.10 agent_shares:复合外键与"禁用"偏好

Agent 共享与知识库共享结构相似,但有两个不同点。

第一,外键是复合的 。agent_shares(migrations/versioned/000012_organizations.up.sql:112)的外键是 (agent_id, source_tenant_id) REFERENCES custom_agents(id, tenant_id)(migrations/versioned/000012_organizations.up.sql:122),因为 custom_agents 主键就是 (id, tenant_id):Agent 身份是"ID + 租户",单看 agent_id 不足以定位一行。唯一索引相应变为 (agent_id, source_tenant_id, organization_id) 的部分唯一索引。这让"同一 UUID 在另一租户下存在同名 Agent"互不干扰,也让共享记录无法指向不存在的租户组合。

第二,接收方可以"隐藏"共享 Agent 。tenant_disabled_shared_agents(migrations/versioned/000012_organizations.up.sql:137)主键是 (tenant_id, agent_id, source_tenant_id),记录"该租户不想在列表里看到这个共享 Agent"。它只影响展示、不影响权限:即使禁用,通过会话 ID 或直接调用仍可能访问。列表把 DisabledByMe 作为展示字段返回,而不是在权限层过滤。

Agent 共享还有几条约束:内置 Agent 不允许跨租户共享(isBuiltinAgent 过滤);WebSearchReady 在源租户上下文解析,只返回布尔值,不暴露源租户的 provider 列表与凭据;共享 Agent 配置引用的知识库在接收方看来是"通过 Agent 间接可见"的资源,列表接口用 SourceFromAgent 标记这种只读来源,避免误以为存在直接的 KB 共享记录。

5.4.11 撤销矩阵

把"什么动作会让共享失效"整理成一张表,排错时可以逐行核对:

动作 显式处理 读路径兜底
源租户删除知识库 服务层调用 DeleteByKnowledgeBaseID 软删除共享 JOIN knowledge_bases ... deleted_at IS NULL
源租户离开/被移出组织 revokeTenantShares 删除该租户在此组织的共享 src_member JOIN
接收方租户离开组织 无需处理(共享仍属于组织) 接收方不再满足 otm.tenant_id 条件
组织被删除 先删 KB/Agent 共享,再软删除组织 组织 deleted_at IS NULL 过滤
单条共享被撤销 软删除 kb_shares 行 deleted_at IS NULL 过滤
知识库被转移租户(若发生) 无自动处理 source_tenant_id 仍是旧值,需人工修正
源租户被停用/软删除 无级联 取决于登录与成员关系是否仍有效

最后两行是已知缺口:共享记录不会跟随知识库迁移,租户停用也没有级联清理共享。它们不是当前版本的高频路径,但做数据治理时必须知道。

5.4.12 索引形态与查询代价

共享相关查询的形态决定了索引选择:

  • idx_kb_shares_kb_id(migrations/versioned/000012_organizations.up.sql:70):按知识库查共享(权限判断的入口,CheckTenantKBPermission 每次都会用);
  • idx_kb_shares_org_id(migrations/versioned/000012_organizations.up.sql:71):组织共享列表;
  • idx_kb_shares_source_tenant(migrations/versioned/000012_organizations.up.sql:72):撤销某租户在组织内的共享时按来源过滤;
  • idx_org_tenant_members_by_tenant:反查"我参加了哪些组织",ListByTenantID 与 ListSharedKBsForTenant 都依赖它;
  • idx_org_tenant_members_unique(migrations/versioned/000045_org_tenant_members.up.sql:44):成员唯一性与按 (org, tenant) 精确查找。

最重的查询 ListSharedKBsForTenant JOIN 知识库、源成员、接收成员、组织四表,再按 otm.tenant_id 过滤。租户加入大量组织、每组织又共享大量 KB 时,结果集很大,Preload 还会再发查询填充关联。分页不在 SQL 层,而在服务层对 map 去重后整体返回------KB 多时是明确的扩展性瓶颈。

另一个代价点是 SearchSearchableOrganizations 的逐组织统计:成员数、共享数、Agent 共享数各一次查询,属于 N+1。当前用默认 limit 20 控制住了规模,但如果搜索页要展示更多结果,需要改成 GROUP BY 批量聚合。

5.4.13 排错清单

看不到共享知识库,按顺序检查:

  1. 调用者租户是否在 organization_tenant_members 里(GetTenantMember 是否成功);
  2. 源租户是否仍是组织成员(src_member JOIN 是否命中);
  3. 组织与知识库是否被软删除;
  4. 共享行是否被软删除;
  5. 列表接口是否因为 SourceTenantID == tenantID 而跳过了自己的共享(ListSharedKnowledgeBases 会跳过,自己的知识库应走普通列表)。

能看到但不能写 :先算三维帽。共享权限是否为 viewer、组织角色是否为 viewer、调用者租户角色是否为 viewer,任何一维是 viewer 都会把结果压到只读。再检查写路径是否走了 RequireKBWrite 的精确 editor 判定,而不是列表接口返回的展示权限。

离开组织后仍能访问 :检查是否通过共享 Agent 的间接路径访问(Agent 配置里引用了该知识库),或请求级权限缓存被跨请求复用。KBSharePermissions 明确设计为请求级、不可跨 goroutine 共享,正常实现下不会出现;如果出现,优先怀疑自定义代码复用了 resolver。

组织删不掉 :调用者租户不是 owner_tenant_id,且不是 legacy 的 owner_id 用户。先查 SELECT owner_id, owner_tenant_id FROM organizations WHERE id = ?,再确认调用者当前租户。owner 用户换过租户是最常见原因,这也正是 owner_tenant_id 存在的理由。

下一节回到知识本身:knowledge_bases、knowledges、chunks、chunk_revisions 如何表达一个文档从上传到可检索的全过程,以及为什么分块表要同时冗余 knowledge_id 与 knowledge_base_id。

5.5 知识库、文档与分块:一条知识的物化过程

上传一个 PDF,最终能在问答里被引用,中间要跨过四张关系表(knowledge_bases、knowledges、chunks、chunk_revisions)和至少两类外部索引(向量、关键词)。这一节按"行"的顺序拆开这个过程,重点不是流程步骤,而是每一层为什么需要这些列、哪些列是权威、哪些列只是快照。

5.5.1 knowledge_bases:配置容器,而不是数据容器

knowledge_bases 这一行几乎不存知识内容,它存的是"这群文档应该如何被解析、切分、索引、展示"的配置。字段分成四组:

分类与归属 :type 取 document、faq、wiki,空值按 document(internal/types/knowledgebase.go:65);tenant_id(internal/types/knowledgebase.go:71);creator_id(internal/types/knowledgebase.go:77)。creator_id 是 RBAC 引入后补的列,允许 Contributor 编辑自建知识库,老数据回填为空间 Owner,可为空。

模型绑定 :embedding_model_id(internal/types/knowledgebase.go:83)、summary_model_id、vlm_config、asr_config。embedding_model_id 的注释写着硬约束:知识库有文档后不能更换------向量索引的维度与语义空间由模型决定,换模型后旧向量既不能比较也不能自动迁移,所以更新路径直接拒绝。

存储与向量后端 :storage_provider_config(只存 provider 选择,凭据来自租户的 StorageEngineConfig)、storage_backend_id、vector_store_id。vector_store_id 的 GORM tag 带 <-:create(internal/types/knowledgebase.go:104),只在创建时写入,服务层更新 DTO 也不暴露它;否则中途改指向会让检索"看起来正常但永远查不到旧数据"。

行为配置 :chunking_config、image_processing_config、extract_config、faq_config、question_generation_config、auto_tag_config、profile_config、wiki_config、indexing_strategy。几乎都是 JSON 列,更新语义统一为"nil 表示不改,传对象(含空对象)表示整体替换"。KnowledgeBaseConfig 注释明确:未提及的字段必须保留原值,否则旧版客户端每次保存都会清空新功能配置;项目用指针类型 + 显式替换语义规避这个陷阱。

is_temporary(internal/types/knowledgebase.go:67)用于"这次对话临时上传的资料",对 UI 隐藏但仍是完整的知识库行:可被正常检索、共享甚至转正(转移时置 IsTemporary 为 false),只是不出现在普通列表里。

is_pinned 与 pinned_at 是"列还在、模型已弃用"的历史:置顶原本存在知识库行上,导致"谁置顶"变成工作区级决策并要经过 kb-edit 的 RBAC 守卫;现在改为 user_kb_pins 表按调用者计算,模型里两个字段都标了 gorm:"-"(internal/types/knowledgebase.go:133),GORM 在任何 CRUD 中都忽略,老列只为回滚安全保留。

5.5.2 knowledges:一个来源对象的账本

knowledges 每行代表"一个被纳入知识库的来源":上传文件、URL、手写 Markdown、FAQ 导入。它不存正文(在 chunks 或 metadata.content 里),存来源身份、处理状态与存储账目。

来源身份 :type(file/url/manual/faq)、source(URL 或 "manual")、channel(web/api/feishu/notion/... 二十余种)、file_name、file_type、file_size、file_hash、file_path、storage_size、folder_path。folder_path 是后加的列(internal/types/knowledge.go:214),迁移 000079 解释了动机(migrations/versioned/000079_knowledge_folder_path.up.sql:8):过去文件夹上传把相对路径编码进 file_name,列表显示整条路径且无法按目录查询;现在路径独立成列,file_name 只留基名。file_path 是物理存储位置,folder_path 只用于展示与导航。

metadata 是系统内部的摄取状态与 ID(数据源 ID、外部 ID、解析器信息),custom_metadata 是用户可编辑的描述性元数据(internal/types/knowledge.go:226、internal/types/knowledge.go:229)。CustomMetadataText() 只输出用户元数据,内部状态不进入摘要与模型上下文;混在一列会让"加业务标签"变成"往解析状态塞键",后续无法安全清理。

处理状态 :parse_status 是一个比想象中复杂的状态机:

  • pending:已入队,等待处理;
  • processing:DocReader 解析、分块、embedding 进行中;
  • finalizing:主解析已完成,文档已经可以被向量检索,但摘要、问题生成、图谱抽取等增强子任务还在跑;pending_subtasks_count(internal/types/knowledge.go:195)记录未完成数量,最后一个子任务结束时原子地把行推进到 completed;
  • completed:所有子任务终态,不再消耗资源,除非用户显式重解析;
  • failed、deleting、cancelled:失败、删除中、用户取消。cancelled 与 deleting 对下游任务都是"短路"语义,但 cancelled 保留已写入的分块与索引,允许重新解析。

finalizing 是很多系统缺失的中间态:没有它只有"处理中/完成"两态,文档已能搜到却仍显示"处理中",无法判断是慢还是卡住;有了它,前端能区分"可查询但仍在增强"与"完全就绪",取消也有明确语义边界。

summary_status(internal/types/knowledge.go:197)是独立的第二状态机(none/pending/processing/completed/failed),因为摘要失败不应该让整篇文档变成 failed------正文索引已经可用,摘要只是增强。

enable_status 默认 enabled(internal/types/knowledge.go:204),用于整体停用一条知识而不删除它。检索时必须同时过滤 enable_status 与 deleted_at,两者语义不同:前者是"暂时不参与",后者是"已移除"。

一个默认值不一致 :DDL 是 parse_status VARCHAR(50) NOT NULL DEFAULT 'unprocessed'(migrations/versioned/000000_init.up.sql:104),而 Go 常量从 pending 开始,全仓库没有地方写入或识别 unprocessed。应用插入总会显式赋值,正常路径不会出现;但原生 SQL 插入或旧版本遗留的行不属于任何已知状态,列表与轮询会当成未知。看到 unprocessed 应理解为"这行不是当前应用写入的"。

重复检测不是数据库约束 。仓储的重复检查(internal/application/repository/knowledge.go:420)按 tenant_id + knowledge_base_id 过滤,排除 failed 与 deleting(internal/application/repository/knowledge.go:434),再按类型比较:

  • 文件:优先按 type = 'file' AND file_hash = ?(internal/application/repository/knowledge.go:452),并且(若请求带 file_type)区分文件类型;注释说明同内容不同格式(如 .md 与 .txt)应允许并存;
  • 没有 hash 时退化为 file_name + file_size + file_type(internal/application/repository/knowledge.go:469);
  • URL:先比 hash,再比 source;
  • 数据源同步:按 metadata->>'datasource_id' 与 metadata->>'external_id' 判重。

排除 failed 与 deleting 是有来历的修复:注释提到 issue #3338,删除中的行若参与判重,一个永不结束的删除任务会让文档永久"已存在",只能手工改 SQL。

没有唯一索引兜底,两个并发上传仍可能同时通过检查,与 kb_shares 相同:应用层判重覆盖绝大多数场景,极端并发下需在清理任务里处理重复行。

5.5.3 chunks:为什么同一个归属要存三遍

chunks 同时有 tenant_id(internal/types/chunk.go:138)、knowledge_id(internal/types/chunk.go:140)、knowledge_base_id(internal/types/chunk.go:142)。二者都可经 knowledge_id join 得到,属于冗余;但检索是最高频、最不能慢的路径,冗余有两个收益:

  1. 按知识库过滤时不需要 join knowledges;
  2. 多租户隔离条件可以直接落在 chunk 表上,即使上层传错了 knowledge_id,tenant_id 仍是一道独立防线。

代价是三者可能不一致:知识被移动到另一个知识库时,chunk 的 knowledge_base_id 必须同步更新(MoveChunksByKnowledgeID(internal/application/repository/chunk.go:761)就是做这件事,同时清空 tag_id)。绕过服务层直接改 knowledges.knowledge_base_id 会留下"知识在新库、分块在旧库"的脏数据:新库搜不到,旧库能搜到但列表没有。

分块自身的字段可以按用途理解:

位置与顺序 :chunk_index(internal/types/chunk.go:158,文档内序号)、start_at/end_at(internal/types/chunk.go:167,原文字符偏移)、pre_chunk_id/next_chunk_id(internal/types/chunk.go:171,相邻链)、seq_id(internal/types/chunk.go:136,对外数字 ID)。pre/next 让"取上下文"不必按 index 重新查;start_at/end_at 让引用可以定位回原文。

层级 :parent_chunk_id(internal/types/chunk.go:177)、chunk_type(internal/types/chunk.go:175)、relation_chunks(internal/types/chunk.go:179)、indirect_relation_chunks(internal/types/chunk.go:181)。父子分块中,父块类型是 parent_text,只用于给子块提供上下文,不参与向量索引;图片相关分块(image_ocr、image_caption、image_vector)挂在显示图片的文本块下。relation_chunks 与 indirect_relation_chunks 是图谱抽取的产物,以 JSON 数组记录关联分块。

类型 :除了文本与图片,还有 summary(摘要块)、entity/relationship(图谱)、faq、web_search(联网搜索结果落入知识库)、table_summary/table_column(表格结构化)、wiki_page(Wiki 页面接入检索管线)。不同类型在索引时的处理不同:image_vector 的索引行存的是图片本身的向量,不是 Content 的文本向量,注释特别警告"任何按文本重建索引的路径都不能处理它"。这是类型字段承担的真实语义,而不是展示标签。

状态 :is_enabled(internal/types/chunk.go:160,单块停用)、flags(internal/types/chunk.go:163,位标志,当前只用了"可推荐")、status(internal/types/chunk.go:165,0/1/2 表示存储/索引阶段)、index_status(internal/types/chunk.go:154,ready/processing/failed)。status 是早期整数阶段,index_status 是后加的面向用户的索引一致性状态;两者并存说明索引写入拆成"先落库、后同步索引"两段:编辑分块时先把 index_status 置为 processing,同步向量与关键词索引成功后再置 ready,失败置 failed。用户能看到"内容已保存但索引没跟上",而不是沉默的不一致。

5.5.4 Content、SourceContent、ContextHeader:三个文本不是冗余

一个分块有三段可能不同的文本:

  • Content:当前生效的正文,用户可编辑;
  • SourceContent:解析器产出的原始文本,不可变,老数据在第一次编辑时从 Content 惰性回填;
  • ContextHeader:索引时前置的 Markdown 标题面包屑。

EmbeddingContent()(internal/types/chunk.go:225)返回 ContextHeader + "\n\n" + strings.TrimSpace(Content):向量化的是"上下文头 + 正文",展示与引用用的是 Content 。同一句"配置项默认为 30 秒"在"超时"与"重试"章节里向量不同。持久化 ContextHeader 是为了编辑后仍能重建同样的索引输入,否则重新索引会丢失章节语义。

编辑时只要正文变了,SourceLocators 就会被清空(internal/application/service/chunk.go:585),因为编辑后的证据不再对应原始文件:失去"跳转到 PDF 第几页"的能力,换来不产生错误定位。SourceContent 保留,作为图片引用校验的基准------编辑时不允许删掉正文引用的图片。

5.5.5 chunk_revisions:版本表只存旧值

ChunkRevision(internal/types/chunk.go:205)的结构有一句注释定义得很清楚:当前内容在 Chunk 上,这张表存被取代的历史版本。编辑分块时,服务层构造一条 revision,Revision 字段取旧值 oldRevision,Content 取旧内容,然后:

go 复制代码
result := tx.Model(&types.Chunk{}).
    Where("id = ? AND tenant_id = ? AND content_revision = ?", chunk.ID, chunk.TenantID, expectedRevision).
    Updates(fields)
if result.RowsAffected != 1 {
    return ErrChunkRevisionConflict
}
return tx.Create(revision).Error

这是标准的乐观并发控制:更新条件带上旧版本号(internal/application/repository/chunk.go:463),受影响行数为 0 说明有人先改了(internal/application/repository/chunk.go:468),返回冲突而不是覆盖;版本号自增与历史插入在同一事务里,不会出现"版本号加了但没有历史"或反之。

保存字段是白名单而非整行 Updates(chunk):整行更新会让 created_at、seq_id、content_hash 被零值覆盖。白名单含 source_content、source_locators、metadata、index_status、last_editor_id,说明编辑还要同步定位信息与索引状态。图片分块走同一入口,但先同步 chunk_images 投影(syncEditedImageCopies),再更新 image_info 与 content_hash;只允许 caption 或 ocr_text 变化,且必须恰好描述一张图片。

chunk_revisions 不存 index_status 与 source_locators:历史只用于"看当时写了什么、回滚",不需要重放索引状态。回滚是把历史内容写回 Chunk 并再生成一条新历史,仍走同一套 CAS。

5.5.6 seq_id:一个全局自增列的代价

chunks.seq_id 在 PostgreSQL 里是 BIGINT NOT NULL,默认值取自 chunks_seq_id_seq 序列(起始 100000000),并建有唯一索引(migrations/versioned/000010_add_seq_id.up.sql:14,17,26);SQLite 版本是普通 INTEGER 加唯一索引(migrations/sqlite/000000_init.up.sql:270,281)。用途写在注释里:对外 API 的稳定数字标识,尤其是 FAQ。UUID 适合内部关联,但对外系统(客服工单、IM 机器人)更愿意用数字 ID(internal/types/chunk.go:136)。

批量插入前,代码调用 AssignChunkSeqIDs(internal/types/chunk.go:238):

go 复制代码
var maxSeqID *int64
tx.Unscoped().Model(&Chunk{}).Select("MAX(seq_id)").Scan(&maxSeqID)
next := int64(1)
if maxSeqID != nil { next = *maxSeqID + 1 }

注意三点:

  1. Unscoped() (internal/types/chunk.go:251):软删除的行也参与最大值计算,否则删除最大 ID 后新块会复用该号,违反"稳定标识"。
  2. 全局而非按租户:不同租户共享同一条序列。这不泄漏信息(数字本身无业务含义),但意味着 ID 会以整个部署的写入速度增长。
  3. 应用层分配而非数据库序列 :注释说这是为了 SQLite 兼容------SQLite 的 AUTOINCREMENT 在批量插入时对 LastInsertId 的处理与 PostgreSQL 不同,应用层显式赋值最稳。

代价是并发:两个插入事务可能读到同一个 MAX,各自从同一值开始分配,seq_id 的唯一索引会让后写者失败。实际路径上分块写入按知识串行,冲突概率低,但这不是数据库层面的保证;彻底消除要改用各数据库的原生序列,代价是放弃 SQLite 兼容性。

5.5.7 标签:两张表与缺失的外键

knowledge_tags 是知识库内的标签定义(tenant_id、knowledge_base_id、name、color、sort_order),knowledge_tag_relations 是多对多关联(migrations/versioned/000063_knowledge_multi_tags.up.sql:7)。迁移 000063 把 knowledges.tag_id 单列迁移到关联表后删除了旧列(migrations/versioned/000063_knowledge_multi_tags.up.sql:30),说明系统从"一知识一标签"演进为"一知识多标签"。

两个结构性问题:

  • knowledge_tags 的唯一索引是 (tenant_id, knowledge_base_id, name)(migrations/versioned/000001_agent.up.sql:255),没有排除软删除行 。删除一个标签后再建同名标签会命中唯一约束。与 users 的用户名问题同源:软删除与普通唯一索引不兼容。
  • knowledge_tag_relations 没有外键,知识被删除后服务层显式调用 DeleteKnowledgeTagRelations。如果删除流程中途失败,关联行会残留;由于关联表本身没有 deleted_at,这些行会一直存在,直到有清理任务或重新插入时被覆盖(主键是 (knowledge_id, tag_id),会冲突)。这也是为什么删除流程把"清标签关系"放在文件删除之前,并且失败只记警告。

chunks.tag_id(internal/types/chunk.go:144)是另一套东西:它用于 FAQ 条目的分类,和知识级多标签不是同一维度。FAQ 导入时按标签组织条目,检索时可按标签过滤;而知识级标签用于文档列表筛选。两者同名但作用域不同,读代码时容易混淆。

5.5.8 删除、重解析与"被取代"的分块

删除一条知识不是一行 DELETE,而是一串协同动作(internal/application/service/knowledge_delete.go:475),顺序经过精心安排:

  1. 把 parse_status 置为 deleting(internal/application/service/knowledge_delete.go:490),阻止异步任务再处理它;
  2. 对正在排队/运行的任务执行 dequeue(尽力而为,worker 自己也会检查删除状态);
  3. 并行删除向量索引、图谱、分块;
  4. 清理图片引用与 Wiki 页面引用;
  5. 先删知识行,再删物理文件。注释解释了原因(issue #2192):如果先删文件后删行,中途失败会留下"行在、文件没了"的僵尸,重解析和重新删除都会失败;反过来失败只会留下孤儿文件,不破坏数据一致性;
  6. 扣减租户 storage_used;
  7. 删除标签关系,刷新知识库描述聚合,写审计。

分块与知识行都是软删除,但 chunk_revisions 不在删除列表里。这带来一个长期成本:知识删除后,历史版本仍留在库中,且无法通过正常接口访问。真正会清理它们的是 PurgeSupersededChunksByKnowledgeID(internal/application/repository/chunk.go:695):它在一次成功的重解析后,找出"已软删除、且同一位置同一类型已有更新分块"的旧块,硬删除这些块及其版本历史。

这个函数的名字和注释值得细读:它只清理"被成功取代"的分块,不清理用户手动删除的分块,也不清理失败/取消的重解析留下的块。理由是手动删除可能是误操作,需要保留恢复能力;失败重解析的块可能还需要排查。系统把"可恢复性"放在"及时释放空间"之前,代价是这些行长期占用存储,直到下一次成功重解析。

重解析本身的语义也与状态机绑定:cancelled 保留已写入的分块与索引,允许再次解析;failed 不自动清理,失败原因留在 error_message。如果用户在失败后重新上传同一文件,重复检测会排除 failed 行,允许创建新行,旧行成为孤儿------这就是为什么需要一个按状态清理的 housekeeping 任务。

5.5.9 索引经济学:为什么删掉三个索引

迁移 000100_chunks_index_diet 是一次很有代表性的优化(migrations/versioned/000100_chunks_index_diet.up.sql:18):它删除了 idx_chunks_chunk_type、idx_chunks_content_hash、idx_chunks_tenant_kg 三个索引。迁移注释给出的理由不是"索引太多",而是逐个论证"它们从不帮助查询":

  • chunk_type 只有几个不同值,且总是与 knowledge_id/knowledge_base_id 组合过滤,后者已有索引,低基数索引的选择性不足以单独使用;
  • content_hash 没有任何查询按它过滤,FAQ diff 虽然读这一列,但扫描入口是 knowledge_base_id;
  • (tenant_id, knowledge_id) 被 idx_chunks_knowledge_enabled(knowledge_id, is_enabled, deleted_at) 覆盖,后者以高基数的 knowledge_id 打头。

这条注释揭示了一个常被忽略的事实:每个索引都在为写入付费。分块是批量写入最多的表,多一个索引就多一次 B-tree 维护。删除"看起来有用"的索引,需要用查询模式来证明,而不是靠直觉。

与之相对,迁移 000076 增加了一个表达式索引(migrations/versioned/000076_knowledge_metadata_external_id_index.up.sql:20):

sql 复制代码
CREATE INDEX idx_knowledges_kb_metadata_external_id
    ON knowledges (knowledge_base_id, (metadata->>'external_id') text_pattern_ops)
    WHERE deleted_at IS NULL;

三个设计点都写在注释里:数据源重同步按 metadata->>'external_id' LIKE '<parent>#%' 扫描,普通 B-tree 在非 C collation 下不能驱动 LIKE 'x%',必须用 text_pattern_ops 按字节比较;部分索引匹配查询自带的 deleted_at IS NULL;IF NOT EXISTS 保证可重复执行。这是"索引跟着查询走"的正例。

idx_knowledges_folder_path 则是 (tenant_id, knowledge_base_id, folder_path) 复合索引(migrations/versioned/000079_knowledge_folder_path.up.sql:20),服务的是目录树查询:先按租户与知识库限定,再按路径前缀取子树。注意它不能直接加速 LIKE 'docs/%'(除非也用 text_pattern_ops),注释没有声称它能,实际查询若用前缀匹配需要确认执行计划。

5.5.10 一致性检查清单

判断"一条知识为什么搜不到",可以按下面的顺序核对:

  1. knowledges.parse_status 是否为 completed 或至少 finalizing;failed/cancelled 不会进入检索;
  2. enable_status 是否为 enabled;停用的知识即使分块完好也不会被召回;
  3. chunks.is_enabled 是否被单块停用;
  4. chunks.index_status 是否为 ready;processing/failed 表示内容在库里但索引没同步;
  5. chunks.tenant_id、knowledge_base_id 是否与知识行一致(移动知识库后未同步的典型症状);
  6. embedding_model_id 是否与知识库当前模型一致(历史数据换过模型的症状是"有分块但向量维度对不上");
  7. 向量库中是否真的存在对应 chunk_id 的索引行;关系库与向量库是两套存储,任何一侧失败都会造成"单边存在"。

判断"删除为什么没释放空间",则要区分软删除与硬删除:知识、分块、共享都是软删除;物理文件由删除流程显式移除;分块历史要等成功重解析后的 purge;向量索引在删除流程中同步清理,失败时只留下孤儿向量。四类资源的生命周期并不一致,这是排查存储账单时必须分开计算的原因。

下一节转向会话:sessions、messages、message_artifacts 如何记录一次多轮对话,消息为什么要存那么多份"冗余"快照,以及当 Agent 步骤、引用、附件都塞进 JSON 列后,如何仍然支持按会话、按时间、按状态查询。

5.6 会话与消息:没有 tenant_id 的消息表

messages 是少数不带 tenant_id 的业务表(internal/types/message.go:473),隔离完全依赖 session_id:会话属于租户,消息属于会话。这减少了冗余,但任何"只按消息 ID 查"的路径都必须先验证会话归属,否则就是跨租户读取。

5.6.1 sessions:从"对话参数表"变成"运行状态表"

早期 sessions 像对话参数表:max_rounds、enable_rewrite、阈值、fallback_strategy 都挂在会话上,如今被整段注释掉。配置来源改为租户默认、知识库配置、请求级参数三层,sessions 只保留属于"这一次对话"的状态:

身份与归属 :tenant_id(internal/types/session.go:97)、user_id(internal/types/session.go:103)、owner_auth_source(internal/types/session.go:109)、kind(internal/types/session.go:100)。user_id 可能是用户 UUID、API 外部用户标识或嵌入访客标识,故为 VARCHAR(512);owner_auth_source 记录服务端认证来源,客户端传入会被 CreateSession 覆盖(internal/application/service/session.go:245),防止伪造来源影响沙箱分配。

展示与排序 :title、description、is_pinned、pinned_at。会话置顶仍是行上字段,因为会话属于单个用户,不存在"多用户看到不同置顶"。

最后一次请求状态 :last_request_state 复用旧的 agent_config 列(internal/types/session.go:121)以不新增迁移,里面实际存 SessionLastRequestState(Agent、模型、知识库范围、联网开关、MCP 列表)。看到 agent_config 不能假设是 Agent 配置,须以 gorm:"column:..." 为准。

沙箱 :sandbox_config_id、sandbox_config_tenant_id(internal/types/session.go:141)、host_workspace_dir。沙箱配置以 (tenant, id) 为键:共享 Agent 的沙箱属于出借方租户而会话属于借用方,只存 ID 会在借用方租户下查不到;零值表示用会话自己的租户,兼容该列出现前的数据。

分叉 :parent_session_id(internal/types/session.go:156)、forked_from_message_id、fork_bootstrap。parent_session_id 刻意不建外键 :父会话可能被删除而分支要继续存活,悬空值按普通会话渲染。forked_from_message_id 指向父会话中的消息:在用户消息处分叉复制之前的消息,在助手消息处分叉则包含该回答。fork_bootstrap 是一次性沙箱初始化指令,用完后清空。

kind 是后加字段(迁移 000121,migrations/versioned/000121_session_kind.up.sql:1):空值表示普通对话,assistant 表示助手历史,agent_delegated 表示子代理的独立记录。迁移把 agent_config->>'agent_id' = 'builtin-weknora-assistant' 的会话回填为 assistant(migrations/versioned/000121_session_kind.up.sql:3)。IsValidSessionKind 只允许空值与 assistant 通过 API 创建,agent_delegated 只能内部写入。

5.6.2 会话列表的三重作用域

会话查询同时受三个维度约束,漏掉任何一个都会越权:

  1. 租户 :tenant_id 必填;
  2. 所有者 :user_id,空值表示"租户级视图",只对 API Key 或管理员开放;
  3. 来源 :web、embed、api、具体 IM 平台。SessionListSourceRequiresAdmin(internal/types/session.go:232)规定:除 web 与空值外,其它来源都要求 Admin+------API 会话是"整个租户所有 API Key 的流量",普通用户不应看到别人的调用记录。

打开单个会话用 loadSessionForManage:先按 (tenant, owner, session) 查;查不到且调用者是 Web 用户 + Admin+ 时,再按 (tenant, session) 查,但要求 SessionRequiresAdminConsoleRead(internal/types/session.go:242)为真------该会话必须是 API、嵌入、IM 或技能维护会话,管理员不能借"管理"名义打开普通用户的私人对话。

5.6.3 messages:快照比"最新值"更重要

一条助手消息同时保存多份看似重复的信息:

  • content:给用户看的最终回答;
  • rendered_content:送给模型的、带检索上下文的完整用户消息(仅用户消息可能有值),用于下一轮保持检索上下文;
  • knowledge_references(internal/types/message.go:485):本次回答引用的分块;
  • agent_steps(internal/types/message.go:489):Agent 的推理与工具调用步骤,只用于历史展示,不进入 LLM 上下文;
  • mentioned_items:用户 @ 的知识库/文件/标签/MCP/技能;
  • images、attachments:附带的图片与文件;
  • usage:本轮所有 LLM 调用的 token 汇总;
  • execution_context(internal/types/message.go:544):生成后续建议所需的非敏感请求快照,含 Agent 配置哈希、知识库 ID、MCP、技能、locale 与 traceparent;
  • used_memories(internal/types/message.go:552):本次回答注入的长期记忆,供 UI 展示与"删除这条记忆";
  • sandbox_checkpoint、context_checkpoint:沙箱提交点与上下文压缩摘要。

这些是按读取场景拆分的历史快照 :当前 Agent 配置与知识库范围随时会变,历史消息若只存引用,回看旧对话就会用今天的配置解释当时的回答。MessageExecutionContext 只用于派生体验,让异步生成在请求结束后仍能拿到当时的非敏感范围,而不是重放。

MessageAttachment.URL 带 json:"-" 且不落库:它是内部存储句柄(provider://path 或 resource://...),预览必须走会话级附件接口,避免把可跨会话下载的引用泄漏给客户端。

agent_id 与 agent_tenant_id(internal/types/message.go:538)逐轮记录,而不是只存会话上的最后一次;agent_tenant_id 不输出 JSON,用于解析共享 Agent 的模型与知识,属内部执行信息。knowledge_id(internal/types/message.go:547)把消息与"聊天记录知识库"关联:租户开启"把对话索引为知识"时,消息被写成 knowledges 记录,此字段即回链。

5.6.4 完成状态不是一个布尔值

is_completed 表示生成是否结束,但"未完成"有两种截然不同的原因:还在生成,或停在某个需要用户输入的中断点。run_state 补上了这个区分,MessageRunStateAwaitingInput 表示本轮以等待输入结束。没有这个字段,前端只能把"等待输入"显示成"生成中",用户永远等不到结果。

与之配套的还有 collaboration_status、pending_prompt、prompt_history 等 gorm:"-" 字段:它们不落库,读取时从协作状态与提示状态投影出来。注释说明协作状态在临时流过期后仍要从持久状态恢复,因此不能只靠内存。这是"消息行是历史,运行状态在别处,读取时合成视图"的分层。

5.6.5 排序键:为什么是 (created_at, id) 而不是自增

消息按时间排序看似足够,但同一毫秒内写入两条消息时,created_at 相同,顺序不确定。会话回退、分页、重写都会因此出现"同一页重复或漏行"。系统统一采用复合游标(internal/application/repository/message.go:216):

go 复制代码
Where("created_at < ? OR (created_at = ? AND id < ?)", boundary, boundary, boundaryID).
Order("created_at ASC, id ASC")

迁移 000106 为此建了 (session_id, created_at DESC, id DESC) 索引(migrations/versioned/000106_messages_session_created_index.up.sql:13),注释说明它同时服务三种读:向后翻页、反向扫描找最新上下文检查点、原有的最近消息读取。此前只有 session_id 索引,每翻一页都要排序整个会话的消息。

还有两个工程细节:CREATE INDEX CONCURRENTLY 不阻塞写入,但不能在事务块里执行;golang-migrate 把整个文件作为一条查询发送,多语句会被包进隐式事务,所以文件里只能有这一条语句 。中断会留下 INVALID 索引,需手工 drop 后重跑。5.11 会再讨论。

5.6.6 回退(rewind):包含与不包含的语义

DeleteMessagesFrom(internal/application/repository/message.go:309)用同一个复合游标删除"某条消息及之后"的记录(internal/application/repository/message.go:240),但有两个模式:

  • inclusive = true:用户回退点一起删除。因为客户端会把这个问题重新填回输入框,旧消息留着会重复;
  • inclusive = false:助手回退点保留,对话从它之后继续。

读取与删除在同一事务里,返回被删的行供后续清理(沙箱提交点、附件、知识条目)。返回的行必须恰好是删掉的行,否则清理会作用在另一批数据上;单独 SELECT 再 DELETE 会因并发插入而错位。

删除后还要 invalidateDependentCheckpoints(internal/application/repository/message.go:329):如果被删区间之后存在上下文压缩检查点,它们引用的历史已经不存在,必须失效,否则下一轮会把"摘要 + 已删除消息"拼进上下文。

5.6.7 message_artifacts:把"文件列表"从 JSON 里拿出来

技能生成的产物最初可能存在消息的 JSON 列里(SQLite 初始表仍有 artifacts TEXT DEFAULT '[]'),后来 PostgreSQL 迁移 000103 建了独立表(migrations/versioned/000103_message_artifacts_table.up.sql:11):

  • (message_id, position) 唯一(migrations/versioned/000103_message_artifacts_table.up.sql:26):一条消息内产物有序且不重复;
  • (session_id, created_at)(migrations/versioned/000103_message_artifacts_table.up.sql:28):按会话列出所有产物;
  • 字段包括 URL、文件名、类型、大小、内容哈希、源路径、修改时间。

独立成表的原因不只是规范化:产物需要按会话聚合下载、按内容哈希去重、按时间清理,这些都不能高效地在 JSON 数组上做。

写入逻辑有一个不寻常的约定:Artifacts 为 nil 时不动 已有行(internal/types/message.go:504);非 nil 时先删后插,但会保留被用户删除的产物的"墓碑"时间(internal/application/repository/message_artifact.go:60):

go 复制代码
deleted, _ := deletedArtifactPositions(tx, message.ID)
tx.Where("message_id = ?", message.ID).Delete(&types.MessageArtifactRecord{})
for i := range rows {
    if at, ok := deleted[rows[i].Position]; ok && rows[i].DeletedAt == nil {
        rows[i].DeletedAt = at
    }
}

如果没有墓碑保留,每次更新消息都会把用户删除过的产物"复活"。这类"重写集合但保留删除标记"的模式,在 JSON 迁移到关系表的场景里很常见。

读取端用 attachArtifacts(internal/application/repository/message_artifact.go:126)批量查一次再回填。ListAssistantCheckpointsUpTo 是反例:只 Select 少量列、不加载产物,因为调用方只问"历史里有没有提交点"。针对不同问题提供窄查询,是控制 JSON 大字段读取成本的主要手段。

5.6.8 删除会话:软删除的边界

删除会话时,消息不级联物理删除,会话行也是软删除。代码注释明确说:技能产物故意不清理,因为消息是软删除,硬删产物会让"未来恢复会话"变成 404,也会与消息语义不一致;真正回收存储应交给独立 GC 或显式硬删接口。

删除流程还会做几件事:停止后台任务(沙箱、流式生成)、异步删除聊天记录知识库中的对应条目、清理 Redis 里的临时联网搜索知识库状态、删除建议记录、销毁绑定沙箱、释放分叉快照、通知外部清理钩子。任何一步失败大多只记日志,因为主体删除已完成,不能让用户看到"删除失败但会话没了"。

StorageSize 与产物文件不计入租户配额的扣减逻辑------会话删除不调整 storage_used,因为消息与产物本来就不在配额统计里。这与其他资源的计量边界需要分开理解。

5.6.9 查询形态与索引成本

会话与消息的查询可以归为四类,各自对应不同索引:

查询 索引 说明
某会话最近 N 条消息 (session_id, created_at DESC, id DESC) 反向扫描,天然有序
会话列表按更新时间 (tenant_id, kind, user_id, updated_at DESC) WHERE deleted_at IS NULL 部分索引,只覆盖活跃会话
分叉关系 idx_sessions_parent_session_id + 未消费分叉的部分索引 父子关系查询
附件引用扫描 messages USING gin (attachments jsonb_path_ops) WHERE role='user' AND deleted_at IS NULL 只为活跃用户消息建索引

JSONB 的 GIN 索引(agent_steps、agent_config、context_config)在早期迁移里建过,但真正高频的过滤条件都被提升为普通列(agent_id、kind、knowledge_id)。这与知识库章节的结论一致:高频过滤列化,低频配置 JSON 化。GIN 索引写入成本高、体积大,只应服务确实存在的包含查询,例如"哪些消息的附件引用了这个文件"。

会话列表的 keyword 过滤是 title ILIKE '%keyword%',前后通配无法走普通 B-tree。数据量大时这是全表扫描,只能靠租户 + 用户 + deleted_at 的部分索引先把候选集压小。若未来要做全文搜索,需要另建 trigram 或全文索引,而不是期待现有索引生效。

5.6.10 排错清单

消息查不到 :确认 session_id 来自正确的会话,且会话未被软删除;消息表没有 tenant_id,用错租户的会话 ID 不会报"无权限",只会返回空。

顺序错乱或分页重复 :检查调用方是否只用了 created_at 作游标。必须带 id 作为第二排序键,否则同毫秒消息的顺序不稳定。

助手消息一直"生成中" :看 is_completed 与 run_state。run_state = awaiting_input 是正常的中断等待,不是卡死;两者都为空且 is_completed = false 才是真正的未完成。

产物下载 404 :先确认产物行是否存在且 deleted_at 为空;再确认消息是否软删除;最后确认存储对象是否还在。产物行与对象存储是两套生命周期,会话软删除不会删对象。

管理员看不到某会话 :loadSessionForManage 的第二段只对 API/嵌入/IM/技能维护会话开放。普通用户会话对管理员同样不可见,这是设计而非缺陷。

下一节进入派生数据:向量索引、关键词索引与图谱如何存储,它们与关系库的边界在哪里,以及为什么"重建索引"是比"恢复备份"更常用的修复手段。

5.7 派生数据:向量索引、关键词索引与关系库的边界

关系库是权威,索引是派生。这句话说起来简单,但在代码里它意味着两套完全不同的存储、两套写入路径、两套失败模式,以及一条必须靠纪律维持的一致性边界。这一节分别看标准版(PostgreSQL + pgvector + ParadeDB)与 Lite 版(SQLite + sqlite-vec + FTS5)如何落地这件事,并解释几个"看起来应该这样、实际却不是"的设计。

5.7.1 两套索引,两种哲学

标准版的索引仍然在 PostgreSQL 里:一张 embeddings 表同时承载向量与全文检索字段,向量列是 halfvec,全文检索用 ParadeDB 的 bm25 索引。Lite 版则把索引拆成三层:

  • lite_embeddings:普通表,存元数据与正文,AutoMigrate 创建(internal/application/repository/retriever/sqlite/repository.go:55);
  • vec_embeddings_<dim>:每个维度一张 vec0 虚表,只存 rowid 与向量(internal/application/repository/retriever/sqlite/repository.go:184);
  • lite_embeddings_fts:contentless FTS5 虚表(internal/application/repository/retriever/sqlite/repository.go:142),存分词后的正文与检索字段。

标准版是"一张表、多种索引",Lite 版是"元数据表 + 多个专用索引表,用 rowid 对齐"。前者查询简单,后者更贴近嵌入式数据库的能力边界:sqlite-vec 不支持在任意列上建索引,FTS5 也不支持向量,只能各建一张虚表再用主键 join。

两者共享同一个抽象:RetrieveEngineRepository 接口,向上暴露 Save、BatchSave、Retrieve、DeleteByKnowledgeIDList 等方法。上层检索服务不需要知道底层是 pgvector 还是 sqlite-vec,但它必须接受一个事实:不同后端的召回行为不完全相同,阈值、TopK、过滤后的结果数都会有差异。

5.7.2 embeddings 表:一张表里的两种检索

标准版的 embeddings 字段如下(迁移 000002,migrations/versioned/000002_embeddings.up.sql:23):

sql 复制代码
CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    source_id VARCHAR(64) NOT NULL,
    source_type INTEGER NOT NULL,
    chunk_id VARCHAR(64),
    knowledge_id VARCHAR(64),
    knowledge_base_id VARCHAR(64),
    content TEXT,
    dimension INTEGER NOT NULL,
    embedding halfvec
);
CREATE UNIQUE INDEX embeddings_unique_source ON embeddings(source_id, source_type);

几个关键决定:

(source_id, source_type) 唯一 (migrations/versioned/000002_embeddings.up.sql:38)。索引源不只是 chunk:FAQ 条目、问题生成、摘要块都可能成为索引源,source_type 区分类型;同一个源重复索引走 upsert 而非插入第二行,保证"重新索引"幂等。

embedding halfvec 不指定维度 (migrations/versioned/000002_embeddings.up.sql:35)。pgvector 的 vector(n) 要求固定维度,而一个部署可能同时存在 798、1024、3584 维的模型;用无维度 halfvec 存、再为每个维度建部分表达式索引,是同时支持多模型的唯一做法。代价是查询必须显式 cast 到具体维度,且 cast 表达式必须与索引定义完全一致,否则规划器不用索引。

dimension 是冗余列,但必须存在 。HNSW 部分索引的谓词是 WHERE (dimension = 3584)(migrations/versioned/000002_embeddings.up.sql:62),查询也必须带 dimension = $n,否则索引不适用;它也让"按维度清理"成为可能。

没有 tenant_id 。这是本章最值得警惕的一点:向量检索 SQL 只按 knowledge_base_id、knowledge_id、tag_id、is_enabled 过滤,没有租户条件,隔离完全依赖调用方传入的知识库 ID 列表来自当前租户------索引层不设防,防线在上层 (5.10 专节审计);任何绕过知识库归属校验、直接把用户输入当 knowledge_base_id 的代码都是跨租户读取。

is_enabled 可空 。查询条件是 (is_enabled IS NULL OR is_enabled = true),历史数据没有该字段时视为启用,代价是索引无法用简单的 is_enabled = true 等值条件,必须写成 OR。

5.7.3 HNSW:三个维度、一个后台建造者

迁移只建了 3584(OpenAI text-embedding-3-large)、798、1024(bge-m3)三个维度的 HNSW 索引,这是历史演进痕迹而非设计限制:其它维度(如 2560、1536)的查询会退化为全表顺序扫描,结果正确但慢。

ensureHNSWIndex 逐条拆解:

  1. 每个维度每个进程只调度一次 。sync.Map 的 LoadOrStore(internal/application/repository/retriever/postgres/hnsw_index.go:47)保证并发请求不重复触发;请求线程只碰一次 map,不阻塞、不因建索引失败而失败。
  2. 后台建索引 。go g.buildHNSWIndex(dimension),失败只打警告并提示"该维度查询将继续顺序扫描,可手工 CREATE INDEX CONCURRENTLY 或重启重试"(internal/application/repository/retriever/postgres/hnsw_index.go:60)。
  3. AUTO_MIGRATE=false 时完全禁用 (internal/application/repository/retriever/postgres/hnsw_index.go:33):schema 由外部管理时,应用不应擅自做 DDL。
  4. 会话级 advisory lock 串行化多副本 。pg_try_advisory_lock(0x574B4E48, dimension)(internal/application/repository/retriever/postgres/hnsw_index.go:97),拿不到锁说明别的进程在建,直接返回。
  5. 先查目录确认已有有效索引 。条件是"USING hnsw + halfvec(<dim>) + halfvec_cosine_ops + 谓词等于 (dimension = dim)",不限索引名,运维手工建的也能识别。
  6. 无效索引分两种 :应用自己命名的(embeddings_embedding_idx_<dim>)先查 pg_stat_progress_create_index,确认没有在建后 DROP INDEX CONCURRENTLY;别人命名的不擅自删除,只在日志提示。
  7. 提升 statement_timeout (internal/application/repository/retriever/postgres/hnsw_index.go:134)。CREATE INDEX CONCURRENTLY 可能跑很久,角色级超时会中断它并留下无效索引;SET LOCAL 不可用(CONCURRENTLY 不能在事务里),只能 SET 后 RESET,而连接会回到池里,RESET 不可省。
  8. 建完验证覆盖范围 。IF NOT EXISTS 找到的同名索引可能有效但只覆盖一个知识库(手工建过部分索引),仅"存在且有效"不够,还要检查定义。

这是全书"防御式 DDL"最完整的样本:并发、超时、中断残留、命名冲突、外部管理与幂等同时处理------在运行中的应用里做 DDL,复杂度远高于在迁移文件里做一次。

5.7.4 向量查询:表达式、预算与召回损失

VectorRetrieve 的 SQL 结构是"子查询取候选 → 外层按阈值过滤 → 最终 TopK":

sql 复制代码
SELECT id, content, ..., (1 - distance) as score
FROM (
    SELECT ..., embedding::halfvec(%d) <=> $1::halfvec(%d) as distance
    FROM embeddings
    WHERE dimension = $2 AND knowledge_base_id IN (...) AND ...
    ORDER BY embedding::halfvec(%d) <=> $1::halfvec(%d)
    LIMIT $3
) AS candidates
WHERE distance <= $4
ORDER BY distance ASC
LIMIT $5

三个非显然的点:

cast 表达式必须逐字匹配索引定义 。注释用大写强调:embedding::halfvec(%d) 两侧的 cast 不是冗余(internal/application/repository/retriever/postgres/repository.go:469),是让 HNSW 索引被使用的唯一方式。pgvector 要求 ORDER BY 的表达式与索引表达式完全一致,否则规划器退化为顺序扫描。这类"语义相同但写法不同导致索引失效"的问题,在表达式索引上是常态。

候选预算被限制在 100--200 。expandedTopK = TopK * 2(internal/application/repository/retriever/postgres/repository.go:449),下限 100、上限 200。注释解释:HNSW 要求 ef_search >= LIMIT,而非常大的 LIMIT 会让 HNSW 走遍图的大部分,比顺序扫描还慢,规划器也会改选 Seq Scan。200 是"够阈值过滤、又不炸 ef_search"的折中。

ef_search 与迭代扫描 。查询在事务里 SET LOCAL hnsw.ef_search = expandedTopK(internal/application/repository/retriever/postgres/repository.go:512),并尝试 SET LOCAL hnsw.iterative_scan = strict_order(internal/application/repository/retriever/postgres/repository.go:526)。后者让 HNSW 在过滤条件很 selective 时继续取候选,而不是只返回 ef_search 条就结束。旧版 pgvector 不认这两个 GUC,代码会在事务失败后去掉 SET 重试,保证仍能返回结果(只是召回可能变差)。这是明确的"功能降级但可用"策略。

阈值语义是 distance <= 1 - threshold(internal/application/repository/retriever/postgres/repository.go:489),分数是 1 - cosine_distance。配置里的 vector_threshold 是余弦相似度下限,不是距离上限;理解反了会把"调高"当"放宽",实际是收紧。

5.7.5 关键词检索:BM25 与两种函数名

标准版关键词索引是 ParadeDB 的 bm25,建在 (id, knowledge_base_id, content, knowledge_id, chunk_id) 上,content 用 chinese_lindera 分词器。查询用 content ||| ?(internal/application/repository/retriever/postgres/repository.go:281,匹配任意 token),排序用 bm25(id) 或 pgsearch.score(id)。

resolveKeywordScoreFunction(internal/application/repository/retriever/postgres/repository.go:60)在启动后第一次查询时探测可用函数名,缓存在互斥锁保护的字段里,只接受两个取值(internal/application/repository/retriever/postgres/repository.go:70),其它一律报错"PostgreSQL keyword retrieval requires paradedb.score(anyelement) or pgsearch.score(anyelement)"------ParadeDB 改名/兼容层导致同名扩展在不同版本里函数名不同,代码不能硬编码。

BM25 索引包含 knowledge_base_id 与 knowledge_id 字段,但过滤仍走普通 WHERE ... IN:索引只当"全文打分器",过滤交给 SQL。小结果集没问题,大租户可能有"先取全局 TopK 再过滤"的召回损失;实际行为由规划器决定,应以 EXPLAIN 为准。

关键词查询同样没有 tenant_id 条件,隔离依赖上层传入的 KB ID。

5.7.6 Lite:一张元数据表 + N 张 vec0 + 一张 FTS5

Lite 版结构更复杂,因为 SQLite 没有统一的向量类型:

lite_embeddings 由 AutoMigrate 创建,字段类似 PG 的 embeddings,但没有 embedding 列,多了 tag_id 与可空的 is_enabled。它是元数据与正文的权威副本;vec0 表只存向量,FTS5 只存分词文本,都通过 rowid = lite_embeddings.id 关联。

vec_embeddings_<dim> 按维度动态创建:

sql 复制代码
CREATE VIRTUAL TABLE IF NOT EXISTS vec_embeddings_2
USING vec0(embedding float[2] distance_metric=cosine)

ensureVecTable 有三个防御:读写锁保护 vecTables 缓存(并发写 map 是 Go 的致命错误);创建后 verifyVecTable(internal/application/repository/retriever/sqlite/repository.go:212)检查 sqlite_master 里确实是 vec0 表(CREATE VIRTUAL TABLE IF NOT EXISTS 遇到同名普通表会静默成功,缓存会永久错误);写失败时 unmarkVecTable(internal/application/repository/retriever/sqlite/repository.go:202)清缓存,让下一次写重新检查。

lite_embeddings_fts 是 contentless FTS5 表(content=''),用 contentless_delete=1 与 unicode61 分词(internal/application/repository/retriever/sqlite/repository.go:142)。中文没有空格,unicode61 会把整句当一个 token,所以写入前用 tokenizeCJKBigram(internal/application/repository/retriever/sqlite/repository.go:923)把连续汉字切成二元组,非汉字按空白/标点切分,单个汉字单独成词;查询侧用同一函数,保证"索引怎么切、查询就怎么切"。

sanitizeFTS5Query(internal/application/repository/retriever/sqlite/repository.go:971)还有两个细节:

  • 单个汉字后加 *:索引里只有二元组,"股"从未作为独立 token 出现,只能前缀匹配"股票""股份"等;
  • 查询限定 content 列:FTS 表也索引了 source/chunk/knowledge/KB ID,不限定列时搜"2023"可能命中 UUID 片段。

召回差异 :vec0 查询必须写 k = ?(internal/application/repository/retriever/sqlite/repository.go:661),过滤在 WHERE rowid IN (SELECT ...) 里后置完成:先取 k 个最近邻,再筛掉不满足 knowledge_base_id/is_enabled 的行,结果可能少于 TopK,且没有 PG 的迭代扫描补偿。过滤越 selective,召回损失越明显------这是 sqlite-vec 的能力边界,不是 bug。

BM25 分数缩放 :FTS5 的 bm25() 返回负值(越小越相关),SQL 里乘 -1000000.0 变成正数(internal/application/repository/retriever/sqlite/repository.go:577)。系数没有理论依据,只是让日志分数"看起来正常",不影响排序;但上层若用绝对分数做阈值就必须知道它。标准版 paradedb.score 返回正分,两套后端分数不可直接比较。

5.7.7 一致性:谁是权威,怎么修

关系库与索引之间没有分布式事务。写入路径是"先写关系库,再写索引",读取路径是"先查索引,再用 chunk_id 回关系库取正文"。这带来几种典型的不一致:

现象 原因 修复
有分块,搜不到 索引写入失败;index_status = failed 重新索引该分块
搜到分块,正文为空/旧 索引行残留,chunk 已改或删 重建该知识/知识库索引
向量维度不匹配 换了 embedding 模型 清空并按新模型重建
Lite 关键词全空 驱动未编译 sqlite_fts5 用发布版二进制,或接受仅向量检索
结果数少于 TopK 后置过滤筛掉太多(Lite) 增大 k 或缩小过滤范围

修复的首选是重建索引,而不是恢复数据库备份。原因在 5.1 已经说过:chunk 是权威,索引可以完全由 chunk 内容 + 模型重新生成。恢复备份反而可能把关系库回退到更旧的状态,制造新的不一致。

重建的粒度有三种:单分块(编辑后的增量同步)、单知识(DeleteByKnowledgeIDList 后重放)、整库(清空该 KB 的所有索引行再全量写入)。选择哪种取决于不一致的范围:index_status = failed 的单块用第一种;模型更换、批量导入异常用第三种。整库重建时要注意先删后写,否则 (source_id, source_type) 的唯一约束会让写入变成更新,旧向量可能残留。

5.7.8 容量与计量

索引占用的存储会计入租户 storage_used。PG 后端的 calculateIndexStorageSize(internal/application/repository/retriever/postgres/repository.go:89)给出估算公式:

  • 正文:len(content) 字节;
  • 向量:dimension * 2 字节(halfvec 每维 2 字节);
  • 元数据:固定 200 字节。

这个公式是估算,不含索引本身的 B-tree/HNSW 开销、行头、TOAST、页填充。真实占用通常显著高于估算,尤其是 HNSW 图结构。因此"配额还剩很多但磁盘满了"是可能的,运维需要同时看数据库实际大小与配额计量。

Lite 版没有单独的索引计量,lite_embeddings 与虚表都在同一个 SQLite 文件里,storage_used 主要统计原始文件与文本。桌面用户看不到配额,这个差异影响不大;但把 Lite 数据迁移到标准版时,不能直接把 storage_used 当作真实占用。

一个容易忽略的成本是多维度并存 。每引入一个新 embedding 模型,就会多一张 vec0 表或一组 HNSW 索引,旧模型的索引不会自动删除。知识库换模型被禁止,但删除知识库/重建时旧维度行可能残留;ensureExistingVecTables 会在启动时把历史维度全部建表,即使那些维度已经没有任何新写入。定期按 dimension 统计行数,是发现"僵尸维度"的简单办法。

5.7.9 排错清单

标准版向量检索很慢 :先确认 EXPLAIN 是否用了 HNSW。若显示 Seq Scan,检查三件事:查询的 cast 维度是否与索引一致;dimension = ? 条件是否存在;该维度是否根本没有索引(看启动日志里的 "No HNSW index for %d-dim")。手工补索引时用 CREATE INDEX CONCURRENTLY,不要在业务高峰做。

召回明显偏低 :检查 vector_threshold 是否被调高(它是相似度下限);检查 TopK 是否小于 ef_search 的默认 40;Lite 版检查后置过滤是否筛掉了大部分候选。

关键词搜不到中文 :标准版确认 pg_search 扩展与 chinese_lindera 分词器可用、BM25 索引存在;Lite 版确认二进制带 sqlite_fts5 tag,且 lite_embeddings_fts 的建表 SQL 里 content=''(旧版可能是外部内容表,启动时会自动迁移)。

索引写入报唯一约束 :(source_id, source_type) 冲突说明同一源被并发索引。标准版应走 upsert 或先删后写;Lite 版 BatchSave 已改为 upsert,注释提到旧实现用 ON CONFLICT DO NOTHING 会让 RETURNING 的 ID 错位,把向量与 FTS 行挂到错误的源上------这是值得记住的教训:批量 upsert 的返回行顺序不能想当然。

下一节离开存储,转向代码层:GORM 在这个项目里被怎样使用,哪些约定是强制的,哪些"看起来能用"的写法实际会踩坑。

5.8 GORM 的真实用法:一个"只用了一小半"的 ORM

WeKnora 大量使用 GORM,但配置与模型定义都很克制:不自动建表、不做关联级联、不依赖钩子做业务、不把事务藏在模型里。本节集中讲"看起来能用、实际会踩坑"的约定------数据层 bug 多数不是 SQL 写错,而是 GORM 默认行为与直觉不一致。

5.8.1 配置只有两个字段

数据库连接建立时的 gorm.Config 几乎为空:

go 复制代码
db, err := gorm.Open(dialector, &gorm.Config{
    NowFunc: func() time.Time {
        return time.Now().UTC()
    },
    Logger: newGormLogger(os.Stdout),
})

没有 NamingStrategy、PrepareStmt、DisableForeignKeyConstraintWhenMigrating、SkipDefaultTransaction------项目接受 GORM 全部默认行为,只在两处覆盖:

  • 时间统一为 UTC 。CreatedAt、UpdatedAt 由 GORM 在应用侧赋值(internal/container/container.go:1086),不是数据库 NOW();时间来源只有应用进程时钟,多实例时钟漂移会带来写入时间漂移,数据库服务器时区不影响数据含义。
  • 日志走自定义实现。默认 logger 会把参数值打进日志,而参数里可能有整段 chunk 文本和上千维向量。

SkipDefaultTransaction 保持默认 false,每个 Create、Update、Delete 都被包一层事务,单条写入多出 BEGIN/COMMIT 两次往返;批量导块时被 CreateInBatches 摊薄,高频小写入(消息、审计、任务状态)仍有开销。项目不关它是正确性优先:多表写入时默认事务避免"一半成功"。要极致吞吐应在仓储内部显式用大事务,而不是关掉全局默认事务。

5.8.2 日志:既要能定位慢查询,又不能泄漏内容

newGormLogger 的配置值得逐项看:

go 复制代码
gormlogger.Config{
    SlowThreshold:             200 * time.Millisecond,
    LogLevel:                  gormlogger.Warn,
    IgnoreRecordNotFoundError: false,
    Colorful:                  true,
    ParameterizedQueries:      true,
}

ParameterizedQueries: true(internal/container/gorm_logger.go:25)最关键:慢查询日志保留 SQL 骨架与耗时,绑定参数被占位符替代,既避免把文档内容、向量字面量写进日志(体积与隐私),也让同形状 SQL 可聚合;代价是排障看不到具体值,需结合业务 ID 另查。

LogLevel: Warn 只记录慢查询、错误和 ErrRecordNotFound;IgnoreRecordNotFoundError: false 让"查不到"也按错误级别打印,使"预期存在的行不存在"第一时间暴露,代价是可选查询路径的噪声------项目保留噪声,因为 record not found 常是真实故障前兆。SlowThreshold(internal/container/gorm_logger.go:21)为 200ms,对 OLTP 偏宽松:主键查询超过 200ms 通常说明索引缺失或锁等待;检索类 SQL 的耗时分布不同,应看 pg_stat_statements 而非应用日志。

5.8.3 模型钩子承担默认值,而不是数据库默认值

项目里有二十多个 BeforeCreate 钩子。它们做的事高度一致:补 UUID、把 nil 切片变成空切片、把空 JSON 变成 {}。例如 Message.BeforeCreate(internal/types/message.go:655):

go 复制代码
func (m *Message) BeforeCreate(tx *gorm.DB) (err error) {
    m.ID = uuid.New().String()
    if m.KnowledgeReferences == nil {
        m.KnowledgeReferences = make(References, 0)
    }
    if m.AgentSteps == nil {
        m.AgentSteps = make(AgentSteps, 0)
    }
    ...
}

Knowledge.BeforeCreate(internal/types/knowledge.go:305)还处理了一个更隐蔽的问题:

go 复制代码
// JSON.Value returns SQL NULL for an empty value. PostgreSQL's column
// default is not applied when GORM explicitly inserts that NULL, so keep the
// application-side representation aligned with the NOT NULL database
// invariant for every knowledge creation path.
if len(k.CustomMetadata) == 0 {
    k.CustomMetadata = JSON(`{}`)
}

注释说清因果关系:JSON 的 Value() 对空值返回 SQL NULL,而 PostgreSQL 列默认值只在插入语句没提到该列时生效;GORM 总是显式列出字段,NULL 便直接撞上 NOT NULL,数据库默认值轮不到。这不是 bug,而是两套默认值机制混用的冲突。

默认值策略可总结为:能在数据库默认值里表达的仍写在 DDL 里;凡是 GORM 会显式写入的列,必须在应用层保证非空。 判断真实默认值不能只看迁移文件,还要看模型钩子与创建路径:parse_status 的 DDL 默认是 unprocessed,新代码创建时写入 pending,读代码时以当前创建路径为准。

5.8.4 JSON 类型的三种"空"

types.JSON 是对 json.RawMessage 的包装,Scan 与 Value 定义了它在数据库与应用之间的转换:

  • len(j) == 0 时,Value() 返回 nil(internal/types/json.go:44),写入 SQL NULL;
  • Scan 读到 NULL 或空字节时,把值设为 nil;
  • MarshalJSON 对空值输出字面量 null(internal/types/json.go:52),而不是 {};
  • ToString() 对空值返回 "{}"(internal/types/json.go:71),这是一个刻意的展示层兜底。

因此同一个"没有配置"在链路上有四种形态:Go 的 nil、数据库的 NULL、JSON 响应的 null、业务代码眼中的 {}。知识库配置约定"字段为 nil 表示本次不修改",这只有在读取路径保留 nil 时才成立;一旦中间层把 nil 统一成 {},部分更新就会清空原配置。

所以更新逻辑必须区分"请求里有没有这个键"(指针或 json.RawMessage 的 nil)与"键的值是否为空"(解析后的零值)。混用会产生"只想改分块大小,却把 VLM 配置清空"的问题。

5.8.5 gorm:"-":读得到,写不进

模型里有大量计算字段带 gorm:"-":

go 复制代码
IsPinned       bool       `json:"is_pinned" gorm:"-"`
PinnedAt       *time.Time `json:"pinned_at" gorm:"-"`
KnowledgeCount int64      `json:"knowledge_count" gorm:"-"`
ChunkCount     int64      `json:"chunk_count" gorm:"-"`
IsProcessing   bool       `json:"is_processing" gorm:"-"`
CreatorName    string     `json:"creator_name,omitempty" gorm:"-"`

这些字段由服务层额外查询后填充:置顶来自 user_kb_pins,计数来自聚合查询,处理状态来自文档状态统计。Message.Artifacts 也是 gorm:"-",实际存储在独立的 message_artifacts 表,读取时由 attachArtifacts 批量挂载。

gorm:"-" 的语义是"完全忽略此字段":查询不扫描,插入不包含,更新不写入。它带来两个必须记住的后果:

  1. 对读出的结构体调用 Save(),计算字段既不写回、也不以零值覆盖------它根本不参与 SQL。
  2. 若误以为它们会持久化并让业务依赖,重启或换查询就会丢失;把 IsPinned 当真实列过滤,SQL 会直接报列不存在。

判断字段是否真实存在,应看迁移文件或 gorm:"-" 标记:结构体是"API 视图 + 数据库视图"的混合体,二者并不总一致。

5.8.6 Updates 的零值陷阱与 Select("*") 的反向陷阱

GORM 用结构体做 Updates 时,会跳过零值字段。这对"只更新非空字段"很方便,但对"把布尔改成 false""把计数改成 0""把状态改成空字符串"是灾难。项目的应对方式分两种。

第一种是显式用 map:

go 复制代码
Updates(map[string]interface{}{
    "folder_path": folderPath,
    "updated_at":  time.Now(),
})

map 里的零值会被如实写入,语义最清楚。大量状态迁移、计数更新、时间戳更新都采用这种方式。

第二种是用 Select("*") 强制更新所有字段:

go 复制代码
return r.db.WithContext(ctx).Debug().Model(&types.Model{}).Where(
    "id = ? AND tenant_id = ?", m.ID, m.TenantID,
).Select("*").Updates(m).Error

这适合"整对象覆盖"的编辑接口,因为调用方已经把完整对象读出来改过。但它要求结构体里不能有 gorm:"-" 的计算字段参与业务判断,否则会出现"读出来是全的、写回去只写真实列"的不对称。

Select("*") 在插入路径上还有另一个坑,项目在分块写入时专门绕开了:

go 复制代码
// GORM substitutes default:true for a zero bool even with Select("*").
// A non-nil pointer makes both true and false explicit on insert, while
// embedding the original chunk keeps generated seq_ids and timestamps on it.
type chunkInsert struct {
    *types.Chunk
    IsEnabled *bool
}

原因是 IsEnabled 字段带 default:true 标签。即使用 Select("*") 明确要求写入该列,GORM 在遇到零值 false 时仍可能用默认值 true 替代(internal/application/repository/chunk.go:70)。解决办法是用 *bool 指针:非 nil 指针表示"这是显式值",GORM 就不会套默认值。这个技巧在需要"显式写入零值"且列上又有默认值的场景里通用。

这类问题的共同点是:GORM 的默认值、零值跳过、Select 三者会相互作用,单看任何一项都推不出最终 SQL。 遇到"明明赋了值却没写进去"或"没赋值却被写成 true",应优先检查字段标签和 Select 组合。

5.8.7 软删除只覆盖"模型查询",不覆盖手写 SQL

gorm.DeletedAt 的默认 scope 只对"以模型为根的查询"生效。以下情况都不会自动加 deleted_at IS NULL:

  • Joins("JOIN ...") 里手写的连接条件;
  • Table("...") 开头的原生风格查询;
  • Raw/Exec 的 SQL;
  • 子查询里的表;
  • 聚合统计里手动写的 COUNT(*)。

项目在多个地方显式补条件,例如共享知识库列表的 JOIN 常量里,对 knowledge_bases 和成员关系都写了 deleted_at IS NULL。这类条件漏写的后果不是报错,而是"删掉的数据又出现在列表里",或者计数偏大。排查统计类问题时,应把每一个 JOIN 的表都过一遍软删除条件,而不是只看主表。

Unscoped() 的使用也要克制。项目在两类场景用它:一是计算 seq_id 的全局最大值(必须包含已删除行,否则会复用编号);二是物理清理已删除数据。前者如果漏掉 Unscoped(),删除一行后新行可能拿到重复编号,撞上唯一索引。后者则必须确认调用方真的想永久删除。

5.8.8 事务边界在仓储内部,服务层无法自由组合

项目里有六十多处 db.Transaction,几乎全部位于仓储实现内部。典型形态是:

go 复制代码
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
    ...
})

仓储接口不暴露 *gorm.DB,也没有 WithTx 之类的方法。这意味着服务层无法把多个仓储调用组合进同一个事务。例如"创建知识库 + 写审计日志 + 更新配额"如果分属三个仓储,就只能各自提交,失败时靠补偿而不是回滚。

这个限制是有意为之:接口保持纯粹,不泄漏 ORM 类型;事务只覆盖单个聚合内部的不变量,例如"分块与其修订记录一起写""知识库行与其标签关系一起改"。跨聚合的一致性交给业务补偿、幂等重试和后台清理。理解这一点,才不会在服务层到处寻找"怎么开事务",也不会误以为一次 HTTP 请求内的所有写入是原子的。

事务内部还有两个细节:

  • SQLite 的写事务是单写者 。AssignChunkSeqIDs 必须在写事务内先读 MAX(seq_id) 再插入(internal/application/repository/chunk.go:88),注释明确说这是为了让读和写落在同一连接上;如果读在事务外,另一个写入者可能插进来,导致编号冲突。PostgreSQL 用序列,跳过这段逻辑,因为序列本身保证唯一。
  • tx.Name() 是方言分支的常用手段 。项目大量使用 tx.Name() == "sqlite" 或 != "sqlite" 来决定是否加 FOR UPDATE、是否手工分配自增 ID、是否使用 ON CONFLICT。这类分支散落在仓储里,是双数据库支持的主要成本来源。

5.8.9 方言差异被压缩成字符串比较

gorm.Open 之后有一道启动检查:

go 复制代码
if name := db.Dialector.Name(); name != "postgres" && name != "sqlite" {
    return nil, fmt.Errorf("unsupported gorm dialector %q; ...", name)
}

注释解释了原因:服务层有代码用 Dialector.Name() 与字符串 "postgres"/"sqlite" 比较(internal/container/container.go:1101),例如向量存储删除时的行级锁保护。如果换成一个包装过的 PostgreSQL 方言(某些托管服务的驱动会这样做),名字可能变成别的字符串,代码就会静默走 SQLite 分支,丢掉 FOR UPDATE。启动时直接拒绝,比运行到一半发现锁没生效要好。

这也说明项目的"双数据库支持"不是抽象出一套统一 SQL,而是承认差异、在必要处分支。常见的分支点包括:

能力 PostgreSQL SQLite
自增非主键列 序列 不支持,应用层 MAX+1
行级锁 SELECT ... FOR UPDATE 无,靠事务串行化
部分唯一索引 支持 不支持,唯一约束覆盖全部行
并发建索引 CREATE INDEX CONCURRENTLY 不适用
全文检索 ParadeDB BM25 FTS5
向量类型 halfvec/vector vec0 虚表

每一行差异都可能变成业务语义差异。最典型的是 5.3 节讲过的成员唯一索引:PostgreSQL 允许软删除后重新添加,SQLite 不允许。写跨方言的仓储代码时,不能假设"同一个接口在两边行为一致",必须逐个确认分支。

5.8.10 AutoMigrate 几乎不存在

除了测试代码和 Lite 检索器的索引表,生产路径几乎不调用 AutoMigrate。Schema 完全由 SQL 迁移定义。这个选择带来三个后果:

  • 模型字段与数据库列的对应关系不会被自动修复。改了结构体却忘了写迁移,运行时才会报"列不存在"。
  • 索引、约束、默认值、部分索引这些 GORM 不擅长表达的东西,可以精确控制。
  • 迁移可以写数据回填、可以分步加约束、可以 CONCURRENTLY,这些都不是 AutoMigrate 能做的。

唯一的例外是 Lite 检索器:lite_embeddings 用 AutoMigrate 创建,vec_embeddings_<dim> 与 FTS5 虚表用原生 DDL 创建。它们被明确视为"索引",可以随时删除重建,所以不需要纳入版本化迁移。这个边界很清楚:业务表走迁移,派生索引走运行时自建。

5.8.11 表名与列名:不要相信复数化规则

GORM 默认把结构体名转成蛇形复数。大多数时候结果正确,但项目仍为不少模型显式实现了 TableName():

go 复制代码
func (AuditLog) TableName() string { return "audit_logs" }
func (CustomAgent) TableName() string { return "custom_agents" }
func (KnowledgeProcessingSpan) TableName() string { return "knowledge_processing_spans" }

原因有两类:一是复数化规则对某些词的结果与迁移里的表名不一致;二是表名是外部契约(备份、监控、运维脚本都按表名写),不能随 ORM 升级而变化。显式声明把表名钉死,是低成本高收益的做法。

列名也有覆盖,通常是因为历史列名与业务语义脱节:

go 复制代码
Trigger AutomationTrigger `gorm:"column:trigger_config;serializer:json;type:text;not null"`
Profile *KnowledgeProfile `json:"profile,omitempty" gorm:"column:profile;type:json"`

serializer:json 是另一种 JSON 存储方式:字段本身是结构体,由 GORM 负责序列化。它与 types.JSON 的区别在于,前者在应用层始终是强类型对象,后者保留原始字节以便"不解析就转发"。项目两种都用:需要业务逻辑处理的结构用 serializer,需要原样透传或延迟解析的用 types.JSON。

5.8.12 错误处理:哨兵值比字符串可靠

仓储层大量返回哨兵错误,例如 ErrChunkRevisionConflict、ErrKnowledgeNotFound。调用方用 errors.Is 判断,而不是比较错误字符串。这一点在 GORM 场景下尤其重要,因为 gorm.ErrRecordNotFound 会被层层包装,直接 == 比较经常失效。

ErrRecordNotFound 的另一个陷阱是:它既可能表示"业务上不存在",也可能表示"租户不匹配导致查不到"。仓储方法如果带了 tenant_id 条件,查不到时无法区分这两种情况。服务层因此通常把它统一映射成"资源不存在",而不是"无权访问",这是有意的信息隐藏:不向调用方泄漏"这个 ID 存在但属于别人"。

至此,GORM 层面的约定已经清楚:配置极简、默认值靠钩子、零值靠 map、方言靠分支、事务靠仓储、Schema 靠迁移。下一节把这些约定放进仓储层的整体设计中,看接口如何划分、哪些方法带租户、哪些故意不带,以及这种设计如何影响上层服务。

5.9 仓储层:租户、方言与事务不变量在哪里编码

仓储层在 WeKnora 里不是"把 GORM 包一层"的薄壳。它承担了三类不能上移到服务层的职责:把租户条件写进 SQL、把方言差异消化掉、把单个聚合内部的事务不变量固定下来。同时它也刻意放弃了一些职责:不做权限判断、不读上下文里的租户、不跨聚合开事务、不发事件。理解这种"做什么"与"不做什么"的分界,才能判断一个改动应该落在哪一层。

5.9.1 两套同名接口:一个给 HTTP,一个给数据

internal/types/interfaces/ 同时定义服务接口与仓储接口,方法名经常重复。以知识为例:

go 复制代码
// KnowledgeService
GetKnowledgeByID(ctx context.Context, id string) (*types.Knowledge, error)

// KnowledgeRepository
GetKnowledgeByID(ctx context.Context, tenantID uint64, id string) (*types.Knowledge, error)

同名不同签名:服务接口面向 handler ,租户来自请求上下文,错误映射成 HTTP 状态码;仓储接口面向数据,租户是显式参数,不知道请求、中间件与调用方。

服务实现的转换很直接:

go 复制代码
func (s *knowledgeService) GetKnowledgeByID(ctx context.Context, id string) (*types.Knowledge, error) {
    tenantID := ctx.Value(types.TenantIDContextKey).(uint64)
    knowledge, err := s.repo.GetKnowledgeByID(ctx, tenantID, id)
    ...
}

这里用的是非断言检查的类型断言 (internal/application/service/knowledge.go:600):上下文没有租户就 panic。全仓这种写法 37 处,带 ok 检查的 122 处(不含测试)。前者依赖"handler 前一定有认证中间件",后者显式处理 tenantless;两种并存,所以"空上下文 panic"的位置常在服务层第一行,而非真正缺租户的入口。

分层让仓储可脱离 HTTP 测试(传任意 tenantID 即可构造跨租户场景),代价是每个方法重复传租户、签名冗长,新增方法容易漏参数。

5.9.2 331 个显式租户参数说明了设计取向

仓储接口中 tenantID uint64 出现 331 次(如 internal/types/interfaces/audit_log.go:32),这是明确的架构选择:隔离条件必须是签名的一部分,不能是隐式全局状态。

三个好处:可审计 ------搜索 tenantID uint64 列出所有带租户约束的方法,搜索不带该参数的方法即得需人工确认的"跨租户入口";可组合 ------后台任务、系统管理员、共享访问可传不同租户,不需切换上下文或设"特权标记";可测试------单测直接构造两个租户的数据,不依赖中间件。

代价:服务层每次调用都要先取租户,取法不统一(断言、ok 检查、MustTenantIDFromContext 三种并存);方法一多,命名与参数顺序漂移(租户有时第二位、有时最后);新增方法若无模板,容易写出不带租户的版本。项目用命名约定缓解第三点:不带租户的方法名通常含 Only、ByIDs、All、System,并在注释说明用途------不是编译期保证,但让 code review 有抓手。

5.9.3 Only 后缀:为权限解析开的一扇门

最典型的例子是 GetKnowledgeByIDOnly(internal/application/repository/knowledge.go:80):

go 复制代码
// GetKnowledgeByIDOnly returns knowledge by ID without tenant filter (for permission resolution).
func (r *knowledgeRepository) GetKnowledgeByIDOnly(ctx context.Context, id string) (*types.Knowledge, error) {
    var knowledge types.Knowledge
    if err := r.db.WithContext(ctx).Where("id = ?", id).First(&knowledge).Error; ...
}

为什么需要这扇门?因为"判断某个用户能否访问某个资源"时,系统必须先按 ID 找到资源,再判断它属于哪个租户、是否被共享、调用者在目标租户里是什么角色。如果第一步就带调用者的租户条件,跨租户共享的资源会直接"查不到",权限判断无从谈起。于是流程变成:

  1. 用 Only 方法按 ID 取出资源(不做租户过滤);
  2. 用资源的 tenant_id 与调用者的租户、组织关系做授权判断;
  3. 授权通过后,再用带租户条件的方法取详情,或直接把第 1 步的结果返回。

这扇门的风险是显而易见的:任何调用方都可以用它读取任意租户的行。项目通过三种方式限制:

  • 方法名与注释都标注"for permission resolution";
  • 调用点集中在少数 handler/service 的授权路径;
  • 返回的对象通常只取少数字段(例如 GetOwningKBCreatorID 只返回 creator ID,不返回整行)。

审计隔离时,这类方法应单独列一份清单,逐个确认调用方在取到数据后确实做了授权判断,而不是直接序列化返回。

5.9.4 不带租户的"普通"方法更危险

比 Only 更隐蔽的是那些名字看起来正常、但没有租户条件的方法。知识库仓储就是例子:

go 复制代码
// GetKnowledgeBaseByID gets a knowledge base by id
// (no tenant scope; caller must enforce isolation where needed)
func (r *knowledgeBaseRepository) GetKnowledgeBaseByID(ctx context.Context, id string) (*types.KnowledgeBase, error) {
    ...
    r.db.WithContext(ctx).Where("id = ?", id).First(&kb)
}

同一个文件里还有 GetKnowledgeBaseByIDAndTenant(internal/application/repository/knowledgebase.go:43),以及 GetKnowledgeBaseByIDs(internal/application/repository/knowledgebase.go:55,按 ID 列表批量取,不带租户)。这些方法服务于不同场景:

  • GetKnowledgeBaseByID:权限解析、跨租户引用、内部任务;
  • GetKnowledgeBaseByIDAndTenant:面向用户的常规读取;
  • GetKnowledgeBaseByIDs:批量补全展示信息,调用方已在前面完成过滤。

问题在于,三者的命名差异只有一个后缀,代码补全时很容易选错。而且选错不会报错,只会悄悄放宽范围。项目没有在类型层面区分"已授权"与"未授权"的句柄,因此正确性依赖开发者对命名约定的熟悉程度。

一个实用的审计方法是:对每个不带租户的仓储方法,追踪它的所有调用点,检查调用链上是否存在以下任一保证:

  1. 调用前已经用带租户的方法确认过资源归属;
  2. 调用方本身就是系统级任务,且输出不直接返回给用户;
  3. 调用后立即做了租户/权限比较。

三者都没有的调用点,就是潜在的越权入口。

5.9.5 过滤、分页与"零值即不过滤"

列表类方法普遍接受一个过滤结构体,零值表示"该维度不过滤"。例如知识列表:

go 复制代码
ListPagedKnowledgeByKnowledgeBaseID(ctx context.Context,
    tenantID uint64, kbID string, page *types.Pagination, filter types.KnowledgeListFilter, ...)

Pagination 只有 Page 与 PageSize(上限 1000,internal/types/search.go:320),并通过 GetPage()/GetPageSize()(internal/types/search.go:332)提供默认值(1 与 20)。这些默认值在 HTTP 层由 binding 标签校验,在仓储层则由 getter 兜底。两层都做,是因为仓储也可能被内部任务直接调用,不能假设入参已经过 HTTP 校验。

过滤结构体的零值语义要求调用方"只填想过滤的字段"。这与 GORM 的零值跳过是同一种思路,但实现方式不同:仓储把每个非零字段翻译成 SQL 条件,而不是把结构体直接丢给 Where。这样做的好处是条件可读、可测试;坏处是新增过滤维度时要同时改结构体、翻译逻辑和索引。

分页还有一个隐含约定:排序必须稳定 。如果只按 created_at 排序,而多条记录时间相同,翻页时可能出现重复或遗漏。项目在消息列表里用 (created_at, id) 复合游标解决这个问题;知识列表则多用 created_at DESC 加主键兜底。判断一个分页接口是否可靠,应先看它的排序键是否唯一。

5.9.6 批量装载替代关联查询

项目很少用 GORM 的 Preload 做深层关联。全仓只有 17 处 Preload,集中在共享 Agent 等少数需要返回嵌套对象的场景。大多数"列表 + 关联信息"采用批量装载:

  • 先查出主对象列表;
  • 收集所有关联 ID;
  • 用一次 IN 查询取回关联数据;
  • 在内存里拼装。

例如消息列表先查 messages,再用 attachArtifacts 一次性取回这批消息的 message_artifacts;知识列表先查 knowledges,再用 GetKnowledgeTags 批量取标签。这种模式避免了 N+1,也避免了 Preload 生成的复杂 JOIN 与软删除条件遗漏。

代价是仓储方法变多:每个关联都需要一个批量查询方法。好处是每个查询都能独立加租户条件、独立加索引、独立测试。对一个需要支持两种数据库的系统来说,这种"显式多次查询"比"让 ORM 生成一条大 SQL"更容易控制行为。

5.9.7 49 个构造函数与依赖装配

仓储实现通过 49 个 NewXxxRepository 构造函数创建(例如 internal/application/repository/knowledgebase.go:21),在容器初始化时注入到服务层。仓储之间一般不互相依赖;需要跨表操作时,要么在同一个仓储内用事务完成,要么由服务层组合两个仓储。

这种扁平结构让依赖图清晰,但也意味着"跨聚合事务"无处安放。前面已经说过,服务层拿不到 *gorm.DB,无法把两个仓储的写入包进一个事务。于是跨聚合的一致性只能靠:

  • 顺序设计:先写权威数据,再写派生数据;失败时重试派生部分;
  • 状态机 :用 parse_status、run_state 等字段记录进度,异步任务可以从中断处继续;
  • 补偿:失败时删除已写入的部分,或标记为待清理;
  • 幂等 :重复执行不产生额外副作用,例如按 (source_id, source_type) upsert。

这套组合不如数据库事务强,但它能跨进程、跨存储(对象存储、向量库)工作,而事务不能。项目的很多"最终一致"设计,根源就在这里。

5.9.8 权限缓存放在 access 包,而不是仓储

共享知识库的权限判断需要多次查询:资源属于哪个租户、该租户是否在组织内、调用者在组织里是什么角色、调用者在自己的租户里又是什么角色。一次请求可能涉及几十个分块,如果每个分块都查一遍,开销不可接受。

项目用 access.KBSharePermissions(internal/application/access/kb_shares.go:14)做请求内缓存:

go 复制代码
func (p *KBSharePermissions) Permission(kbID string) (types.OrgMemberRole, bool, error) {
    result, ok := p.results[kbID]
    if !ok {
        result.role, result.shared, result.err = p.lookup.CheckTenantKBPermission(...)
        p.results[kbID] = result
    }
    return result.role, result.shared, result.err
}

几个设计点值得注意:

  • 缓存键是知识库 ID,不是分块 ID 。同一知识库下的所有分块共享一次判断(internal/application/access/kb_shares.go:46),这正是批量场景需要的粒度。
  • 失败也被缓存 。查询出错时记录 err,后续调用直接返回同一个错误,避免对故障中的依赖反复打请求。
  • 实例是请求级的。注释明确说"不要跨请求共享,不要跨 goroutine 使用",因为它内部是普通 map,没有锁。
  • 它不授予租户所有权。注释强调"deliberately does not grant tenant ownership or shared-agent access",即共享权限与租户内权限是两条独立的判断链,不能互相替代。

把缓存放在 access 包而不是仓储,是因为它属于"授权决策",不属于"数据访问"。仓储只回答"这行数据是什么",access 回答"这个调用者能不能用它"。两者混在一起,会导致仓储接口膨胀、缓存生命周期失控。

5.9.9 仓储刻意不做的四件事

总结起来,仓储层不做以下四件事:

  1. 不读上下文里的租户 。全仓仓储实现中对 TenantIDFromContext 的引用为零。租户必须由调用方显式传入,避免"上下文缺租户时静默查全表"。
  2. 不做权限判断。仓储不知道角色、不知道共享、不知道组织。它只执行带条件的查询。
  3. 不跨聚合开事务。事务边界固定在单个仓储方法内部,跨聚合一致性交给状态机与补偿。
  4. 不发领域事件。没有 hook 去发消息、写审计、触发索引。这些由服务层在写入成功后显式调用。

这四条边界让仓储可预测:同样的入参,同样的 SQL,同样的结果。排查数据问题时,可以把仓储当成一个纯函数来看;排查权限问题时,则应该离开仓储,去看 access 与服务层的判断链。

下一节把前面散落的隔离细节收拢成一份审计方法:从请求入口到 SQL,租户在哪一层可能丢失,如何系统地找出缺口。

5.10 租户隔离审计:从请求到 SQL 的六个检查点

前面各节多次提到"隔离靠应用层谓词"。这容易被误解为"只要 SQL 带 tenant_id 就安全";一次跨租户越权可能发生在六个位置,SQL 只是最后一环。这一节给出一条可执行的审计路径:从请求进入,到结果返回,每一层分别该看什么。

检查点一:身份与租户是否成对写入

认证中间件 applyAuthSession(internal/middleware/auth_context.go:53)把身份写入两个表面:gin.Context 与 request.Context。任何一层的读取方式失效,都会表现为"某些 handler 有租户、另一些没有"。审计时应确认:

  • 目标 handler 读的是哪一个表面;
  • 该表面是否在认证中间件里被写入;
  • tenantless 会话是否会走到这个 handler。

tenantless 的判断条件是 TenantID == 0。此时中间件不写 TenantIDContextKey,也不写 TenantInfoContextKey。于是后续任何使用 ctx.Value(...).(uint64) 的代码都会 panic,而使用 TenantIDFromContext 的代码会得到 (0, false)。两种失败模式都不安全,只是表现不同:panic 至少会暴露,静默的零值则可能被当成合法租户继续查询。

角色也有类似的兜底:TenantRoleFromContext 在缺失时返回 Viewer。这是 fail-closed 的设计,但它只保证"不会因为缺角色而获得高权限",并不保证"后续逻辑会把 Viewer 当作已认证"。如果某个接口只检查"角色 >= Viewer",tenantless 用户就会被当作只读成员放行。因此需要租户的接口必须在入口显式拒绝 TenantID == 0,而不能只依赖角色兜底。

检查点二:目标租户是否经过成员关系验证

多租户用户可以通过 X-Tenant-ID 切换目标租户。resolveTargetTenant(internal/middleware/auth.go:324)会综合 JWT 声明、请求头、主租户与成员关系来决定本次请求的租户。关键问题是:切换目标租户时,是否验证了调用者在该租户里有 active 成员关系?

设计上的答案是:CanAccessAllTenants 只是"允许尝试切换",不是"无条件通行";真正的准入仍要求 active 成员关系,或在特定配置下允许跨租户访问。审计时应检查:

  • 目标租户是否来自可信来源(JWT 声明或经校验的请求头),而不是请求体;
  • 成员关系查询是否过滤了 status = 'active' 与 deleted_at IS NULL;
  • 系统管理员旁路是否有独立开关,是否被记录到审计日志。

一个常见的误判是把 users.tenant_id 当作权限来源。它只是"主租户",用户可能已经切换过空间;权限的真实来源是 tenant_members 的 active 行。任何以主租户做授权判断的代码,在用户切换空间后都会给出错误结论。

检查点三:路由准入是否覆盖了所有子资源

资源级中间件(如 kb_access)在进入 handler 前校验归属与角色。它解决的是"这个用户能不能操作这个知识库"。但子资源路由------文档、分块、标签、FAQ、文件、消息附件------很容易漏挂中间件,或者只校验了父资源 ID 的存在性,没有校验父资源归属。

access 包的 README 把这类边界列成了一张表,其中几条值得特别注意:

  • 文档/分块详情 走 ResolveKB(internal/application/access/knowledgebase.go:95):先看是否本租户,再看组织共享,最后看只读共享 Agent;
  • FAQ/标签读取 走 resolveKBReadTenant:执行租户或组织共享;直接跨租户调用必须有用户身份,不能隐式回退到 Agent;
  • FAQ/标签写入 走 RequireKBWrite:要求精确的 Editor 授权,设置执行租户或传 KB ID 都不够;
  • 文件代理 走 ResolveKBFile:要求精确的 Viewer 授权、文件确实绑定到该 KB、存储路径属于该租户。

审计时应对照路由表逐条确认:每个带 :kb_id、:knowledge_id、:chunk_id 的路由,是否都有一个明确的解析函数,并且该函数同时检查了"资源存在""资源属于哪个租户""调用者对该租户/资源共享有什么权限"。

检查点四:服务层是否正确取得并传递租户

服务层从上下文取租户,再传给仓储。这里是前面提到的 37 处非检查断言与 122 处检查断言并存的地方。审计重点不是"用了哪种写法",而是:

  • 取到的租户是否与检查点二确定的目标租户一致;
  • 是否存在"上下文里是 A 租户,但业务对象属于 B 租户"却继续执行的路径;
  • 跨租户共享场景是否使用了执行租户(effective tenant)而不是调用者租户。

access 包对此有一套明确模型:

go 复制代码
type KBAccess struct {
    KnowledgeBase     *types.KnowledgeBase
    Caller            types.Caller
    EffectiveTenantID uint64
    Permission        types.OrgMemberRole
    operationPermission types.OrgMemberRole
}
  • Caller 是认证身份,永不改变;
  • EffectiveTenantID 是资源所属租户,用于后续查询与存储访问;
  • Permission 是解析出的资源权限;
  • operationPermission 把"这次操作需要的权限"钉死,防止一次读授权被复用成写授权。

Context()(internal/application/access/knowledgebase.go:41)只有在调用者未被替换时才切换执行租户:

go 复制代码
scoped := a.WithGrant(ctx)
if types.CallerFromContext(scoped) != a.Caller.Normalize() {
    return ctx
}
return types.WithExecutionTenant(scoped, a.EffectiveTenantID)

这段代码防的是"授权对象与上下文身份不一致"的替换攻击:如果上下文中已经有一个不同的调用者,授权上下文不会被套用。WithExecutionTenant 本身不授予任何权限,它只是改变后续查询的租户作用域;权限来自 WithGrant 写入的不可变快照。

检查点五:SQL 是否真的带上了租户条件

到了仓储层,隔离体现为三种形态:

  1. 显式 tenant_id = ?:大多数 CRUD 方法。
  2. 通过父资源间接约束 :例如按 knowledge_base_id 查分块,租户条件可能只在父资源校验时出现。
  3. 完全不带租户 :Only 方法、ByIDs 批量方法、系统级扫描。

第三种最需要警惕,但第一、二种也不是绝对安全。举例来说,如果方法签名是 GetChunksByKnowledgeID(ctx, kbID),而调用方传入的 kbID 来自请求体且未经验证,那么 SQL 里有没有 tenant_id 已经不重要了------攻击者可以直接指定别人的知识库 ID。隔离的前提是"资源 ID 已经过授权",而不是"SQL 里有租户列"。

检索路径更能说明这一点。向量检索与关键词检索的 SQL 里没有 tenant_id 条件,它们按 knowledge_base_id 过滤:

go 复制代码
// VectorRetrieve 的过滤条件是 knowledge_base_id IN (...)
// KeywordsRetrieve 同样只按 KB 与文档范围过滤

安全性完全依赖调用方传入的 KB ID 列表已经过授权:本租户的 KB、组织共享的 KB、共享 Agent 允许的 KB。SharedAgentKBScope 对此有明确规则(internal/types/shared_agent_access.go:6):all 表示该 Agent 所属租户的全部 KB,selected 表示显式非空 ID 集合,none、未知模式与空集合都不授权任何 KB;nil/空切片绝不隐式授予整个租户。审计检索越权时,应直接看 KB ID 列表是怎么构造的,而不是在检索 SQL 里找租户条件。

检查点六:返回结果是否泄漏了源租户信息

共享资源会让"调用者租户"与"资源租户"不一致。返回结果时要注意:

  • 是否返回了资源所属租户的内部 ID、成员列表、存储路径;
  • 是否把"共享可见"误当成"可管理";
  • 缓存是否跨请求复用。

KBSharePermissions 的注释明确说它是请求级缓存,不跨请求、不跨 goroutine。这样撤销共享后,下一个请求会重新解析并看到最新状态。如果把它提升为进程级缓存,撤销就会延迟生效,甚至永久不生效。类似的还有上下文中携带的授权快照:README 明确说"它们不会作为后续请求的持久授权",API Key 的作用域在消费授权时还要重新应用。

共享 Agent 的回退也有边界:ResolveKB 只在所需权限是 Viewer、且显式指定了 Agent 时,才检查该 Agent 是否包含此 KB;没有指定 Agent 时,才走"该租户能否通过某个共享 Agent 访问此 KB"的检查。显式指定的 Agent 永远不会回退到另一个 Agent。这个细节防的是"用一个无权访问的 Agent ID 触发宽泛回退"的绕过。

一份可执行的审计清单

把上面六点压缩成清单,可以直接用于 code review:

  • 该路由是否挂在认证中间件之后?tenantless 是否被拒绝?
  • 目标租户是否经过 active 成员关系校验?系统管理员旁路是否受控?
  • 父资源 ID 是否在进入业务逻辑前完成了归属校验?
  • 服务层传给仓储的租户,是调用者租户还是资源执行租户?是否与授权结果一致?
  • 仓储方法是否带租户条件?若不带,调用链上是否有等价保证?
  • 检索/批量接口的 ID 列表是否由授权后的查询构造?空列表是否被当作"全部"?
  • 返回结果是否包含源租户敏感字段?缓存生命周期是否限于单请求?
  • 授权失败是否统一映射为"不存在",避免泄漏资源存在性?

这张清单不能替代测试,但能快速定位设计缺口。真正的回归保障仍然是跨租户集成测试:用两个租户的数据,逐条验证列表、详情、搜索、下载、写操作在无共享、有共享、共享撤销三种状态下的行为。

下一节转向迁移体系。前面多次提到两套迁移历史、部分索引差异、CONCURRENTLY 限制,现在把它们放回完整的迁移生命周期中:谁在执行、失败会怎样、脏状态如何恢复、为什么有些迁移必须单语句。

5.11 迁移体系:两条历史、一种执行器、若干条硬约束

Schema 是系统的长期契约,迁移是把契约从一个版本带到下一个版本的全部操作。WeKnora 的迁移体系有几个不常见的特点:两套完全独立的历史、启动时失败不阻断、默认自动从脏状态恢复、部分迁移必须严格单语句。这些特点单独看都合理,组合起来却决定了升级时的真实风险。本节按"谁执行、失败怎样、如何写"的顺序展开。

5.11.1 两条互不相通的历史

迁移文件分放在两个目录:

  • migrations/versioned/:PostgreSQL,当前 138 个版本、276 个文件(每个版本一对 up/down);
  • migrations/sqlite/:SQLite,当前 54 个版本、108 个文件。

两条历史都从 000000_init 开始,但内容规模差异巨大:

  • PostgreSQL 的初始迁移只建 7 张表,其余表由后续 137 个版本逐步添加;
  • SQLite 的初始迁移一次性建 47 张表,后续版本只做增量修补。

PostgreSQL 版本承载完整演进史:每次加表、加列、加索引都留下一个版本,便于老库逐级升级。SQLite 主要服务 Lite 版,用户通常从较新版本开始,历史包袱小,于是把大量建表压缩进初始迁移以减少升级步数。

两条历史的版本号不对应。000045 在 PostgreSQL 是组织成员关系重构,在 SQLite 可能是完全不同的内容;同一个功能在两边可能落在不同版本号,甚至 SQLite 完全没有对应迁移(例如某些仅标准版使用的表)。因此:

  • 不能把一个目录的文件复制到另一个目录;
  • 不能假设"PostgreSQL 升到 137 等价于 SQLite 升到 137";
  • 排查某个字段的来源时,必须分别查两个目录。

也没有跨方言迁移工具。从 SQLite 迁到 PostgreSQL 需要导出数据、在目标库跑完整迁移、再按表导入,且要处理类型差异(自增、布尔、JSON、时间)与 ID 冲突。

5.11.2 执行器:golang-migrate 的两种接入方式

迁移由 golang-migrate 执行,入口是 RunMigrationsWithOptions(internal/database/migration.go:101)。它根据 DSN 前缀选择目录:

go 复制代码
migrationsPath := "file://migrations/versioned"
if strings.HasPrefix(dsn, "sqlite3://") {
    migrationsPath = "file://migrations/sqlite"
}

PostgreSQL 走标准的 migrate.New(path, dsn);SQLite 因为驱动注册方式不同,使用已经打开的 sql.DB 构造 WithInstance,再 NewWithDatabaseInstance。两种方式的共同点是:迁移状态记录在数据库内的版本表里,而不是文件或环境变量里。

PostgreSQL 的 DSN 里还塞了一个自定义参数(internal/container/container.go:1049):

go 复制代码
migrateDSN = fmt.Sprintf(
    "postgres://...?sslmode=disable&options=-c%%20app.skip_embedding=%s",
    skipEmbedding,
)

app.skip_embedding 由 RETRIEVE_DRIVER 是否包含 postgres 决定,迁移文件据此用 current_setting('app.skip_embedding', true) 判断是否建向量表。开关放进连接参数而非环境变量,是因为迁移执行器只拿到 DSN、不读应用配置,连接参数是唯一能同时传给迁移 SQL 与会话的通道。

5.11.3 启动策略:迁移失败只告警

这是最需要记住的一条。容器初始化时:

go 复制代码
if err := database.RunMigrationsWithOptions(migrateDSN, migrationOpts); err != nil {
    // Log warning but don't fail startup - migrations might be handled externally
    logger.Warnf(context.Background(), "Database migration failed: %v", err)
    logger.Warnf(context.Background(),
        "Continuing with application startup. Please run migrations manually if needed.")
}

迁移失败不会阻止应用启动(internal/container/container.go:1131)。设计意图是支持"迁移由外部 Job 执行、应用只负责服务"的部署方式。但它带来一个严重的运行态风险:应用可能带着旧 Schema 启动并对外服务 。此时健康检查仍然返回(internal/router/router.go:150):

go 复制代码
r.GET("/health", func(c *gin.Context) {
    c.JSON(200, gin.H{"status": "ok"})
})

它不检查数据库连通性,也不检查迁移版本。编排系统看到 200 就把流量导入实例,用户随后遇到"列不存在""表不存在"这类运行时错误,而不是启动失败。排查此类故障,第一步应查启动日志里的 Database migration failed,而不是查业务代码。

更稳妥的部署方式是把迁移拆成独立步骤:升级前先跑 migrate up,确认版本与 dirty 状态,再滚动更新应用;或给健康检查增加迁移版本校验。项目提供了 GetMigrationVersion(internal/database/migration.go:302)与内部状态记录,但默认健康检查没有使用。

5.11.4 脏状态与"自动恢复"的真实含义

golang-migrate 在每个版本执行前把版本表标记为 dirty,成功后清除。如果迁移中途失败,版本会停在失败的那个版本且 dirty=true。下次启动时,RunMigrationsWithOptions 会检测到脏状态:

  • 若 AutoRecoverDirty 开启(默认开启,除非显式设为 false),调用 recoverFromDirtyState(internal/database/migration.go:262);
  • 若关闭,直接返回错误,并打印手动修复步骤(migrate force <version>)。

recoverFromDirtyState 的做法很简单:把版本强制回退到前一个版本,清除 dirty,然后重试 m.Up()。版本 0 是特例(internal/database/migration.go:265),无法再回退,于是 Force(-1),让迁移从头再跑一遍:

go 复制代码
if dirtyVersion == 0 {
    // ... requires the init migration to be idempotent
    if err := m.Force(-1); err != nil { ... }
    return nil
}
forceVersion := int(dirtyVersion) - 1
if err := m.Force(forceVersion); err != nil { ... }

这里有两个必须理解的前提:

  1. 强制回退只改版本号,不回滚已执行的 DDL。 如果失败迁移已经建了表、加了列,这些对象仍然存在。重试时,迁移必须能容忍"对象已存在",否则会再次失败。
  2. 版本 0 的恢复依赖初始迁移全部使用 IF NOT EXISTS。 PostgreSQL 与 SQLite 的初始迁移确实大量使用该子句,但并非每一个语句都能幂等(例如 ALTER SEQUENCE ... RESTART、数据回填、约束添加)。因此"自动恢复"不是万能修复,只是把手工 force 自动化了一步。

这也解释了为什么迁移作者要在文件里写大量存在性检查:CREATE TABLE IF NOT EXISTS、CREATE INDEX IF NOT EXISTS、DO $$ BEGIN IF NOT EXISTS (...) THEN ... END IF; END $$;、以及"先查 information_schema 再决定是否 ALTER"。这些不是风格偏好,而是脏恢复机制能工作的必要条件。

5.11.5 单语句约束:CONCURRENTLY 与隐式事务

在线建索引必须用 CREATE INDEX CONCURRENTLY,否则会长时间锁表。但它不能运行在事务块里。项目在 000106 的注释里写清了约束:

sql 复制代码
-- CONCURRENTLY keeps writes to messages flowing while the index builds. It
-- cannot run inside a transaction block, so this file must hold exactly this
-- one statement: golang-migrate sends a file as one query, and a query with
-- several statements runs as an implicit transaction. If the build is
-- interrupted it leaves an INVALID index behind; drop it and rerun.
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_messages_session_created_id
    ON messages (session_id, created_at DESC, id DESC);

三个要点:

  • 一个文件只能有一条语句 。多条语句会被当作一个隐式事务,CONCURRENTLY 直接报错。
  • 失败会留下 INVALID 索引 。它不会被查询使用,但会占空间、拖慢写入。恢复方式是先 DROP INDEX 再重跑,而不是简单重试。
  • IF NOT EXISTS 不能修复 INVALID 索引 。同名索引存在时它会跳过,即使那个索引是无效的。因此运维要知道"检查 pg_index.indisvalid"这一步。

000059 展示了另一种折中:它用 DO 块包裹条件判断,而 DO 块本身开启隐式事务,所以不能用 CONCURRENTLY(migrations/versioned/000059_embeddings_hnsw_1024.up.sql:16);注释明确建议生产环境先手工 CREATE INDEX CONCURRENTLY,再应用迁移,此时迁移里的 IF NOT EXISTS 变成幂等空操作。这是"迁移负责收敛状态、运维负责在线构建"的分工。

5.11.6 条件迁移:同一个版本在不同部署下做不同的事

000002_embeddings 是否建向量表,取决于部署是否使用 PostgreSQL 检索:

sql 复制代码
IF current_setting('app.skip_embedding', true) = 'true' THEN
    RAISE NOTICE 'Skipping migration embeddings (app.skip_embedding=true)';
    ...

同一个迁移版本在"用 pgvector"和"用外部向量库"两种部署下都能通过,且不留无用表;代价是执行结果依赖连接参数,回放历史时必须知道当时的 RETRIEVE_DRIVER。后来改了检索驱动,向量表也不会自动补建,需手工处理或新增迁移。

000059 还加了表存在性守卫(migrations/versioned/000059_embeddings_hnsw_1024.up.sql:32):跳过 000002 的部署没有 embeddings 表,直接 CREATE INDEX 会失败并把库置为 dirty;守卫让"没有表"成为合法的跳过条件。

5.11.7 数据回填:先回填、再收紧

结构变更容易写,数据变更才考验迁移设计。000045(组织成员关系从"按用户"改为"按租户")是一个完整例子:

  1. 新建按租户的成员表;
  2. 从旧表聚合成员,同一租户多条记录取最高角色(max-role-wins);
  3. 冲突时用 RAISE NOTICE 记录,而不是静默丢弃;
  4. 为每个租户选一个确定性的代表用户;
  5. 重命名旧表为 organization_members_pre_plan3,保留回溯能力;
  6. 去重待处理的加入申请,并添加"每租户仅一条 pending"的唯一约束。

000046 紧接着给 organizations 加 owner_tenant_id:先从 owner 用户回填,再从组织成员表里找最早加入的管理员租户,两者都没有则 RAISE EXCEPTION,最后设为 NOT NULL。这是标准的"加可空列 → 回填 → 加约束"三段式,安全性建立在两者于同一迁移里顺序执行;若拆成两个版本,中间窗口可能写入空值。

这类迁移失败代价很高:RAISE EXCEPTION 会让整个迁移失败并置 dirty;自动恢复会强制回退版本号后重试,但已写入的数据不会撤销。因此回填 SQL 必须可重复执行(幂等),或能在失败后被人工清理。

5.11.8 SQLite 迁移的特殊约束

SQLite 的迁移写法受引擎能力限制,常见差异包括:

  • 不能给非主键列加 AUTOINCREMENT 。seq_id 只能由应用层 MAX+1 分配,这也是分块写入要在事务内先读后写的原因。
  • 不支持部分唯一索引 。PostgreSQL 用 WHERE deleted_at IS NULL 实现"软删除后可重新添加",SQLite 只能建全量唯一索引,导致软删除后重新添加会冲突。
  • 改列通常要重建表 。SQLite 的 ALTER TABLE 能力有限,复杂变更需要"建新表 → 拷数据 → 删旧表 → 重命名",期间要处理外键与索引。
  • 外键需要显式开启 。连接串里带 _foreign_keys=on,否则外键约束不生效。
  • 单写者 。连接池被限制为 SetMaxOpenConns(1)(internal/container/container.go:1168),注释说明这是为了避免 WAL 模式下的 database is locked。迁移与业务写入因此天然串行。

这些限制是选型带来的边界,而非"Lite 版的缺陷"。写跨方言迁移不能直接翻译 PostgreSQL 写法,必须确认 SQLite 有无等价能力,没有就改业务语义或加应用层补偿。

5.11.9 迁移之后:应用侧的数据修正

有些"迁移"不适合放在 SQL 里,因为需要读取应用配置或调用 Go 代码。项目在迁移之后执行两步修正:

  • resolveStorageProviderPending:把历史知识库里 storage_provider_config 的 __pending_env__ 标记替换为当前 STORAGE_TYPE;
  • migrateLegacyStorageBackends:把旧版存储配置迁移到新的后端表;
  • LoadBuiltinModelsConfig:从配置文件加载内置模型定义。

这些步骤不在版本表里,没有 dirty 标记,失败通常只记录日志,适合"尽力而为"的修正。判断变更该放 SQL 迁移还是应用钩子,标准是是否需要外部配置或 Go 逻辑:需要就放钩子并接受其不被事务保护,不需要就放迁移并获得版本管理。

5.11.10 down 迁移存在,但生产很少用

每个版本都有 .down.sql,但生产回滚很少依赖它。原因有三:

  • 删表、删列的 down 会丢数据,执行前必须确认没有写入;
  • 某些变更不可逆,例如把 JSON 拆成列后,down 无法还原原始结构;
  • 多实例部署时,回滚应用版本与回滚 Schema 的时序很难协调。

项目更现实的做法是"前向修复":迁移有问题就新增版本修正,而不是回滚;down 文件更多用于本地开发与测试清理。审计迁移风险时,不应把"有 down 文件"当成"可安全回滚"。

5.11.11 发布顺序:代码与 Schema 的兼容窗口

即使迁移本身正确,发布顺序也会决定可用性。安全的顺序通常是:

  1. 加列/加表(向后兼容),应用旧版本不受影响;
  2. 部署新代码,开始双写或读取新结构;
  3. 回填历史数据;
  4. 加约束/删旧列,确认没有旧版本实例仍在运行。

WeKnora 的部分迁移遵循这个模式(加可空列、回填、再加 NOT NULL),但并非全部。应用启动时自动执行迁移,如果新版本删了旧列,而滚动更新期间还有旧实例在跑,旧实例查询会立即失败。生产升级应避免"应用与破坏性迁移同时滚动",或把迁移拆成独立前置步骤并确认所有实例已升级。

下一节离开 Schema 演进,转向运行期的一致性:当一个操作要同时改关系库、对象存储、向量索引和任务队列时,系统如何保证"最终看起来是对的",以及失败时留下的中间状态如何被清理。

5.12 运行期一致性:一个操作,四个存储

数据模型回答"数据长什么样",一致性回答"当一次操作同时涉及多个存储时,失败会留下什么"。WeKnora 的一次文档删除会同时触碰关系库、对象存储、向量索引、图索引与任务队列;一次上传会触碰对象存储、关系库与队列。这些存储没有共同事务,系统只能靠顺序、状态机、幂等与补偿来逼近一致。本节把这条链拆开,指出每一步失败的真实后果。

5.12.1 四个存储,一个权威

先明确各自的角色:

存储 内容 是否权威 失败后的恢复方式
关系库 知识库、文档、分块、状态、配置 是 备份恢复;从备份点重放
对象存储 原始文件、提取的图片、导出物 部分(原文是权威) 从关系库记录重建索引;原文丢失则不可恢复
向量/图索引 embedding、知识图谱 否 从分块文本重建
任务队列 待处理任务、重试、死信 否 由状态字段与扫描任务重建

"是否权威"决定了故障时的方向:派生数据坏了就重建,权威数据坏了才恢复。 判断一个清理脚本是否安全,先问它删的是权威还是派生。删除向量索引永远不会造成不可逆损失;删除原始文件则可能永久丢失内容,即使数据库行还在。

5.12.2 上传:文件先落盘,行后写,失败删文件

文件型知识的创建顺序在 knowledge_create.go 里很明确:

  1. 计算哈希、构造 Knowledge 结构体(ParseStatus: "pending",尚未入库);
  2. 调用 fileSvc.SaveFile(internal/application/service/knowledge_create.go:209)把文件写入对象存储,得到 filePath;
  3. 调用 persistKnowledgeForCreation(internal/application/service/knowledge_create.go:218)写数据库行;
  4. 若第 3 步失败,调用 DeleteFile(context.WithoutCancel(ctx), filePath)(internal/application/service/knowledge_create.go:221)删除刚写的文件;
  5. 写标签关系;
  6. 投递解析任务到 Asynq。

文件先于行,因为反过来会产生"行存在但文件不存在":用户看到"一直处理中/解析失败",重试无法解析,删除报 not found;而"文件存在但行不存在"只是孤儿文件,可被扫描任务清理。两害相权取其轻。

第 4 步用 context.WithoutCancel(ctx):失败时请求上下文往往已取消,直接删除会立即返回取消错误,留下孤儿文件;WithoutCancel 保留值、去掉取消信号,让清理动作尽力完成。

第 5 步写标签失败时直接返回错误,不回滚已写入的行与文件,留下"文档存在、标签缺失"的不一致窗口:不破坏数据,重新打标签即可。项目只对"行与文件"做补偿,其余接受最终一致,以免每步都做补偿带来的复杂度。

5.12.3 解析:状态机 + 幂等重试

解析任务由 Asynq 执行,失败会自动重试。要让重试安全,解析必须幂等。项目通过三件事保证:

  • 状态字段 :pending → processing → finalizing → completed,失败为 failed,删除为 deleting,取消为 cancelled。重试前会检查当前状态,已完成的不会重复处理。
  • 分块写入的幂等:写入前清理该文档的旧分块,或按内容哈希去重;重复执行不会产生两份分块。
  • 子任务计数 :finalizing 状态配合 pending_subtasks_count,只有当所有子任务(图片描述、问题生成、表格摘要等)都完成后才进入 completed。重试某个子任务不会让主状态提前完成。

注释多次出现"idempotent parse runs again":失败时错误返回队列重试,重跑同一套幂等解析而不是从半成品继续。这比"断点续传"简单,代价是重复计算,对可重复的 CPU/IO 密集解析可以接受。

重试耗尽后任务进入死信表 task_dead_letters,含义是"停止自动重试并保留证据",不是删除。运维能看到失败原因、重试次数与原始 payload,再决定手工重放或放弃;没有死信,失败任务会静默消失,用户只看到"一直处理中"。

5.12.4 删除:一条有明确顺序的链

删除比创建复杂,因为它要清理四个存储。executeKnowledgeDelete(internal/application/service/knowledge_delete.go:475)的顺序是:

  1. 标记 deleting (internal/application/service/knowledge_delete.go:490):逐条把 parse_status 设为 deleting,防止并发的解析任务继续写入;
  2. 取消下游任务 :对处于 pending/processing 的文档,按 ID 逐个清理队列中的任务;
  3. 并行清理派生数据:向量索引、知识图谱、分块三路并发;
  4. 清理 Wiki 引用:必须在删分块之前做,因为需要根据分块引用判断哪些 Wiki 页面失去来源;
  5. 删除标签关系;
  6. 删除知识行;
  7. 删除物理文件;
  8. 扣减存储配额,并清理提取的图片。

第 6 步与第 7 步的顺序在注释里写得很清楚:

go 复制代码
// 6. Delete the knowledge rows FIRST, then drop their physical files. See
// Deferring file removal until the rows are gone avoids "file missing but row
// present" zombies that break reparse / re-delete when an earlier cleanup step
// failed (issue #2192). A failure below only orphans storage.

这是"选择留下哪种垃圾"的决策:

  • 先删文件、后删行:删行失败会留下"行在、文件没了"的僵尸,重试解析读不到文件,再次删除报 not found。
  • 先行、后删文件:删文件失败只留下孤儿文件,数据库状态干净,孤儿由后台清理。

顺序按"哪种残留更容易自动修复"排列。凡是"先删外部资源、后删数据库行"的实现,都值得怀疑。

第 3 步的并行也有边界:三路清理只要有一路失败,wg.Wait() 就返回错误,后续删行、删文件都不执行。此时文档已标记 deleting 但行还在,用户看到"删除失败/卡在删除中";再次删除会重走流程,派生数据清理幂等,因此可重试。这是"快速失败 + 可重试"而非"尽力而为"。

5.12.5 软删除让"删除"分成两个阶段

DeleteKnowledgeList 在仓储层是软删除(置 deleted_at),文件在服务层真删,于是"删除"分成:

  • 可见性删除:行被软删除,查询默认看不到;
  • 资源释放:文件、向量、图、分块(分块也是软删除)被清理;
  • 物理清理:被软删除的行何时真正从表中消失,由独立任务决定。

这三个阶段不是原子的。可能出现"行已软删除,但向量还在"------如果第 3 步失败且没有重试;"文件已删,行还在"------如果第 7 步成功但事务外没有后续;"分块软删除,但 superseded 分块仍占空间"------需要 PurgeSupersededChunksByKnowledgeID 这类物理清理。

软删除的价值是给误删留了恢复窗口,代价是每个"删除"都要额外定义"什么时候真正释放"。判断一个删除实现是否完整,应分别问:可见性何时消失、派生索引何时清理、物理资源何时释放、配额何时扣减。四者缺一,就会在某处留下长期占用。

5.12.6 任务队列:从 Redis List 到持久表

早期实现用 Redis List 做待处理队列,问题是 TTL 驱逐:队列里的任务可能在执行前消失,且没有任何记录。000041 迁移引入了 task_pending_ops 表:

sql 复制代码
CREATE TABLE IF NOT EXISTS task_pending_ops (...)
COMMENT ON TABLE task_pending_ops IS 'Generic durable pending-op queue keyed by
(task_type, scope, scope_id). Replaces ad-hoc Redis-list queues that were
vulnerable to TTL eviction.';

这张表的关键设计是 (task_type, scope, scope_id) 与 dedup_key:

  • 同一个文档的同类操作可以按 dedup_key 去重,避免重复入队;
  • ClaimBatch 用 SELECT ... FOR UPDATE SKIP LOCKED 让多个 worker 领取互不相交的批次;
  • claimed_at 记录领取时间,超过阈值的领取视为 worker 崩溃,可被下一个 worker 接管;
  • Lite 模式没有 Redis,按 KB 在进程内串行,claimed_at 留空。

这套设计解决的是"至少一次投递 + 重复消费"的经典问题:队列保证任务不丢,消费方必须幂等。dedup_key 只能减少重复,不能消除重复;真正防止重复副作用的是业务层的状态检查与幂等写入。

死信表 task_dead_letters 由两类写入者填充:Asynq 中间件在重试耗尽时写入,Wiki ingest 服务在单文档操作超过批内重试配额时写入。它让"失败"成为可查询的数据,而不是日志里的一行。

5.12.7 配额:一个必然会漂移的计数器

tenants.storage_used 在删除时扣减 knowledge.StorageSize,在上传时增加。它是一个应用层维护的聚合值,不是数据库触发器,也不是实时 SUM。因此它一定会漂移:

  • 删除文件失败但配额已扣:计数偏低;
  • 重复上传同一文件(内容去重前)再删除:计数来回波动;
  • 外部直接写入对象存储:完全不计;
  • 软删除后恢复:计数不会自动回补。

项目把它当作软配额:用于拦截明显超限的上传,而不是财务级计费。审计时应把 storage_used 与对象存储的实际占用做周期性对账,而不是假设它精确。对账任务应能重算、覆盖,而不是增量修正,否则误差会累积。

5.12.8 失败模式表

把上面的分析压缩成一张表,便于排障时对照:

失败点 留下的状态 用户可见表现 恢复方式
文件写入失败 无 上传报错 重试
行写入失败 孤儿文件 无 清理任务删除孤儿
标签写入失败 行在、无标签 文档无标签 重新编辑
解析任务丢失 pending 长期不变 一直处理中 扫描 pending 超时重投
解析失败重试耗尽 failed + 死信 解析失败 查看死信、手工重放
向量清理失败 行 deleting、向量残留 删除失败/卡住 重试删除;残留向量按 KB 重建清理
删行后删文件失败 孤儿文件 无 清理任务
配额扣减失败 计数偏高 可用空间偏小 对账重算

这张表说明一个总体判断:系统的大多数不一致是"多占了资源",而不是"丢了数据"。 这是刻意设计的偏向------宁可留下可清理的垃圾,也不要留下无法恢复的缺失。

5.12.9 判断一致性的三个问题

面对任何跨存储操作,可以用三个问题快速判断其可靠性:

  1. 权威是谁? 失败时以哪个存储为准?如果两个都被当成权威,迟早会冲突。
  2. 操作幂等吗? 重试会不会产生重复行、重复向量、重复扣减?队列是至少一次投递,幂等不是可选项。
  3. 残留能被自动发现吗? 孤儿文件、孤儿向量、卡在中间态的行,是否有扫描任务能识别并清理?如果没有,残留就是永久债务。

WeKnora 的答案分别是:关系库权威、解析与清理尽量幂等、孤儿通过状态字段与定期扫描发现。这套答案不完美,但边界清晰,排障时有据可依。

下一节把视角拉到运维层面:备份该备什么、恢复的顺序是什么、哪些表可以重建、哪些指标能提前暴露问题。

5.13 运维视角:备份、恢复、连接与索引健康

数据层设计最终要在运维动作里兑现:备份什么、恢复按什么顺序、连接池怎么设、索引坏了怎么发现。很多"数据库问题"其实是运维动作与模型不匹配:只备 PostgreSQL 忘了对象存储,恢复后文档"存在但打不开";只重建表忘了向量索引,检索退化成全表扫描。本节按运维动作把模型知识落到步骤上。

5.13.1 备份:数据库只是三分之一

一次完整备份需要三个部分:

  1. 关系库 :PostgreSQL 用 pg_dump/物理备份,SQLite 用文件拷贝或 VACUUM INTO;
  2. 对象存储:本地目录、MinIO bucket、COS 桶里的原始文件与提取图片;
  3. 配置与密钥:环境变量、模型凭据、存储凭据、加密密钥。

三者缺一不可:只备份数据库,恢复后 knowledges.file_path 指向的文件不存在,文档列表正常但点开 404/解析失败;只备份文件,则没有元数据,文件成为孤儿。

数据库备份的敏感性远高于普通业务库(见 5.3):auth_tokens.token 存令牌原文,tenants.credentials、tenants.storage_engine_config、parser_engine_config 里可能有第三方密钥,tenant_api_keys 存可用的 API Key。备份应按"凭据 + 用户内容"管理:加密存储、限制访问、避免进入通用日志或工单附件。

SQLite 的备份要特别小心。数据库运行在 WAL 模式,直接拷贝 .db 文件可能丢掉尚未 checkpoint 的 WAL 内容。安全做法是:

  • 停写后拷贝 .db、.db-wal、.db-shm 三个文件;或
  • 用 VACUUM INTO 'backup.db' 生成一致性快照;或
  • 用 SQLite 的在线备份 API。

只拷 .db 是 Lite 版最常见的备份错误,表现为"恢复后少了最近一段时间的数据"。

5.13.2 恢复顺序:先权威,后派生

恢复的正确顺序是:

  1. 恢复关系库,跑完所有迁移到目标版本;
  2. 恢复对象存储 到原路径或新路径,并确认 storage_provider_config 指向正确;
  3. 重建派生索引:向量、全文、图、Wiki 索引;
  4. 校验:抽样检查文档可打开、分块数一致、检索可用。

第 3 步是关键:向量索引不是权威数据,不应从备份还原,而应从分块文本重新生成;重建还会使用当前 embedding 模型与索引参数,顺带完成一次"索引升级"。

重建前要确认两件事:

  • embedding 模型可用 。如果模型服务不可达,重建会失败;embeddings 表里的 dimension 与模型输出维度必须匹配。
  • 分块文本完整。如果分块也是从备份恢复的,直接重建即可;如果分块丢失,需要先重新解析原文件。

seq_id 是全局唯一编号,恢复后新增分块从 MAX(seq_id)+1 继续。若恢复旧备份而外部系统已记录更大的 seq_id,编号会回退;对外暴露的数字 ID 不适合作为长期唯一标识,恢复场景尤其明显。

5.13.3 连接池:两种数据库,两种策略

PostgreSQL 的连接池默认没有上限(由驱动与数据库决定),只设置了空闲连接数与生命周期:

go 复制代码
sqlDB.SetMaxIdleConns(10)
applyDBMaxOpenConns(ctx, sqlDB)   // 受 DB_MAX_OPEN_CONNS 控制,未设置则不限制
sqlDB.SetConnMaxLifetime(10 * time.Minute)

DB_MAX_OPEN_CONNS 未设置时不做上限。生产环境应显式设置,并与 PostgreSQL 的 max_connections、PgBouncer 的池大小协调。多实例部署时,总连接数是"实例数 × 每实例上限",很容易超过数据库承载能力。

SQLite 则相反,强制单连接:

go 复制代码
// SQLite only supports one concurrent writer even in WAL mode.
// Limiting to a single open connection serialises all DB access and
// prevents "database is locked" errors from concurrent goroutines.
sqlDB.SetMaxOpenConns(1)

单连接意味着所有查询串行,这对 Lite 版合理:单用户或小团队、写入量低,避免锁冲突优先于吞吐。代价是长查询会阻塞后续请求,Lite 版因此不适合大型聚合或批量导入;如有需要,应放到后台任务并接受请求排队。

连接串里还有三个 SQLite 参数:_journal_mode=WAL、_busy_timeout=5000、_foreign_keys=on。WAL 提升并发读;busy_timeout 让写锁等待 5 秒而非立即报错;foreign_keys=on 是外键生效的前提(SQLite 默认关闭)。缺任何一个都会表现为"偶发锁错误"或"外键形同虚设"。

5.13.4 索引健康:三类常见故障

第一类:HNSW 索引缺失或无效。 PostgreSQL 的向量索引是按维度建的部分索引。如果当前 embedding 维度没有对应索引,查询会退化为顺序扫描:结果正确,但延迟随数据量线性增长。项目用运行时自动建索引缓解:

  • 每个维度一个 sync.Map 记录状态;
  • 后台异步构建,避免阻塞首个查询;
  • 用会话级 advisory lock 让多副本轮流建,而不是同时 DDL;
  • 构建前抬高 statement_timeout,结束后 RESET;
  • 检查 pg_index.indisvalid,发现 INVALID 索引则重建。

自动建索引受 AUTO_MIGRATE=false 约束:如果部署把 Schema 管理交给外部工具,运行时不会擅自 DDL。此时必须由迁移或运维手工建索引,否则检索性能会悄悄退化。

第二类:表达式不匹配导致索引不生效。 HNSW 索引建在 embedding::halfvec(1024) 上,查询也必须用同样的表达式与同样的类型转换。写成 embedding::vector(1024) 或让参数以 text 传入,都会让规划器放弃索引。排查方法是 EXPLAIN 看是否出现 Index Scan using idx_...,而不是凭感觉判断"加了索引就应该快"。

第三类:Lite 版的 vec 表与 FTS 表失配。 vec_embeddings_<dim> 按维度分表,lite_embeddings 记录元数据。如果维度变化或表创建失败,代码会 unmarkVecTable(internal/application/repository/retriever/sqlite/repository.go:202)并在下次请求时重建。FTS5 是 contentless 表,删除与更新需要显式命令;CJK 分词用 bigram,查询串也要经过同样的分词与转义。索引损坏时,最稳妥的修复是删除这些派生表并让系统重建,而不是手工修补。

5.13.5 观测:日志之外还需要什么

应用层能提供三类信号:

  • GORM 日志 :慢查询(>200ms)、错误、record not found。参数被省略,只能看到 SQL 形状。
  • 迁移状态 :RunMigrationsWithOptions(internal/database/migration.go:101)记录版本、dirty、错误信息;GetMigrationVersion(internal/database/migration.go:302)可单独查询。
  • 审计日志 :audit_logs 记录敏感操作,包含操作者、租户、资源、结果。

但默认健康检查只有一个静态 {"status":"ok"},不检查数据库、迁移版本与索引,因此"迁移失败仍启动"不会被编排系统发现。建议补充检查:数据库 Ping 与当前迁移版本是否等于期望版本;embeddings 是否有当前维度的有效 HNSW 索引;对象存储是否可写(写探针对象再删除);任务队列是否有大量积压或死信增长。

数据库侧还应关注:

  • 连接数:接近上限时新请求会排队或失败;
  • 锁等待:长事务会阻塞 DDL 与写入;
  • 表与索引膨胀:软删除只置位不删行,长期运行后表会持续增长;
  • autovacuum 是否跟得上 :大量更新 parse_status、updated_at 会产生死元组;
  • 复制延迟(如果使用只读副本):向量检索若走副本,可能读到旧索引。

5.13.6 容量:软删除的隐性成本

软删除让"删除"不释放空间。一张 chunks 表可能包含大量 deleted_at 非空的行,索引也仍然为它们维护条目。长期运行的系统需要:

  • 物理清理任务:按保留期硬删除已软删除的行,顺序是先子表后主表,或依赖外键级联;
  • VACUUM/REINDEX :PostgreSQL 清理死元组、重建膨胀索引;SQLite 用 VACUUM 回收空间;
  • 监控"逻辑删除比例":如果已删除行占比很高,说明清理策略缺失或保留期过长。

seq_id 的全局分配也值得监控:PostgreSQL 用序列,删除不会回收编号;需要永久标识时应使用 UUID 或独立的不可回收序列。

下一节把五个事实、四类表与三条链重新串起来。

5.14 本章收束:三条链与十条不变量

本章从表结构讲到运维,要记住的不是字段,而是三条链与维护它们的不变量。

5.14.1 三条链

租户链:请求身份 → 目标租户 → 路由准入 → 服务层租户传递 → 仓储谓词 → SQL → 结果投影。任何一环松动都会产生越权或数据错配;逐条审计见 5.10。

知识链:上传 → 存储 → 元数据入库 → 解析 → 分块 → 索引 → 可检索 → 删除。分块是权威,向量是派生;删除顺序与失败模式见 5.12。

索引链:分块文本 → embedding → 向量索引 / 全文索引 / 图索引 → 检索 → 重排。HNSW 是按维度的部分索引,索引可重建,重建输入是分块文本。

5.14.2 十条不变量

如果把本章压缩成一份可贴在 code review 模板里的清单,就是下面十条:

  1. 关系库是唯一权威 ;文件原文是第二权威;向量、全文、图、Wiki 索引都是派生数据(HNSW 的构建与 advisory lock 在 internal/application/repository/retriever/postgres/hnsw_index.go:97)。
  2. Schema 只由迁移定义 ;生产路径不调用 AutoMigrate,唯一例外是 Lite 检索索引表。
  3. 仓储不读上下文租户;租户是显式参数,跨租户方法是少数且必须命名可辨。
  4. 不带租户的查询必须有等价保证:前置归属校验、系统级任务、或授权后过滤,三者之一。
  5. 资源 ID 的授权先于 SQL ;SQL 里有 tenant_id 不代表安全,ID 本身可能来自未校验的请求。
  6. 软删除不释放空间;每个软删除都需要定义物理清理与配额回退。
  7. 删除先删行、后删外部资源;宁可留下可清理的孤儿,也不留下无法恢复的缺失。
  8. 队列是至少一次投递;所有消费者必须幂等,重复执行不产生额外副作用。
  9. 迁移失败不阻断启动;部署必须自己检查迁移版本,健康检查不能只看 200。
  10. 默认值有三层:DDL 默认、GORM 钩子默认、业务创建路径默认;判断真实值时以创建路径为准。

这些约束适用于任何"多租户 + 关系库 + 派生索引 + 异步任务"系统。

相关推荐
guuguo28 分钟前
【做个开源软件】Mac 上 node 进程莫名吃掉 6G 内存?给 AI / MCP 做了个深度归因和安全回收工具
人工智能·开源·github
双鱼大猫1 小时前
opencode 吃掉 100G 空间:Agent 会话数据要分级清理
人工智能·agent·ai编程
用户5833339816681 小时前
RPA 流程的异常处理设计:重试、降级与告警,生产环境实战指南
人工智能
sanxing三省2 小时前
DeepSeek Harness 到底是什么?标题里最重的词其实不是「DeepSeek」
前端·人工智能·deepseek
合尘猫3 小时前
用 6GB 显卡搭短视频产线:MiniMax H3 + ffmpeg 全流程实录(55 秒片 / 40 分钟)
人工智能·音视频
ZONGYUAN-ROOT3 小时前
【自愈治理】自愈式数据管道:大规模公开数据采集的治理方法
人工智能
Starry-sky(jing)3 小时前
Hermes Agent 升级 v0.23.2:先辨更新渠道,再看 CLI 退出残留修复
人工智能·python·ai agent
oil欧哟4 小时前
AI Agent Skill 入门指南:文件夹本质、渐进式加载与挑选方法
人工智能·ai编程