gsync 文件同步工具部署手册

基于 Go + gRPC 的双向文件同步工具（files-mirror / gsync），本文记录从编译到两端联调的完整过程。

源码：/home/zbc/code_pangu/files-mirror
服务器公网 IP：43.173.92.61（内网 192.168.3.104）
同步目录：Linux /home/zbc/micode/GeneralAndroid ↔ Windows D:/zbc/GeneralAndroid

架构说明

[Linux agent]  ──┐
                 ├──► [gsync server :7443] ◄──── [Windows agent]
                 └─── (本机回环)

server：中转节点，不存储文件，只转发 agent 之间的同步消息。agent 连 server，server 路由消息。
agent：运行在每台机器上，监控本地目录变化，通过 server 与对端 agent 双向同步。
同步模式：realtime_watch=true 时用 fsnotify 监听文件变化实时推送，fallback_interval 作为兜底轮询。

一、Linux 端部署（server + agent）

1.1 编译

cd /home/zbc/code_pangu/files-mirror
 
# Linux 版（本机）
go build -o build/gsync ./cmd/gsync
 
# Windows 版（交叉编译，用于给 Windows 机器）
GOOS=windows GOARCH=amd64 go build -o build/gsync.exe ./cmd/gsync

1.2 安装 server

# 创建系统用户（已存在则跳过）
sudo useradd --system --home /nonexistent --shell /usr/sbin/nologin gsync
 
# 创建目录
sudo install -d -m 755 /opt/gsync/bin /opt/gsync/config/tls
sudo install -d -m 755 /var/log/gsync /var/lib/gsync/chunk-cache
 
# 安装二进制
sudo install -m 755 build/gsync /opt/gsync/bin/gsync
 
# 安装 TLS 证书（项目自带自签名证书）
sudo install -m 644 config/tls/server.cert.pem /opt/gsync/config/tls/server.cert.pem
sudo install -m 640 config/tls/server.key.pem  /opt/gsync/config/tls/server.key.pem
sudo chown root:gsync /opt/gsync/config/tls/server.key.pem
 
# 日志/缓存目录授权
sudo chown -R gsync:gsync /var/log/gsync /var/lib/gsync/chunk-cache

1.3 server 配置文件

/opt/gsync/config/server.yaml：

addr: "0.0.0.0:7443"
log_file: "/var/log/gsync/server.log"
cert_file: "/opt/gsync/config/tls/server.cert.pem"
key_file:  "/opt/gsync/config/tls/server.key.pem"
chunk_cache_enabled: true
chunk_cache_dir: "/var/lib/gsync/chunk-cache"

1.4 server systemd 服务

/etc/systemd/system/gsync-server.service：

[Unit]
Description=GSync server (gRPC file mirror)
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=gsync
Group=gsync
WorkingDirectory=/opt/gsync
ExecStart=/opt/gsync/bin/gsync server --config /opt/gsync/config/server.yaml
Restart=always
RestartSec=3
LimitNOFILE=1048576
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
ReadWritePaths=/var/log/gsync /var/lib/gsync
 
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now gsync-server.service
 
# 验证
curl -fsS http://127.0.0.1:7443/healthz          # 应返回 ok
curl -s http://127.0.0.1:7443/api/admin/summary  # 查看连接状态

1.5 Linux agent 配置文件

/home/zbc/code_pangu/files-mirror/config/agent-linux.yaml：

client_id: linux-home
log_level: info
realtime_watch: true
watch_debounce_ms: 300
fallback_interval: "30s"
 
server:
  addr: "127.0.0.1:7443"      # 本机 agent 用回环地址，避免云服务器 NAT 回环问题
  tls:
    insecure_skip_verify: true # 自签证书跳过校验
 
roots:
  - dir_id: general-android
    path: /home/zbc/micode/GeneralAndroid
 
pairs:
  - peer_id: win-laptop
    local_dir_id: general-android
    peer_dir_id: general-android

