local-ledger

一款面向 macOS 和 Windows 的个人记账桌面应用,所有数据都存在本机的加密数据库里,应用不发出任何网络请求。

  • Electron
  • TypeScript
  • React
  • SQLCipher
  • 桌面应用安全
2026 年 11 月的概览页:收入 3,850.00 澳元,支出 3,898.72 澳元;四条预算进度条,其中外出就餐和咖啡已超支;下方是最近五笔交易,左侧边栏列出四个账户。 2026 年 11 月的概览页:收入 3,850.00 澳元,支出 3,898.72 澳元;四条预算进度条,其中外出就餐和咖啡已超支;下方是最近五笔交易,左侧边栏列出四个账户。
概览页:当月收支、预算进度和最近的交易。

关键指标

应用发出的网络请求;端到端测试和打包检查都会读取 Chromium 的网络日志,出现任何请求即失败
0
用 Argon2id 派生密钥的耗时,参数为 64 MiB 内存、3 轮、4 条并行通道,在工作线程中运行
321 ms
这次派生在工作线程中运行时阻塞事件循环的时长;放在主线程上则是 281 ms
7 ms
主密码的最少字符数,依据 NIST SP 800-63B-4 对单因素密码的要求
15

耗时在 2.1 GHz、4 核的 Xeon 上用 Electron 45 测得。解锁不限制尝试次数,因为复制走文件的攻击者根本不受这种限制;拖慢猜测靠的是 Argon2id 的计算代价。 决策记录

问题与目标

local-ledger 是一款数据从不离开本机的个人记账应用。它导入银行的 CSV 文件,用规则给交易分类,设定每月预算,画图表,把一个月的账单导出为 Excel 或 PDF,所有数据都在一个加密数据库里,由一个主密码打开。它没有云同步,不连接银行,忘了密码也无法找回。

规格定下的要求有:整库加密,密钥由 Argon2id 派生;加固过的 Electron 应用,配一套带类型的 IPC 接口;空闲时自动锁定;内置四家澳大利亚银行的文件模板,另有列映射向导;模糊查重、分类规则、带超支提醒的预算、图表、导出、加密备份和深色模式。测试要能证明渲染进程碰不到 Node.js,非法的 IPC 参数会被拒绝,普通 SQLite 打不开数据库,锁定之后数据无法读取。

导出的文件和导入的 CSV 文件放在哪里都是明文。以同一用户身份运行的恶意软件不在防护范围内:保险库打开时它能读取内存,锁定时它能在下次解锁时记下密码。发布的安装包没有代码签名,两个系统在首次启动时都会警告;下载的文件可信与否,取决于用户有没有核对校验和与构建来源证明。

架构

页面运行在 Chromium 的沙箱里,没有 Node.js,由 app://local-ledger 提供,带严格的内容安全策略。它只能通过预加载脚本暴露的带类型的 window.ledger 接口调用保险库,走的是通向一个工具进程(保险库宿主)的专用端口,由宿主用 zod 校验每个参数;主进程接受应用自己页面的两种请求,一个通向保险库宿主的端口和一次锁定。在保险库宿主中,保险库在工作线程里用 Argon2id 从主密码派生出密钥,解开 vault.json 里封存的数据密钥;数据密钥再打开数据库 ledger-<n>.db,它的每一页都由 SQLite3 Multiple Ciphers 按 SQLCipher 4 格式加密。导入、导出和备份也在宿主中进行:CSV 文件经系统的打开对话框(由主进程显示)或拖放到窗口里进来,导出文件只写到用户在系统保存对话框里选定的位置,并且不加密;备份就是加密的数据库本身,外加一个封存的文件头。主进程负责窗口、对话框、打印 PDF 和处理锁定,锁定会结束宿主和页面的进程。

