business-assistant/docs/deployment.md

部署操作指南

麒麟 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 [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 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	六大服务板块

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路径。失败时保留当前清单，远端可能留下未发布的新集合；修复后可重跑。切换目录失败会尝试恢复旧目录；机器在两次目录重命名之间异常断电时，应从保留的旧目录恢复后重试。不要并行运行知识规整、摘要或手工替换文件。

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

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