# 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. ✅ 日志文件中的错误信息

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