Excel文件同步功能支持将Excel数据与系统数据库进行双向同步，适用于以下场景：

业务人员在Excel中维护数据，需要自动同步到数据库

系统数据库中的数据需要定期导出到Excel报表

多台电脑上的Excel文件需要与同一数据库保持同步

核心特性

增量同步

只传输变化的数据行，传输量减少99%

双向同步

支持推送(A=>B)和拉取(B=>A)两个方向

加密传输

AES-CBC加密 + 会话密钥协商 + Token认证

_sync_id主键对应

通过数据库主键ID建立Excel行与数据库行的稳定对应，修改/删除精准识别

查重更新

基于指定字段判断重复，支持只更新变化字段（_sync_id缺失时退化匹配）

定时执行

支持定时任务和文件监听自动同步

Web配置界面

双击即可启动浏览器配置，无需手动编辑配置文件

两种方案

方案A：服务器本地同步

当Excel文件位于服务器本地（或局域网共享目录）时，Go后端直接读取文件并入库，无需客户端。

适用场景：服务器Windows运行，Excel文件在同一台机器或共享目录上。

方案B：远程客户端同步

当Excel文件不在服务器上时，使用Go编译的同步客户端，通过加密通道与服务器通信。

适用场景：远程电脑上的Excel文件需要与服务器数据库同步。

方案A使用方法

1. 配置同步

进入项目表的配置页面，切换到"Excel文件同步"标签页：

输入服务器本地Excel文件路径（如 D:\data\report.xlsx）

点击"测试文件"验证路径是否正确

选择工作表

勾选需要同步的字段

配置字段映射（Excel列名 → 数据库字段名）

保存配置

2. 手动同步

点击"立即同步"按钮，后端直接读取Excel文件并入库。

3. 定时同步

在计划任务中添加Excel同步类型的任务，选择要同步的项目，设置执行周期。

方案B使用方法

1. 生成同步链接

在项目表的"Excel文件同步"标签页中，点击"生成同步链接"按钮，系统会生成：

推送地址(A=>B)：用于客户端向服务端推送数据

拉取地址(B=>A)：用于客户端从服务端拉取数据

同步Token：客户端认证凭证

项目表名：目标数据表标识

2. 配置客户端

根据同步方向，点击"复制推送配置(A=>B)"或"复制拉取配置(B=>A)"，将内容保存为客户端目录下的 config.json 文件，修改 filePath 为本地Excel路径：

