数据库设计

数据选型

以下保留各表结构、字段解释和示例 SQL。当前部署使用 1024 维向量；历史基础表还需执行本文末尾的增量迁移。不要在已有业务库直接重建表。Windows 扩展安装见第 29 章，下面的 apt 命令仅适用于对应 Linux 环境。

前端：使用 MossKB 前端
后端：采用 Java 进行开发
模型端：使用 OpenAI-4o-mini 系列模型
数据端：使用 PostgreSQL + pgvector 存储向量数据

1. 创建用户、授予权限及安装 `pgvector` 插件

以下步骤演示了在 PostgreSQL 中创建新用户和数据库，授予必要权限，并安装及测试 pgvector 插件的过程。

1.1 切换到 PostgreSQL 用户

su - postgres

1.2 连接到 PostgreSQL

psql

1.3 创建数据库和用户

在 psql 提示符下执行以下命令，以创建名为 moss_kb 的数据库以及同名用户，并设置密码：

-- 创建数据库
CREATE DATABASE moss_kb;

-- 创建用户并设置密码
CREATE USER moss_kb WITH PASSWORD '<替换为自己的数据库密码>';

1.4 授予用户权限

-- 授予用户 moss_kb 对数据库 moss_kb 的所有权限
GRANT ALL PRIVILEGES ON DATABASE moss_kb TO moss_kb;

-- 切换到 moss_kb 数据库
\c moss_kb

-- 授予用户 moss_kb 在 public 模式下创建表的权限
GRANT ALL PRIVILEGES ON SCHEMA public TO moss_kb;

提示：在大多数情况下，无需更改 public 模式的所有者，除非有其他特殊需求。

1.5 安装并启用 `pgvector` 插件

安装插件（以基于 Debian/Ubuntu 的系统为例，需根据自身 PostgreSQL 版本调整命令）：
```
sudo apt-get update
sudo apt-get install postgresql-14-pgvector
```

启用插件：

-- 再次确保在 moss_kb 数据库下
\c moss_kb

CREATE EXTENSION IF NOT EXISTS vector;

验证是否成功启用：
```
SELECT * FROM pg_extension WHERE extname = 'vector';
```
如果能查询到返回结果，则表示扩展已启用。

1.6 测试 `pgvector`

在数据库中创建一个测试表，确认 vector 类型可用：

CREATE TABLE vector_test (
    id SERIAL PRIMARY KEY,
    v VECTOR(3)
);

如果能成功创建表，说明 pgvector 已正常启用。

2. 数据库设计

以下是本项目所需的主要数据表结构与示例创建脚本。

2.1 设计规范

主键：统一使用 64 位的雪花 ID（Snowflake ID），BIGINT 类型。
租户 ID：所有表均增加 tenant_id，默认为 0。
逻辑删除：多数表均包含 deleted 字段，建议使用 0 表示正常，1 代表已删除。实际生产环境中也可采用其他标志位或多租户/软删除策略。
时间戳：采用 TIMESTAMP WITH TIME ZONE 或 TIMESTAMP WITHOUT TIME ZONE 存储创建/更新时间，具体可视业务需求调整。
向量列：embedding、title_embedding 等使用 VECTOR 类型且不写死维度，维度由 Embedding 模型决定（当前部署为 1024 维）。
例外：后期增量表（moss_kb_chat_context、moss_kb_function_lib、moss_kb_model_provider、moss_kb_model_catalog）是平台/缓存/附属表，不带 tenant_id；其中 moss_kb_function_lib 的 deleted 为 BOOLEAN，与基础表的 SMALLINT 约定不同，各表下已单独标注。

2.2 全表总览

截至本文更新，moss_kb 库 public 模式共 32 张表，与 2.3 小节一一对应；另有 1 张（moss_kb_web_page_cache）仅被代码引用、尚未建表，见表 28。

