From 37bbd82563e933068b23861ef2136fbfd6bca41d Mon Sep 17 00:00:00 2001
From: mzl <mzl@hnxinyouhe.com>
Date: Fri, 9 Jan 2026 16:53:04 +0800
Subject: [PATCH] ts

---
 docs/GIT_WORKFLOW.md | 435 +++++++++++++++++++++++++++++++++++++++++++
 quick_push.bat       |  35 ++++
 scripts/auto_pull.sh |  91 +++++++++
 3 files changed, 561 insertions(+)
 create mode 100644 docs/GIT_WORKFLOW.md
 create mode 100644 quick_push.bat
 create mode 100644 scripts/auto_pull.sh

diff --git a/docs/GIT_WORKFLOW.md b/docs/GIT_WORKFLOW.md
new file mode 100644
index 0000000..1463db1
--- /dev/null
+++ b/docs/GIT_WORKFLOW.md
@@ -0,0 +1,435 @@
+# Git 自动化部署使用指南
+
+## 工作原理
+
+通过 Git + 服务端自动拉取方案，实现代码修改后自动同步到服务器并重启服务：
+
+```
+本地开发 → quick_push.bat → Git 仓库 → 服务器定时拉取 → 自动重启服务
+```
+
+## 一、初始设置
+
+### 1.1 创建远程 Git 仓库
+
+在以下平台之一创建仓库（推荐私有仓库）：
+
+- **GitHub**: https://github.com/new
+- **GitLab**: https://gitlab.com/projects/new
+- **Gitee**: https://gitee.com/projects/new
+- **自建 Gitea**: 如果服务器上已有 Gitea
+
+仓库名建议：`xhs_cloud_stable_v2`
+
+### 1.2 本地配置 Git 远程仓库
+
+在项目根目录执行：
+
+```bash
+# 查看当前远程仓库
+git remote -v
+
+# 添加远程仓库（替换为你的仓库地址）
+git remote add origin https://github.com/your-username/xhs_cloud_stable_v2.git
+
+# 或者如果已有 origin，更新地址
+git remote set-url origin https://github.com/your-username/xhs_cloud_stable_v2.git
+
+# 推送已有提交到远程仓库
+git push -u origin master
+```
+
+**注意**：如果远程仓库默认分支是 `main`，请将上面的 `master` 改为 `main`
+
+### 1.3 服务器端配置
+
+#### 1.3.1 克隆仓库到服务器
+
+```bash
+# SSH 登录到服务器
+ssh user@your-server-ip
+
+# 进入目标目录（根据实际情况修改）
+cd /path/to/your/projects
+
+# 克隆仓库
+git clone https://github.com/your-username/xhs_cloud_stable_v2.git
+cd xhs_cloud_stable_v2
+```
+
+#### 1.3.2 配置自动拉取脚本
+
+编辑 `scripts/auto_pull.sh`，修改配置项：
+
+```bash
+# 编辑脚本
+vi scripts/auto_pull.sh
+
+# 修改以下配置项：
+PROJECT_DIR="/path/to/your/xhs_cloud_stable_v2"  # 改为服务器上的实际路径
+GIT_REPO="your-git-repo-url"  # 改为实际的 Git 仓库地址
+```
+
+**示例配置**：
+```bash
+PROJECT_DIR="/home/user/projects/xhs_cloud_stable_v2"
+GIT_REPO="https://github.com/your-username/xhs_cloud_stable_v2.git"
+```
+
+#### 1.3.3 设置脚本执行权限
+
+```bash
+chmod +x scripts/auto_pull.sh
+```
+
+#### 1.3.4 配置定时任务（cron）
+
+```bash
+# 编辑 crontab
+crontab -e
+
+# 添加以下行（每 2 分钟检查一次更新）
+*/2 * * * * /path/to/your/xhs_cloud_stable_v2/scripts/auto_pull.sh >> /path/to/your/xhs_cloud_stable_v2/logs/cron.log 2>&1
+```
+
+**说明**：
+- `*/2 * * * *` 表示每 2 分钟执行一次
+- 可以改为 `*/5 * * * *`（每 5 分钟）或 `* * * * *`（每 1 分钟）
+- 日志会保存到 `logs/cron.log`
+
+#### 1.3.5 手动测试脚本
+
+```bash
+# 手动执行一次，检查是否正常
+./scripts/auto_pull.sh
+
+# 查看日志
+cat logs/auto_pull.log
+```
+
+## 二、日常使用
+
+### 2.1 本地开发流程
+
+1. **修改代码**
+   - 在本地编辑代码文件
+
+2. **快速提交推送**
+   - 双击运行 `quick_push.bat`
+   - 或在命令行执行：
+     ```bash
+     quick_push.bat
+     ```
+
+3. **输入提交信息**
+   - 脚本会提示输入提交信息（默认：`update code`）
+   - 例如：`fix: 修复采集去重逻辑`
+   - 直接回车使用默认信息
+
+4. **等待推送完成**
+   - 脚本会自动执行：
+     - `git add .` - 添加所有修改
+     - `git commit` - 提交
+     - `git push` - 推送到远程仓库
+
+### 2.2 服务器自动更新
+
+推送成功后，服务器会：
+
+1. **检测更新**（最多等待 2 分钟，根据 cron 配置）
+2. **拉取代码** `git pull`
+3. **更新依赖**（如果 `requirements.txt` 有变化）
+4. **重启服务**
+   - 如果使用 `docker-compose.yml`，会执行 `docker-compose down && docker-compose up -d`
+   - 如果使用 systemd，取消注释 `systemctl restart xhs-crawler`
+   - 如果使用 supervisor，取消注释 `supervisorctl restart xhs-crawler`
+
+### 2.3 查看服务器日志
+
+```bash
+# SSH 登录服务器
+ssh user@your-server-ip
+
+# 查看自动拉取日志
+cat /path/to/your/xhs_cloud_stable_v2/logs/auto_pull.log
+
+# 查看 cron 日志
+tail -f /path/to/your/xhs_cloud_stable_v2/logs/cron.log
+
+# 查看应用日志
+tail -f /path/to/your/xhs_cloud_stable_v2/logs/app.log
+```
+
+## 三、故障排查
+
+### 3.1 本地推送失败
+
+**问题**：`git push` 失败，提示认证错误
+
+**解决**：
+```bash
+# 如果使用 HTTPS，配置 Git 凭据存储
+git config --global credential.helper store
+
+# 再次推送，输入用户名和密码（或 Personal Access Token）
+git push
+```
+
+**建议**：使用 GitHub Personal Access Token 替代密码
+- 创建地址：https://github.com/settings/tokens
+
+### 3.2 服务器无法拉取
+
+**问题**：服务器执行 `git pull` 失败
+
+**排查步骤**：
+```bash
+# 1. 检查 Git 是否已安装
+git --version
+
+# 2. 手动执行拉取测试
+cd /path/to/your/xhs_cloud_stable_v2
+git fetch origin
+git pull origin master
+
+# 3. 检查仓库地址是否正确
+git remote -v
+
+# 4. 如果是私有仓库，配置 SSH 密钥或凭据
+# 方式一：SSH 密钥（推荐）
+ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
+# 将 ~/.ssh/id_rsa.pub 添加到 GitHub/GitLab 的 SSH keys
+
+# 方式二：凭据存储
+git config --global credential.helper store
+git pull  # 输入用户名和密码/Token
+```
+
+### 3.3 服务未自动重启
+
+**问题**：代码已拉取但服务未重启
+
+**排查步骤**：
+```bash
+# 1. 检查 auto_pull.sh 中服务重启方式是否正确
+vi scripts/auto_pull.sh
+
+# 2. 根据实际部署方式取消注释对应代码
+# Docker 用户：确认 docker-compose.yml 存在
+# Systemd 用户：取消注释 systemctl restart xhs-crawler
+# Supervisor 用户：取消注释 supervisorctl restart xhs-crawler
+
+# 3. 手动测试重启命令
+docker-compose down && docker-compose up -d
+# 或
+systemctl restart xhs-crawler
+# 或
+supervisorctl restart xhs-crawler
+
+# 4. 检查服务状态
+docker-compose ps
+# 或
+systemctl status xhs-crawler
+# 或
+supervisorctl status xhs-crawler
+```
+
+### 3.4 Cron 未执行
+
+**问题**：定时任务未运行
+
+**排查步骤**：
+```bash
+# 1. 检查 cron 服务状态
+systemctl status cron  # Ubuntu/Debian
+# 或
+systemctl status crond  # CentOS/RHEL
+
+# 2. 查看当前用户的 cron 任务
+crontab -l
+
+# 3. 检查 cron 日志
+tail -f /var/log/syslog | grep CRON  # Ubuntu/Debian
+# 或
+tail -f /var/log/cron  # CentOS/RHEL
+
+# 4. 确认脚本路径和权限
+which bash
+ls -la /path/to/your/xhs_cloud_stable_v2/scripts/auto_pull.sh
+```
+
+## 四、高级配置
+
+### 4.1 使用 SSH 代替 HTTPS（推荐）
+
+**优势**：无需输入密码，更安全
+
+**步骤**：
+
+1. **生成 SSH 密钥**（本地和服务器都需要）
+```bash
+ssh-keygen -t ed25519 -C "your_email@example.com"
+# 或使用 RSA
+ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
+```
+
+2. **添加公钥到 Git 仓库**
+```bash
+# 查看公钥
+cat ~/.ssh/id_ed25519.pub
+# 或
+cat ~/.ssh/id_rsa.pub
+
+# 复制输出，添加到：
+# GitHub: Settings → SSH and GPG keys → New SSH key
+# GitLab: Preferences → SSH Keys
+# Gitee: 设置 → SSH 公钥
+```
+
+3. **更新远程仓库地址**
+```bash
+# 本地
+git remote set-url origin git@github.com:your-username/xhs_cloud_stable_v2.git
+
+# 服务器
+cd /path/to/your/xhs_cloud_stable_v2
+git remote set-url origin git@github.com:your-username/xhs_cloud_stable_v2.git
+```
+
+4. **更新 auto_pull.sh 中的 GIT_REPO**
+```bash
+GIT_REPO="git@github.com:your-username/xhs_cloud_stable_v2.git"
+```
+
+### 4.2 使用 Git分支进行开发
+
+```bash
+# 创建开发分支
+git checkout -b dev
+
+# 在 dev 分支开发
+# ... 修改代码 ...
+quick_push.bat
+
+# 测试无误后合并到主分支
+git checkout master
+git merge dev
+git push origin master
+```
+
+### 4.3 配置 Git 钩子实现更快的部署
+
+如果 cron 的 2 分钟延迟太长，可以使用 **Git Webhook**：
+
+1. **在服务器上安装 webhook 接收工具**（如 `webhook` 或 `adnanh/webhook`）
+2. **配置 Git 仓库的 Webhook**，指向服务器 URL
+3. **推送时代码立即触发服务器拉取**
+
+这种方式可以实现 **秒级部署**，但配置更复杂。
+
+## 五、最佳实践
+
+### 5.1 提交信息规范
+
+```bash
+# 功能添加
+feat: 添加批量导入账号功能
+
+# Bug 修复
+fix: 修复采集数量限制不生效的问题
+
+# 文档更新
+docs: 更新部署文档
+
+# 性能优化
+perf: 优化去重检查性能
+
+# 代码重构
+refactor: 重构采集任务管理器
+```
+
+### 5.2 忽略敏感文件
+
+`.gitignore` 已配置忽略以下文件：
+- `data/crawled_ids.json` - 去重记录（本地运行生成）
+- `data/storage_state*.json` - 登录状态（敏感）
+- `output/` - 采集输出文件
+- `logs/*.log` - 日志文件
+- `.env` - 环境变量（敏感）
+
+**注意**：首次部署时，需要在服务器上手动创建必要的空文件和目录：
+```bash
+ssh user@your-server-ip
+cd /path/to/your/xhs_cloud_stable_v2
+mkdir -p data output logs
+touch data/config.json
+touch data/profiles.json
+touch data/storage_state.json
+```
+
+### 5.3 备份重要数据
+
+```bash
+# 服务器端定期备份去重记录
+crontab -e
+
+# 添加：每天凌晨 3 点备份
+0 3 * * * cp /path/to/your/xhs_cloud_stable_v2/data/crawled_ids.json /path/to/backups/crawled_ids_$(date +\%Y\%m\%d).json
+```
+
+## 六、快速参考
+
+### 常用 Git 命令
+
+```bash
+# 查看状态
+git status
+
+# 查看日志
+git log --oneline -10
+
+# 撤销本地修改（慎用）
+git reset --hard HEAD
+
+# 查看远程仓库
+git remote -v
+
+# 拉取最新代码
+git pull origin master
+
+# 推送代码
+git push origin master
+```
+
+### 服务器常用命令
+
+```bash
+# 查看服务状态
+docker-compose ps  # Docker
+systemctl status xhs-crawler  # Systemd
+supervisorctl status xhs-crawler  # Supervisor
+
+# 重启服务
+docker-compose restart
+systemctl restart xhs-crawler
+supervisorctl restart xhs-crawler
+
+# 查看实时日志
+tail -f logs/app.log
+
+# 手动触发拉取
+./scripts/auto_pull.sh
+```
+
+---
+
+## 需要帮助？
+
+如果遇到问题，请检查：
+1. ✅ Git 仓库地址是否正确
+2. ✅ 服务器网络是否正常
+3. ✅ 脚本路径和权限是否正确
+4. ✅ cron 服务是否运行
+5. ✅ 日志文件中的错误信息
+
+**提示**：大多数问题都可以通过查看日志找到原因！
diff --git a/quick_push.bat b/quick_push.bat
new file mode 100644
index 0000000..e0f816e
--- /dev/null
+++ b/quick_push.bat
@@ -0,0 +1,35 @@
+@echo off
+REM Windows 快速提交脚本
+REM 使用方法：双击运行或在命令行执行
+
+echo ========================================
+echo   XHS 采集器 - 快速提交脚本
+echo ========================================
+echo.
+
+REM 设置颜色
+color 0A
+
+echo [1/3] 检查 Git 状态...
+git status --short
+
+echo.
+echo [2/3] 添加所有修改...
+git add .
+
+echo.
+set /p MESSAGE="请输入提交信息（默认：update code）: "
+if "%MESSAGE%"=="" set MESSAGE=update code
+
+echo.
+echo [3/3] 提交并推送...
+git commit -m "%MESSAGE%"
+git push
+
+echo.
+echo ========================================
+echo   提交完成！
+echo ========================================
+echo.
+echo 提示：服务器将在下次自动拉取时获取这些更新
+pause
diff --git a/scripts/auto_pull.sh b/scripts/auto_pull.sh
new file mode 100644
index 0000000..853ea65
--- /dev/null
+++ b/scripts/auto_pull.sh
@@ -0,0 +1,91 @@
+#!/bin/bash
+# 服务端自动拉取并重启服务脚本
+# 使用方法：将此脚本设置为 cron 任务或手动执行
+
+set -e
+
+# 配置项
+PROJECT_DIR="/path/to/your/xhs_cloud_stable_v2"  # 修改为实际的服务器路径
+GIT_REPO="your-git-repo-url"  # 修改为实际的 Git 仓库地址
+LOG_FILE="$PROJECT_DIR/logs/auto_pull.log"
+
+# 创建日志目录
+mkdir -p "$(dirname "$LOG_FILE")"
+
+# 日志函数
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
+}
+
+log "========== 开始检查更新 =========="
+
+cd "$PROJECT_DIR" || {
+    log "错误：无法进入项目目录 $PROJECT_DIR"
+    exit 1
+}
+
+# 检查是否为 Git 仓库
+if [ ! -d ".git" ]; then
+    log "警告：当前目录不是 Git 仓库，尝试克隆..."
+    git clone "$GIT_REPO" "$PROJECT_DIR" || {
+        log "错误：Git 克隆失败"
+        exit 1
+    }
+fi
+
+# 获取当前分支名
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+log "当前分支：$CURRENT_BRANCH"
+
+# 拉取最新代码
+log "执行 git fetch..."
+git fetch origin
+
+# 检查是否有新提交
+LOCAL=$(git rev-parse HEAD)
+REMOTE=$(git rev-parse origin/"$CURRENT_BRANCH")
+
+if [ "$LOCAL" != "$REMOTE" ]; then
+    log "发现新更新，开始拉取..."
+
+    # 拉取代码
+    git pull origin "$CURRENT_BRANCH" || {
+        log "错误：Git pull 失败"
+        exit 1
+    }
+
+    log "代码更新成功！"
+
+    # 检查是否有 requirements.txt 变化
+    if git diff HEAD@{1} HEAD --name-only | grep -q "requirements.txt"; then
+        log "检测到 requirements.txt 变化，更新依赖..."
+        pip install -r requirements.txt >> "$LOG_FILE" 2>&1 || {
+            log "警告：依赖安装失败，请手动检查"
+        }
+    fi
+
+    # 重启服务（根据实际部署方式调整）
+    log "重启服务..."
+
+    # 方式1：使用 docker-compose
+    if [ -f "docker-compose.yml" ]; then
+        docker-compose down
+        docker-compose up -d
+        log "Docker 服务已重启"
+    fi
+
+    # 方式2：使用 systemd 服务
+    # systemctl restart xhs-crawler
+    # log "Systemd 服务已重启"
+
+    # 方式3：使用 supervisor
+    # supervisorctl restart xhs-crawler
+    # log "Supervisor 服务已重启"
+
+    log "========== 更新完成 =========="
+else
+    log "没有新更新，无需操作"
+fi
+
+log "========== 检查结束 =========="
+echo ""