{ ”serverUrl”: ”https://your-server.com/v1/SyncExcelRows”, ”syncToken”: ”从后台复制的Token”, ”tablename”: ”从后台复制的表名”, ”filePath”: ”C:\\data\\report.xlsx”, ”sheet”: ””, ”fields”: ””, ”mapping”: ””, ”interval”: 300, ”cacheDir”: ””, ”syncDirection”: ”push”}

配置项说明

3. 运行客户端

直接双击 excelsyncclient.exe，程序会：

读取当前目录下的 config.json

如果 filePath 为空，自动搜索当前目录下的xlsx文件（只有一个时自动使用）

如果缺少必要配置（serverUrl/syncToken），自动打开浏览器配置界面

Web配置界面

当配置不完整或使用 -gui 参数启动时，自动打开浏览器配置界面：

excelsyncclient.exe配置不完整时自动进入Web UIexcelsyncclient.exe -gui# 强制启动Web配置界面excelsyncclient.exe -port 18280# 指定Web界面端口（默认18280）

Web界面功能：

📊 同步状态面板：实时显示总行数、已同步、新插入、已更新、已删除、已跳过

⚙️ 连接配置：填写服务器地址、Token、表名、同步方向、定时间隔

📄 Excel文件选择：自动列出当前目录下的xlsx文件，点击即选

📋 同步日志：实时显示同步结果

🔄 一键操作：立即同步 / 启动定时同步 / 停止定时

命令行方式

单次同步excelsyncclient.exe -config config.json# 定时同步（每5分钟）excelsyncclient.exe -config config.json -interval 300# 监听文件变化自动同步excelsyncclient.exe -config config.json -watch# 强制全量同步（忽略缓存）excelsyncclient.exe -config config.json -full

命令行参数

同步方向详解

A=>B 推送模式 (syncDirection: "push")

以客户端Excel数据为准，将本地xlsx的变化推送到服务端数据库。

流程：

客户端读取Excel文件，对每行数据计算SHA256哈希

与本地SQLite缓存对比，找出新增和变化的行

对比缓存与当前Excel的 _sync_id 集合，找出被删除的行

只发送变化行和删除行到服务端（加密传输）

服务端优先按 _sync_id 精确更新，无 _sync_id 时按查重字段处理；删除行按 _sync_id 物理删除

同步成功后更新本地缓存

适用场景：Excel是数据源，业务人员在Excel中维护数据。

B=>A 拉取模式 (syncDirection: "pull")

以服务端数据库为准，将数据库的变化写回客户端xlsx。

流程：

客户端发送上次同步的数据哈希到服务端

服务端对比当前数据哈希，无变化则返回空

有变化时返回全部数据行（含 _sync_id 字段，即数据库主键ID）

客户端读取本地xlsx，优先按 _sync_id 匹配已有行，无 _sync_id 时按查重字段退化匹配

更新变化的单元格，新增行追加到末尾

Excel中存在但服务端已不存在的 _sync_id 对应的行被删除

保存xlsx文件并更新缓存

适用场景：数据库是数据源，需要将数据更新到本地Excel报表。

如果文件正被excel软件打开，则不可写入，会先写到临时文件中，在关闭excel后再写入到正式文件：

_sync_id 主键对应机制

为什么需要 _sync_id

传统基于查重字段(cczd)匹配存在两个根本缺陷：

修改变新建：查重字段值被修改后，匹配失败导致旧行残留+新行追加

删除无法识别：无任何机制判断哪些行被删除，导致已删除行永久残留

_sync_id 列存储数据库行主键ID，作为Excel行与数据库行的稳定唯一对应关系，不受业务字段修改影响。

_sync_id 列的维护

拉取模式：服务端 PullExcelRows 返回数据时自动包含 _sync_id 字段，客户端写入Excel时自动维护该列（放在最后一列）

推送模式：客户端读取Excel时自动读取 _sync_id 列，发送给服务端按主键更新/删除

匹配优先级

服务端 SyncExcelRows 和客户端 writeRowsToExcel 均按以下优先级匹配：

优先按 _sync_id 匹配（最稳定，按数据库主键精确对应）退化按查重字段匹配（当 _sync_id 缺失时，如首次同步或旧Excel文件）追加为新行（无任何匹配时）

首次使用建议

推送模式下首次同步时Excel无 _sync_id 列，会全量推送插入。建议首次使用时先执行一次拉取让Excel获得 _sync_id 列，之后推送/拉取都能精确识别修改和删除。

若不便先拉取，推送模式也会在后续同步中通过查重字段建立对应关系，但修改/删除的识别精度会降低（依赖查重字段值不变）。

增量同步原理

传统全量同步每次传输整个Excel文件（base64编码→JSON→AES加密），即使只改了几行也要传输完整文件。

增量同步使用SQLite本地缓存+行级SHA256哈希对比：

每行数据 → 字段名排序拼接 → SHA256 → 与缓存对比 → 只发送变化行

无数据变化时零传输，直接跳过。

安全机制

Token认证：每个项目生成唯一的同步Token，请求时通过 X-Sync-Token 头部验证

会话密钥协商：客户端请求 /v1/getsession 获取临时会话密钥

AES-CBC加密：请求体和响应体均使用AES-CBC加密，每次请求生成随机IV

无JWT依赖：同步接口使用独立的Token认证，不依赖用户登录JWT

API接口

SyncExcelRows 请求结构

{ ”rows”: [{”_sync_id”: 1, ”姓名”: ”张三”, ”年龄”: ”25”}, ...], ”deletedRows”: [{”_sync_id”: 5}, {”_sync_id”: 8}], ”mode”: ”increment”, ”totalRows”: 100}

rows：新增/修改的行数据，含 _sync_id 时按主键更新，否则按查重字段处理

deletedRows：被删除的行，仅含 _sync_id，服务端按主键物理删除

mode：full(全量) / increment(增量)

totalRows：Excel文件总行数（用于日志）

PullExcelRows 响应结构

{ ”changed”: true, ”dataHash”: ”abc123...”, ”rows”: [{”_sync_id”: 1, ”姓名”: ”张三”, ”年龄”: ”25”}, ...], ”totalRows”: 100, ”cczdFields”: [”姓名”], ”gxsjFields”: [”年龄”]}

rows：中每行含 _sync_id 字段（数据库主键ID），客户端据此建立行对应

cczdFields：gxsjFields 为中文名，供客户端无 _sync_id 时退化匹配

常见问题

Q: 首次同步很慢？

A: 首次同步SQLite缓存为空，会自动退化为全量同步，后续同步只传输变化行。

Q: Excel列名和数据库字段名不一致怎么办？

A: 在配置中使用mapping字段映射，格式为Excel列名=数据库字段名，多个用逗号分隔。

Q: 如何处理重复数据？

A: 系统优先按 _sync_id（数据库主键）精确匹配。无 _sync_id 时退化按查重字段(cczd)判断。可在项目表配置中设置查重字段和更新字段(gxsj)。

Q: 修改行的数据为什么以前会变成新建？

A: 旧版本基于查重字段匹配，查重字段值被修改后匹配失败导致旧行残留+新行追加。新版引入 _sync_id 主键列，按数据库主键精确对应，不受业务字段修改影响。建议首次使用时先执行一次拉取让Excel获得 _sync_id 列。

Q: 删除的行会如何处理？

A: 推送模式：Excel删除的行，客户端检测到 _sync_id 缺失，发送删除请求，服务端按主键物理删除。拉取模式：服务端删除的行，客户端检测到 _sync_id 不在服务端返回数据中，从Excel删除对应行。

Q: 客户端缓存损坏怎么办？

A: 删除缓存目录中的 .db 文件，或使用 -full 参数强制全量同步，客户端会自动重建缓存。

Q: 多个客户端同步同一项目会冲突吗？

A: 服务端通过 _sync_id 主键和查重字段保证数据一致性，多个客户端推送的数据会按对应逻辑合并，不会产生重复记录。

Q: 双击exe后没有同步？

A: 双击运行时，如果config.json中缺少filePath，程序会自动搜索当前目录下的xlsx文件；如果缺少serverUrl或syncToken，会自动打开浏览器配置界面，在界面中完成配置后即可同步。

Q: Web配置界面端口被占用怎么办？

A: 程序会自动从默认端口18280开始递增寻找可用端口，无需手动处理。

Q: _sync_id 列可以手动编辑吗？

A: 不建议手动编辑。_sync_id 由系统自动维护，手动修改会导致行对应关系错乱。若不慎损坏，删除该列后执行一次拉取即可重建。