# 部署操作指南

## 麒麟 V10 断网部署（ARM64 / CPU）

交付`offline-release-kylin-20260929-r3.zip`（项目、`.env`、知识和模型，**仅限受控传输**）、`offline-env-arm64-cpu-20260929-r2.zip`（uv 和依赖）及对应的`offline-checksums-20260929-r3.txt`。不要混用旧项目包。目标机需先安装标准 CPython 3.14；目前尚未在目标机完成安装验证。

### 1. 采集环境

Python 安装后，将`scripts/collect-offline-env.sh`单独传至服务器并运行：

```sh
sh collect-offline-env.sh > offline-env.txt 2>&1
```

把`offline-env.txt`发回。确认输出为`aarch64`、glibc不低于2.28、Python 3.14且`pidfd: available`；任一项不符，先暂停部署。若脚本退出1，仍请发回输出。当前只准备CPU依赖，不使用CUDA。

### 2. 校验并解包

将两个ZIP和校验文件上传至服务器同一目录，进入该目录后执行：

```sh
sha256sum -c offline-checksums-20260929-r3.txt
python3.14 offline-release-kylin-20260929-r3.zip verify offline-release-kylin-20260929-r3.zip
python3.14 offline-release-kylin-20260929-r3.zip extract offline-release-kylin-20260929-r3.zip /srv/business-assistant
python3.14 -m zipfile -t offline-env-arm64-cpu-20260929-r2.zip
python3.14 -m zipfile -e offline-env-arm64-cpu-20260929-r2.zip /srv/business-assistant/offline-env
```

使用全新部署目录；解包器拒绝覆盖同名文件。任一步失败即停止，保留报错供补包。

### 3. 安装环境

在项目`.env`中将`EMBEDDING_DEVICE`设为`cpu`，并核对各服务地址；DMS使用`DMS_BASE_URL`的主机、`AUTH_PORT`登录取token、`DMS_PORT`访问数据。勿把凭据写入日志。然后执行：

```sh
sh /srv/business-assistant/offline-env/install_offline_env.sh /srv/business-assistant
```

Python 不在`PATH`时，在命令前加`PYTHON_BIN=/绝对路径/python3.14`。安装脚本只用包内wheel，创建全新的`.venv`，并检查依赖和本地模型；已有`.venv`时会停止，不会覆盖。

### 4. 政务网内检查DMS、恢复知识并启动

确认`pidfd: available`、`.env`配置及 Milvus/Redis 等服务可达后，在可访问政务网的部署机先执行只读DMS检查，再恢复知识和启动：

```sh
cd /srv/business-assistant
sh deploy-offline.sh check-dms
sh deploy-offline.sh import-knowledge
sh deploy-offline.sh deploy
sh deploy-offline.sh status
sh deploy-offline.sh check-milvus
sh deploy-offline.sh check-redis
sh deploy-offline.sh check-deepseek
sh deploy-offline.sh check-qcc "用于联调的企业完整名称"
```

上述命令各自的作用如下；除`deploy`外，单项诊断不会启动或重启API。

| 命令 | 作用与结果 |
| --- | --- |
| `check-dms` | 只读登录并核验五个DMS栏目的ID、名称、父栏目和模型字段；不读取业务记录。失败要区分网络、认证、权限和模型不匹配。 |
| `import-knowledge [ZIP路径 [库名]]` | 校验并导入指定全量包或单库包，回读成功后切换清单并备份旧目录；不启动或重启API。不传路径时读取项目下`output/knowledge-snapshot.zip`。 |
| `deploy` | 检查现有`.venv`、本地模型及知识清单；准备完成后停止本项目旧API并启动新API，等待`/health`就绪。首次部署或需要完整部署检查时使用。 |
| `status` | 显示本项目API进程、健康状态和日志路径；进程不存在或不健康时返回非零退出码。 |
| `check-milvus` | 只读核对发布清单对应的Milvus六库、集合和记录数量。 |
| `check-redis` | 对当前Redis执行一次PING并关闭连接。 |
| `check-deepseek` | 发起一次很短的真实模型请求，验证接口可调用；可能产生费用。 |
| `check-qcc "企业完整名称"` | 用指定名称验证企查查886搜索；仅有唯一精确匹配时继续验证410详情和1001荣誉，可能产生费用。 |

