From fbc1b35ea810c97d0c34f89c22797eb9835dcb54 Mon Sep 17 00:00:00 2001
From: mzl <mzl@hnxinyouhe.com>
Date: Fri, 9 Jan 2026 17:37:39 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=BC=BA=E7=89=88=E7=83=AD=E6=9B=B4?=
 =?UTF-8?q?=E6=96=B0=E8=84=9A=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/HOTPATCH_GUIDE.md | 212 +++++++++++++++++++++++++++++++++++++++++
 quick_hotpatch.sh      |  62 ++++++++++--
 2 files changed, 268 insertions(+), 6 deletions(-)
 create mode 100644 docs/HOTPATCH_GUIDE.md

diff --git a/docs/HOTPATCH_GUIDE.md b/docs/HOTPATCH_GUIDE.md
new file mode 100644
index 0000000..d6b9170
--- /dev/null
+++ b/docs/HOTPATCH_GUIDE.md
@@ -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` 即可快速应用更新，无需等待漫长的镜像重建过程！
diff --git a/quick_hotpatch.sh b/quick_hotpatch.sh
index 2ae804f..55210e1 100644
--- a/quick_hotpatch.sh
+++ b/quick_hotpatch.sh
@@ -1,17 +1,67 @@
 #!/usr/bin/env bash
-set -euo pipefail
-# Fast hot-patch without rebuild: copy host app/ into container then restart.
+# Fast hot-patch without rebuild: copy host code into container then restart.
 # Usage: ./quick_hotpatch.sh
 
+set -e
+
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$ROOT_DIR"
 
-echo "[hotpatch] Copying app/ into xhs-web..."
+echo "========================================"
+echo "  XHS 采集器 - 快速热更新"
+echo "========================================"
+echo ""
+
+# 检查容器是否运行
+if ! docker ps | grep -q "xhs-web"; then
+    echo "❌ 容器 xhs-web 未运行，请先启动服务："
+    echo "   ./quick_start.sh"
+    exit 1
+fi
+
+echo "[热更新] 同步代码到容器..."
+# 同步核心 Python 文件
+echo "  - xhs_crawler_core.py"
+docker cp xhs_crawler_core.py xhs-web:/app/xhs_crawler_core.py
+
+echo "  - app/server.py"
 docker cp ./app/server.py xhs-web:/app/app/server.py
+
+echo "  - app/static/index.html"
 docker cp ./app/static/index.html xhs-web:/app/app/static/index.html
 
-echo "[hotpatch] Restarting xhs-web..."
+echo ""
+echo "[热更新] 重启容器..."
 docker restart xhs-web >/dev/null
 
-echo "[hotpatch] Tail logs..."
-docker logs xhs-web --tail=50
+echo "⏳ 等待服务启动..."
+sleep 3
+
+echo ""
+echo "[热更新] 检查服务状态..."
+if docker ps | grep -q "xhs-web"; then
+    echo "✅ 容器运行正常"
+else
+    echo "❌ 容器启动失败"
+    docker logs xhs-web --tail=50
+    exit 1
+fi
+
+echo ""
+echo "[热更新] 健康检查..."
+# 检查 Web 界面
+WEB_STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:28000/ || echo "000")
+if [ "$WEB_STATUS" = "200" ]; then
+    echo "✅ Web 界面正常 (HTTP $WEB_STATUS)"
+else
+    echo "⚠️  Web 界面响应异常 (HTTP $WEB_STATUS)"
+fi
+
+echo ""
+echo "========================================"
+echo "  热更新完成！"
+echo "========================================"
+echo ""
+echo "提示：修改 xhs_crawler_core.py 或 app/server.py 后，"
+echo "      运行此脚本即可快速应用更新，无需重新构建镜像"
+echo ""