技能｜<知识库系统>全量迁移部署SOP

适用场景

把办公室开发机（本机 <项目根目录>）上的「<我的知识库>工作台」（FastAPI + PyInstaller 桌面壳）全量迁移到家里另一台电脑。触发词：迁移、部署、换电脑、全量打包、离线交付、搬家。敏感红线：全程本地，严禁联网/上云。

敏感红线（最高优先级）

全程本地复制/压缩，严禁任何联网、上传公有云、外网操作。产物仅落 <项目根目录>\PC服务器端\知识库系统操作手册\。

操作步骤

1. 组装全量包目录 kb_full/：
   - src/ ← 复制 <运行时目录>\<应用>\ 全部源代码（.py/.html/.json 等），排除 dist/、__pycache__/、*.pyc、PyInstaller 构建垃圾（build*、dist_new/v2/v3、_bw/_bd、webview_profile）及编译二进制（*.exe/*.pkg/*.pyd/*.dll/*.toc 等）；保留 installer/*.nsi。
   - data/知识库根/ ← 复制 知识库根\ 全量数据。
   - scripts/ ← 复制 程序源代码\scripts\。
   - 根目录关键配置复制到 kb_full\ 根：wechat_queue.json、_ms.json、wb_cookies.txt、知识库目录_<我的知识库>.xlsx、start_workbench.bat。
   - dist/ ← 复用已编译产物 <运行时目录>\<应用>\dist\<应用>\（含 <应用>.exe）。dist 完整则直接复制，不重打包；缺失才 PyInstaller 重建（pyinstaller --onefile --name <应用> app.py 兜底）。
2. 写 README_迁移部署.md：含新机环境要求（Windows 10+/可选 Python 3.11）、解压即跑（dist\exe 双击）、源码运行（python app.py）、本地 LLM 配置（<本机地址>:8080 Qwen3-30B）、登录默认密码 <请自设口令>（建议改）、常见故障排查。
3. 压缩：优先 7z；无则 Python zipfile（ZIP_DEFLATED），非 ASCII 文件名自动加 EFS（UTF-8）标志。产出 <知识库系统>全量迁移包V1.0.zip。
4. 更新四份工作手册：改 build_manuals.py（修 BASE 偏差、版本号 V1.1、插入「X、开发机→家用机 全量迁移与部署」章节：①为何迁移 ②包清单 ③解压安装 ④启动 ⑤本地LLM ⑥登录改密 ⑦常见问题），重跑生成四份 V1.1，不覆盖 V1.0。
5. 最终交付包：把「安装包 zip + 四份 V1.1 手册 + <应用> 源代码」再压 知识库系统迁移交付包V1.0.zip。
6. 删除中间目录：分批改删（每批 ≤40 文件，规避 rm -rf 沙箱批量删除拦截）+ 清空空目录；或送回收站（见注意边界）。

注意边界

• 敏感红线：仅本机、零联网；压缩复制全程本地。
• build_manuals.py（已归位 程序源代码\scripts）的 BASE 旧值曾指向不存在的 <项目根目录>\知识库系统文档，现已改为 PC服务器端\知识库系统操作手册，否则 V1.1 落错处。
• src 必须排除 PyInstaller 构建临时目录与编译二进制，否则包从 2MB 膨胀到 53MB+（混进 health_check.exe 等）。
• 版本规则：文件名带版本号、内容不写版本说明文字；每次修订另存新文件、不覆盖原文件。

反例避雷

关联笔记

• 相关笔记：[[技能｜看门狗守护与自愈SOP]]、[[技能｜本机服务回归测试与计时法]]、[[技能｜版本保留与清理法]]
• 知识库四线部署方案V1.0（跨端部署参考；存于 程序源代码\docs\知识库四线部署方案V1.0.md）

实战战绩

2026-09-26 首跑：全量包 49.3MB（866 条目）、四份手册成功升 V1.1、交付包 51.7MB；中间目录 869 文件分批改删清空；全程零联网。

版本记录