213 lines
4.8 KiB
Markdown
213 lines
4.8 KiB
Markdown
# 代码热更新使用说明
|
||
|
||
## 概述
|
||
|
||
修改代码后，**不需要重新构建 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` 即可快速应用更新，无需等待漫长的镜像重建过程！
|