`check-dms`先通过认证端口取token，再只读核验配置中五个栏目的名称、父栏目和字段类型；诉求词3043与企业基础信息3037目前有数据，其他栏目无数据不影响元数据检查。成功须退出码为0且报告两组均为`usable`；失败时先按`dms_transport_failed`、`dms_login_failed`、`dms_permission_denied`、`dms_column_mismatch`或`dms_schema_mismatch`区分网络、认证、权限及模型问题。token失效后客户端自动重新登录并最多重试一次。当前开发机无法访问政务网，真实DMS连接仍待本步完成。

### 5. 后续启动、重启与停止

首次部署已由`deploy`启动服务。日常操作在项目目录执行：

```sh
sh deploy-offline.sh start    # 服务已停止时启动；已健康运行则直接返回
sh deploy-offline.sh restart  # 使用当前代码和现有.venv停止并重新启动API
sh deploy-offline.sh status   # 查看进程和健康状态
sh deploy-offline.sh stop     # 停止本项目API
```

`start`只启动服务，不导入知识；`restart`会先检查环境和配置，再停止本项目API并启动，不重新导入知识。修改代码或`.env`后使用`restart`使新进程生效；更新知识则先运行`import-knowledge`，再`restart`。`status`的`healthy: true`表示API本身就绪，不表示所有外部依赖实时可用。

### 6. 更新全部知识或指定知识库

知识ZIP必须由本项目的`portable export`生成，包含原文、摘要、向量与校验清单；普通JSON文件压缩包不能直接导入。库名使用下表短名称，必须与单库包内声明一致。单库包是该库的**完整版本**，导入后该库只包含包内记录；不执行条目级追加合并，其他五库保持原有内容与集合。

| 库名 | 内容 |
| --- | --- |
| `policy` | 惠企政策 |
| `finance` | 金融产品 |
| `qa` | 问答 |
| `article` | 文章、法规及规范性文件 |
| `service_guide` | 办事指南 |
| `service_catalog` | 六大服务板块 |

```sh
cd /srv/business-assistant
# 全量更新：不写库名；首次部署也用此方式
sh deploy-offline.sh import-knowledge /srv/transfer/knowledge-all.zip

# 只更新文章库：传文章库完整包及article，已有全量知识快照时使用
sh deploy-offline.sh import-knowledge /srv/transfer/knowledge-article.zip article

# 两种更新方式择一执行成功后，核对六库，再按维护窗口重启
sh deploy-offline.sh check-milvus
sh deploy-offline.sh restart
sh deploy-offline.sh status
```

支持绝对路径及相对于**执行命令时所在目录**的相对路径；含空格的路径需加引号。首次初始化需导入全量包，再进行单库更新。全量包不能带库名，单库包必须带对应库名；错包、错库、模型不匹配或校验失败会明确停止。仍支持省略ZIP路径的旧命令，但不会自动扫描或选择最新ZIP。

导入不调用摘要服务、不生成新向量，使用包内已生成的向量。全量更新允许替换现有不同版本；单库更新要求与其他库使用相同模型及索引契约。写入新集合并回读全部导入记录、向量后才切换本地清单。旧Milvus集合不删除，旧本地目录保存在`knowledge/prepared.previous-<唯一编号>`，成功输出`backup`路径。失败时保留当前清单，远端可能留下未发布的新集合；修复后可重跑。切换目录失败会尝试恢复旧目录；机器在两次目录重命名之间异常断电时，应从保留的旧目录恢复后重试。不要并行运行知识规整、摘要或手工替换文件。

制作后续单库包时，在保存最新知识的机器上执行：

```sh
.venv/bin/python -m src.step2_knowledge_ingest.portable export /路径/article新版本.zip --database article
.venv/bin/python -m src.step2_knowledge_ingest.portable verify /路径/article新版本.zip
```

省略`--database`导出全量包；旧全量ZIP格式继续兼容。任何导入都不会自动重启在线服务，文件更新不代表目标麒麟服务器已完成联调。

每条诊断独立运行；失败时保留脱敏输出和退出码，不继续宣称部署成功。`deploy-offline.sh`不下载依赖或模型；离线只指安装资源离线，业务接口仍需连通。内存隔离见[内存安全说明](memory-safety.md)，知识恢复细节见[知识入库说明](../knowledge/ingestion.md)。