xhs_crawler/docs/HOTPATCH_GUIDE.md

代码热更新使用说明

概述

修改代码后，不需要重新构建 Docker 镜像。使用热更新脚本可以快速将代码同步到容器并重启服务。

支持的文件

以下文件修改后可以使用热更新：

• ✅ xhs_crawler_core.py - 核心采集逻辑
• ✅ app/server.py - Web 服务器
• ✅ app/static/index.html - 前端页面

使用方法

1. 修改代码

在本地修改上述任一文件，例如：

vi xhs_crawler_core.py

2. 执行热更新

./quick_hotpatch.sh

3. 等待完成

脚本会自动：

1. 检查容器运行状态
2. 同步修改的文件到容器
3. 重启容器
4. 健康检查

输出示例

========================================
  XHS 采集器 - 快速热更新
========================================

[热更新] 同步代码到容器...
  - xhs_crawler_core.py
  - app/server.py
  - app/static/index.html

[热更新] 重启容器...
⏳ 等待服务启动...

[热更新] 检查服务状态...
✅ 容器运行正常

[热更新] 健康检查...
✅ Web 界面正常 (HTTP 200)

========================================
  热更新完成！
========================================

提示：修改 xhs_crawler_core.py 或 app/server.py 后，
      运行此脚本即可快速应用更新，无需重新构建镜像

常见问题

❌ 容器未运行

❌ 容器 xhs-web 未运行，请先启动服务：
   ./quick_start.sh

解决：先启动服务

./quick_start.sh

❌ 容器启动失败

如果容器重启后失败，脚本会显示日志：

❌ 容器启动失败
[显示最近 50 行日志]

解决：检查日志中的错误信息，可能需要：

1. 检查代码语法错误
2. 查看完整日志：docker logs xhs-web
3. 必要时重新构建：./quick_start.sh

工作原理

Docker 容器文件系统

宿主机                          容器
├─ xhs_crawler_core.py     →   /app/xhs_crawler_core.py
├─ app/
   ├─ server.py            →   /app/app/server.py
   └─ static/
      └─ index.html        →   /app/app/static/index.html

热更新流程

1. docker cp - 将文件从宿主机复制到容器
2. docker restart - 重启容器应用新代码
3. 健康检查 - 验证服务正常运行

为什么不需要重新构建？

• 代码文件在容器外部（通过 docker cp 复制）
• 没有修改 requirements.txt（不需要重新安装依赖）
• 没有修改 Dockerfile（不需要重建镜像层）

什么时候需要重新构建？

以下情况需要运行 ./quick_start.sh 重新构建：

• 修改了 requirements.txt（添加/删除 Python 依赖）
• 修改了 Dockerfile 或 Dockerfile.novnc
• 修改了 docker-compose.yml
• 修改了系统级配置或环境变量

对比：热更新 vs 重新构建

操作	热更新	重新构建
命令	./quick_hotpatch.sh	./quick_start.sh
耗时	~5-10 秒	~2-5 分钟
场景	修改 Python/HTML 代码	修改依赖/配置
是否重建镜像	❌ 否	✅ 是

最佳实践

1. 开发流程

   修改代码 → 保存 → ./quick_hotpatch.sh → 测试
   

2. 提交代码前

   # 确保热更新能正常工作
   ./quick_hotpatch.sh
   
   # 测试功能正常
   # 然后提交
   ./quick_push.bat  # Windows
   # 或
   git add . && git commit -m "xxx" && git push
   

3. 批量修改多个文件

   • 可以一次性修改多个文件
   • 运行一次 ./quick_hotpatch.sh 即可同步所有文件

技术细节

docker cp 命令

# 语法
docker cp <宿主机路径> <容器名>:<容器内路径>

# 示例
docker cp xhs_crawler_core.py xhs-web:/app/xhs_crawler_core.py

容器内路径映射

根据 docker-compose.yml：

volumes:
  - ./data:/app/data      # 数据目录（挂载）
  - ./out:/app/out        # 输出目录（挂载）
  - ./logs:/app/logs      # 日志目录（挂载）
  # 代码目录未挂载，需要 docker cp

注意：代码目录没有挂载，所以需要通过 docker cp 同步。

进阶：自动热更新

如果觉得手动运行 ./quick_hotpatch.sh 麻烦，可以考虑：

方案 1: 使用文件监控

# 安装 fswatch (macOS/Linux)
brew install fswatch  # macOS
apt install fswatch  # Ubuntu

# 监控文件变化并自动热更新
fswatch -o xhs_crawler_core.py app/server.py | xargs -n1 ./quick_hotpatch.sh

方案 2: 使用 Git webhook

配置 Git 仓库的 webhook，推送到服务器后自动执行热更新脚本。

详细配置参考：docs/GIT_WORKFLOW.md

---

总结：日常开发修改代码后，使用 ./quick_hotpatch.sh 即可快速应用更新，无需等待漫长的镜像重建过程！