Nginx-rsync实时推送

一、引言：当"定时同步"无法满足业务需求

在传统的 Nginx 静态资源或配置分发场景中，我们通常使用 Crontab 定时执行 rsync 命令。这种方式简单可靠，但存在一个致命短板：延迟。

• 前端构建完成后，需要等待下一个 Cron 周期才能生效；
• 紧急修复的配置变更，无法做到秒级全网生效；
• 高频更新场景下，固定间隔要么造成资源浪费，要么导致同步滞后。

真正的"实时推送"，不是缩短 Cron 间隔，而是由文件系统事件驱动 。当本地文件发生变更的瞬间，立即触发 rsync 增量同步。本文将系统讲解两种主流方案：轻量级的 inotify + rsync 脚本方案，以及生产级的 lsyncd 守护进程方案，并附带完整的避坑指南。

---

二、核心原理：从"轮询"到"事件驱动"

Linux 内核自 2.6.13 起提供了 inotify 机制，允许用户空间程序监控文件系统的创建、修改、删除、移动等事件。实时推送的本质就是：

文件变更 → inotify 捕获事件 → 触发 rsync 增量同步 → 目标 Nginx 服务器更新

相比定时轮询，事件驱动具备三大优势：

1. 零延迟：变更即同步，理论延迟仅受网络和磁盘 IO 限制。
2. 低开销：无变更时不消耗 CPU 和网络资源。
3. 精准增量：rsync 只传输实际变化的文件块，带宽占用极低。

---

三、方案选型：Shell 脚本 vs lsyncd

对比维度	inotify + rsync 脚本	lsyncd
实现复杂度	低（纯 Shell）	中（Lua 配置）
防抖/合并能力	❌ 需手动实现	✅ 内置智能合并
并发控制	❌ 易产生进程风暴	✅ 内置队列与限流
断线重连	❌ 需额外处理	✅ 自动重试
日志与监控	基础	完善（支持状态查询）
适用场景	学习验证、低频简单同步	生产环境首选

📌 选型建议 ：生产环境直接使用 lsyncd 。Shell 脚本方案仅适合理解原理或在极端受限环境中临时使用。未经防抖处理的 inotify 脚本，在批量写入（如 npm run build）时会瞬间 fork 出成百上千个 rsync 进程，直接打爆服务器。

---

四、方案一：inotify + rsync 脚本（理解原理）

1. 安装 inotify-tools

# CentOS/RHEL
sudo yum install -y inotify-tools

# Ubuntu/Debian
sudo apt install -y inotify-tools

2. 基础监控脚本

#!/bin/bash
WATCH_DIR="/data/build/dist/"
REMOTE="deploy@192.168.1.100:/var/www/html/"
SSH_KEY="$HOME/.ssh/nginx_deploy_key"

inotifywait -m -r -e modify,create,delete,move \
    --format '%w%f %e' "$WATCH_DIR" | while read file event; do
    
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $event: $file"
    
    # ⚠️ 此处仅为演示，生产环境必须加防抖！
    rsync -avz --delete \
        -e "ssh -i $SSH_KEY -o StrictHostKeyChecking=accept-new" \
        "${WATCH_DIR}" "${REMOTE}"
done

3. ⚠️ 致命缺陷与改进方向

上述脚本在 npm run build 等批量操作时，每个文件的写入都会触发一次完整 rsync，导致：

• 进程数爆炸，系统负载飙升
• 大量重复传输，带宽浪费
• 目标端频繁写入，IO 抖动

改进思路：引入事件队列 + 延迟合并。收到事件后不立即同步，而是等待一个短暂窗口期（如 1-2 秒），将窗口内的所有事件合并为一次 rsync 调用。这正是 lsyncd 的核心价值。

---

五、方案二：lsyncd 生产级实时推送（推荐）

lsyncd 是专为实时同步设计的守护进程，内置了事件合并、并发控制、断线重试等生产必备能力。

1. 安装 lsyncd

# CentOS/RHEL (EPEL)
sudo yum install -y epel-release && sudo yum install -y lsyncd

# Ubuntu/Debian
sudo apt install -y lsyncd