关键点：server 和 agent 在同一台机器时，agent 必须用 127.0.0.1 而不是公网 IP。云服务器的公网 IP 通常是 NAT 地址，机器本身不持有该 IP，从本机发往公网 IP 的包无法回环，导致连接一直卡在 Establishing gRPC connection...。

1.6 Linux agent systemd 服务

/etc/systemd/system/gsync-agent.service：

[Unit]
Description=GSync agent (linux-home)
After=network-online.target gsync-server.service
Wants=network-online.target
 
[Service]
Type=simple
User=zbc
WorkingDirectory=/home/zbc/code_pangu/files-mirror
ExecStart=/opt/gsync/bin/gsync agent --config /home/zbc/code_pangu/files-mirror/config/agent-linux.yaml
Restart=always
RestartSec=5
 
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now gsync-agent.service
 
# 验证 agent 已连上
curl -s http://127.0.0.1:7443/api/admin/summary | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print('connected:', d['hub']['connected']); [print(' -',c['id']) for c in d['hub']['clients']]"
# 期望输出：
# connected: 1
#  - linux-home

1.7 防火墙

sudo ufw allow 7443/tcp
sudo ufw status | grep 7443

如果是云服务器，还需要在云控制台安全组开放 TCP 7443 inbound。

二、Windows 端部署（agent）

2.1 获取文件

从 Linux 机器拷贝以下两个文件到 Windows（通过 scp、U盘、共享目录均可）：

文件	Linux 路径
`gsync.exe`	`/home/zbc/code_pangu/files-mirror/build/gsync.exe`
`agent-win.yaml`	`/home/zbc/code_pangu/files-mirror/config/agent-win.yaml`

也可以直接打包传输：

# Linux 上打包
mkdir -p /tmp/gsync-win
cp build/gsync.exe config/agent-win.yaml /tmp/gsync-win/
cd /tmp && zip -r gsync-win.zip gsync-win/
# 然后把 /tmp/gsync-win.zip 传到 Windows

2.2 Windows 目录结构

解压后放到 D:\gsync\：

D:\gsync\
  gsync.exe
  agent-win.yaml

2.3 Windows agent 配置文件

agent-win.yaml（已预置，内容如下）：

client_id: win-laptop
log_level: info
realtime_watch: true
watch_debounce_ms: 300
fallback_interval: "30s"
 
server:
  addr: "43.173.92.61:7443"   # 公网 IP
  tls:
    insecure_skip_verify: true
 
roots:
  - dir_id: general-android
    path: D:/zbc/GeneralAndroid
 
pairs:
  - peer_id: linux-home
    local_dir_id: general-android
    peer_dir_id: general-android

pairs 配置必须互为镜像：Linux 端 peer_id: win-laptop，Windows 端 peer_id: linux-home，dir_id 名称对应。

2.4 创建同步目录

确保 D:\zbc\GeneralAndroid\ 目录已存在，不存在则新建：

New-Item -ItemType Directory -Force -Path "D:\zbc\GeneralAndroid"

2.5 启动 agent

打开 PowerShell 或 CMD，进入 D:\gsync\：

cd D:\gsync
.\gsync.exe agent --config agent-win.yaml

连接成功日志：

[INFO] gRPC connection established
[INFO] Stream opened, sending handshake...
[INFO] Handshake complete, agent connected
[INFO] Realtime watch enabled debounce=300ms fallback=30s
[INFO] Sync enabled with 1 pair(s), mode=realtime fallback=30s

日志默认写入 D:\gsync\logs\agent.log.YYYY-MM-DD。

2.6 Windows 开机自启（计划任务）

在 管理员 PowerShell 中执行：

$action  = New-ScheduledTaskAction `
    -Execute "D:\gsync\gsync.exe" `
    -Argument "--config D:\gsync\agent-win.yaml" `
    -WorkingDirectory "D:\gsync"
 
$trigger  = New-ScheduledTaskTrigger -AtLogon
$settings = New-ScheduledTaskSettingsSet `
    -RestartOnIdle `
    -RunOnlyIfNetworkAvailable
 
Register-ScheduledTask `
    -TaskName "gsync-agent" `
    -Action $action `
    -Trigger $trigger `
    -Settings $settings `
    -RunLevel Highest

