diff --git a/management/sanguo_auto_sync/AUTO-SYNC-MANAGEMENT.md b/management/sanguo_auto_sync/AUTO-SYNC-MANAGEMENT.md index a75d2895f..930a91be0 100644 --- a/management/sanguo_auto_sync/AUTO-SYNC-MANAGEMENT.md +++ b/management/sanguo_auto_sync/AUTO-SYNC-MANAGEMENT.md @@ -4,39 +4,49 @@ 这是一个基于文件变化监控的自动Git同步系统,监听 `/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live` 目录,当任何文件变化时自动执行双向git同步。 +**当前使用方案:fswatch 实时监控** (基于 macOS 内核 FSEvents) + ## 核心组件 -1. **监控器** (`simple-file-watcher.py`) - Python脚本,每2秒检查文件变化 -2. **启动脚本** (`start-simple-watcher.sh`) - 启动监控器为后台守护进程 -3. **停止脚本** (`stop-simple-watcher.sh`) - 停止监控器 -4. **状态脚本** (`status-simple-watcher.sh`) - 检查监控器状态 +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 -./start-simple-watcher.sh +cd management/sanguo_auto_sync +./start-watcher.sh ``` ### 停止监控器 ```bash -./stop-simple-watcher.sh +./stop-watcher.sh ``` ### 检查状态 ```bash -./status-simple-watcher.sh +./status-watcher.sh ``` ### 查看监控日志 ```bash -tail -f simple-watcher.log +tail -f /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/file-watcher.log ``` ### 查看同步日志 ```bash -tail -f auto-sync.log +tail -f /Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/auto-sync.log ``` ## 文件变化触发流程 @@ -44,7 +54,9 @@ tail -f auto-sync.log ``` 文件创建/修改/删除 ↓ -监控器检测到变化 (2秒内) +fswatch 内核事件通知 (毫秒级) + ↓ +监控器检测到变化,防限流等待1秒 ↓ 执行 auto-sync.sh ↓ @@ -62,30 +74,32 @@ tail -f auto-sync.log ## 技术细节 ### 监控器特性 -- 轮询间隔:2秒 -- 忽略文件:.log, .tmp, ~ (临时文件) -- 忽略目录:.git -- 防重复执行:使用锁文件 `/tmp/sanguo_sync.lock` -- 日志记录:`simple-watcher.log` +- **实时事件驱动** - 无需轮询,文件变化立即响应 +- **忽略文件**:`.log`, `.pyc`, `.tmp`, `~` (临时文件) +- **忽略目录**:`.git`, `venv`, `.venv`, `__pycache__`, `node_modules` +- **防重复执行**:使用锁文件 `/tmp/sanguo_sync.lock`,避免频繁触发 +- **限流保护**:同步后等待1秒,合并批量变化 +- **日志记录**:`/.../file-watcher.log` ### 同步脚本特性 - 自动处理未跟踪文件 -- 错误处理:失败重试2次 +- **删除检测**:支持文件删除同步 +- 错误处理:推送失败重试2次 - 日志记录:`auto-sync.log` -- 防冲突:先pull再push +- 防冲突:先pull再push,避免冲突 ### PID管理 -### PID管理 -- PID文件:`simple-watcher.pid` +- PID文件:`management/sanguo_auto_sync/watcher.pid` - 自动清理:停止时删除PID文件 - 状态检查:通过PID验证进程运行状态 ## 故障排除 ### 监控器没有启动 -1. 检查Python3是否安装:`python3 --version` -2. 检查脚本权限:`chmod +x simple-file-watcher.py` -3. 检查日志:`tail -f simple-watcher.log` +1. 检查 fswatch 是否安装:`which fswatch` +2. 如果未安装:`brew install fswatch` +3. 检查脚本权限:`chmod +x file-watcher.sh` +4. 检查日志:`tail -f file-watcher.log` ### 同步失败 1. 检查网络连接 @@ -94,42 +108,51 @@ tail -f auto-sync.log 4. 查看错误日志:`tail -f auto-sync.log` ### 文件变化未触发同步 -1. 检查监控器是否运行:`./status-simple-watcher.sh` -2. 检查文件是否被忽略(如.log文件) -3. 检查监控间隔:默认2秒,可能需要等待 +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" && nohup python3 simple-file-watcher.py > /dev/null 2>&1 & +cd "/Users/chufeng/.openclaw/sanguo_projects/sanguo_quant_live/management/sanguo_auto_sync" && ./start-watcher.sh ``` ### 与其他系统集成 - 可以与CI/CD系统集成 - 可以扩展为多目录监控 -- 可以添加通知功能(邮件、Slack等) +- 可以添加通知功能(邮件、Slack、Feishu等) ## 性能考虑 -- 轮询间隔2秒,对系统负载影响小 -- 监控整个目录树,但忽略.git目录 +- **fswatch 基于内核事件**,几乎不占用CPU,大部分时间休眠 +- 忽略虚拟环境和缓存目录,避免无效事件触发 - 同步脚本有防重复执行机制,避免频繁触发 ## 安全注意事项 -1. 确保.gitignore正确配置,不提交敏感信息 +1. 确保 `.gitignore` 正确配置,不提交敏感信息 2. 监控器在后台运行,确保有适当权限 3. 同步脚本会推送所有变更,确保不推送机密数据 -## 扩展功能 -如需扩展功能,可以修改 `simple-file-watcher.py`: -1. 添加文件类型过滤 -2. 添加事件类型区分(创建/修改/删除) -3. 添加批量处理(多个变化一次同步) -4. 添加通知机制 - ## 维护 - 定期清理日志文件 - 监控磁盘空间 - 检查Git仓库健康状态 -- 更新Python依赖(如有) \ No newline at end of file + +## 变更日志 + +| 日期 | 变更 | 作者 | +|------|------|------| +| 2026-03-26 | 切换到 fswatch 实时监控方案 | 诸葛亮 | +| 2026-03-26 | 修复删除文件检测问题 | 诸葛亮 | +| 2026-03-26 | 添加虚拟环境目录忽略 | 诸葛亮 | +| 2026-03-26 | 初始版本 Python 轮询方案 | - | \ No newline at end of file