xhs_crawler/docs/GIT_WORKFLOW.md

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 远程仓库

在项目根目录执行：

# 查看当前远程仓库
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 克隆仓库到服务器

# 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，修改配置项：

# 编辑脚本
vi scripts/auto_pull.sh

# 修改以下配置项：
PROJECT_DIR="/path/to/your/xhs_cloud_stable_v2"  # 改为服务器上的实际路径
GIT_REPO="your-git-repo-url"  # 改为实际的 Git 仓库地址

示例配置：

PROJECT_DIR="/home/user/projects/xhs_cloud_stable_v2"
GIT_REPO="https://github.com/your-username/xhs_cloud_stable_v2.git"

1.3.3 设置脚本执行权限

chmod +x scripts/auto_pull.sh

1.3.4 配置定时任务（cron）

# 编辑 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 手动测试脚本

# 手动执行一次，检查是否正常
./scripts/auto_pull.sh

# 查看日志
cat logs/auto_pull.log

二、日常使用

2.1 本地开发流程

1. 修改代码

   • 在本地编辑代码文件

2. 快速提交推送

   • 双击运行 quick_push.bat
   • 或在命令行执行：

     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 查看服务器日志

# 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 失败，提示认证错误

解决：

# 如果使用 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 失败

排查步骤：

# 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 服务未自动重启

问题：代码已拉取但服务未重启

排查步骤：

# 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 未执行

问题：定时任务未运行

排查步骤：

# 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 密钥（本地和服务器都需要）

ssh-keygen -t ed25519 -C "your_email@example.com"
# 或使用 RSA
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

2. 添加公钥到 Git 仓库

# 查看公钥
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. 更新远程仓库地址

# 本地
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

GIT_REPO="git@github.com:your-username/xhs_cloud_stable_v2.git"

4.2 使用 Git分支进行开发

# 创建开发分支
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 提交信息规范

# 功能添加
feat: 添加批量导入账号功能

# Bug 修复
fix: 修复采集数量限制不生效的问题

# 文档更新
docs: 更新部署文档

# 性能优化
perf: 优化去重检查性能

# 代码重构
refactor: 重构采集任务管理器

5.2 忽略敏感文件

.gitignore 已配置忽略以下文件：

• data/crawled_ids.json - 去重记录（本地运行生成）
• data/storage_state*.json - 登录状态（敏感）
• output/ - 采集输出文件
• logs/*.log - 日志文件
• .env - 环境变量（敏感）

注意：首次部署时，需要在服务器上手动创建必要的空文件和目录：

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 备份重要数据

# 服务器端定期备份去重记录
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 命令

# 查看状态
git status

# 查看日志
git log --oneline -10

# 撤销本地修改（慎用）
git reset --hard HEAD

# 查看远程仓库
git remote -v

# 拉取最新代码
git pull origin master

# 推送代码
git push origin master

服务器常用命令

# 查看服务状态
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. ✅ 日志文件中的错误信息

提示：大多数问题都可以通过查看日志找到原因！