三、验证双向同步

两端 agent 都连上 server 后，在 Linux 端查看状态：

curl -s http://127.0.0.1:7443/api/admin/summary | python3 -m json.tool
# hub.connected 应为 2，clients 应包含 linux-home 和 win-laptop

测试 Linux → Windows：

echo "hello from linux" > /home/zbc/micode/GeneralAndroid/sync-test.txt

几秒内 Windows 的 D:\zbc\GeneralAndroid\sync-test.txt 应出现相同内容。

测试 Windows → Linux：

在 Windows 新建或修改一个文件，Linux 端应同步收到。

四、日常运维

查看状态

# server 服务状态
sudo systemctl status gsync-server
 
# agent 服务状态
sudo systemctl status gsync-agent
 
# 实时日志
sudo journalctl -u gsync-server -f
sudo journalctl -u gsync-agent -f
 
# 管理面板（浏览器）
http://43.173.92.61:7443/

重启

sudo systemctl restart gsync-server
sudo systemctl restart gsync-agent

升级二进制

cd /home/zbc/code_pangu/files-mirror
 
# 重新编译
go build -o build/gsync ./cmd/gsync
GOOS=windows GOARCH=amd64 go build -o build/gsync.exe ./cmd/gsync
 
# 覆盖安装 Linux 版
sudo install -m 755 build/gsync /opt/gsync/bin/gsync
sudo systemctl restart gsync-server
sudo systemctl restart gsync-agent
 
# 验证
curl -fsS http://127.0.0.1:7443/healthz

Windows 端：停止运行中的 gsync.exe，替换新文件，重新启动即可。

五、配置文件速查

文件	用途
`/opt/gsync/config/server.yaml`	server 运行配置
`/home/zbc/code_pangu/files-mirror/config/agent-linux.yaml`	Linux agent 配置
`/home/zbc/code_pangu/files-mirror/config/agent-win.yaml`	Windows agent 配置（传给 Windows 端）
`/opt/gsync/config/tls/server.cert.pem`	TLS 证书（自签，仅做加密，不验证域名）
`/etc/systemd/system/gsync-server.service`	server systemd 单元
`/etc/systemd/system/gsync-agent.service`	Linux agent systemd 单元

六、常见问题

Q：agent 日志一直显示 Establishing gRPC connection... 不成功

本机 agent 连公网 IP 时云服务器 NAT 回环失败。把 server.addr 改为 127.0.0.1:7443 即可。

Q：Windows 连不上

检查云控制台安全组是否开放 TCP 7443 inbound。
确认 server.addr 用公网 IP 43.173.92.61:7443，不要用内网 IP。
检查 agent-win.yaml 中 peer_id 是否与 Linux agent 的 client_id 一致（linux-home）。

Q：如何增加新的同步目录

在两端的 agent 配置里各加一个 roots 条目和 pairs 条目，dir_id 两边对应，重启 agent 生效。

Q：大文件同步慢

提高并行分片数：

# Linux
sudo systemctl edit gsync-agent
# 添加：
# [Service]
# ExecStart=
# ExecStart=/opt/gsync/bin/gsync agent --config ... --chunk-send-conns 4
 
# Windows
.\gsync.exe agent --config agent-win.yaml --chunk-send-conns 4

Quartz 4

Explorer

gsync 文件同步工具部署手册

gsync 文件同步工具部署手册

架构说明

一、Linux 端部署（server + agent）

1.1 编译

1.2 安装 server

1.3 server 配置文件

1.4 server systemd 服务

1.5 Linux agent 配置文件

1.6 Linux agent systemd 服务

1.7 防火墙

二、Windows 端部署（agent）

2.1 获取文件

2.2 Windows 目录结构

2.3 Windows agent 配置文件

2.4 创建同步目录

2.5 启动 agent

2.6 Windows 开机自启（计划任务）

三、验证双向同步

四、日常运维

查看状态

重启

升级二进制

五、配置文件速查

六、常见问题

Graph View

Table of Contents