表名	用途	结构
`moss_kb_user`	用户账号	表 1
`moss_kb_user_token`	用户令牌	表 2
`moss_kb_model`	用户模型实例与凭据	表 3
`moss_kb_application`	应用配置	表 4
`moss_kb_application_access_token`	应用对外访问令牌	表 5
`moss_kb_task`	文档处理任务进度	表 6
`moss_kb_file`	文件元信息	表 7
`moss_kb_dataset`	知识库（数据集）	表 8
`moss_kb_application_dataset_mapping`	应用与知识库关联	表 9
`moss_kb_document`	文档	表 10
`moss_kb_paragraph`	段落（向量检索单元）	表 11
`moss_kb_sentence`	句子（细粒度检索）	表 12
`moss_kb_problem`	问题	表 13
`moss_kb_problem_paragraph_mapping`	问题与段落关联	表 14
`moss_kb_embedding_cache`	向量缓存	表 15
`moss_kb_document_markdown_cache`	文档 Markdown 缓存	表 16
`moss_kb_document_markdown_page_cache`	分页 Markdown 缓存与 Token 统计	表 17
`moss_kb_application_chat`	会话	表 18
`moss_kb_application_chat_record`	会话问答记录	表 19
`moss_kb_application_temp_setting`	应用临时设置	表 20
`moss_kb_paragraph_summary_cache`	段落摘要缓存	表 21
`moss_kb_application_public_access_client`	公共访问客户端统计	表 22
`libre_office_converted_mapping`	文档转换映射	表 23
`moss_kb_chat_context`	会话摘要与压缩水位	表 24
`moss_kb_function_lib`	隔离执行的 Python 函数库	表 25
`moss_kb_model_provider`	模型平台目录	表 26
`moss_kb_model_catalog`	平台基础模型目录	表 27
`moss_kb_web_page_cache`	网页抓取缓存（未建表）	表 28
`moss_kb_document_split_task`	分段预览任务的进度与结果	表 29

除上表之外，schema.sql 还建出 system_setting、moss_kb_user_api_key、moss_kb_application_api_key 等基础表，字段以 schema.sql 为准。

2.3 各表结构及示例

注意：以下脚本均采用默认的 public 模式。
编号仅用于顺序说明，实际建表顺序可根据依赖关系灵活调整。
本节已按实际库核对：public 模式共 32 张表，与 2.2 总览一一对应。

表 1：`moss_kb_user`

DROP TABLE IF EXISTS "public"."moss_kb_user";

