# 代码热更新使用说明

## 概述

修改代码后，**不需要重新构建 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` 即可快速应用更新，无需等待漫长的镜像重建过程！