
Actual Budget 26.7.0 版本深度解析CLI 稳定版、Akahu 新西兰银行同步与标签管理增强【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual Budget本地优先的个人财务应用于 2026 年 7 月发布 26.7.0 版本。本版本以实验性功能铺路、稳定性收敛为主线actual-app/cli正式摘掉 experimental 标签成为稳定能力新增新西兰银行同步供应商 Akahu大幅增强标签Tags的显示控制、批量操作与过滤语义并为月支出报告加入可配置平均区间、为折线报告加入趋势线。本文将结合仓库源码与配套文档逐一拆解这些核心变更的实现原理与使用方式帮助读者快速评估升级收益并上手新功能。版本概览26.7.0 改了什么按照 发布文档 的说明本版本的核心主题是新增实验性银行同步供应商、CLI 转正、报告与标签管理增强以及大量修复。发布文摘概括如下银行同步失败状态在刷新与跨设备同步后依然保留Actual CLIactual-app/cli从 experimental 转为稳定标签支持显示/隐藏、批量操作并新增 has any tag / has all tags 过滤器月支出报告支持可配置平均区间折线报告支持趋势线预算组内类别支持按字母快速排序A→Z / Z→A实验性新增新西兰银行同步供应商 Akahu实验性预算自动化Budget AutomationsUI 持续改进并支持移动端实验性金额输入新增移动端计算器Docker 镜像标签为26.7.0自托管用户可直接以actualbudget/actual-server:26.7.0部署升级。实验性功能Akahu 新西兰银行同步26.7.0 通过 PR #6041 引入了面向新西兰用户的实验性银行同步供应商 Akahu。由于该功能仍处于实验阶段Akahu 配置文档 明确提示最新稳定版中可能并不包含全部能力需要按实验性功能启用指南开启实验特性并建议使用nightly镜像获取最新实现。申请 Akahu 凭证接入 Akahu 的第一步是注册并登录 Akahu 账户my.akahu.nz完成以下操作在 Akahu 中关联你的银行账户进入开发者页面my.akahu.nz/developers获取APP ID Token与User Access Token两个凭证若尚未创建个人应用需同意 Akahu 开发者条款并点击 Continue随后完成身份验证并设置多因素认证MFA完成后应用即被创建两个 Token 会展示给你。在 Actual 中链接账户拿到 Token 后在 Actual 中进入More → Bank Sync找到Akahu卡片点击Set up粘贴 App ID 与 User Access Token仍在同一 Bank Sync 页面点击 Akahu 卡片下的Link bank account按提示完成账户关联。源码层面的集成细节从仓库实现看Akahu 集成不止拉取交易这么简单发布说明中还有三项配套优化交易描述兜底为收款方名称PR #8116当 Akahu 交易缺少明确 payee 时使用交易描述作为兜底收款方名避免大量未分类交易陈旧账户自动刷新PR #8115同步前若发现 Akahu 账户数据过期会自动刷新保证拉取到的是最新交易相关实现位于 sync-server/src/app-akahu 目录作为独立的应用模块与 GoCardless、Enable Banking、SimpleFin 等供应商并列存在。标签管理增强显示控制、批量操作与新过滤语义标签功能在 26.7.0 中获得了一组集中增强PR #7919、#7848、#8093显示/隐藏标签用户可自行决定哪些标签出现在界面中配合已有的隐藏能力管理杂乱更好的批量标签操作对多条交易进行批量打标签/去标签时交互与数据处理更可靠新过滤语义引入has any tag任一标签过滤器并将原 has tag 重命名为has all tags全部标签语义边界更清晰——前者匹配命中任意一个指定标签的交易后者要求交易同时具备所有指定标签标签搜索不区分大小写在标签自动补全与搜索中忽略大小写降低输入成本。过滤器在规则引擎中的实现标签过滤器并非仅在 UI 层实现而是进入了规则引擎的算子体系。在 loot-core/src/shared/rules.ts 中字符串类型字段的可用算子列表包含hasTags与hasAnyTagloot-core/src/server/rules/condition.ts 进一步约束了二者的取值行为hasTags/hasAnyTag要求非空字符串作为值hasTags must have non-empty string与contains、matches等算子不同这两个算子不做小写归一化return value原样返回说明标签匹配本身对大小写不敏感的特性由其他环节保证在 loot-core/src/server/transactions/transaction-rules.ts 中二者的查询变换逻辑被显式排除在$transform之外![hasTags, hasAnyTag].includes(op)意味着它们走的是专门的标签匹配路径。配套测试见 transaction-rules.test.ts覆盖了两个标签的 hasAnyTag 查询返回全部命中项单个标签查询等场景可作为理解语义的参考。可操作场景日常使用中新的过滤器适合这样的查询has any tag找出带有出差或报销任一标签的交易用于聚合两类可报销支出has all tags找出同时带有2026与旅行标签的交易精确圈定某个年度的旅行开销。Actual CLI从实验走向稳定26.7.0 中最具工程意义的变化是actual-app/cli正式转正PR #8102不再标记为 experimental。CLI 的完整说明见 packages/docs/docs/api/cli.md 与 packages/cli/README.md二者是同一套能力的两份呈现。定位与安装该 CLI 面向终端用户连接一个运行中的 Actual 同步服务器在终端查询/修改预算数据——账户、交易、类别、收款方、规则、日程、标签等。它不直接操作本地预算文件这是与同步服务器自身 CLIactual-app/sync-server的本质区别。# 全局安装要求 Node.js 22 npm install --locationglobal actual-app/cli # 或作为项目依赖安装 npm install --save actual-app/cli快速上手# 配置连接信息 export ACTUAL_SERVER_URLhttp://localhost:5006 export ACTUAL_PASSWORDyour-password export ACTUAL_SYNC_IDyour-sync-id # 位于 设置 → 高级 → Sync ID # 列出账户 actual accounts list # 查看余额 actual accounts balance id # 查看某月预算 actual budgets month 2026-03配置优先级与文件CLI 配置按以下优先级解析高优先级覆盖低优先级CLI 标志--server-url、--password等环境变量配置文件基于 cosmiconfig默认值dataDir默认为~/.actual-cli/data环境变量一览变量说明ACTUAL_SERVER_URL同步服务器 URL必填ACTUAL_PASSWORD服务器密码与 Token 二选一ACTUAL_SESSION_TOKEN会话 Token替代密码ACTUAL_SYNC_ID预算 Sync ID多数命令必填ACTUAL_DATA_DIR本地预算缓存目录ACTUAL_CACHE_TTL缓存 TTL秒默认 60ACTUAL_LOCK_TIMEOUT预算目录锁等待超时秒默认 10ACTUAL_NO_LOCK设为1禁用目录锁配置文件支持.actualrcJSON/YAML、.actualrc.json/.yaml/.yml、actual.config.json/.yaml/.yml、package.json中的actual键以及全局配置目录Linux 下如~/.config/actual/下的config/config.json/config.yaml/config.yml。26.7.0 配套的维护变更PR #8208还让 CLI 支持在父目录与全局配置目录中向上搜索配置文件在多项目脚本环境中更友好。{ serverUrl: http://localhost:5006, password: your-password, syncId: 1cfdbb80-6274-49bf-b0c2-737235a4c81f, cacheTtl: 60, lockTimeout: 10, noLock: false }安全提示不要在配置文件中存放明文密码若确需存放请将文件权限收紧Linux 下chmod 600并加入.gitignore。优先使用ACTUAL_PASSWORD/ACTUAL_SESSION_TOKEN环境变量。常用命令速查命令说明actual accounts list列出账户默认排除已关闭actual budgets month 2026-03查看某月预算actual categories list列出类别actual transactions add --account id --data [...]添加交易金额为整数分actual transactions import --account id --data [...]带去重的导入actual tags create --tag vacation创建标签actual rules create --data {...}创建规则actual schedules list列出日程actual query run --table transactions --filter {amount:{$lt:0}}执行 ActualQL 查询actual server bank-sync [--account id]触发银行同步actual server version查询服务器版本典型工作流示例# 查找账户 ID 并查余额 actual server get-id --type accounts --name Checking actual accounts balance id # 导出一年交易为 CSV actual transactions list --account id \ --start 2026-01-01 --end 2026-12-31 --format csv transactions.csv # 查询最近 10 笔支出负数金额 actual query run --table transactions \ --filter {amount:{$lt:0}} --order-by date:desc --limit 10金额约定与缓存/并发CLI 全程使用整数分作为金额单位5000表示 $50.00-12350表示 -$123.50。--format table与--format csv输出会自动将分值转为十进制小数JSON 输出则始终返回原始分值便于程序化处理。缓存与并发方面读命令在 TTL默认 60 秒内复用本地缓存预算避免每次调用都访问服务器写命令始终在写前/写后与服务器同步。actual sync --status可查看缓存新鲜度--refresh/--no-cache强制单次同步。并发控制采用读共享锁、写独占锁写操作串行执行若锁被占用进程最多等待--lock-timeout默认 10 秒后报错--no-lock可在可信的单进程场景下显式退出。报告增强月支出平均区间与折线趋势线报告模块在 26.7.0 中收获了两项实用增强月支出报告的可配置平均区间PR #7920此前平均值基于固定周期计算现在用户可以配置平均区间按需调整统计窗口配套变更PR #8114让预算平均值排除不完整的月份避免当前未结束月份拉低/扭曲平均结果折线报告趋势线PR #7954在自定义折线报告中叠加趋势线便于快速判断数据走向而不必肉眼拟合。同类修复还包括月支出报告按类别组正确过滤预算PR #8043、现金流水报告卡片文字闪烁问题通过 memoize recharts 动画修复PR #8150等。银行同步失败状态持久化与跨设备同步一个对多设备用户影响显著的修复是账户的银行同步失败状态在刷新页面后不再丢失并且会跨设备同步PR #8017、#8170。此前一旦页面刷新失败的红色标记即消失用户可能在毫不知情的情况下错过一次失败的同步现在失败状态会像其他预算数据一样被持久化并同步到其他设备在账户页显示同步错误横幅即使错误发生在另一台设备上也能看到。配套修复还包括修复银行同步无限挂起移动端 spinner 不停转PR #8113、SimpleFIN 增加 SSRF 防护PR #8012、Enable Banking 跳过无法导入的交易无日期或非数值金额而不是让整次账户同步失败PR #8086等。API 与浏览器支持本版本在 API 层有一个值得关注的能力扩展PR #8166为actual-app/api增加浏览器构建使 API 可以在浏览器中运行——核心逻辑loot-core跑在 Web Worker 中。从 packages/api/index.browser.ts 的源码可以看到浏览器入口通过new InlineWorker()内联创建 Worker调用startBackendWorker启动后端并暴露init/shutdown方法对 Worker 生命周期进行管理shutdown时会先尝试sync再close-budget最后终止 Worker。配套维护工作还包括修复 Node.js 环境导入actual-app/api时的ReferenceError构建相对路径处理问题PR #8037、把浏览器 Web Worker 引导与多标签协调逻辑从 desktop-client 移入 loot-corePR #8143等。其他值得关注的增强与修复类别排序预算组内支持按字母 A→Z / Z→A 一键排序桌面与移动端均可使用PR #7831Balance Forecast 增强可使用未来跟踪预算条目投影余额而不依赖日程PR #7884并修复已过账的分拆交易与日程交易重复计数问题PR #7955、#8029余额预测文案补充期末余额与最低点上下文信息PR #7957多币种新增 IRR伊朗里亚尔、PKR巴基斯坦卢比、MXN墨西哥比索等可用币种PR #7945、#7993、#8060主题自定义主题目录新增 Rose Pine、Rose Pine Moon、Rose Pine Dawn 三套主题PR #8214公式引擎Excel 公式执行移除 regex 依赖提升性能与可靠性PR #7990自动化 UI新增每项自动化的备注与预算页 tooltipPR #7906、日程与保存优先级不匹配时给出警告PR #8088、支持移动端PR #8099、按 ID 关联日程使其在重命名后依然有效PR #8308体验细节收款方与类别的自动补全支持不区分大小写搜索PR #8079、标题栏在浏览器不支持 SharedArrayBuffer 时显示警告指示器PR #7922、桌面端新建分拆交易默认两笔空分拆与移动端一致PR #8234性能与数据规模为交易表增加性能索引PR #8335、提升多年数据长周期预算的加载速度PR #8140、大预算通过乐观更新与非阻塞渲染改善性能PR #8209。升级建议与总结26.7.0 是一个功能铺路 稳定性收口的版本。对普通用户而言最直接的收益是银行同步失败状态不再一刷新就消失、标签管理更顺手、报告更直观、CLI 可放心进入脚本与自动化流程。对开发者与自托管用户而言使用 Docker 部署的可直接升级到26.7.0镜像想体验 Akahu 或预算自动化等实验功能需要按实验性功能文档启用实验特性并可用nightly镜像获取最新实现若希望在新旧客户端混用、或让旧客户端连接新版本服务器本版本还针对客户端/API 使用旧数据库结构连接新预算的场景增加了明确的 update required 提示PR #8026替代此前晦涩的no such column报错升级排障体验更友好。更多细节可继续阅读CLI 文档、Akahu 接入文档、CLI 仓库 README以及发布说明原文 2026-07-02-release-26-7-0.md。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考