DatabaseSchema：采购文件搜索服务

目录

• 概述
• 数据库文件
• 表清单
• files 表
• files_fts 虚拟表
• 触发器
• audit_logs 表
• download_tokens 表
• 字段影响范围
• 后续表设计

概述

本项目 MVP 使用 SQLite 作为 OpenClaw 服务器本地文件索引库。搜索请求查询本地 SQLite/FTS 索引，不依赖群晖搜索能力。

当前数据库保存：

• 文件元数据。
• FTS 搜索索引。
• 基础审计日志。
• 下载 token。

当前数据库不保存文件正文，也不保存文件内容。

数据库文件

默认路径：

./data/file_index.sqlite

该路径可通过 config.json 的 index_db 配置修改。

表清单

files 表

建表逻辑位于：

po_file_search/indexer.py

表结构：

CREATE TABLE IF NOT EXISTS files (
    id INTEGER PRIMARY KEY,
    root_name TEXT NOT NULL,
    file_name TEXT NOT NULL,
    folder_path TEXT NOT NULL,
    full_path TEXT NOT NULL UNIQUE,
    extension TEXT NOT NULL,
    size INTEGER NOT NULL,
    modified_time REAL NOT NULL
);

字段说明：

写入规则

• 新文件：插入 files。
• 已存在文件：按 full_path 冲突更新元数据。
• 读取失败的文件：跳过。
• 隐藏文件：跳过。
• 忽略目录：由 config.json 的 ignored_dirs 控制。

删除清理

索引任务会记录本轮扫描看到的 full_path。扫描结束后，同一 root_name 下没有再次出现的旧记录会从 files 删除，并通过触发器同步清理 files_fts。

files_fts 虚拟表

表结构：

CREATE VIRTUAL TABLE IF NOT EXISTS files_fts USING fts5(
    file_name,
    folder_path,
    full_path UNINDEXED,
    content='files',
    content_rowid='id'
);

字段说明：

说明：

• files_fts 使用 files 作为内容表。
• content_rowid='id' 表示 FTS 记录与 files.id 对应。
• full_path UNINDEXED 表示不对完整路径做全文索引。
• smart 模式会优先使用 FTS 搜索。
• left_contains、right_contains、contains、exact 使用 files 表上的 LIKE 或等值匹配。

触发器

files_ai

files 插入后，同步插入 files_fts。

影响：保证新增文件可以被 FTS 搜索到。

files_ad

files 删除后，同步删除 files_fts。

影响：保证已删除文件不会继续出现在 FTS 搜索中。

files_au

files 更新后，先删除旧 FTS 记录，再写入新 FTS 记录。

影响：保证文件重命名、移动或修改元数据后，搜索结果同步更新。

audit_logs 表

表结构：

CREATE TABLE IF NOT EXISTS audit_logs (
    id INTEGER PRIMARY KEY,
    event_type TEXT NOT NULL,
    user_id TEXT,
    query TEXT,
    file_id INTEGER,
    recipient TEXT,
    channel TEXT,
    created_at REAL NOT NULL,
    metadata TEXT NOT NULL DEFAULT '{}'
);

字段说明：

download_tokens 表

表结构：

CREATE TABLE IF NOT EXISTS download_tokens (
    token TEXT PRIMARY KEY,
    file_id INTEGER NOT NULL,
    user_id TEXT,
    expire_at REAL NOT NULL,
    used_at REAL,
    created_at REAL NOT NULL,
    FOREIGN KEY(file_id) REFERENCES files(id)
);

字段说明：

下载校验规则：

• token 不存在：拒绝下载。
• expire_at > 0 且当前时间大于 expire_at：拒绝下载。
• expire_at = 0：不做时间过期校验。
• 文件不存在：拒绝下载。

字段影响范围

后续表设计

后续接入企业级权限后，建议增加用户、角色、目录授权等表。

permissions

建议字段：

索引同步配置说明

索引同步配置不存储在 SQLite 中，而是存储在 config.json：

"index": {
  "sync_interval_minutes": 60,
  "sync_on_startup": false
}

同步任务会更新 files 和 files_fts，并清理已经不存在的旧文件记录。

当前同步策略说明

当前暂行方案删除后台增量同步，只保留：

• 每天指定时间全量同步一次，默认 23:23。
• 管理员手动全量同步。

同步配置不存储在 SQLite 中，而是存储在 config.json：

"index": {
  "auto_full_sync_enabled": true,
  "full_sync_time": "23:23",
  "full_sync_on_startup": false
}

全量同步会更新 files 和 files_fts，并清理已经不存在的旧文件记录。

历史版本曾实验目录级增量同步，但实测瓶颈主要是 SMB 目录遍历，无变化增量同步耗时仍接近全量同步，因此暂不保留后台增量同步。