目标:一个案件 = 一个目录;程序资产与业务数据严格分离;数据库里只存相对路径,换存储根不需要改库。
<项目/部署根>/
└── qingjian/
├── system/ # 程序资产与系统状态(升级/备份时可整体替换,不含业务数据)
└── data/ # 业务数据(唯一需要备份的目录)
qingjian。storage.local.root-path 配置,默认 ./qingjian/data;相对路径按项目根
(PathConst.ROOT_PATH)解析,不是 JVM 的 user.dir,所以 IDE 从 ai-server/ 启动也不会写出第二套数据。qingjian/system 不走配置,由 PathConst.SYSTEM_PATH 固定。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 清理)
{业务ID}_{安全原名}(导入、附件、知识库)或
{uuid}.{ext}(EDS 媒体)或 {域}_{工具}_{时间戳}_{uuid8}.{ext}(AI 工具产物)。/),读取时由 StorageLayout.resolve(String) 还原;
StorageLayout.relative(Path) 负责写库前的转换。StorageLayout.safeName(...):去路径段、过滤 \/:*?"<>| 与控制字符、限制长度。{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 为准。caseId 与 packageId,删案/删包可整目录清理,不同案件同采集编号不会撞目录。data/cases/{caseId} + PG/ES/Redis 清理。| 场景 | 行为 |
|---|---|
| 建案 | 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,脚本会因目标非空而跳过迁移。
storage:
local:
root-path: "${STORAGE_LOCAL_ROOT_PATH:./qingjian/data}"
base-url: "${STORAGE_LOCAL_BASE_URL:http://localhost:8980/js/a}"
/files/** 映射到数据根(LocalFileResourceConfig)。/files/cases/*/materials/*/media/**(浏览器 <img>/<video> 不能带 x-token)。qingjian/data;qingjian/system 属于安装资产,按版本随程序发布。qingjian/data 即可,库里的路径都是相对的。QingJian/workspace、QingJian/chat-attachments、.agentscope、data/files;
确认不再需要后运行 deploy/storage-legacy-clean.sh --yes 清理。