部署操作指南

麒麟 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 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和校验文件上传至服务器同一目录，进入该目录后执行：

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 /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检查，再恢复知识和启动：

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 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不下载依赖或模型；离线只指安装资源离线，业务接口仍需连通。内存隔离见内存安全说明，知识恢复细节见知识入库说明。

deployment.md 5.4 KB Historie Surový