# kp-sticky-notes-sync **Repository Path**: jocundmo/kp-sticky-notes-sync ## Basic Information - **Project Name**: kp-sticky-notes-sync - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-29 - **Last Updated**: 2026-11-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # StickyNotes Sync Windows 后台同步程序(**手动模式**):把 sticky-notes(SQLite 数据库 `Notes.db`)的每一张便签导出为一个 JSON 文件, 对端通过「手动导入」把同步介质(普通目录 / WebDAV)中的文件写回它自己的本地数据库。 无主界面,常驻任务栏托盘图标,提供配置窗口。 - 语言/框架:C# / .NET 8(Windows),WinForms(托盘 + 配置窗口) - 依赖:Microsoft.Data.Sqlite(唯一第三方库) - 详细设计见 [DESIGN.md](DESIGN.md) ## 功能 - **导出:手动 + 可选定时自动**:托盘「手动导出」,或在配置里开启**定时自动导出**(开关 + 间隔分钟数可配,仅导出、不自动导入)。默认关闭。 - **导入:始终手动**:托盘「手动导入」——导入后便签软件不会主动刷新,必须重启才看得到变化,所以自动导入意义不大。 - **同步文件**:每张便签一个 JSON(`note_<机器号>_.json`),包含全部字段 + RTF 内容(Base64);文件名还会追加**标题与便签内容(TEXT 列)的前 100 个字符**便于人工识别,如 `note_5d89d927_1_<标题>_<内容前100字>.json`(空段省略、非法字符替换为 `_`;身份识别仍只看开头的 `note_<机器号>_`,改标题不会影响同步);每个笔记本一个 JSON(`notebook_<机器号>_.json`,文件名同样追加**笔记本名称**,如 `notebook_621572db_1_<名称>.json`)。 - **笔记本(NOTEBOOKS 表)同步**:与便签同一套机制(LWW / ID 映射 / 墓碑)——笔记本新建、改名、删除都会传播;**把便签“移动”到另一笔记本**(修改便签的 NOTEBOOK 字段)也会同步,对端便签字段与 NOTEBOOKS 表都正确(自动补行,不产生重复行)。 - **同步介质**: - 普通目录(本地 / 网络共享 / NAS 同步目录) - WebDAV(通用实现,Basic 认证,可选忽略 TLS 证书错误;适用于群晖 WebDAV Server、Nextcloud 等) - **冲突处理**:按 `UPDATED`(或 `DELETED`)时间戳后写者胜(便签用数据库时间戳;笔记本表无时间戳,由本机合成并持久化)。 - **删除传播**:墓碑文件标记删除,过期(默认 30 天,可配置)清理。 - **ID 冲突**:机器实例标识 + 自动 ID 映射;同一拷贝镜像场景按 ID+CREATED 识别同源便签,避免重复。 - **开机自启**:写入当前用户注册表 Run 键(可在配置中关闭)。 - **无主界面**:托盘图标常驻;右键菜单:打开配置 / 手动导出 / 手动导入 / 打开同步目录 / 打开日志目录 / 退出。 ## 构建与发布 需要 .NET SDK 8.0 或更高(本机已装 9.0)。 ```powershell # 一键发布(默认自包含单文件 exe,对端无需安装 .NET) ./build.ps1 # 或手动: dotnet publish src/StickyNotesSync/StickyNotesSync.csproj -c Release -r win-x64 ` --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -o publish ``` 产物:`publish/StickyNotesSync.exe`(含运行时与 SQLite 原生库)。 运行测试(无框架控制台;覆盖导出/导入、双向、ID冲突、收养、墓碑、LWW、空库恢复、真实库往返, 以及**多端同步场景**——新建传播、修改传播、并发编辑 LWW、并发新建同 ID、编辑 vs 删除、 删除/墓碑传播、三端收敛、离线重连、重启持久化、旧版本保护、幂等收敛、 以及**笔记本同步**——新建/改名/删除传播、移动便签、并发改名 LWW、同名统一、防复活、多端收敛): ```powershell dotnet run --project tests/SyncTests -c Release ``` ## 部署(两台电脑) 1. 两台电脑都运行同一款便签软件(先各运行一次,确保本机 `Notes.db` 已生成)。 2. 拷贝 `StickyNotesSync.exe` 到两台电脑(例如 `C:\Program Files\StickyNotesSync\`)。 3. 双击启动(或首次通过托盘菜单"打开配置"),在配置窗口里设置: - **数据库路径**:本机便签软件的 `Notes.db` 路径(每台机器填各自的)。 - **同步模式**: - `本地目录`:填同步目录(两端通过同一网络共享 / NAS 目录访问,如 `E:\diskstation\T03.Backup\sticky_notes`,即与便签备份同目录); - `WebDAV`:填服务器地址、用户名、密码(密码用 Windows DPAPI 加密存储)。 - 其余按需调整(墓碑保留天数、导出前等待、**定时自动导出开关与间隔**、开机自启)。 4. 保存后程序应用新配置。**导出**: - 手动:托盘「手动导出」(会先等待"导出前等待"秒数,默认 5 秒,等便签软件把修改写入数据库后再导出,避免刚编辑完就导出到旧数据); - 自动:配置里勾选"启用定时自动导出"并设间隔(如 30 分钟),程序会按间隔自动导出(不等待、不弹提示,仅失败时提示)。**自动仅导出,不会自动导入**。 - **导入**:托盘「手动导入」(建议先关闭便签软件)。 > **重要**:便签软件导入后不会自动刷新界面。建议**先关闭便签软件再「手动导入」**,导入完成后再启动便签软件。 > 首次对接建议:让两台机器从**同一份**便签库起步(先在其中一台建好便签, > 另一台对接前把 `Notes.db` 复制过去一次),可避免"同 ID 但不同内容"的便签被当作两条导入。 > 若两端各自独立建库,同 ID 不同 CREATED 的便签会被视为两条(各自保留),属预期行为。 ## 命令行一次性执行 不启动托盘,执行一次即退出(可配合计划任务/脚本): ```powershell StickyNotesSync.exe --export # 手动导出一次(同样会先等待"导出前等待"秒数) StickyNotesSync.exe --import # 手动导入一次 ``` ## 数据与配置位置 | 内容 | 位置 | |---|---| | 配置 | `%AppData%\StickyNotesSync\config.json` | | ID 映射 | `%AppData%\StickyNotesSync\idmap.json` | | 笔记本同步状态(时间戳/映射) | `%AppData%\StickyNotesSync\notebook_state.json` | | 日志 | `%AppData%\StickyNotesSync\logs\sync-YYYYMMDD.log` | | WebDAV 本地缓存 | `%LocalAppData%\StickyNotesSync\cache\` | ## 常见问题 - **便签位置(LEFT/TOP/WIDTH/HEIGHT/ZORDER)是本机状态,不参与同步**:仅移动/改大小/调层级不会触发导出;导入更新已有便签时也不会覆盖本机位置(新导入的便签才采用文件里的位置)。 - **定时自动导出**:配置里勾选"启用定时自动导出"+ 间隔分钟数(1–1440,默认 30)。程序启动后按间隔自动导出(仅导出,不自动导入;不弹气泡,仅失败时提示);导出前不会等待"导出前等待"时长(该等待只用于手动导出)。保存配置即重启引擎生效。 - **手动导出提示"等待 N 秒…"**:便签软件写入数据库有延迟,导出前默认等待 5 秒(可在配置里改"导出前等待",0 表示不等待),避免刚编辑完立刻导出读到旧数据。 - **手动导入提示"新增 X 条、更新 Y 条"**:导入会如实报告条数。若提示"N 个文件均无需导入",说明同步目录里的文件内容与本机数据库一致(或为本机自己导出的内容)。 - **数据库被清空/便签丢失后如何恢复**:只要同步目录里还有 `note_*.json`,点"手动导入"即可按原 ID 恢复;本机自己导出的文件也会被恢复(旧版只会跳过)。 - **数据库被便签软件占用/锁定**:程序以 busy-timeout 5 秒访问;若便签软件正开着,导出/导入可能失败,请关闭便签软件后重试。 - **把便签“移动”到另一笔记本后对端没变化**:移动 = 修改便签的 NOTEBOOK 字段,走正常便签同步(导出→导入)。对端导入后便签会出现在新笔记本下,且 NOTEBOOKS 表会自动补上该笔记本(不会产生重复行)。 - **笔记本改名/删除**:改名走 LWW 传播(行 ID 不变);删除(行消失)走墓碑传播,对端对应行被删除。NOTEBOOKS 表无时间戳,时间戳由程序合成记录在 `notebook_state.json`,首次同步前的改名会按“后导出者胜”收敛。 - **导入后界面没变化**:便签软件不会自动刷新,请重启便签软件(或先关闭再导入)。 - **便签软件编辑后 UPDATED 未更新**:LWW 语义下该次修改可能不会同步(罕见),属设计边界。 - **WebDAV 服务器兼容性**:按 RFC 4918 通用实现(PROPFIND/GET/PUT/DELETE/MKCOL + Basic)。 若你的服务器行为特殊,日志会给出线索;群晖自签名证书请勾选"忽略 TLS 证书错误"。 - **修改配置后**:保存即应用,无需重启程序。 - **想停止程序**:托盘右键"退出",并可在配置里关闭"开机自动启动"。