增强版热更新脚本

2026-01-09 17:37:39 +08:00
parent e6845620cc
commit fbc1b35ea8
2 changed files with 268 additions and 6 deletions
@@ -0,0 +1,212 @@
+# 代码热更新使用说明
+
+## 概述
+
+修改代码后，**不需要重新构建 Docker 镜像**。使用热更新脚本可以快速将代码同步到容器并重启服务。
+
+## 支持的文件
+
+以下文件修改后可以使用热更新：
+
+- ✅ `xhs_crawler_core.py` - 核心采集逻辑
+- ✅ `app/server.py` - Web 服务器
+- ✅ `app/static/index.html` - 前端页面
+
+## 使用方法
+
+### 1. 修改代码
+
+在本地修改上述任一文件，例如：
+
+```bash
+vi xhs_crawler_core.py
+```
+
+### 2. 执行热更新
+
+```bash
+./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
+```
+
+**解决**：先启动服务
+
+```bash
+./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. **提交代码前**
+   ```bash
+   # 确保热更新能正常工作
+   ./quick_hotpatch.sh
+
+   # 测试功能正常
+   # 然后提交
+   ./quick_push.bat  # Windows
+   # 或
+   git add . && git commit -m "xxx" && git push
+   ```
+
+3. **批量修改多个文件**
+   - 可以一次性修改多个文件
+   - 运行一次 `./quick_hotpatch.sh` 即可同步所有文件
+
+## 技术细节
+
+### docker cp 命令
+
+```bash
+# 语法
+docker cp <宿主机路径> <容器名>:<容器内路径>
+
+# 示例
+docker cp xhs_crawler_core.py xhs-web:/app/xhs_crawler_core.py
+```
+
+### 容器内路径映射
+
+根据 `docker-compose.yml`：
+
+```yaml
+volumes:
+  - ./data:/app/data      # 数据目录（挂载）
+  - ./out:/app/out        # 输出目录（挂载）
+  - ./logs:/app/logs      # 日志目录（挂载）
+  # 代码目录未挂载，需要 docker cp
+```
+
+**注意**：代码目录没有挂载，所以需要通过 `docker cp` 同步。
+
+## 进阶：自动热更新
+
+如果觉得手动运行 `./quick_hotpatch.sh` 麻烦，可以考虑：
+
+### 方案 1: 使用文件监控
+
+```bash
+# 安装 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](GIT_WORKFLOW.md)
+
+---
+
+**总结**：日常开发修改代码后，使用 `./quick_hotpatch.sh` 即可快速应用更新，无需等待漫长的镜像重建过程！