关键决策

  • D013 封存的数据密钥与数据库代次

    数据库用随机生成的 32 字节数据密钥加密;由主密码派生出的密钥再用 AES-256-GCM 封存这把数据密钥,经过认证的文件头绑定了代次和密钥派生参数。因此密码输错时,GCM 校验在碰到数据库之前就会失败,可以和数据库损坏区分开。修改密码时生成新的数据密钥,把数据库复制一份重新加密、校验之后,重命名为下一代;用新的 vault.json 覆盖旧文件是唯一的提交点:在此之前崩溃,旧密码照常可用,之后则以新密码为准。代价是要重写整个数据库,20,000 行用时 7 ms。

  • D047 锁定即结束保险库的进程

    每次解锁、锁定和成功修改密码时,主进程都在一个新视图里重新加载页面并关掉旧视图,旧的渲染进程随之退出(D016)。每次锁定还会结束保险库宿主,也就是持有保险库、数据库、导入和导出的工具进程,它拿过的内容随之释放。清空状态仓库抹不掉 JavaScript 字符串和 DOM 里留下的内容,结束进程会释放它们,但不会覆写。即使保险库已经锁着,锁定操作也会替换页面,这样输入了却没提交的密码也留不下来;端到端测试会断言旧进程确已退出。在 0.2.1 中,保险库在主进程里,一项读取每个进程内存的测试在锁定之后,在 Linux、Windows 和 macOS 的主进程中都找到了导入的文本和数据密钥的一半(至少这些),在 Linux 上还找到了主密码和封存用的密钥。现在锁定之后,主进程里仍有 PDF 导出的页面和键入文本的副本,但没有主密码,宿主最多还会保留数据 30 秒,等进行中的调用结束。

  • D025 用指纹识别重复交易

    导入的每一行都有一个指纹:日期、金额和描述(忽略大小写和空白),再加上它在同一文件的相同行中排第几,在所属账户内唯一,做法与 YNAB 的 import_id 相同。两笔完全相同的真实交易分别是第 1 次和第 2 次出现,所以都会导入,之后有重叠的文件也不会让它们重复。没有精确匹配的行,如果账户里 4 天内有一笔金额相同、尚未被其他行认领的交易,就标为疑似重复;疑似重复默认不勾选,并显示它像哪一笔交易。每次导入是一个 SQLite 事务,记为一个批次,因此可以撤销。

  • D027 把转账识别成一对交易

    两个账户的文件都导入后,同一笔转账会出现两次:一边转出,另一边转入同样的金额。两笔交易要算作一笔转账,必须位于同一币种的不同账户,金额正好相反,日期相差不超过 4 天,因为周五发起的转账可能周二才到账。导入之后,这样的一对要同时满足两点才会自动配对:一是描述显示这是转账,即一方写出了另一方的账户名,或者双方都用了“payment”之类的词;二是没有别的一对与它共用交易,或者同一天的配对能让每笔交易恰好有一个对应方。其他的都留给用户决定。有些应用用一个“转账”类别来处理,可类别一旦选错,就会悄无声息地出错。

  • D009 自定义协议,网络始终关闭

    页面由 app://local-ledger 提供,这个协议在应用就绪之前注册,处理器只响应 GET 请求,拒绝构建目录之外的任何路径;每个响应,包括报错,都带有严格的内容安全策略。新窗口、页面跳转、重定向、webview 和权限请求一律拒绝,应用之外的请求全部取消。拼写检查关闭且不设语言,否则 Chromium 会在启动时从它的 CDN 下载词典。端到端测试和打包检查都会读取 Chromium 的网络日志,出现任何网络请求即失败。

决策记录

难点与解法

  • 没有文档的银行格式

    CommBank、NAB、ANZ 和 Westpac 都提供 CSV 导出,却不公布列格式。每种格式都参照了针对真实导出文件编写的开源解析器,只采用至少两个来源一致的部分,并用这些项目公开的样例文件核对过。由于没有一种格式拿真实导出文件验证过,读取时会接受各来源之间的所有差异:逐字段加引号或完全不加、CRLF 或 LF、字节顺序标记、末尾缺换行、空行、字段两侧的空格。应用认不出的文件会进入列映射向导;npm run csv:shape 只描述文件结构、不含任何数据,可以用来报告应用读不了的格式。

  • 预览五万行

    一次导入最多可达 50,000 行,全部绘制时预览大约要 4 秒,点一个复选框最长要 1 秒才有反应。现在预览只绘制可见的行和上下各二十行,其余用占位元素撑开;每行固定 35 像素高,所以行的位置可以由滚动位置直接算出,各行做了记忆化,点复选框只会重绘它所在的那一行。预览降到约 0.2 秒,复选框约 15 ms。用虚拟列表库要为大约 60 行代码多引入一个依赖;只用 CSS 的 content-visibility 能跳过布局和绘制,却省不掉 React 的计算。

  • 不会执行公式的导出文件

    交易描述来自银行文件,像 =HYPERLINK(...) 这样的描述有可能在导出的工作簿里变成会执行的公式。工作簿由项目自己写的一个小型生成器输出,用 fflate 打包:所有文本单元格都是内联字符串,生成器里根本没有公式元素;文本单元格使用文本格式,以后编辑也不会被当成公式;按 OWASP 的列表,看起来像公式开头的文本还会加上引号前缀。在 LibreOffice 里,这些开头都按原样显示;Excel 和 Numbers 还没有试过。换用 exceljs 要装 193 个包,npm 上的 xlsx 包在那里也已不再更新。