2. 配置文件 /etc/lsyncd.conf.lua

settings {
    logfile      = "/var/log/lsyncd.log",
    statusFile   = "/var/log/lsyncd.status",
    maxDelays    = 1000,      -- 最大累积事件数，超过则立即触发同步
    maxProcesses = 4,         -- 最大并发 rsync 进程数
    insist       = true,      -- 目标不可达时持续重试，不退出
}

sync {
    default.rsyncssh,
    source    = "/data/build/dist/",
    host      = "deploy@192.168.1.100",
    targetdir = "/var/www/html/",
    delay     = 1,            -- ⭐ 关键：1秒防抖窗口，合并批量事件
    delete    = true,         -- 保持目标与源一致（谨慎使用）
    
    rsync = {
        binary   = "/usr/bin/rsync",
        archive  = true,
        compress = true,
        verbose  = false,
        _extra   = { "--chown=www-data:www-data" }  -- 自动修正权限
    },
    
    ssh = {
        identityFile = "/home/deploy/.ssh/nginx_deploy_key",
        port         = 22,
        _extra       = { "-o", "StrictHostKeyChecking=accept-new" }
    }
}

3. 启动与管理

sudo systemctl enable --now lsyncd

# 查看实时状态
sudo tail -f /var/log/lsyncd.log

# 查看同步队列状态
cat /var/log/lsyncd.status

4. 多目标扇出推送

Nginx 集群通常有多台服务器，lsyncd 原生支持多目标：

-- 定义多个 sync 块即可
sync { default.rsyncssh, source="/data/build/dist/", 
       host="deploy@192.168.1.100", targetdir="/var/www/html/", delay=1 }

sync { default.rsyncssh, source="/data/build/dist/", 
       host="deploy@192.168.1.101", targetdir="/var/www/html/", delay=1 }

sync { default.rsyncssh, source="/data/build/dist/", 
       host="deploy@192.168.1.102", targetdir="/var/www/html/", delay=1 }

---

六、⚠️ 生产环境必知的五大避坑指南

1. inotify watch 数量上限

默认值通常为 8192，大型前端项目节点数轻松超限，导致监控静默失效：

# 临时调整
sudo sysctl fs.inotify.max_user_watches=524288

# 永久生效
echo 'fs.inotify.max_user_watches=524288' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

2. --delete 的安全边界

实时同步中 --delete 风险更高。务必确保：

• 目标目录专用于本次同步，不含用户上传文件、SSL 证书等非托管内容
• 首次启用前先用 delete = false 观察日志，确认同步行为符合预期
• 考虑使用 exclude 保护关键路径：exclude = { '.htaccess', 'uploads/', '*.pem' }

3. 构建过程的中间态问题

npm run build 会先清空 dist 再逐步写入。如果 inotify 在清空后立即触发同步，目标端可能被短暂清空。

解决方案：

• 构建输出到临时目录，完成后原子 mv 到监控目录
• 或使用 lsyncd 的 delay 参数（≥2秒），跳过构建中间态

4. SSH 免密是前置条件

实时推送完全无人值守，必须提前配置好 SSH 密钥免密认证。参考本系列《Nginx-rsync客户端免密》文章完成配置。

5. 监控与告警

lsyncd 不会因单次同步失败而退出（insist=true），但可能长期处于错误状态。建议：

• 定期解析 /var/log/lsyncd.status 检查队列积压
• 对日志中的 ERROR、FAIL 关键字设置告警
• 配合 Prometheus + node_exporter 监控 inotify watch 使用率

---

七、性能调优参考

参数	推荐值	说明
delay	1~3秒	平衡实时性与合并效果，构建密集场景适当增大
maxProcesses	2~8	根据目标服务器数量和带宽调整，避免过载
maxDelays	500~2000	防止事件堆积过久，超过阈值强制触发
compress	true	文本资源开启，二进制大文件关闭（压缩收益低且耗CPU）
bwlimit	按需设置	共享带宽环境下限制 rsync 速率，避免影响业务

---

八、结语

感谢您的阅读！如果你有任何疑问或想要分享的经验，请在评论区留言交流！