核心用法
Actual Budget API 是开源记账软件 Actual Budget 的官方 Node.js SDK，采用无头模式运行，通过环境变量配置服务器连接后，可在本地缓存预算数据并执行各类财务操作。主要功能模块包括：预算概览查询（getBudgetMonths/getBudgetMonth）、账户管理（创建/关闭/余额查询）、交易处理（导入支持自动去重和规则匹配、更新、ActualQL 复杂查询）、分类与商家管理、预算金额设定、自动规则（Rules）与定期账单（Schedules），以及 GoCardless/SimpleFIN 银行同步。
显著优点
1. 官方维护：由 Actual Budget 核心团队开发，API 与产品功能同步更新
2. 完整功能覆盖：涵盖个人财务管理的全链路操作，从数据导入到自动化规则
3. ActualQL 查询语言：类似 MongoDB 的链式查询语法，支持分组聚合、模糊搜索等复杂分析
4. 自托管友好：专为私有化部署设计，支持端到端加密和自签名证书
5. 交易去重机制：importTransactions 内置重复检测，适合银行数据自动化导入
潜在缺点与局限性
- 部署门槛高：必须自建 Actual Budget 服务器，配置同步 ID、密码等环境变量
- Node.js 专用：仅限 JavaScript/TypeScript 生态，无 Python/Go 等语言官方支持
- 本地状态管理：需手动处理 init → downloadBudget → shutdown 生命周期，易因遗漏 shutdown 导致资源泄漏
- 金额单位为分：所有金额需整数转换（$1.23 → 123），增加开发心智负担
- 错误处理不透明：部分操作失败时返回信息较简略，需结合服务器日志排查
适合人群
- 已使用或计划自托管 Actual Budget 的技术用户
- 需要将银行数据自动导入预算系统的开发者
- 希望构建个人财务自动化工作流（如定时同步、支出分析报表）的工程师
常规风险
- 凭据泄露风险：ACTUAL_PASSWORD、ACTUAL_ENCRYPTION_PASSWORD 等敏感信息需妥善保管
- 自签名证书误配：若不当禁用 TLS 验证或配置错误的 CA 证书，存在中间人攻击风险
- 数据同步冲突：多客户端同时修改预算可能导致同步冲突，需遵循 sync() 调用规范
- 预算数据本地缓存：ACTUAL_DATA_DIR 目录需设置适当权限，避免其他用户读取财务数据