keep_sync

keep_sync 是一个本地到远端的自动同步工具。程序会持续监控本地目录变化，并通过 FTP/SFTP 自动把变更同步到服务器。

亮点

• 多规则同步: 一个 keep_sync.ini 可定义多条 sync.* 规则，把不同本地目录同步到不同服务器目录。
• 启动全量与自动增量: 启动时可先全量扫描，再进入实时监听，减少“启动前差异”问题。
• 事件监听与周期补偿: 使用文件系统事件实时捕获变化，并用周期性快照对比补偿漏事件。
• 删除安全策略: 本地删除时，不会直接删远端物理文件，默认移动到远端回收站目录。
• 热重载配置: 修改 keep_sync.ini 后可自动重载；新配置有误时保留旧配置继续运行。
• 冲突策略可控: 同一文件命中多规则时支持 fanout / first_match / longest_prefix。

功能

• 支持：FTP、SFTP（用户名/密码）、新增/修改/删除文件、新增目录、目录删除事件、重试、回收站、热重载。
• 支持：SFTP 通过 libssh2 接入（构建内置 curl 时自动通过 FetchContent 拉取）。
• 限制：startup_prune_remote=true 仅记录告警，未实现远端清理。

Windows 运行

目录下应包含keep_sync.ini、keep_sync.exe，双击打开keep_sync.exe即可运行。

命令行运行

keep_sync [--config <path>] [--once] [--validate-config]

• --config <path>
  指定配置文件路径。默认使用 <exe_dir>/keep_sync.ini。
• --once
  只执行一次启动同步流程后退出（适合 CI 或手动校验）。
• --validate-config
  只做配置解析与校验，不执行同步。

常见退出码：

• 0：成功
• 1：参数错误或启动失败
• 2：配置校验失败

配置文件

示例文件：keep_sync.ini.example

运行时默认读取当前程序相同目录下的 keep_sync.ini。

配置结构

• [global]：全局设置
• [sync.<rule_id>]：单条同步规则（可多条）

---

[global] 配置项

配置项	类型	默认值	说明
config_hot_reload	bool	true	是否开启配置热重载。若开启，程序运行中每隔约 2 秒检查配置文件变更。
match_policy	enum	fanout	多规则命中策略：fanout 全执行，first_match 按配置顺序取第一条，longest_prefix 取本地根目录最长匹配。
reconcile_interval_sec	int	300	周期补偿扫描间隔（秒），用于修复可能漏掉的事件。必须 > 0。
debounce_ms	int	300	事件防抖窗口（毫秒）。必须 >= 0。
retry_max	int	5	单任务最大重试次数。必须 >= 0。
retry_base_ms	int	1000	重试基准延迟（毫秒），指数退避。必须 > 0。
log_file	string(path)	<exe_dir>/keep_sync.log	日志文件路径。若写相对路径，会按“配置文件所在目录”解析。
log_level	enum	info	日志级别（常用：debug/info/warn/error）。
ignore_dirs	csv(string)	空	忽略目录名列表（按名称匹配路径段）。
ignore_files	csv(string)	空	忽略文件名列表（按文件名匹配，作用于所有子目录）。
recycle_dir	string(path)	/.keep_sync_trash	远端回收站根目录。
startup_mode	enum	full_scan	启动策略：full_scan 或 watch_only。
startup_prune_remote	bool	false	暂不支持此设置项

---

[sync.<rule_id>] 配置项

配置项	类型	默认值	必填	说明
enabled	bool	true	否	是否启用该规则。
local_root	string(path)	无	是	本地根目录。支持相对路径，相对路径按“程序启动时工作目录”解析。
protocol	enum	ftp	是	ftp 或 sftp。
host	string	无	是	服务器地址。
port	int	ftp=21 sftp=22	否	端口。必须在 1..65535。
username	string	无	是	登录用户名。
password	string	无	是	登录密码。
remote_root	string(path)	/	否	远端根目录。
passive_mode	bool	true	否	FTP 被动模式开关（仅 FTP 有效）。
timeout_sec	int	30	否	连接与传输超时（秒）。
ignore_dirs	csv(string)	空	否	规则级目录忽略，和全局 ignore_dirs 叠加。
ignore_files	csv(string)	空	否	规则级文件忽略，和全局 ignore_files 叠加。
recycle_dir	string(path)	继承全局	否	覆盖该规则的回收站目录。
startup_mode	enum	inherit	否	inherit/full_scan/watch_only。inherit 表示继承全局。

枚举值清单

• match_policy: fanout, first_match, longest_prefix
• startup_mode:
  • 全局：full_scan, watch_only
  • 规则：inherit, full_scan, watch_only
• protocol: ftp, sftp

同步行为说明

• 同步方向：单向，本地 -> 远端。
• 路径映射：remote_root + 本地相对路径。
• 事件映射：
  • 文件新增/修改 -> 上传覆盖
  • 目录新增 -> 远端递归建目录
  • 文件/目录删除 -> 远端移动到回收站
• 回收站路径格式：
  /<recycle_dir>/<rule_id>/<UTC时间戳>/<relative_path>
• 忽略规则按“名称”匹配，不是通配符模式。

热重载行为

• 当 config_hot_reload=true 时，程序会检测 keep_sync.ini 的修改时间变化。
• 新配置解析或校验失败时，不会替换当前生效配置，会继续按旧配置运行并记录错误日志。

构建

环境要求

• CMake >= 4.0
• C/C++ 编译器（示例使用 MinGW GCC）

依赖策略

使用 FetchContent 自动管理依赖（spdlog、inih、efsw、curl、libssh2）。

使用 CMake Presets

cmake --preset windows-mingw-ninja
cmake --build --preset windows-mingw-ninja

可用 preset：

• windows-mingw-ninja
• windows-mingw-makefiles
• linux-gcc-ninja

手动构建

cmake -DCMAKE_BUILD_TYPE=Debug ^
  -DCMAKE_MAKE_PROGRAM=C:/Users/<you>/AppData/Local/Programs/CLion/bin/ninja/win/x64/ninja.exe ^
  -G Ninja -S . -B cmake-build-debug

cmake --build cmake-build-debug --target keep_sync -j 8

安装

cmake --install cmake-build-debug --prefix ./dist

MinGW 静态链

满足 MINGW + GNU + KEEP_SYNC_MINGW_STATIC_RUNTIME=ON 时，程序启用：

• -static-libgcc
• -static-libstdc++

并在构建后复制 libwinpthread-1.dll 到可执行文件目录，减少运行时缺库问题。

日志

• 默认日志文件：keep_sync.log
• 典型字段：rule_id、op、local_path、remote_path、attempt、status、latency_ms、error
• 常见 op：upload_overwrite、mkdir_p、recycle_move

安全建议

• 当前配置文件明文保存密码，建议控制配置文件权限。

错误排除

• 配置时报 INI parse error near line N：检查对应行语法。
• No enabled sync.* rules found.：未配置可用规则或都被 enabled=false。
• local_root does not exist：本地路径不存在，属于 warning，规则不会产生实际同步。
• SFTP 连接失败：检查目标主机、端口、账号密码和网络连通性。

快速开始

1. 复制示例：keep_sync.ini.example -> keep_sync.ini
2. 修改服务器地址、账号密码、本地目录、远端目录
3. 先校验配置：

   keep_sync --validate-config --config ./keep_sync.ini

4. 试运行一次：

   keep_sync --once --config ./keep_sync.ini

5. 持续运行：

   keep_sync

   或

   keep_sync --config ./keep_sync.ini