CREATE TABLE "public"."moss_kb_user" (
  "id" BIGINT NOT NULL PRIMARY KEY,
  "email" VARCHAR,
  "phone" VARCHAR NOT NULL,
  "nick_name" VARCHAR NOT NULL,
  "username" VARCHAR NOT NULL,
  "password" VARCHAR NOT NULL,
  "role" VARCHAR NOT NULL,
  "is_active" BOOLEAN NOT NULL,
  "source" VARCHAR NOT NULL,
  "remark" VARCHAR(256),
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

-- 创建索引
CREATE INDEX "user_email_index_like" ON "public"."moss_kb_user" USING btree (
  "email" varchar_pattern_ops
);
CREATE INDEX "user_username_index_like" ON "public"."moss_kb_user" USING btree (
  "username" varchar_pattern_ops
);

-- 插入初始记录（管理员账户）
INSERT INTO "public"."moss_kb_user"
VALUES (
  1,
  '',
  '',
  '系统管理员',
  'admin',
  '608fd4367502762e76a77ee348c9f1c7',
  'ADMIN',
  TRUE,
  'LOCAL',
  '',
  '',
  CURRENT_TIMESTAMP,
  '',
  CURRENT_TIMESTAMP,
  0,
  0
);

-- 备注：默认密码 “Kimi@2024” 的 MD5（或其他加密形式）

用途

存储用户账号信息：邮箱、电话、昵称、用户名、密码、角色、是否激活、备注等。

当前增量：007-user-sessions.sql 追加 token_version BIGINT NOT NULL DEFAULT 0。登录签发的令牌携带该值，改密、重置或停用账号时服务端自增，旧令牌立即失效（见第 16 章、第 34 章）。

表 2：`moss_kb_user_token`

DROP TABLE IF EXISTS "public"."moss_kb_user_token";

CREATE TABLE "public"."moss_kb_user_token" (
  "id" BIGINT NOT NULL PRIMARY KEY,
  "token" VARCHAR NOT NULL,
  "remark" VARCHAR(256),
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

用途

存储用户认证令牌、令牌备注等信息，用于管理用户登录、会话等。

表 3：`moss_kb_model`

DROP TABLE IF EXISTS "public"."moss_kb_model";

CREATE TABLE "public"."moss_kb_model" (
  "id" BIGINT NOT NULL PRIMARY KEY,
  "name" VARCHAR NOT NULL,
  "model_type" VARCHAR NOT NULL,
  "model_name" VARCHAR NOT NULL,
  "provider" VARCHAR NOT NULL,
  "credential" VARCHAR NOT NULL,
  "user_id" BIGINT NOT NULL,
  "meta" JSONB,
  "status" VARCHAR,
  "permission_type" VARCHAR NOT NULL,
  "remark" VARCHAR(256),
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX "idx_user_id" ON "public"."moss_kb_model" USING btree ("user_id");

用途

存储大模型的配置信息，包含模型名称、类型、提供方、密钥/凭证、元数据、状态、权限类型、归属用户等。

当前增量：008-model-catalog.sql 追加 model_params_form JSONB NOT NULL DEFAULT '[]'，用于按平台表单声明实例参数；密钥只存于本表 credential，平台表不保存用户 API Key（见第 35 章）。

表 4：`moss_kb_application`

DROP TABLE IF EXISTS "public"."moss_kb_application";

CREATE TABLE "public"."moss_kb_application" (
  "id" BIGINT PRIMARY KEY,
  "code" INT,
  "course_name" VARCHAR,
  "owner_name" VARCHAR,
  "state" INT,
  "name" VARCHAR NOT NULL,
  "desc" VARCHAR NOT NULL,
  "prompt" VARCHAR,
  "prologue" VARCHAR NOT NULL,
  "dialogue_number" INT NOT NULL,
  "dataset_setting" JSONB NOT NULL,
  "model_setting" JSONB NOT NULL,
  "problem_optimization" BOOLEAN NOT NULL,
  "model_id" BIGINT,
  "user_id" BIGINT NOT NULL,
  "icon" VARCHAR,
  "type" VARCHAR NOT NULL,
  "work_flow" JSONB,
  "show_source" BOOLEAN DEFAULT TRUE,
  "multiple_rounds_dialogue" BOOLEAN DEFAULT TRUE,
  "model_params_setting" JSONB NOT NULL,
  "stt_model_id" BIGINT,
  "stt_model_enable" BOOLEAN NOT NULL,
  "tts_model_id" BIGINT,
  "tts_model_enable" BOOLEAN NOT NULL,
  "tts_type" VARCHAR NOT NULL,
  "problem_optimization_prompt" VARCHAR,
  "tts_model_params_setting" JSONB,
  "clean_time" INT,
  "remark" VARCHAR(256),
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX "application_model_id" ON "public"."moss_kb_application" USING btree ("model_id");
CREATE INDEX "application_stt_model_id" ON "public"."moss_kb_application" USING btree ("stt_model_id");
CREATE INDEX "application_tts_model_id" ON "public"."moss_kb_application" USING btree ("tts_model_id");
CREATE INDEX "application_user_id" ON "public"."moss_kb_application" USING btree ("user_id");

用途

存储各类知识库应用的信息，包括前端配置、提示语、对话数量、关联模型、关联用户、语音识别/合成等配置。

表 5：`moss_kb_application_access_token`

DROP TABLE IF EXISTS "public"."moss_kb_application_access_token";

CREATE TABLE "public"."moss_kb_application_access_token" (
  "application_id" BIGINT PRIMARY KEY,
  "access_token" BIGINT NOT NULL,
  "is_active" BOOLEAN NOT NULL,
  "access_num" INT NOT NULL,
  "white_active" BOOLEAN NOT NULL,
  "white_list" VARCHAR[] NOT NULL,
  "show_source" BOOLEAN NOT NULL,
  "language" VARCHAR(16),
  "remark" VARCHAR(256),
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX "moss_kb_application_access_token_access_token" ON "public"."moss_kb_application_access_token" USING btree ("access_token");

用途

应用对外提供的访问令牌管理表，支持访问次数统计、白名单配置、是否显示内容来源等。
language 为该应用公开分享页的界面语言，取值 en-US、zh-CN、zh-Hant，为空表示跟随访客浏览器语言，详见独立对话页。

表 6：`moss_kb_task`

DROP TABLE IF EXISTS "public"."moss_kb_task";

CREATE TABLE "public"."moss_kb_task" (
  "id" BIGINT NOT NULL PRIMARY KEY,
  "file_id" BIGINT,
  "file_name" VARCHAR NOT NULL,
  "file_size" BIGINT,
  "dataset_id" BIGINT NOT NULL,
  "document_id" BIGINT,
  "progress" SMALLINT DEFAULT 0,
  "status" VARCHAR NOT NULL,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT NOT NULL DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

用途

存储文件处理/任务相关的进度信息，如进度、状态、关联的数据集与文档等。

表 7：`moss_kb_file`

DROP TABLE IF EXISTS "public"."moss_kb_file";

CREATE TABLE "public"."moss_kb_file" (
  "id" BIGINT PRIMARY KEY,
  "md5" VARCHAR(32) NOT NULL,
  "filename" VARCHAR(64) NOT NULL,
  "file_size" BIGINT NOT NULL,
  "user_id" BIGINT,
  "platform" VARCHAR(64) NOT NULL,
  "region_name" VARCHAR(32),
  "bucket_name" VARCHAR(64) NOT NULL,
  "file_id" VARCHAR(64),
  "target_name" VARCHAR(255) NOT NULL,
  "tags" JSON,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT NOT NULL DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

用途

存储文件的基础信息（MD5 值、大小、文件名、上传位置、存储路径等），方便后续在对象存储或本地文件系统中查找。

当前增量：003-filename-capacity.sql 将 filename 由 VARCHAR(64) 改为 TEXT，以容纳法规、公告类完整长文件名。

表 8：`moss_kb_dataset`

DROP TABLE IF EXISTS "public"."moss_kb_dataset";

CREATE TABLE "public"."moss_kb_dataset" (
  "id" BIGINT PRIMARY KEY,
  "name" VARCHAR NOT NULL,
  "desc" VARCHAR,
  "type" VARCHAR,
  "embedding_mode_id" BIGINT,
  "llm_mode_id" BIGINT,
  "meta" JSONB,
  "user_id" BIGINT,
  "remark" VARCHAR(256),
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

用途

用于管理各数据集元信息：名称、描述、类型、所使用的向量/Embedding 配置、归属用户等。

当前增量：002-gitee-models.sql 追加 llm_mode_id BIGINT（对话模型），与 embedding_mode_id（向量模型）成对使用。

表 9：`moss_kb_application_dataset_mapping`

DROP TABLE IF EXISTS "public"."moss_kb_application_dataset_mapping";

CREATE TABLE "public"."moss_kb_application_dataset_mapping" (
  "id" BIGINT PRIMARY KEY,
  "application_id" BIGINT NOT NULL,
  "dataset_id" BIGINT NOT NULL
);

用途

建立应用与数据集之间的关联关系：即一个应用可以关联多个数据集。

表 10：`moss_kb_document`

DROP TABLE IF EXISTS "public"."moss_kb_document";

CREATE TABLE "public"."moss_kb_document" (
  "id" BIGINT NOT NULL PRIMARY KEY,
  "file_id" BIGINT,
  "user_id" BIGINT,
  "title" VARCHAR,
  "name" VARCHAR NOT NULL,
  "type" VARCHAR NOT NULL,
  "url" VARCHAR,
  "content" text,
  "char_length" INT,
  "status" VARCHAR,
  "is_active" BOOLEAN,
  "meta" JSONB,
  "dataset_id" BIGINT NOT NULL,
  "hit_handling_method" VARCHAR,
  "directly_return_similarity" FLOAT8,
  "paragraph_count" INT,
  "files" JSON,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT NOT NULL DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

用途

管理文档的基础信息（文件关联、标题、字符数、索引状态等），以及分段方法、相似度直接返回的阈值或配置等。

状态值示例
由于此处为 VARCHAR 类型，常见做法是存储数字或关键字字符串。例如：

"0"：索引中
"1"：处理完成
"2"：识别中
"3"：排队中
"4"：生成问题中

具体可根据业务场景进行约定。

表 11：`moss_kb_paragraph`

DROP TABLE IF EXISTS "public"."moss_kb_paragraph";

CREATE TABLE "public"."moss_kb_paragraph" (
  "id" BIGINT PRIMARY KEY,
  "source_id" BIGINT,
  "source_type" VARCHAR,
  "title" VARCHAR,
  "content" VARCHAR NOT NULL,
  "md5" VARCHAR NOT NULL,
  "status" VARCHAR,
  "hit_num" INT,
  "is_active" BOOLEAN,
  "dataset_id" BIGINT NOT NULL,
  "document_id" BIGINT NOT NULL,
  "embedding" VECTOR,
  "title_embedding" VECTOR,
  "meta" JSONB,
  "search_vector" TSVECTOR,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

用途

存储文档的“段落”级别信息，包含文本内容、向量表示（embedding）、TS 向量（search_vector）等，便于向量搜索或全文检索。

向量维度：库中 embedding、title_embedding 为不带维度约束的 VECTOR，维度由所选 Embedding 模型决定，当前部署实际写入 1024 维（Qwen3-Embedding-8B）。表 12 的 embedding 同理。不同维度的向量不能混放，切换模型后需重新向量化，见「当前增量表结构及迁移」。

表 12：`moss_kb_sentence`

DROP TABLE IF EXISTS "public"."moss_kb_sentence";

CREATE TABLE "public"."moss_kb_sentence" (
  "id" BIGINT PRIMARY KEY,
  "type" INT,
  "content" VARCHAR NOT NULL,
  "md5" VARCHAR NOT NULL,
  "hit_num" INT NOT NULL,
  "dataset_id" BIGINT NOT NULL,
  "document_id" BIGINT NOT NULL,
  "paragraph_id" BIGINT NOT NULL,
  "embedding" VECTOR,
  "meta" JSONB,
  "search_vector" TSVECTOR,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

用途

按“句子”维度拆分文档内容，通常在需要更精细的向量检索场景下使用。

type 字段示例

1：来自正文
2：段落摘要

表 13：`moss_kb_problem`

DROP TABLE IF EXISTS "public"."moss_kb_problem";

CREATE TABLE "public"."moss_kb_problem" (
  "id" BIGINT PRIMARY KEY,
  "content" VARCHAR NOT NULL,
  "hit_num" INT NOT NULL,
  "dataset_id" BIGINT NOT NULL,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX "moss_kb_problem_dataset_id" ON "public"."moss_kb_problem" USING btree ("dataset_id");

用途

存储常见或已识别的问题，便于后续做 FAQ 或查询等操作。

表 14：`moss_kb_problem_paragraph_mapping`

DROP TABLE IF EXISTS "public"."moss_kb_problem_paragraph_mapping";

CREATE TABLE "public"."moss_kb_problem_paragraph_mapping" (
  "id" BIGINT PRIMARY KEY,
  "dataset_id" BIGINT NOT NULL,
  "document_id" BIGINT NOT NULL,
  "paragraph_id" BIGINT NOT NULL,
  "problem_id" BIGINT NOT NULL,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX "moss_kb_problem_paragraph_mapping_dataset_id"   ON "public"."moss_kb_problem_paragraph_mapping" USING btree ("dataset_id");
CREATE INDEX "moss_kb_problem_paragraph_mapping_document_id"  ON "public"."moss_kb_problem_paragraph_mapping" USING btree ("document_id");
CREATE INDEX "moss_kb_problem_paragraph_mapping_paragraph_id" ON "public"."moss_kb_problem_paragraph_mapping" USING btree ("paragraph_id");
CREATE INDEX "moss_kb_problem_paragraph_mapping_problem_id"   ON "public"."moss_kb_problem_paragraph_mapping" USING btree ("problem_id");

用途

问题与段落的多对多关联，便于快速检索“某个问题可命中到哪些段落”的信息。

表 15：`moss_kb_embedding_cache`

DROP TABLE IF EXISTS "public"."moss_kb_embedding_cache";

CREATE TABLE "public"."moss_kb_embedding_cache" (
  "id" BIGINT PRIMARY KEY,
  "t" TEXT,
  "m" VARCHAR,
  "v" VECTOR,
  "md5" VARCHAR
);

CREATE INDEX "idx_moss_kb_embedding_cache_md5" ON "public"."moss_kb_embedding_cache" USING btree ("md5");
CREATE INDEX "idx_moss_kb_embedding_cache_md5_m" ON "public"."moss_kb_embedding_cache" USING btree ("md5", "m");

用途

缓存文本与其向量表示的映射，以免重复向外部接口请求 Embedding。

表 16：`moss_kb_document_markdown_cache`

DROP TABLE IF EXISTS "public"."moss_kb_document_markdown_cache";

CREATE TABLE "public"."moss_kb_document_markdown_cache" (
  "id" VARCHAR PRIMARY KEY,
  "target" VARCHAR,
  "content" TEXT
);

用途

存储文档转换为 Markdown 后的缓存结果，可用于预览或快速查阅。

表 17：`moss_kb_document_markdown_page_cache`

DROP TABLE IF EXISTS "public"."moss_kb_document_markdown_page_cache";

CREATE TABLE "public"."moss_kb_document_markdown_page_cache" (
  "id" VARCHAR PRIMARY KEY,
  "target" VARCHAR,
  "content" TEXT,
  "elapsed" BIGINT,
  "model" VARCHAR,
  "system_fingerprint" VARCHAR,
  "completion_tokens" INT,
  "prompt_tokens" INT,
  "total_tokens" INT
);

用途

针对分页级别做 Markdown 缓存，以及与大模型的调用信息统计（tokens 等）。

表 18：`moss_kb_application_chat`

DROP TABLE IF EXISTS "public"."moss_kb_application_chat";

CREATE TABLE "public"."moss_kb_application_chat" (
  "id" BIGINT PRIMARY KEY,
  "abstract" VARCHAR,
  "application_id" BIGINT NOT NULL,
  "client_id" BIGINT,
  "chat_type" INT NOT NULL,
  "is_deleted" BOOLEAN NOT NULL DEFAULT FALSE,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX "moss_kb_application_chat_application_id" ON "public"."moss_kb_application_chat" USING btree ("application_id");

用途

存储应用的会话信息，区分调试会话、普通会话等。

chat_type

0：普通会话
1：调试会话

表 19：`moss_kb_application_chat_record`

DROP TABLE IF EXISTS "public"."moss_kb_application_chat_record";

CREATE TABLE "public"."moss_kb_application_chat_record" (
  "id" BIGINT PRIMARY KEY,
  "vote_status" VARCHAR NOT NULL DEFAULT '-1',
  "problem_text" VARCHAR NOT NULL,
  "answer_text" VARCHAR,
  "message_tokens" INT NOT NULL,
  "answer_tokens" INT,
  "const" INT NOT NULL DEFAULT 0,
  "details" JSONB,
  "improve_paragraph_id_list" BIGINT[],
  "run_time" FLOAT8,
  "index" INT,
  "chat_id" BIGINT NOT NULL,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX "moss_kb_application_chat_record_chat_id" ON "public"."moss_kb_application_chat_record" USING btree ("chat_id");

用途

存储具体的聊天记录内容、投票状态、Token 消耗情况等。

表 20：`moss_kb_application_temp_setting`

DROP TABLE IF EXISTS "public"."moss_kb_application_temp_setting";

CREATE TABLE "public"."moss_kb_application_temp_setting" (
  "id" BIGINT PRIMARY KEY,
  "setting" JSONB
);

用途

临时存储应用的一些推理、配置等 JSON 格式数据。

表 21：`moss_kb_paragraph_summary_cache`

DROP TABLE IF EXISTS "public"."moss_kb_paragraph_summary_cache";

CREATE TABLE "public"."moss_kb_paragraph_summary_cache" (
  "id" BIGINT PRIMARY KEY,
  "md5" VARCHAR,
  "src" TEXT,
  "content" TEXT,
  "elapsed" BIGINT,
  "model" VARCHAR,
  "system_fingerprint" VARCHAR,
  "completion_tokens" INT,
  "prompt_tokens" INT,
  "total_tokens" INT
);

用途

缓存段落摘要信息，包括原文 MD5、摘要内容、模型、耗时、Token 统计等。

表 22：`moss_kb_application_public_access_client`

DROP TABLE IF EXISTS "public"."moss_kb_application_public_access_client";

CREATE TABLE "public"."moss_kb_application_public_access_client" (
  "id" BIGINT PRIMARY KEY,
  "access_num" INT NOT NULL,
  "intraday_access_num" INT NOT NULL,
  "application_id" BIGINT NOT NULL,
  "client_id" BIGINT,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

用途

公共访问客户端统计表，记录某应用被匿名/公共访问的次数、当日访问量等。

表 23：`libre_office_converted_mapping`

原脚本中名为 libre_office_converted_maping，存在拼写错误，建议修改为 libre_office_converted_mapping。

DROP TABLE IF EXISTS "public"."libre_office_converted_mapping";

CREATE TABLE "public"."libre_office_converted_mapping" (
  "id" BIGINT NOT NULL PRIMARY KEY,
  "input_file_id" BIGINT,
  "input_md5" VARCHAR,
  "output_file_id" BIGINT,
  "output_md5" VARCHAR,
  "remark" VARCHAR(256),
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

表 24：`moss_kb_chat_context`

CREATE TABLE IF NOT EXISTS moss_kb_chat_context (
  chat_id BIGINT PRIMARY KEY REFERENCES moss_kb_application_chat(id) ON DELETE CASCADE,
  summary TEXT NOT NULL DEFAULT '',
  through_record_id BIGINT NOT NULL DEFAULT 0,
  compacted_rounds INTEGER NOT NULL DEFAULT 0,
  revision INTEGER NOT NULL DEFAULT 0,
  update_time TIMESTAMP NOT NULL DEFAULT now()
);

CREATE INDEX IF NOT EXISTS idx_chat_record_context
  ON moss_kb_application_chat_record (chat_id, id) WHERE answer_text IS NOT NULL;

用途

每个会话一行，保存上下文压缩后的摘要与水位：summary 是压缩摘要，through_record_id 是已并入摘要的最后一条 moss_kb_application_chat_record.id，compacted_rounds 是已压缩轮数。
revision 用于乐观并发控制，写入时带上读取到的 revision，避免并发压缩互相覆盖。
chat_id 既是主键也是外键，会话删除时级联删除；本表不带 tenant_id、deleted。实现见第 32 章。

表 25：`moss_kb_function_lib`

CREATE TABLE IF NOT EXISTS moss_kb_function_lib (
  id BIGINT PRIMARY KEY, user_id BIGINT NOT NULL,
  name VARCHAR(128) NOT NULL, "desc" TEXT NOT NULL DEFAULT '', code TEXT NOT NULL,
  input_field_list JSONB NOT NULL DEFAULT '[]', init_field_list JSONB NOT NULL DEFAULT '[]',
  init_params JSONB NOT NULL DEFAULT '{}', permission_type VARCHAR(16) NOT NULL DEFAULT 'PRIVATE',
  is_active BOOLEAN NOT NULL DEFAULT true, deleted BOOLEAN NOT NULL DEFAULT false,
  create_time TIMESTAMP NOT NULL DEFAULT now(), update_time TIMESTAMP NOT NULL DEFAULT now()
);

CREATE INDEX IF NOT EXISTS idx_function_owner ON moss_kb_function_lib (user_id) WHERE deleted = false;

用途

存放可隔离执行的 Python 函数：code 是函数源码，input_field_list/init_field_list 是入参与初始化字段表单，init_params 是初始参数。
permission_type 取 PRIVATE/PUBLIC，PUBLIC 函数可被其他用户引用。
注意：deleted 为 BOOLEAN 且不带 tenant_id，与基础表约定不同（见 2.1）。执行沙箱见第 32 章。

表 26：`moss_kb_model_provider`

CREATE TABLE IF NOT EXISTS moss_kb_model_provider (
  provider VARCHAR(128) PRIMARY KEY,
  name VARCHAR(200) NOT NULL,
  icon TEXT NOT NULL DEFAULT '',
  api_base TEXT NOT NULL DEFAULT '',
  protocol VARCHAR(40) NOT NULL DEFAULT 'OPENAI_COMPATIBLE',
  model_types JSONB NOT NULL,
  credential_form JSONB NOT NULL,
  params_form JSONB NOT NULL,
  enabled BOOLEAN NOT NULL DEFAULT true,
  sort_order INTEGER NOT NULL DEFAULT 0,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

用途

模型平台目录：以 provider 为主键描述一个平台，api_base、protocol 给出接入方式，model_types、credential_form、params_form 驱动前端表单。
本表不保存用户 API Key，凭据只存于 moss_kb_model.credential。目录更新不需要重新编译，见第 35 章。

表 27：`moss_kb_model_catalog`

CREATE TABLE IF NOT EXISTS moss_kb_model_catalog (
  provider VARCHAR(128) REFERENCES moss_kb_model_provider(provider),
  model_type VARCHAR(30) NOT NULL,
  model_id VARCHAR(256) NOT NULL,
  description TEXT,
  source TEXT NOT NULL DEFAULT 'seed',
  enabled BOOLEAN NOT NULL DEFAULT true,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (provider, model_type, model_id)
);

用途

平台下的基础模型清单，供新增模型实例时下拉选择；source 区分内置（seed）与自定义登记。
联合主键 (provider, model_type, model_id)，provider 外键指向表 26。快照数据由 009-model-catalog-snapshot.sql 登记，见第 35 章。

表 28：`moss_kb_web_page_cache`（⚠ 代码引用，库中尚未创建）

该表目前不在任何初始化脚本中，实际库也不存在。PlaywrightService 读写的是 web_page_cache（没有 moss_kb_ 前缀），而 SchduleTaskPerHour 的定时清理语句写的是 moss_kb_web_page_cache，两处命名不一致：开启网页抓取（kb.playwright.enable=true）并走到缓存分支后，其中一处必然报“表不存在”。建议统一为下表名称，并同步修改 PlaywrightService.cache_table_name。

CREATE TABLE IF NOT EXISTS moss_kb_web_page_cache (
  id BIGINT PRIMARY KEY,
  url TEXT NOT NULL,
  text TEXT,
  html TEXT,
  create_time TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX IF NOT EXISTS idx_web_page_cache_url ON moss_kb_web_page_cache ("url");

用途

缓存 Playwright 抓取到的网页正文（text）与原始 HTML（html），按 url 去重，避免重复抓取；SchduleTaskPerHour 每小时清理一天前的记录。
如需额外防止并发重复写入，可把 url 索引改为唯一索引；若沿用无前缀的 web_page_cache，则必须同步修改定时清理语句，两种命名只能保留一种。

表 29：`moss_kb_document_split_task`

CREATE TABLE IF NOT EXISTS "public"."moss_kb_document_split_task" (
  "id" BIGINT NOT NULL PRIMARY KEY,
  "user_id" BIGINT,
  "file_id" BIGINT,
  "file_name" VARCHAR NOT NULL,
  "file_size" BIGINT,
  "status" VARCHAR(16) NOT NULL DEFAULT 'running',
  "progress" SMALLINT NOT NULL DEFAULT 0,
  "total" INT NOT NULL DEFAULT 0,
  "result" JSONB,
  "error_message" TEXT,
  "creator" VARCHAR(64) DEFAULT '',
  "create_time" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "updater" VARCHAR(64) DEFAULT '',
  "update_time" TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  "deleted" SMALLINT NOT NULL DEFAULT 0,
  "tenant_id" BIGINT NOT NULL DEFAULT 0
);

CREATE INDEX IF NOT EXISTS "moss_kb_document_split_task_user_id"
  ON "public"."moss_kb_document_split_task" USING btree ("user_id");

用途

分段预览任务：上传接口保存文件后建一行并立刻返回任务 ID，解析在后台线程里逐页推进，前端按固定间隔轮询本表取进度或最终分段。
status 取 running、success、failed；progress 是已完成百分比，total 是总页数；result 保存成功后前端要用的分段列表，error_message 保存失败原因。
查询按 id 与 user_id 一起过滤，任务只对创建者可见。
本表只承载“预览中的中间状态”，确认后的分段写入 moss_kb_paragraph 等正规表；预览结果不应被当成已入库的知识。实现见第 42 章。

当前增量表结构及迁移

保留上文基础表和字段说明。当前程序通过 scripts/Initialize-Database.ps1 顺序执行初始化及增量脚本。IF NOT EXISTS 不会自动改变旧列类型；旧向量空间与新模型不能混用。表 24–27 就是这些脚本建出的表，本节给出脚本清单与字段级变更。

.\scripts\Initialize-Database.ps1 -PostgresBin '<PostgreSQL安装目录>\bin'

增量脚本清单

脚本	作用	关联对象
`init-db.sql`	建基础表及索引，写入管理员账号	表 1–23
`002-gitee-models.sql`	写入默认 Gitee 平台模型 1001/1002	`moss_kb_model`、`moss_kb_dataset.llm_mode_id`
`003-filename-capacity.sql`	放宽文件名长度	`moss_kb_file.filename`
`004-keyword-search.sql`	安装 `pg_trgm`，支撑模糊/关键词检索	扩展，非表
`005-agent-context.sql`	建会话摘要与压缩水位表	表 24
`006-python-functions.sql`	建隔离执行的函数库表	表 25
`007-user-sessions.sql`	令牌版本，用于让旧令牌失效	`moss_kb_user.token_version`
`008-model-catalog.sql`	建平台与模型目录表并初始化表单	表 26、表 27、`moss_kb_model.model_params_form`
`009-model-catalog-snapshot.sql`	登记模型目录快照数据	表 27 的数据

字段级变更

基础建表脚本不含下列列，历史库需按顺序执行。ADD COLUMN IF NOT EXISTS 可重复执行，但不会改变已存在列的类型，ALTER COLUMN ... TYPE 必须显式执行：

ALTER TABLE moss_kb_user    ADD COLUMN IF NOT EXISTS token_version BIGINT NOT NULL DEFAULT 0;
ALTER TABLE moss_kb_dataset ADD COLUMN IF NOT EXISTS llm_mode_id BIGINT;
ALTER TABLE moss_kb_model   ADD COLUMN IF NOT EXISTS model_params_form JSONB NOT NULL DEFAULT '[]';
ALTER TABLE moss_kb_file    ALTER COLUMN filename TYPE TEXT;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

向量空间一致性

切换 Embedding 模型时，moss_kb_embedding_cache 与 moss_kb_paragraph、moss_kb_sentence 中的旧向量维度与新模型不一致，检索会直接报维度错误。此时不能只改模型 ID，需要先清空缓存并对文档重新向量化。

平台表不保存用户 API Key；凭据由用户模型实例管理。008-model-catalog.sql 还初始化平台与表单，009-model-catalog-snapshot.sql 登记模型目录快照。目录更新不需要重新编译，完整接口及数据关系见第 35 章。