jerryandClaude Fable 5
27946edc2b
- legacy_plantai_server_package/: phase_a–f + compile_* + bin/plantai_admin.py + tools/(audit/elf_visibility/smoke/build_delivery_manifest) 完整基线 - legacy_docker_packager/: protected 形态参考 - crypto/client/: plantai_core.py(AES-GCM 原语) + install_plantai.sh 参考 - secrets/provision 严格排除(gitignore),入 git 前已脱敏清理 - LEGACY_MAPPING.md 记录源与改造方向 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
187 lines
9.0 KiB
Markdown
187 lines
9.0 KiB
Markdown
# 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` 包含客户凭证，禁止提交到代码仓库或分享
|
||
|
||
## 交付结构
|
||
|
||
```text
|
||
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 末尾追加客户档案：
|
||
```markdown
|
||
## 本次交付记录
|
||
- **客户名称**:
|
||
- **DEVICE_ID**:
|
||
- **发行包版本**:
|
||
- **交付日期**:
|
||
- **供应商负责人**:
|
||
```
|
||
|
||
### 交付前 checklist
|
||
|
||
- [ ] `client/` 中删除了 `install.env`（只留 `.example`）
|
||
- [ ] `client/` 中删除了 `package_client.sh`
|
||
- [ ] `install.env.example` 中无真实密码
|
||
- [ ] 发行包 `plantai-rag-release-<VERSION>.tar.gz` 已单独发给客户
|
||
|
||
## 1. 准备配置与发行包
|
||
|
||
```bash
|
||
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 一键脚本：
|
||
|
||
```bash
|
||
./phase_d_tpm.sh
|
||
```
|
||
|
||
它会依次检查 TPM、复用或创建 TPM 密钥、采集指纹，并拒绝缺少 TPM 公钥/attestation 的弱指纹。
|
||
|
||
下面是等价的手工命令，仅用于排错：
|
||
|
||
```bash
|
||
ls -l /dev/tpmrm0 /dev/tpm0
|
||
tpm2_getrandom 8
|
||
./install_plantai.sh tpm2-setup
|
||
```
|
||
|
||
不要删除 `$PLANTAI_ROOT/config/tpm/`，也不要反复运行初始化。更换 TPM/主板或删除持久化 TPM key 后，旧授权将无法解封。
|
||
|
||
## 3. 采集指纹并交给供应商
|
||
|
||
### 无真实 TPM 时的软件测试入口
|
||
|
||
```bash
|
||
./phase_d_swtpm_test.sh
|
||
```
|
||
|
||
该入口会使用端口 2321/2322 的 swtpm，自动运行阶段 D，并在指纹中写入 `test_only_swtpm=true`。它只能验证流程，不能提供硬件级保护。阶段 E 测试签发必须显式设置 `ALLOW_SOFTWARE_TPM_TEST=1`。
|
||
|
||
```bash
|
||
./install_plantai.sh fingerprint
|
||
```
|
||
|
||
将 `$PLANTAI_ROOT/config/device_fingerprint.json` 发给供应商。生产授权必须包含 `tpm_public_key` 和 `attestation`；只有普通 DMI/磁盘信息的指纹不能提供 TPM 硬件绑定。
|
||
|
||
## 4. 导入授权并安装
|
||
|
||
```bash
|
||
PROVISION_BUNDLE=/path/to/plantai-provision-DEVICE.tar.gz ./install_plantai.sh install
|
||
```
|
||
|
||
校验并展开随包交付的持久化运行数据：
|
||
|
||
```bash
|
||
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 解密。任何一步失败都不应启动服务。
|
||
|
||
正式启动：
|
||
|
||
```bash
|
||
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。启动脚本会使用交付数据自动拉起依赖，无需
|
||
联网拉取模型。默认端口如下：
|
||
|
||
```bash
|
||
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。
|