PlantAI-rag-new/tooling/crypto/client/README.md

PlantAI + RAG + QA 客户端部署包

本目录可以交给客户：不含供应商私钥和明文 K_master，只能采集指纹、配置 TPM、验证供应商签名、解封密钥和解密已授权资产。

客户专属配置 — install.env 变量详解

以下表格覆盖 install.env.example 中所有变量。每客户交付时据此填写 install.env。

变量	默认值	作用	影响路径	每客户必改	取值依据
PLANTAI_ROOT	/opt/PlantAI 或 $HOME/PlantAI	安装根目录，其下自动创建所有子目录	→ bin/ config/ assets/ data/ releases/ runtime/	通常不改	客户目录规范（如 /data/PlantAI）
RELEASE_SRC	./release	供应商发行包解压目录，安装时从此取 VERSION / app/ / assets/ / config/	→ $PLANTAI_ROOT/releases/<VERSION>/ 的源	不改	保留默认值
DEVICE_ID	$(hostname)	设备业务标识，写入许可证和日志，用于绑定设备身份	→ 出现在 license.json / 监控系统	必改	<客户缩写>-<机器角色>-<序号>，如 huanuo-web01
PLANTAI_WEB_PORT	7880	PlantAI Web 服务监听端口	→ 服务绑定端口	偶尔改	客户现有服务已占用时
RAG_PORT	7900	RAG 服务监听端口	→ 服务绑定端口	偶尔改	客户现有服务已占用时
PLANTAI_PYTHON	python3	PlantAI 后端使用的 Python 解释器路径	→ 执行 plantai_client.py / 后端进程	必改	问客户 conda 环境路径，如 /opt/miniconda3/envs/plantai/bin/python
RAG_PYTHON	同 PLANTAI_PYTHON	RAG 服务使用的 Python 解释器路径	→ 执行 start_qa_v1_0_0_7908.sh 等	必改	同上，通常与 PLANTAI_PYTHON 相同
NEO4J_URI	bolt://127.0.0.1:7687	Neo4j 图数据库连接地址	→ 应用通过此 URI 连接图数据库	通常改 IP	客户 Neo4j 实际主机 IP
NEO4J_USER	neo4j	Neo4j 用户名	→ 数据库连接认证	通常不改	除非客户改了用户名
NEO4J_PASSWORD	无	Neo4j 密码	→ 数据库连接认证	必改	客户管理员提供，禁用默认/空密码
QDRANT_URL	http://127.0.0.1:6333	Qdrant 向量数据库 HTTP 地址	→ 应用通过此 URL 读写向量	通常改 IP	客户 Qdrant 实际主机 IP
V15_QDRANT_COLLECTION	无	Qdrant 集合名，反映客户 + 数据版本	→ 读写此集合中的向量数据	必改	v15_<客户缩写>_<日期>，如 v15_huanuo_20260701
V15_BGE_MODEL	bge-m3:567m	Ollama 中的 embedding 模型名	→ 文本向量化使用的模型	不改	仅更换 embedding 策略时动
V15_OLLAMA_EMBED_URL	http://127.0.0.1:11434	Ollama 服务 URL	→ embedding API 调用地址	偶尔改	Ollama 不在本机时改 IP
INSTALL_USER_SERVICE	0	是否注册 systemd --user 自启服务	→ $HOME/.config/systemd/user/plantai.service	可选	客户要求开机自启时设 =1

安全要求：

• install.env 创建后执行 chmod 600
• 只写入真实密码到 install.env，install.env.example 永远只含占位符
• install.env 包含客户凭证，禁止提交到代码仓库或分享

交付结构

client/
  bin/plantai_client.py        # 客户端工具（采集指纹、TPM、解密）
  bin/PlantAI-launcher         # 启动器（解密代码运行资产到 tmpfs，启动三项目）
  install_plantai.sh           # 安装脚本（fingerprint / install / tpm2-setup）
  install.env.example          # ⬅ 客户据此创建 install.env（每客户不同）
  phase_d_tpm.sh               # 阶段 D：TPM 初始化 + 指纹采集（硬件）
  phase_d_swtpm_test.sh        # 软件 TPM 测试版本
  README.md                    # 本文件
  release/                     ⬅ 解压供应商发行包到这里
    VERSION
    app/PlantAI_compiled/
    app/RAG/
    app/QA/
    app/start_all.sh
    DELIVERY_MANIFEST.json
    assets/runtime-assets.enc
    assets/runtime-assets.manifest.json
    config/supplier_public_key.pem

另随包交付 plantai-rag-runtime-data-<VERSION>.tar 及对应 .sha256，其中包含 Qdrant、Neo4j 数据卷、BGE reranker 和本地 Ollama 模型 bge-m3:567m、qwen2.5:14b-instruct。数据库卷不放入 /dev/shm，避免约 70GB 持久数据占满内存文件系统。

install.env（含真实密码）由客户在部署时根据 install.env.example 创建，不包含在初始交付包中。

每客户修改指南（交付前必做）

