storage-layout.md 6.7 KB

文件存储布局(qingjian/system + qingjian/data)

目标:一个案件 = 一个目录;程序资产与业务数据严格分离;数据库里只存相对路径,换存储根不需要改库。

1. 根目录

<项目/部署根>/
└── qingjian/
    ├── system/     # 程序资产与系统状态(升级/备份时可整体替换,不含业务数据)
    └── data/       # 业务数据(唯一需要备份的目录)
  • 根目录名统一小写 qingjian。
  • 业务数据根由 storage.local.root-path 配置,默认 ./qingjian/data;相对路径按项目根 (PathConst.ROOT_PATH)解析,不是 JVM 的 user.dir,所以 IDE 从 ai-server/ 启动也不会写出第二套数据。
  • qingjian/system 不走配置,由 PathConst.SYSTEM_PATH 固定。

2. 完整目录树

qingjian/
├── system/
│   ├── conf/                         # c5e503ad.json / a4961dbp.json / config.yml /
│   │                                 # eds_table_columns.tsv / 基站导入模板.xls
│   ├── db/5w8mf4kf                   # 基础案件库模板(保持原名)
│   ├── db/plat、db/temp              # 平台库 / 全局临时库
│   ├── license/                      # license.xlts、regInfo
│   ├── rocksdb/d5e03ad1、uy76tkp8    # 银行卡 BIN、运营商、RogueMap
│   ├── libs/cell/                    # libCell.dll/.so、BSSinfo_sc.bin
│   ├── libs/7zip/                    # 7z.exe / 7zz
│   ├── native/                       # OpenCV 原生库
│   ├── models/bge-m3、models/vosk-model
│   ├── tools/ffmpeg/
│   ├── extension/
│   └── lock.lck
└── data/
    ├── cases/{caseId}/
    │   ├── case.json                 # 案件快照:id/name/ownerId/createdAt/dbPath/schemaVersion
    │   ├── db/case.duckdb            # 案件 DuckDB(+ .wal)
    │   ├── imports/{batchId}/        # 清洗导入原件
    │   │   └── {uuid}{ext}
    │   ├── materials/{packageId}/    # 电子数据包
    │   │   ├── {uuid}.zip
    │   │   ├── extracted/            # 解压临时,导入后删除
    │   │   └── media/{采集编号MD5}/{uuid}.{ext}
    │   ├── attachments/              # 案件级附件(人员头像等)
    │   │   └── {uuid}{ext}
    │   ├── knowledge/                # 预留:案件级知识库
    │   ├── ai/
    │   │   ├── artifacts/            # 工具 CSV、agent_file_*
    │   │   ├── sessions/{sessionId}/attachments/
    │   │   ├── agents/{agentRowId}/  # harness 工作区(sessions/memory/tool files)
    │   │   ├── insight/              # 研判 agent 工作区
    │   │   ├── python/
    │   │   │   ├── out/{execId}/     # Python 产物(图片/HTML/Word/PDF/CSV)
    │   │   │   ├── sandbox/{execId}/ # 运行时沙箱,执行完删除
    │   │   │   ├── snapshot/case.duckdb
    │   │   │   └── mpl/matplotlibrc
    │   │   └── graph/{graphHisId}_{名称}.json
    │   └── tmp/                      # 案件级临时
    ├── users/{userId}/knowledge/{kbId}/
    │   └── docs/{uuid}{ext}          # 原件(保持原 UUID 命名逻辑)
    │       └── {uuid}.txt            # Tika 全文 sidecar(同目录、同名换扩展名)
    ├── index/cases.tsv               # caseId / name / ownerId / createdAt / dbPath
    └── tmp/                          # 全局临时(24h 清理)

3. 命名与路径规则

  1. 目录名固定英文小写;文件名为 {业务ID}_{安全原名}(导入、附件、知识库)或 {uuid}.{ext}(EDS 媒体)或 {域}_{工具}_{时间戳}_{uuid8}.{ext}(AI 工具产物)。
  2. 数据库只存相对数据根的路径(POSIX /),读取时由 StorageLayout.resolve(String) 还原; StorageLayout.relative(Path) 负责写库前的转换。
  3. 用户输入的文件名统一经过 StorageLayout.safeName(...):去路径段、过滤 \/:*?"<>| 与控制字符、限制长度。
  4. 磁盘统一 UUID 重命名,展示用源文件名:所有上传文件落盘名为 {uuid}{ext} (清洗导入、EDS 包、对话附件、知识库文档、EDS 媒体、人员头像一致); 数据库里的 file_info.file_name、chat_attachment.file_name、knowledge_doc.file_name、 eds_material.file_name 保存源文件名,列表与下载展示源文件名。 人员头像的 URL 中就是 UUID 文件名;人员与文件的关联以 person_basic_info.photograph 为准。
  5. EDS 媒体路径必须带 caseId 与 packageId,删案/删包可整目录清理,不同案件同采集编号不会撞目录。
  6. 案件是唯一物理隔离单元:删案 = 删除 data/cases/{caseId} + PG/ES/Redis 清理。

4. 生命周期

场景 行为
建案 StorageLayout.initCase(caseId) 建骨架;复制 system/db/5w8mf4kf 到 db/case.duckdb;写 case.json 与 data/index/cases.tsv
改名 更新 case.json 与索引行
删案 先清 PG/ES/Redis,再 deleteCase(caseId) 整目录删除
删会话 删除 ai/sessions/{sessionId} 与 Redis slot
Python 执行 sandbox/{execId} 执行完删除;产物移入 out/{execId}
定时清理 data/tmp、cases/{caseId}/tmp、ai/python/sandbox 保留 24h;artifact.retain-days > 0 时按天清理全部产物
首次部署 运行 deploy/storage-layout-init.sh(Windows 用 .ps1)把旧 qingjian/{conf,db,license,...} 迁入 system/

升级顺序:先停服 → 运行 deploy/storage-layout-init(建议先 --dry-run)→ 再启动新版本。 如果先启动,StorageBootstrap 会先建出空的 system/ 子目录/空 RocksDB,脚本会因目标非空而跳过迁移。

5. 配置与访问

storage:
  local:
    root-path: "${STORAGE_LOCAL_ROOT_PATH:./qingjian/data}"
    base-url: "${STORAGE_LOCAL_BASE_URL:http://localhost:8980/js/a}"
  • /files/** 映射到数据根(LocalFileResourceConfig)。
  • EDS 媒体目录免登录:/files/cases/*/materials/*/media/**(浏览器 <img>/<video> 不能带 x-token)。
  • 其余文件(案件库、导入原件、AI 产物)仍要求登录。

6. 备份与迁移

  • 业务备份只备份 qingjian/data;qingjian/system 属于安装资产,按版本随程序发布。
  • 迁移到新机器:拷贝 qingjian/data 即可,库里的路径都是相对的。
  • 历史数据:本方案不自动迁移旧 QingJian/workspace、QingJian/chat-attachments、.agentscope、data/files; 确认不再需要后运行 deploy/storage-legacy-clean.sh --yes 清理。