企业官网建设流程全解析

free-stockdb断点续传机制详解：同步中断后重跑，数据零丢失

【免费下载链接】free-stockdb面向 A 股日K、分钟K与ETF分钟数据的本地量化引擎，集成增量同步、本地缓存、复权、批量查询、回测与指标计算。项目地址: https://gitcode.com/GitHub_Trending/fr/free-stockdb

free-stockdb 是一款面向 A 股日K、分钟K 与 ETF 分钟数据的本地量化数据引擎，其内置的数据同步工具原生支持断点续传：同步中途断网、断电、手动退出后，再次运行只需重跑未完成的部分，已校验通过的数据不会重复下载，从机制上保证数据零丢失。本文带你从使用者视角理解这套机制，让你第一次全量同步时也能放心挂机。

为什么全量同步必须有断点续传

A 股全市场数据（日线 + 分钟线，Zstd 压缩后约 5~20GB）首次同步耗时长，以下情况几乎一定会发生：

💡 一句话总结：free-stockdb 的断点续传不需要你记录"传到了哪"，文件落盘本身即是进度。

断点续传是如何实现的：三层防线

整个机制围绕 docs/DATA_SOURCE.md 中定义的镜像清单协议实现，核心源码见 cpp/src/updater.cpp。

1️⃣ 文件级清单：manifest.txt 定义"应该有什么"

每个数据镜像根目录都带一份manifest.txt清单，每行格式为：

<sha256> <文件大小(字节)> <相对路径>

同步器每次运行时先读取清单（HTTP 镜像或本地目录均支持），逐项与本地./data目录比对。这相当于把"下载多少文件、每个文件多大、内容指纹是什么"全部写在明处，进度判断不依赖任何额外状态文件。

2️⃣ 逐文件校验：已完成的自动跳过

对清单中的每一个文件，同步器检查本地文件是否同时满足三个条件：

• 文件已存在
• 字节大小与清单一致
• SHA-256 指纹与清单一致

三者全部命中即判定该文件"已完成"，直接跳过（见updater.cpp中sync_incremental()的比对逻辑）。因此中断重跑时，已经传完且校验通过的文件一个字节都不会重复传输，这是"增量同步 + 断点续传"的共同基础。

3️⃣ 临时文件原子替换：中断不会产生半截文件

这是保证"数据零丢失"最关键的一层设计：

下载中：目标名.part（临时文件，可随时删除重来） 校验后：rename 原子替换为正式文件名 校验失败：删除 .part 临时文件，下一轮自动重传

• 文件写入前先落盘为*.part临时文件；
• 下载完成后再次校验大小与 SHA-256，失败即删除临时文件、记入失败统计，不影响其他文件；
• 校验通过后通过rename原子操作替换正式文件——要么完整替换成功，要么保持旧文件不变，磁盘上永远不会出现"传了一半"的正式数据文件。

所以哪怕正在下载第 3000 个文件时断电，重启后重跑：前 2999 个文件秒过校验，第 3000 个文件从.part重新拉取，其余照常进行。

同步中断后怎么重跑：只需双击，再等一会

面向使用者的操作非常简单，以 Windows 发行包为例（详见 先看！这个！！使用说明.txt）：

1. 退出stockdb.exe（数据服务）；
2. 双击【数据更新.exe】开始同步；
3. 中断后再次双击运行同一个工具即可——官方说明明确支持**"可多次退出/重启运行，直到完全同步"**；
4. 每轮结束会打印 Sync Summary：清单文件数、本次更新数、失败数、传输字节数、耗时，方便确认进度。

Sync Summary: - Files in manifest: 8600 - Updated files: 12 - Failed files: 0 - Transferred bytes: 345,210,336 - Time Elapsed: 86.4 seconds

第一轮Updated files可能很大，重跑时趋近于 0——这正是断点续传生效的直观信号。

同步完成后，如何验证数据完整性

除了同步时自动校验，工具还提供独立的完整性检查模式（入口见 cpp/tools/main_updater.cpp）：

• 带--verify参数运行时，同步器会重新拉取清单，对本地每一个已同步文件逐一复核大小与 SHA-256；
• 任何一项不符都会打印[Updater] Verification failed: ...并以非零码退出；
• 复核不通过的文件，下一轮--sync会自动重传覆盖。

配合清单中 SHA-256 的覆盖范围，可以回答一个常见疑虑："我上次同步中途断网过，现在的数据能用吗？"——用校验模式确认一遍即可，通过即代表与镜像逐字节一致。

同步完成后的数据长什么样

数据全部落盘到./data后，可双击 数据网页版.html 在浏览器中直接查看多周期行情，无需写任何代码：

图中看板背后的数据，就是经由上述"清单比对 + 临时文件校验 + 原子替换"流程同步到本地的——同步层与查询层完全解耦，离线状态下本地查询、回测照常可用。

最佳实践清单 📌

延伸阅读

• 镜像清单协议与校验规则：docs/DATA_SOURCE.md
• 断点续传与校验核心实现：cpp/src/updater.cpp
• 同步工具命令行入口（--sync/--verify）：cpp/tools/main_updater.cpp
• 数据源配置：sync_url.txt
• 新手上手步骤：先看！这个！！使用说明.txt

总结：free-stockdb 的断点续传 = 清单驱动的逐文件指纹比对 +.part临时文件原子替换 + 中断后原地重跑。三层机制叠加，让"同步中断"从事故退化为普通暂停——重跑一次，数据依然零丢失。

【免费下载链接】free-stockdb面向 A 股日K、分钟K与ETF分钟数据的本地量化引擎，集成增量同步、本地缓存、复权、批量查询、回测与指标计算。项目地址: https://gitcode.com/GitHub_Trending/fr/free-stockdb