# 文件存储布局(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}/ # 清洗导入原件 │ │ └── {原名}_{雪花id}{ext} │ ├── materials/{packageId}/ # 电子数据包 │ │ ├── {原名}_{雪花id}.zip │ │ ├── extracted/ # 解压临时,导入后删除 │ │ └── media/{采集编号MD5}/{uuid}.{ext} │ ├── attachments/ # 案件级附件(人员头像等) │ │ └── {原名}_{雪花id}{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/{原名}_{雪花id}{ext} # 原件 │ └── {原名}_{雪花id}.txt # Tika 全文 sidecar(同目录、同名换扩展名) ├── index/cases.tsv # caseId / name / ownerId / createdAt / dbPath └── tmp/ # 全局临时(24h 清理) ``` ## 3. 命名与路径规则 1. **目录名固定英文小写**;上传文件名为 `{原名}_{雪花id}{ext}`(清洗导入、EDS 包、对话附件、 知识库文档、人员头像统一);EDS 包内解压出的媒体仍为 `{uuid}.{ext}`(包内原始文件名 可能乱码,且不是用户直接上传);AI 工具产物为 `{域}_{工具}_{时间戳}_{uuid8}.{ext}`。 2. **数据库只存相对数据根的路径**(POSIX `/`),读取时由 `StorageLayout.resolve(String)` 还原; `StorageLayout.relative(Path)` 负责写库前的转换。 3. 用户输入的文件名统一经过 `StorageLayout.safeName(...)`:去路径段、过滤 `\/:*?"<>|` 与控制字符、限制长度。 4. **磁盘统一重命名为 `{原名}_{雪花id}{ext}`,展示用源文件名**:雪花 id 保证唯一, 原文件名保留可读性;数据库里的 `file_info.file_name`、`chat_attachment.file_name`、 `knowledge_doc.file_name`、`eds_material.file_name` 保存**源文件名**,列表与下载展示源文件名。 人员头像的 URL 中就是重命名后的文件名;人员与文件的关联以 `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. 配置与访问 ```yaml 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/**`(浏览器 `/