cfdaily
158 lines
4.6 KiB
Markdown
158 lines
4.6 KiB
Markdown
# 自动同步监控系统管理指南
|
||
|
||
## 系统概述
|
||
|
||
这是一个基于文件变化监控的自动Git同步系统，监听 `/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live` 目录，当任何文件变化时自动执行双向git同步。
|
||
|
||
**当前使用方案：fswatch 实时监控** (基于 macOS 内核 FSEvents)
|
||
|
||
## 核心组件
|
||
|
||
1. **监控器** (`file-watcher.sh`) - Bash脚本，使用 fswatch 监控文件系统事件
|
||
2. **启动脚本** (`start-watcher.sh`) - 启动监控器为后台守护进程
|
||
3. **停止脚本** (`stop-watcher.sh`) - 停止监控器
|
||
4. **状态脚本** (`status-watcher.sh`) - 检查监控器状态
|
||
5. **同步脚本** (`auto-sync.sh`) - 执行git拉取、添加、提交、推送
|
||
|
||
## 可用方案对比
|
||
|
||
| 方案 | 机制 | 响应速度 | 资源占用 | 依赖 |
|
||
|------|------|----------|----------|------|
|
||
| **fswatch** (当前) | 内核事件通知 | **实时 (< 3秒)** | **极低** | 需要 `brew install fswatch` |
|
||
| simple-file-watcher | 轮询遍历 | 1分钟 | 中等 | Python 3 (无需额外依赖) |
|
||
|
||
## 使用方法
|
||
|
||
### 启动监控器
|
||
```bash
|
||
cd management/sanguo_auto_sync
|
||
./start-watcher.sh
|
||
```
|
||
|
||
### 停止监控器
|
||
```bash
|
||
./stop-watcher.sh
|
||
```
|
||
|
||
### 检查状态
|
||
```bash
|
||
./status-watcher.sh
|
||
```
|
||
|
||
### 查看监控日志
|
||
```bash
|
||
tail -f /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/file-watcher.log
|
||
```
|
||
|
||
### 查看同步日志
|
||
```bash
|
||
tail -f /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/auto-sync.log
|
||
```
|
||
|
||
## 文件变化触发流程
|
||
|
||
```
|
||
文件创建/修改/删除
|
||
↓
|
||
fswatch 内核事件通知 (毫秒级)
|
||
↓
|
||
监控器检测到变化，防限流等待1秒
|
||
↓
|
||
执行 auto-sync.sh
|
||
↓
|
||
1. git pull origin main (拉取远程变更)
|
||
↓
|
||
2. git add . (添加所有变更)
|
||
↓
|
||
3. git commit -m "auto-sync: ..." (提交)
|
||
↓
|
||
4. git push origin main (推送)
|
||
↓
|
||
完成同步，等待下次变化
|
||
```
|
||
|
||
## 技术细节
|
||
|
||
### 监控器特性
|
||
- **实时事件驱动** - 无需轮询，文件变化立即响应
|
||
- **忽略文件**：`.log`, `.pyc`, `.tmp`, `~` (临时文件)
|
||
- **忽略目录**：`.git`, `venv`, `.venv`, `__pycache__`, `node_modules`
|
||
- **防重复执行**：使用锁文件 `/tmp/sanguo_sync.lock`，避免频繁触发
|
||
- **限流保护**：同步后等待1秒，合并批量变化
|
||
- **日志记录**：`/.../file-watcher.log`
|
||
|
||
### 同步脚本特性
|
||
- 自动处理未跟踪文件
|
||
- **删除检测**：支持文件删除同步
|
||
- 错误处理：推送失败重试2次
|
||
- 日志记录：`auto-sync.log`
|
||
- 防冲突：先pull再push，避免冲突
|
||
|
||
### PID管理
|
||
- PID文件：`management/sanguo_auto_sync/watcher.pid`
|
||
- 自动清理：停止时删除PID文件
|
||
- 状态检查：通过PID验证进程运行状态
|
||
|
||
## 故障排除
|
||
|
||
### 监控器没有启动
|
||
1. 检查 fswatch 是否安装：`which fswatch`
|
||
2. 如果未安装：`brew install fswatch`
|
||
3. 检查脚本权限：`chmod +x file-watcher.sh`
|
||
4. 检查日志：`tail -f file-watcher.log`
|
||
|
||
### 同步失败
|
||
1. 检查网络连接
|
||
2. 检查Git配置：`git remote -v`
|
||
3. 检查Git权限：确保有推送权限
|
||
4. 查看错误日志：`tail -f auto-sync.log`
|
||
|
||
### 文件变化未触发同步
|
||
1. 检查监控器是否运行：`./status-watcher.sh`
|
||
2. 检查文件是否被忽略（参考上面的忽略列表）
|
||
3. 检查锁文件：如果 `/tmp/sanguo_sync.lock` 存在且同步正在进行，等待完成
|
||
|
||
## 回退方案
|
||
|
||
如果 fswatch 不可用，可以回退到 Python 轮询方案：
|
||
```bash
|
||
./stop-watcher.sh
|
||
./start-simple-watcher.sh
|
||
```
|
||
|
||
## 系统集成
|
||
|
||
### 开机自启动
|
||
可以将以下命令添加到crontab或launchd以实现开机自启动：
|
||
```bash
|
||
cd "/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/management/sanguo_auto_sync" && ./start-watcher.sh
|
||
```
|
||
|
||
### 与其他系统集成
|
||
- 可以与CI/CD系统集成
|
||
- 可以扩展为多目录监控
|
||
- 可以添加通知功能（邮件、Slack、Feishu等）
|
||
|
||
## 性能考虑
|
||
- **fswatch 基于内核事件**，几乎不占用CPU，大部分时间休眠
|
||
- 忽略虚拟环境和缓存目录，避免无效事件触发
|
||
- 同步脚本有防重复执行机制，避免频繁触发
|
||
|
||
## 安全注意事项
|
||
1. 确保 `.gitignore` 正确配置，不提交敏感信息
|
||
2. 监控器在后台运行，确保有适当权限
|
||
3. 同步脚本会推送所有变更，确保不推送机密数据
|
||
|
||
## 维护
|
||
- 定期清理日志文件
|
||
- 监控磁盘空间
|
||
- 检查Git仓库健康状态
|
||
|
||
## 变更日志
|
||
|
||
| 日期 | 变更 | 作者 |
|
||
|------|------|------|
|
||
| 2026-03-26 | 切换到 fswatch 实时监控方案 | 诸葛亮 |
|
||
| 2026-03-26 | 修复删除文件检测问题 | 诸葛亮 |
|
||
| 2026-03-26 | 添加虚拟环境目录忽略 | 诸葛亮 |
|
||
| 2026-03-26 | 初始版本 Python 轮询方案 | - | |