# KB 加密与打包操作指南(agent 专用)

> 适用时机:**数据库定版后**执行。定版前数据库持续增长,不做真实加密。
> 本指南对应方案 §五(Knowledge 设计);工具均已通过加密往返验证(2026-08-31)。

## 一、工具清单(tooling/)

| 工具 | 作用 |
|---|---|
| `kb/encrypt_kb.sh` | 一键:快照/冷拷 → 断言加密 → 单一 tar → sha256 → 计数清单 |
| `kb/kb_encrypt_backfill.py` | AES-256-GCM 加密器,两种模式(见下) |
| `crypto/init_keys.sh` | 生成 KB 主密钥(已生成:build/2.0.0/kb.key,勿重复生成) |

## 二、加密语义(已确认)

| 数据 | 处理 | 原因 |
|---|---|---|
| Qdrant 向量(70G) | **明文**,snapshot API 导出 | 检索数学需要 |
| raw_export.jsonl(9.5G) | `properties_json` 字段 AES-256-GCM | 断言全文 |
| assertions.parquet(2.7G) | 整文件 AES-256-GCM(`--file-encrypt`) | 断言导出 |
| Neo4j normalized data(8.2G) | **明文冷拷**(frozen 目录) | 存储引擎限制;08-24 起无写入 |
| registry JSONL(17M) | 明文(仅论文元数据,无断言文本) | 无敏感字段 |

**加密格式**:`enc:v1:<b64 nonce>:<b64 ciphertext>`(字段级=字符串,文件级=二进制)。解密见文末。

## 三、执行步骤(数据库定版后)

```bash
cd /home/xzq/5090/teamWorkspace/zh/PlantAI-rag-new

# 0. 预检:磁盘余量 ≥200G;密钥存在
df -h /home | tail -1
ls -la tooling/build/2.0.0/kb.key   # 若无 → VERSION=2.0.0 bash tooling/crypto/init_keys.sh

# 1. 一键执行(全部步骤,耗时约 1–2 小时,建议 setsid 后台)
bash tooling/kb/encrypt_kb.sh 2.0.0
```

### 分步执行(排查问题时)

```bash
# ① Qdrant 快照(70G,约 20–60 分钟;POST 后轮询容器目录)
curl -X POST http://127.0.0.1:27333/collections/plant_srt_pc2025_v3_20260817_normalized/snapshots
# 完成后从容器拷贝(文件出现在 /qdrant/snapshots/<collection>/)
docker cp <qdrant容器>:/qdrant/snapshots/plant_srt_pc2025_v3_20260817_normalized/<name>.snapshot tooling/build/2.0.0/knowledge-stage/

# ② Neo4j 冷拷(frozen 目录,rsync 8.2G)
# ③ 断言导出加密(9.5G jsonl 字段级 + 2.7G parquet 整文件)
python3 tooling/kb/kb_encrypt_backfill.py \
  --input <raw_export.jsonl> \
  --output tooling/build/2.0.0/knowledge-stage/assertions/raw_export.enc.jsonl \
  --key-file tooling/build/2.0.0/kb.key --fields properties_json
python3 tooling/kb/kb_encrypt_backfill.py \
  --input <assertions.parquet> \
  --output tooling/build/2.0.0/knowledge-stage/assertions/assertions.parquet.enc \
  --key-file tooling/build/2.0.0/kb.key --file-encrypt

# ④ 单一 tar(不压缩)+ sha256
tar -C tooling/build/2.0.0/knowledge-stage -cf tooling/build/2.0.0/knowledge-2.0.0.tar .
sha256sum tooling/build/2.0.0/knowledge-2.0.0.tar > tooling/build/2.0.0/knowledge-2.0.0.tar.sha256
```

## 四、关键约束(踩坑记录)

1. **绝不 rsync 活动挂载卷**——Qdrant 70G 存储是 27333 容器在线库,直拷会撕裂数据。必须走 snapshot API。Neo4j 5.15 community **不支持在线 dump**(`neo4j-admin database dump` 拒绝运行库),只能用 frozen 目录冷拷(08-24 后无写入已核实)。
2. **canonical 库(18788, 14G)不在 KB 交付内**——它是 SDK KG 浏览依赖,不是 QA 检索链(NEO4J_URI=19788)。
3. **kb.key 权限 600,离线备份**——丢失无法解密已交付包。密钥在 `tooling/build/2.0.0/kb.key`(gitignored)。
4. **计数校验**:解密安装后由 QA backend_guard 验证,期望值见 `tooling/build/2.0.0/EXPECTED_COUNTS.json`(papers=31207 / canon_entities=3820996 / asserts=8246875 / norm_entities=6316654 / points=12963472)。
5. **registry JSONL 顶层无断言文本字段**(实测:paper_id/title/doi/pmid/pmcid…),断言文本在 Qdrant payload(evidence/best_evidence)与 staging 的 raw_export.jsonl——加密目标已按实测调整。

## 五、解密验证(交付后 QA)

```python
import base64, json
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
key = base64.b64decode(open("tooling/build/2.0.0/kb.key").read().strip())
aesgcm = AESGCM(key)
# 字段级
enc = rec["properties_json"]; _, n, ct = enc.split(":")
pt = aesgcm.decrypt(base64.b64decode(n), base64.b64decode(ct), None).decode()
# 文件级
blob = open("assertions.parquet.enc","rb").read(); _, n, ct = blob.split(b":")
pt = aesgcm.decrypt(base64.b64decode(n), base64.b64decode(ct), None)
```

## 六、定版后接入打包流水线

`encrypt_kb.sh` 已预留为 `tooling/build_all.sh` 的子步骤(方案 §六):编译 SDK+3 agent → 审计 → 冒烟 → **encrypt_kb.sh** → assemble → SHA256SUMS → 泄露检查。定版后只需在 build_all.sh 中启用该步骤(当前标注 SKIP_KB=1 占位)。