# 部署操作指南

## 麒麟 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` | 校验包内知识快照并恢复到Milvus，检查发布清单；不启动API。首次部署前执行，已有发布清单时`deploy`也可自动导入。 |
| `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本身就绪，不表示所有外部依赖实时可用。

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