Actual Budget 25.4.0 版本解析Pluggy.ai 巴西银行同步、内嵌同步服务器与移动端预算体验升级【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actualActual Budget本地优先的个人财务管理应用于 2025 年 4 月 3 日发布了 25.4.0 版本Docker 镜像标签为25.4.0。本版本围绕三大主线展开一是通过 Pluggy.ai 为巴西银行提供实验性的银行同步能力二是将同步服务器sync-server实验性地嵌入 Electron 桌面应用三是围绕移动端预算页、交易列表与日期国际化做了一系列体验增强。本文以官方发布文档packages/docs/blog/2025-04-03-release-25-4-0.md为骨架结合仓库源码逐项拆解这些能力的实现细节与使用方式。核心特性Features1. Pluggy.ai巴西银行同步的实验性支持25.4.0 首次引入了面向巴西银行的 Pluggy.ai 银行同步PR #4049。这是一项实验性能力需要在同步服务器侧完成凭据配置后才能使用。从源码结构看Pluggy.ai 集成位于 packages/sync-server/src/app-pluggyai/ 目录包含两个文件app-pluggyai.js负责定义 Express 路由/status、/accounts、/transactions并完成权限校验、文件访问控制与数据归一化pluggyai-service.js封装对pluggy-sdk的调用负责创建 Pluggy 客户端、拉取账户与交易。凭据配置与三级路由设计pluggyai-service.js中的getCredentialSource(fileId)定义了凭据的两种来源function getCredentialSource(fileId) { if (!!fileId hasCredentials(fileId)) { return per-budget-file; } if (hasCredentials()) { return global; } return null; }per-budget-file为单个预算文件单独配置的 Pluggy 凭据clientId、clientSecret、itemIdsglobal全局共享的 Pluggy 凭据适用于所有预算文件。hasCredentials()要求三个密钥pluggyai_clientId、pluggyai_clientSecret、pluggyai_itemIds同时存在才认为已配置这些密钥通过secretsService读写并缓存在内存中的pluggyClientsMap 中以文件 ID 与凭据序列化为缓存键。itemIds以逗号分隔存储解析时会被拆分、去空格并过滤空项。三个路由的职责与鉴权app-pluggyai.js挂载了requestLoggerMiddleware、express.json()与validateSessionMiddleware并统一从请求头X-Actual-File-Id读取文件 ID通过canAccessFile()管理员或对该文件有访问权的用户校验权限非法文件 ID 返回400 invalid-file-id无权限返回403 file-access-deniedPOST /status返回当前文件是否已配置 Pluggy 及凭据来源configured与sourcePOST /accounts遍历所有itemIds调用pluggyaiService.getAccountsByItemId()聚合账户列表若未配置凭据返回400 not-configuredPOST /transactions接收{ accountId, startDate }拉取交易并归一化为 Actual 的转账格式同时返回起始余额startingBalance与余额对象balances。交易归一化的关键逻辑/transactions路由中的归一化逻辑值得注意交易按booked已入账与pending待入账分组判断依据是trans.status PENDING早于startDate且非沙箱的交易会被跳过信用卡account.type CREDIT账户的金额与余额会被取反以符合 Actual 的记账方向交易日期通过getTransactionDateCorrected()修正若交易携带信用卡分期元数据creditCardMetadata.installmentNumber则基于purchaseDate按月数递推分期日期并使用addMonthsClamped()防止 31 日跨月溢出交易对象经flattenObject()扁平化后与归一化字段合并收款方payee名称优先取merchant.name/merchant.businessName其次按借贷方向取paymentData.receiver或paymentData.payer的名称或证件号documentNumber.value所有交易按sortOrder交易日期的时间戳降序排列返回all、booked、pending三组结果。沙箱账户的兼容处理pluggyai-service.js中getTransactionsByAccountId()对 Pluggy 沙箱账户做了特殊处理沙箱数据不会自动推移日期交易往往超过 90 天因此当账户 owner 为John Doe时将startDate强制设为2000-01-01并给交易打上sandbox: true标记以便测试时能取回全部历史数据。25.4.0 还修复了 Pluggy.ai 信用卡交易金额反相#4628与外币交易#4712等问题。2. 账户新增 上次核对时间last reconciledPR #4459 为账户模型增加了last_reconciled时间戳字段。对应的数据库迁移文件为 packages/loot-core/migrations/1740506588539_add_last_reconciled_at.sqlBEGIN TRANSACTION; ALTER TABLE accounts ADD COLUMN last_reconciled text; COMMIT;在服务端packages/loot-core/src/server/accounts/app.ts 的账户查询中新增了last_reconciled字段并将其纳入账户实体的返回结果dbAccount.last_reconciled ?? null同时支持在账户更新时回写该字段。桌面客户端侧账户头部Header.tsx、对账弹窗AccountReconcileModal.tsx与对账组件Reconcile.tsx均读取该字段用于展示账户最近一次完成对账的时间帮助用户跟踪对账节奏。3. 实验性将同步服务器嵌入桌面应用PR #4526 是 25.4.0 的另一项重要实验将 sync-server 直接嵌入 Electron 桌面应用使用户无需单独部署 Actual Server 即可在同一进程体系中获得完整的服务端能力。从 packages/desktop-electron/index.ts 的实现看桌面应用通过utilityProcess.fork()启动 sync-server 的构建产物actual-app/sync-server/package.json所在目录下的build/app.js并通过环境变量完成配置注入const envVariables: Env { ...process.env, // required ACTUAL_PORT: ${syncServerConfig.port}, ACTUAL_HOSTNAME: ${syncServerConfig.hostname}, ACTUAL_SERVER_FILES: ${syncServerConfig.ACTUAL_SERVER_FILES}, ACTUAL_USER_FILES: ${syncServerConfig.ACTUAL_USER_FILES}, ACTUAL_DATA_DIR: ${syncServerConfig.ACTUAL_SERVER_DATA_DIR}, ACTUAL_WEB_ROOT: webRoot, };其中ACTUAL_SERVER_DATA_DIR是 sync-server 的数据根目录服务端文件server-files与用户文件user-files均在其下ACTUAL_WEB_ROOT指向actual-app/web的构建目录由 web 客户端提供界面。桌面端通过 IPC 暴露了start-sync-server、stop-sync-server、is-sync-server-running三个通道见 preload.ts分别用于启动、停止与查询内嵌服务状态子进程的 stdout/stderr 会转发到主窗口日志中。该功能在开发模式下还会为 fork 的子进程附加--inspect以便调试。使用方式与前置条件该特性属于实验性能力需自行构建或使用支持此功能的桌面端版本内嵌服务的数据目录、端口等可通过环境变量ACTUAL_DATA_DIR、ACTUAL_PORT等控制与独立部署 sync-server 时一致。同一版本还配套修复了sync-server.Dockerfile未正确构建客户端的问题#4677。体验增强Enhancements日期与日期选择器的国际化翻译PR #4211 为日期与日期选择器datepicker增加了按所选语言翻译的能力将日期控件从硬编码英文切换为 i18n 驱动的本地化文案。25.4.0 同时收录了 PR #4635为规则rules与字段增加了更多翻译条目规则编辑器中的条件、操作与字段名在切换语言后能够同步本地化。移动端预算页的 Banner 提示PR #4643重做为移动端预算表引入了 Banner 机制用于主动提醒用户各类预算待办事项。实现位于 packages/desktop-client/src/components/mobile/budget/BudgetPage.tsx共实现三类 BannerOverbudgetedBanner超预算警告typecritical当toBudget金额为负时显示 You have budgeted more than your available funds提供Cover按钮打开cover弹窗从其他类别或 To Budget 中移入资金覆盖超预算部分OverspendingBanner超支类别警告typecritical通过useOverspentCategories()统计超支类别显示超支类别数量提供覆盖cover-overspending与类别选择弹窗category-autocomplete且支持显示隐藏的超支类别#4680UncategorizedTransactionsBanner未分类交易提醒typewarning统计未分类交易条数与总额提供Categorize按钮跳转至/categories/uncategorized。Banner 的配色随主题变量变化errorBackground、warningBackground、noticeBackground在无相关事项时返回null不占位避免干扰正常浏览。移动端交易与账户操作增强子交易搜索#4471移动端支持搜索子交易split 中的条目方便在拆分交易中快速定位明细拖拽排序#4476、#4482移动端支持拖拽重排账户列表与预算页的收入类别目前仅支持 Chromium 内核浏览器标记转账#4511小屏设备上允许将交易标记为转账Transfer拆分交易#4536当拆分中不存在空条目时交易编辑按钮显示 Add New Split 文案目标与预算信息展示#4546移动端展示类别的目标goal与预算信息收入类别余额跳转#4621点击收入类别余额可查看对应交易列表通知滑动关闭#4606左右滑动即可关闭通知提醒搜索/过滤时拆分交易折叠#4600带搜索或过滤条件时支持折叠/展开拆分交易。银行同步相关增强最后同步时间人性化#4523银行同步的最后时间以自然语言如 2 hours ago展示取代原始时间戳有限历史银行名单扩充#4416将INDUSTRIEL_CMCIFRPAXXX、QONTO_QNTOFRP1加入BANKS_WITH_LIMITED_HISTORY常量这些银行仅提供约 90 天交易历史同期 #4595 将捷克 AirBank 加入同类名单删除交易不再被重复导入#4644新增配置项控制银行同步时是否重新导入已删除的交易机构列展示#4646关联账户弹窗中的账户名称旁增加机构institution列外部账户记忆化#4540对银行同步弹窗中的外部账户列表做 memoize减少重复请求同步摘要月度平均改进#4302改进汇总报表summary report的月度平均计算方式。关键 Bugfix 一览25.4.0 修复了大量与同步服务器、OpenID、移动端交互相关的问题值得运维与重度用户关注同步服务器与 OpenID 配置ACTUAL_OPENID_DISCOVERY_URL新变量#4530与ACTUAL_OPENID_ENFORCE强制启用修复#4533生产构建缺失convict与pluggy-sdk依赖#4534、默认数据目录配置#4535、ACTUAL_PORT/PORT变量处理#4537、config 文件中的对象类型支持#4688、OpenID 响应缺失iss参数#4626这些修复与 packages/sync-server/src/load-config.js 中基于convict的配置体系ACTUAL_*环境变量、config.json加载、tokenExpiration自定义格式校验直接相关。银行同步mBank 波兰交易日期修复#4493、SimpleFIN 批量同步超时与调试日志#4515、银行同步 API 错误收集修复#4689、GoCardless 机构结构差异导致SelectLinkedAccounts失效#4667。规则与交易排程无 payee 时自动补充 payee is nothing 规则条件#4267、规则创建拆分交易失败#4623、scheduleIsRecurring空值判断#4627、带模板规则保存失败#4686、转账交易过滤#4519。移动端与界面iOS 上预算金额聚焦#4651、移动端远程预算文件切换#4596、自定义报表 any 条件保存#4652、报表仪表盘现金流组件过滤#4683、service worker 缓存上限提升至 5MB#4665。维护与架构演进Maintenance25.4.0 背后包含大量架构级维护工作这些改动虽不直接面向用户但为后续版本奠定了更清晰的分层结构Redux Toolkit 迁移第二阶段#4114、#4119、#4126、#4127、#4128budgets、modals、notifications、preferences、users 等 slice 相继迁移至 Redux Toolkit服务端 handler 拆分#4442、#4443、#4649、#4661将预算类别、payee、spreadsheet、同步相关的服务端 handler 从庞大的main.ts中抽取到独立的server/*/app.ts并统一使用实现函数类型减少类型重复#4650组件库收敛#4554、#4556、#4563、#4568图标文件、Select、Input、useResponsive等组件与 Hook 迁入actual-app/components组件库移除废弃的MenuButton、Button组件依赖与构建治理#4592、#4609、#4610、#4641、#4654、#4656、#4717loot-core 路径解析迁移至 yarn workspaces、数据模型导入统一走 barrel 文件、yarn 升级至 4.7.0、axios 升至 1.8.3、tar-fs 升至 2.1.2、构建禁用名称混淆#4532类型系统强化#4248、#4249、#4542、#4524db.first、db.firstSync、db.all泛型化预算表组件类型细化发布流程自动化#4664新增 release note 生成器后续版本发布说明可由脚本自动生成这正是本文所依据的发布文档的产出渠道之一。升级与验证建议使用 Docker 部署 Actual Server 的用户可拉取actualbudget/actual:25.4.0镜像完成升级last_reconciled字段通过迁移脚本自动添加无需手动改库尝试 Pluggy.ai 巴西银行同步的用户需在同步服务器中配置pluggyai_clientId、pluggyai_clientSecret、pluggyai_itemIds三组密钥支持全局或按预算文件并通过POST /status验证配置是否生效关注 OpenID 配置的运维人员本版本对ACTUAL_OPENID_DISCOVERY_URL、ACTUAL_OPENID_ENFORCE、ACTUAL_PORT等环境变量的行为做了多项修复建议升级后回归验证登录与端口绑定桌面端用户可在设置中体验内嵌同步服务器实验性注意其数据目录与独立部署版本相互独立迁移数据时需分别处理。25.4.0 是 Actual Budget 在银行同步生态拓展 桌面端架构收敛 移动端体验打磨三线并进的一次集中发布Pluggy.ai 的实验性接入填补了巴西银行同步的空白内嵌同步服务器为单机用户提供了更完整的本地优先方案而预算 Banner、日期翻译与大量移动端交互改进则显著降低了日常记账的摩擦成本。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考