install.env.example → install.env 按上方表格填写即可，此处只列 README 中需要客户化的文本：

位置	当前内容	改为
准备配置	tar -C release -xzf plantai-rag-release-1.0.0.tar.gz	版本号改为本次实际版本
导入授权	PROVISION_BUNDLE=/path/to/plantai-provision-DEVICE.tar.gz	DEVICE 替换为 install.env 中 DEVICE_ID
正式启动	PLANTAI_ROOT=/opt/PlantAI	改为 install.env 中 PLANTAI_ROOT 值
外部服务	ollama pull qwen3:0.6b	模型版本按本次实际版本改

另在 README 末尾追加客户档案：

## 本次交付记录
- **客户名称**:
- **DEVICE_ID**:
- **发行包版本**:
- **交付日期**:
- **供应商负责人**:

交付前 checklist

• client/ 中删除了 install.env（只留 .example）
• client/ 中删除了 package_client.sh
• install.env.example 中无真实密码
• 发行包 plantai-rag-release-<VERSION>.tar.gz 已单独发给客户

1. 准备配置与发行包

cp install.env.example install.env
chmod 600 install.env
mkdir -p release
tar -C release -xzf plantai-rag-release-1.0.0.tar.gz
sha256sum -c release/SHA256SUMS

在 install.env 设置安装路径、Python 解释器以及 Neo4j/Qdrant/Ollama 变量。真实密码不要写入 install.env.example。

2. TPM 2.0 初始化（每台目标机只做一次）

推荐直接执行阶段 D 一键脚本：

./phase_d_tpm.sh

它会依次检查 TPM、复用或创建 TPM 密钥、采集指纹，并拒绝缺少 TPM 公钥/attestation 的弱指纹。

下面是等价的手工命令，仅用于排错：

ls -l /dev/tpmrm0 /dev/tpm0
tpm2_getrandom 8
./install_plantai.sh tpm2-setup

不要删除 $PLANTAI_ROOT/config/tpm/，也不要反复运行初始化。更换 TPM/主板或删除持久化 TPM key 后，旧授权将无法解封。

3. 采集指纹并交给供应商

无真实 TPM 时的软件测试入口

./phase_d_swtpm_test.sh

该入口会使用端口 2321/2322 的 swtpm，自动运行阶段 D，并在指纹中写入 test_only_swtpm=true。它只能验证流程，不能提供硬件级保护。阶段 E 测试签发必须显式设置 ALLOW_SOFTWARE_TPM_TEST=1。

./install_plantai.sh fingerprint

将 $PLANTAI_ROOT/config/device_fingerprint.json 发给供应商。生产授权必须包含 tpm_public_key 和 attestation；只有普通 DMI/磁盘信息的指纹不能提供 TPM 硬件绑定。

4. 导入授权并安装

PROVISION_BUNDLE=/path/to/plantai-provision-DEVICE.tar.gz ./install_plantai.sh install

校验并展开随包交付的持久化运行数据：

sha256sum -c plantai-rag-runtime-data-1.0.0.tar.sha256
mkdir -p "${PLANTAI_ROOT:-/opt/PlantAI}/data"
tar -C "${PLANTAI_ROOT:-/opt/PlantAI}/data" \
  -xf plantai-rag-runtime-data-1.0.0.tar

安装结束会执行 PlantAI-launcher --check-only：验证许可证签名、硬件匹配、TPM 解封、资产清单和 AES-GCM 解密。任何一步失败都不应启动服务。

正式启动：

PLANTAI_ROOT=/opt/PlantAI /opt/PlantAI/bin/PlantAI-launcher

启动器默认把加密的 PlantAI/RAG models/prompts 解密到 /dev/shm；QA 的 Qdrant、Neo4j 与大模型保留在 $PLANTAI_ROOT/data/runtime-assets。客户启动 脚本会依次检查/启动 Qdrant、Neo4j、独立端口的本地 Ollama、QA、RAG、 PlantAI。不要设置 PLANTAI_PERSIST_RUNTIME=1，除非明确接受代码运行资产明文落盘风险。

5. 依赖与端口

客户机需预装 Docker 与 Ollama。启动脚本会使用交付数据自动拉起依赖，无需 联网拉取模型。默认端口如下：

curl -fsS http://127.0.0.1:16333/collections  # Qdrant
curl -fsS http://127.0.0.1:17474              # Neo4j HTTP
curl -fsS http://127.0.0.1:11435/api/tags     # 交付专用 Ollama
curl -fsS http://127.0.0.1:7925/api/v1/qa-v1-1-73/health
curl -fsS http://127.0.0.1:7900/health
curl -fsS http://127.0.0.1:7880/

安全边界

• .so 是逆向加固，不是密码学加密。
• TPM 保护的是解封 K_master 的能力；私钥从不离开 TPM。
• 许可证和 asset.key.enc 通过 SHA-256 绑定，不能跨设备混用。
• 客户端没有生成供应商密钥、自签许可证或重新加密资产的命令。
• 供应商的 plantai_server_package、私钥、口令文件、master_keys/ 永不进入 client。