尧图网页设计 
Actual Budget 25.5.0 版本深度解析全新 CLI 工具、交易合并与报表导出实战指南【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual本篇技术指南以 Actual Budget 官方发布文档 2025-05-03-release-25-5-0.md 为骨架结合仓库源码与包文档系统讲解 25.5.0 版本的核心能力无需 Docker、无需源码构建即可通过一行命令运行同步服务器的新版 CLI 工具自定义报表一键导出图片、多笔交易合并等新特性以及 OpenID 登录增强、移动端拖拽排序等改进与关键修复。读完本文你将掌握这套版本中每一个可实操的功能入口、配置参数与底层实现位置。版本概览Actual Budget 25.5.0Docker tag25.5.0发布于 2025 年 5 月是本项目local-first 个人财务管理应用一次规模较大的版本迭代。官方发布文档总结了本版本的四大亮点下载自定义报表为图片PR #4219合并多笔交易为一笔交易PR #4739新增 sync-server CLI 工具无需 Docker 容器、也无需从源码构建即可运行 Actual 服务器PR #4798详细用法见官方安装文档Cloudflare Access 隧道连接 Actual 实例本轮修复PR #4844。除此之外本版本还包含 5 项新功能、16 项增强、30 余项 Bugfix 与一批工程化维护工作Maintenance。下面按“重点特性 → 增强改进 → Bugfix 精选 → 工程维护”四个层次展开。重点特性一自定义报表导出为图片在 25.5.0 中用户可以将自定义报表Custom Report直接导出为 PNG 图片方便把预算报表分享到群聊、嵌入文档或归档。从源码看该能力实现在 ReportTopbar.tsx 中组件引入了html-to-image库的toPng函数将报表 DOM 节点渲染为 PNG然后通过构造a链接并设置link.download触发浏览器下载默认文件名为${monthUtils.currentDay()} - ${title}.png即“当日日期 报表标题”。下载入口位于报表顶栏的下拉菜单中onSelect{downloadSnapshot}。实操要点打开任意一张自定义报表在顶栏菜单选择“下载/导出为图片”即可得到 PNG 文件导出的文件名会自动带上当天日期与报表标题便于归档检索该功能依赖浏览器能力桌面端与 Web 端均可用。重点特性二合并多笔交易对于重复录入、拆分错误的交易25.5.0 新增了“合并交易”能力选中多笔交易后可将它们合并为一笔PR #4739。从源码可以确认该功能的完整链路账户页 Account.tsx 中注册了transactions-merge动作移动端交易列表 TransactionList.tsx 在合并成功后提示Successfully merged transactions快捷键面板 KeyboardShortcutModal.tsx 中定义了merge-selected-transactions快捷键入口。实操要点在账户的交易列表中选择多笔交易通过右键菜单或键盘快捷键触发“合并”合并后交易金额与明细会整合为单笔记录移动端同样支持该操作若存在拆分交易合并时注意区分父交易与子交易避免金额重复计算。重点特性三全新 sync-server CLI 工具25.5.0 最大的工程亮点是引入了独立的 CLI 工具包PR #4798位于 packages/cli它允许用户不需要 Docker 容器、不需要从源码构建用一条命令运行 Actual 同步服务器并支持通过终端查询和修改预算数据——账户、交易、分类、收款人、规则、排班等。安装与快速开始CLI 以 npm 全局包形式发布要求Node.js 22npm install -g actual-app/cli安装后通过环境变量配置连接信息注意CLI 连接的是正在运行的 Actual 同步服务器并不直接操作本地预算文件# 设置连接信息 export ACTUAL_SERVER_URLhttp://localhost:5006 export ACTUAL_PASSWORDyour-password export ACTUAL_SYNC_IDyour-sync-id # 在 设置 → 高级 → Sync ID 中查看 # 列出账户 actual accounts list # 查看余额 actual accounts balance account-id # 查看某月预算 actual budgets month 2026-03配置解析优先级CLI 的配置解析顺序优先级从高到低定义在 config.ts 的resolveConfig中CLI 全局标志--server-url、--password等环境变量ACTUAL_SERVER_URL、ACTUAL_PASSWORD等配置文件通过 cosmiconfig 查找默认值dataDir默认~/.actual-cli/data。从源码可见serverUrl与认证password/sessionToken 至少其一为硬性必填项缺失会直接抛出明确错误数值型配置cacheTtl、lockTimeout会被校验为非负整数配置文件还会拒绝未知键。环境变量与全局标志CLI 支持的环境变量如下与 README 及 index.ts 中的 Commander 定义一致变量说明ACTUAL_SERVER_URLActual 同步服务器 URL必填ACTUAL_PASSWORD服务器密码使用 token 时可省略ACTUAL_SESSION_TOKEN会话令牌密码的替代方案ACTUAL_SYNC_ID预算 Sync ID大多数命令必填ACTUAL_DATA_DIR本地预算数据缓存目录ACTUAL_CACHE_TTL缓存 TTL秒默认 60ACTUAL_LOCK_TIMEOUT预算目录锁等待超时秒默认 10ACTUAL_NO_LOCK设为1时禁用预算目录锁ACTUAL_ENCRYPTION_PASSWORD端到端加密密码对应的全局标志--server-url、--password、--session-token、--sync-id、--data-dir、--cache-ttl0表示禁用缓存默认 60、--refresh/--no-cache强制同步忽略缓存、--lock-timeout默认 10、--no-lock慎用、--formatjson/table/csv默认json、--verbose。配置文件CLI 使用 cosmiconfig 进行配置查找配置文件可位于当前工作目录到主目录之间的任意层级支持以下格式.actualrcJSON 或 YAML、.actualrc.json/.actualrc.yaml/.actualrc.ymlactual.config.json/actual.config.yaml/actual.config.ymlpackage.json中的actual键全局配置目录下的actual/config、config.json、config.yaml、config.ymlLinux 下如~/.config/actual/示例.actualrc.json{ serverUrl: http://localhost:5006, password: your-password, syncId: 1cfdbb80-6274-49bf-b0c2-737235a4c81f, cacheTtl: 60, lockTimeout: 10, noLock: false }安全建议官方文档明确提示配置文件尽量不存明文密码如确实存放请在 Linux 上设置 600 权限并加入.gitignore优先使用ACTUAL_PASSWORD/ACTUAL_SESSION_TOKEN环境变量或在配置中使用会话令牌而非密码。命令一览与实战示例CLI 在 index.ts 中注册了 12 个顶级命令对应 commands 目录下的独立实现文件命令功能accounts管理账户budgets管理预算与分配categories管理分类category-groups管理分类组transactions管理交易payees管理收款人tags管理标签rules管理交易规则schedules管理排班交易query运行 ActualQL 查询server服务器工具与查询sync刷新或检查本地缓存常用示例金额统一使用整数分5000 $50.00-12350 -$123.50# 列出账户默认排除已关闭账户可加 --include-closed actual accounts list [--include-closed] --format table # 按名称查找实体 ID actual server get-id --type accounts --name Checking # 新增一笔交易-2500 -$25.00 actual transactions add --account id \ --data [{date:2026-03-14,amount:-2500,payee_name:Coffee Shop}] # 导出交易为 CSV actual transactions list --account id \ --start 2026-01-01 --end 2026-12-31 --format csv transactions.csv # 设置预算金额$500 50000 分 actual budgets set-amount --month 2026-03 --category id --amount 50000 # 运行 ActualQL 查询 actual query run --table transactions \ --select date,amount,payee --filter {amount:{$lt:0}} --limit 10输出格式说明--format table/csv会自动把分值转换为十进制金额如1665.00而json始终输出原始分值便于脚本处理。缓存与并发锁机制CLI 会在本地保留一份预算副本避免每条命令都请求服务器。读取类命令list、balance、query run等在 TTL默认 60 秒内直接复用缓存写命令add、update、set-amount等则始终在写入前后与服务器同步。相关控制actual sync—— 立即刷新缓存actual sync --status—— 显示本地缓存的新鲜度actual sync --clear—— 删除本地缓存下条命令重新下载--refresh/--no-cache—— 单次调用强制同步--cache-ttl seconds—— 单次覆盖 TTL0禁用缓存。从 sync.ts 源码可见sync --status会输出neverSynced、syncedAt、ageSeconds、stale等字段帮助判断缓存是否过期sync --clear会先获取排他锁再删除缓存文件避免删除正在写入的半成品状态。并发方面CLI 对每个预算的缓存目录读取时加共享锁、写入时加排他锁实现见 lock.ts。多进程并行读取安全写入会被串行化若锁被占用后续调用最多等待--lock-timeout默认 10 秒后报错。信任的单进程环境可传--no-lock跳过加锁。本地开发运行方式在 monorepo 内调试 CLI 时见 README# 1. 构建 CLI yarn build:cli # 2. 另开终端启动本地同步服务器 yarn start:server-dev # 3. 浏览器打开 http://localhost:5006创建预算后 # 在 设置 → 高级 → Sync ID 找到 Sync ID # 4. 直接运行构建产物 ACTUAL_SERVER_URLhttp://localhost:5006 \ ACTUAL_PASSWORDyour-password \ ACTUAL_SYNC_IDyour-sync-id \ node packages/cli/dist/cli.js accounts list重点特性四Cloudflare Access 隧道连接25.5.0 修复了通过 Cloudflare Access 隧道连接 Actual 实例的问题PR #4844当 Access 会话过期、认证重定向发生时页面会在所有重定向上自动 reload以正确处理 Cloudflare Access 的过期刷新避免用户陷入空白页或反复跳转。这意味着把 Actual 部署在 Cloudflare Access 之后的用户可以用隧道稳定访问自托管的 Actual 实例。其他新特性控制导入交易时是否导入备注PR #4593交易导入流程新增选项可决定是否把导入文件中的 notes 写入 Actual避免导入大量无用备注污染账本预算表类别名称可调宽度PR #4807允许用户调整预算表中类别名称列的尺寸方便长名称分类展示移动端拖拽排序预算页支持拖拽调整支出分类顺序PR #4484与分类组顺序PR #4599目前仅 Chromium 内核浏览器支持跟踪预算中隐藏分类不计入合计PR #4567跟踪预算tracking budget的合计值不再包含被隐藏的分类或分类组移动端账户页显示已关闭账户PR #4584MonthPicker 新增上/下月按钮PR #4692月份选择器可直接切换相邻月份银行同步设置中可解除账户关联PR #4714Unlink 账户后不再被同步拉取新增 KBCBEKBC_KREDBEBB银行PR #4743列入历史数据受限银行清单桌面应用可调用内部同步服务器命令PR #4847Electron 桌面版允许 UI 直接调用内嵌 sync server 命令Strawberry 信用卡交易金额翻转PR #4857修正该银行流水方向。认证与登录增强ACTUAL_USER_CREATION_MODElogin自动建号25.5.0 为 OpenID/OAuth2 登录新增了ACTUAL_USER_CREATION_MODE环境变量PR #4421。该变量在 load-config.js 中定义默认manual可选manual或loginmanual默认使用 OpenID/OAuth2 认证前必须在 Actual 中手动创建同用户名的账号loginOpenID/OAuth2 用户首次认证时自动在 Actual 创建账号免除管理员预建号步骤。官方文档 oauth-auth.md 对此有完整说明部署 OpenID 场景时按需配置即可。OpenID 首登确认密码与 returnUrl 修复本版本还改进了 OpenID 登录链路均可在发布文档的 Enhancements/Bugfix 中确认首次登录改为确认密码PR #4446OpenID 用户首次登录时要求设置/确认密码而非直接放行修复 returnUrl 问题PR #4836认证回调后的跳转地址恢复正常修复使用 config.json 或环境变量配置时的首登逻辑PR #4902配套新增的配置项还包括ACTUAL_OPENID_DISCOVERY_URL、ACTUAL_OPENID_CLIENT_ID、ACTUAL_OPENID_CLIENT_SECRET、ACTUAL_OPENID_SERVER_HOSTNAME、ACTUAL_OPENID_AUTH_METHODopenid/oauth2、ACTUAL_OPENID_ENFORCE、ACTUAL_TOKEN_EXPIRATION等详见 oauth-auth.md。Bugfix 精选除上述重点修复外25.5.0 的 Bugfix 按模块可归纳为交易与排班修复提前过账的排班交易误用未来排班日期改用当天日期PR #4719修复拆分排班预览的运行余额PR #4881修复交易列表打开新建交易弹窗时的崩溃PR #4812导入重做导入逻辑允许同时接受所有金额选项修复 In/Out 模式与既有拆分列共存时的 UI 卡死PR #4715ofx2json 逻辑中的 HTML 转义 bugPR #4838支持更长时间的 SimpleFIN 交易请求PR #4780自定义报表切换区间或日期范围时持久化过滤器PR #4724新增显示趋势线设置相关 SQL 迁移见 loot-core/migrations移动端修复收入分类不随激活月份变色PR #4774、超支横幅显示上月错误分类PR #4875、隐藏分类组未生效PR #4880侧边栏与偏好侧边栏固定偏好刷新后不保留PR #4733saveGlobalPrefs无法保存假值PR #4837银行同步GoCardless 初始账户链接的错误处理改进PR #4756Commerzbank 收款人正则转义PR #4845桌面端桌面应用加载备份弹窗白屏PR #4853、部分菜单链接失效PR #4860CLI无配置文件时ACTUAL_DATA_DIR环境变量未生效PR #4825其他关闭账户流程未校验转账或分类目标PR #4769模板目标在特定条件下未清除PR #4749开发模式多余警告清理PR #4735。工程维护与内部重构25.5.0 同步完成了一批内部治理工作对贡献者与集成方有实际参考价值React 19 升级PR #4700前端运行栈整体更新测试体系迁移 vitestsync-serverPR #4840、crdtPR #4851、api / desktop-client / eslint-plugin-actualPR #4856、loot-corePR #4859全部迁移到 vitest同时新增 Electron Playwright 测试与 fixturePR #4674、PR #4752服务端处理器拆分将预算文件、认证、加密相关处理器从 main.ts 分别抽到 server/budgetfiles/app.ts、server/auth/app.ts、server/encryption/app.tsPR #4547、PR #4660、PR #4662AQL 增强category_groups 表新增categories查询选项可用q(category_groups).options({ categories: all }).select(*)一并查询关联分类PR #4544IndexedDB 文件转严格 TypeScriptPR #4672loot-core 客户端代码迁移到 desktop-clientPR #4816移除 Electron 中的 ngrok 依赖后续将改为插件化方案PR #4768依赖与工具链升级 vite5.4.8 → 5.4.18、nanoid3.3.7 → 3.3.11、http-proxy-middleware3.0.3 → 3.0.5eslint自动修复接入 lint-staged部分.d.ts转.ts。升级建议服务器端以 Docker 部署的用户升级镜像 tag 至25.5.0即可获得全部新特性想脱离 Docker 快速体验的用户可直接npm install -g actual-app/cli参考 packages/cli/README.md 完成服务器部署与预算数据管理启用 OpenID 登录且希望免手动建号的管理员可配置ACTUAL_USER_CREATION_MODElogin详见 oauth-auth.md迁移到 25.5.0 后建议关注排班交易与自定义报表的修复项历史数据中可能存在的异常如提前过账日期错误、报表过滤器丢失会在新版本得到纠正。本版本所有改动条目均可回溯至发布文档 2025-05-03-release-25-5-0.md仓库内对应源码、迁移脚本与测试为上述功能提供了完整的可验证依据。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Actual Budget 25.5.0 版本深度解析：全新 CLI 工具、交易合并与报表导出实战指南
Actual Budget 25.5.0 版本深度解析全新 CLI 工具、交易合并与报表导出实战指南【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual本篇技术指南以 Actual Budget 官方发布文档 2025-05-03-release-25-5-0.md 为骨架结合仓库源码与包文档系统讲解 25.5.0 版本的核心能力无需 Docker、无需源码构建即可通过一行命令运行同步服务器的新版 CLI 工具自定义报表一键导出图片、多笔交易合并等新特性以及 OpenID 登录增强、移动端拖拽排序等改进与关键修复。读完本文你将掌握这套版本中每一个可实操的功能入口、配置参数与底层实现位置。版本概览Actual Budget 25.5.0Docker tag25.5.0发布于 2025 年 5 月是本项目local-first 个人财务管理应用一次规模较大的版本迭代。官方发布文档总结了本版本的四大亮点下载自定义报表为图片PR #4219合并多笔交易为一笔交易PR #4739新增 sync-server CLI 工具无需 Docker 容器、也无需从源码构建即可运行 Actual 服务器PR #4798详细用法见官方安装文档Cloudflare Access 隧道连接 Actual 实例本轮修复PR #4844。除此之外本版本还包含 5 项新功能、16 项增强、30 余项 Bugfix 与一批工程化维护工作Maintenance。下面按“重点特性 → 增强改进 → Bugfix 精选 → 工程维护”四个层次展开。重点特性一自定义报表导出为图片在 25.5.0 中用户可以将自定义报表Custom Report直接导出为 PNG 图片方便把预算报表分享到群聊、嵌入文档或归档。从源码看该能力实现在 ReportTopbar.tsx 中组件引入了html-to-image库的toPng函数将报表 DOM 节点渲染为 PNG然后通过构造a链接并设置link.download触发浏览器下载默认文件名为${monthUtils.currentDay()} - ${title}.png即“当日日期 报表标题”。下载入口位于报表顶栏的下拉菜单中onSelect{downloadSnapshot}。实操要点打开任意一张自定义报表在顶栏菜单选择“下载/导出为图片”即可得到 PNG 文件导出的文件名会自动带上当天日期与报表标题便于归档检索该功能依赖浏览器能力桌面端与 Web 端均可用。重点特性二合并多笔交易对于重复录入、拆分错误的交易25.5.0 新增了“合并交易”能力选中多笔交易后可将它们合并为一笔PR #4739。从源码可以确认该功能的完整链路账户页 Account.tsx 中注册了transactions-merge动作移动端交易列表 TransactionList.tsx 在合并成功后提示Successfully merged transactions快捷键面板 KeyboardShortcutModal.tsx 中定义了merge-selected-transactions快捷键入口。实操要点在账户的交易列表中选择多笔交易通过右键菜单或键盘快捷键触发“合并”合并后交易金额与明细会整合为单笔记录移动端同样支持该操作若存在拆分交易合并时注意区分父交易与子交易避免金额重复计算。重点特性三全新 sync-server CLI 工具25.5.0 最大的工程亮点是引入了独立的 CLI 工具包PR #4798位于 packages/cli它允许用户不需要 Docker 容器、不需要从源码构建用一条命令运行 Actual 同步服务器并支持通过终端查询和修改预算数据——账户、交易、分类、收款人、规则、排班等。安装与快速开始CLI 以 npm 全局包形式发布要求Node.js 22npm install -g actual-app/cli安装后通过环境变量配置连接信息注意CLI 连接的是正在运行的 Actual 同步服务器并不直接操作本地预算文件# 设置连接信息 export ACTUAL_SERVER_URLhttp://localhost:5006 export ACTUAL_PASSWORDyour-password export ACTUAL_SYNC_IDyour-sync-id # 在 设置 → 高级 → Sync ID 中查看 # 列出账户 actual accounts list # 查看余额 actual accounts balance account-id # 查看某月预算 actual budgets month 2026-03配置解析优先级CLI 的配置解析顺序优先级从高到低定义在 config.ts 的resolveConfig中CLI 全局标志--server-url、--password等环境变量ACTUAL_SERVER_URL、ACTUAL_PASSWORD等配置文件通过 cosmiconfig 查找默认值dataDir默认~/.actual-cli/data。从源码可见serverUrl与认证password/sessionToken 至少其一为硬性必填项缺失会直接抛出明确错误数值型配置cacheTtl、lockTimeout会被校验为非负整数配置文件还会拒绝未知键。环境变量与全局标志CLI 支持的环境变量如下与 README 及 index.ts 中的 Commander 定义一致变量说明ACTUAL_SERVER_URLActual 同步服务器 URL必填ACTUAL_PASSWORD服务器密码使用 token 时可省略ACTUAL_SESSION_TOKEN会话令牌密码的替代方案ACTUAL_SYNC_ID预算 Sync ID大多数命令必填ACTUAL_DATA_DIR本地预算数据缓存目录ACTUAL_CACHE_TTL缓存 TTL秒默认 60ACTUAL_LOCK_TIMEOUT预算目录锁等待超时秒默认 10ACTUAL_NO_LOCK设为1时禁用预算目录锁ACTUAL_ENCRYPTION_PASSWORD端到端加密密码对应的全局标志--server-url、--password、--session-token、--sync-id、--data-dir、--cache-ttl0表示禁用缓存默认 60、--refresh/--no-cache强制同步忽略缓存、--lock-timeout默认 10、--no-lock慎用、--formatjson/table/csv默认json、--verbose。配置文件CLI 使用 cosmiconfig 进行配置查找配置文件可位于当前工作目录到主目录之间的任意层级支持以下格式.actualrcJSON 或 YAML、.actualrc.json/.actualrc.yaml/.actualrc.ymlactual.config.json/actual.config.yaml/actual.config.ymlpackage.json中的actual键全局配置目录下的actual/config、config.json、config.yaml、config.ymlLinux 下如~/.config/actual/示例.actualrc.json{ serverUrl: http://localhost:5006, password: your-password, syncId: 1cfdbb80-6274-49bf-b0c2-737235a4c81f, cacheTtl: 60, lockTimeout: 10, noLock: false }安全建议官方文档明确提示配置文件尽量不存明文密码如确实存放请在 Linux 上设置 600 权限并加入.gitignore优先使用ACTUAL_PASSWORD/ACTUAL_SESSION_TOKEN环境变量或在配置中使用会话令牌而非密码。命令一览与实战示例CLI 在 index.ts 中注册了 12 个顶级命令对应 commands 目录下的独立实现文件命令功能accounts管理账户budgets管理预算与分配categories管理分类category-groups管理分类组transactions管理交易payees管理收款人tags管理标签rules管理交易规则schedules管理排班交易query运行 ActualQL 查询server服务器工具与查询sync刷新或检查本地缓存常用示例金额统一使用整数分5000 $50.00-12350 -$123.50# 列出账户默认排除已关闭账户可加 --include-closed actual accounts list [--include-closed] --format table # 按名称查找实体 ID actual server get-id --type accounts --name Checking # 新增一笔交易-2500 -$25.00 actual transactions add --account id \ --data [{date:2026-03-14,amount:-2500,payee_name:Coffee Shop}] # 导出交易为 CSV actual transactions list --account id \ --start 2026-01-01 --end 2026-12-31 --format csv transactions.csv # 设置预算金额$500 50000 分 actual budgets set-amount --month 2026-03 --category id --amount 50000 # 运行 ActualQL 查询 actual query run --table transactions \ --select date,amount,payee --filter {amount:{$lt:0}} --limit 10输出格式说明--format table/csv会自动把分值转换为十进制金额如1665.00而json始终输出原始分值便于脚本处理。缓存与并发锁机制CLI 会在本地保留一份预算副本避免每条命令都请求服务器。读取类命令list、balance、query run等在 TTL默认 60 秒内直接复用缓存写命令add、update、set-amount等则始终在写入前后与服务器同步。相关控制actual sync—— 立即刷新缓存actual sync --status—— 显示本地缓存的新鲜度actual sync --clear—— 删除本地缓存下条命令重新下载--refresh/--no-cache—— 单次调用强制同步--cache-ttl seconds—— 单次覆盖 TTL0禁用缓存。从 sync.ts 源码可见sync --status会输出neverSynced、syncedAt、ageSeconds、stale等字段帮助判断缓存是否过期sync --clear会先获取排他锁再删除缓存文件避免删除正在写入的半成品状态。并发方面CLI 对每个预算的缓存目录读取时加共享锁、写入时加排他锁实现见 lock.ts。多进程并行读取安全写入会被串行化若锁被占用后续调用最多等待--lock-timeout默认 10 秒后报错。信任的单进程环境可传--no-lock跳过加锁。本地开发运行方式在 monorepo 内调试 CLI 时见 README# 1. 构建 CLI yarn build:cli # 2. 另开终端启动本地同步服务器 yarn start:server-dev # 3. 浏览器打开 http://localhost:5006创建预算后 # 在 设置 → 高级 → Sync ID 找到 Sync ID # 4. 直接运行构建产物 ACTUAL_SERVER_URLhttp://localhost:5006 \ ACTUAL_PASSWORDyour-password \ ACTUAL_SYNC_IDyour-sync-id \ node packages/cli/dist/cli.js accounts list重点特性四Cloudflare Access 隧道连接25.5.0 修复了通过 Cloudflare Access 隧道连接 Actual 实例的问题PR #4844当 Access 会话过期、认证重定向发生时页面会在所有重定向上自动 reload以正确处理 Cloudflare Access 的过期刷新避免用户陷入空白页或反复跳转。这意味着把 Actual 部署在 Cloudflare Access 之后的用户可以用隧道稳定访问自托管的 Actual 实例。其他新特性控制导入交易时是否导入备注PR #4593交易导入流程新增选项可决定是否把导入文件中的 notes 写入 Actual避免导入大量无用备注污染账本预算表类别名称可调宽度PR #4807允许用户调整预算表中类别名称列的尺寸方便长名称分类展示移动端拖拽排序预算页支持拖拽调整支出分类顺序PR #4484与分类组顺序PR #4599目前仅 Chromium 内核浏览器支持跟踪预算中隐藏分类不计入合计PR #4567跟踪预算tracking budget的合计值不再包含被隐藏的分类或分类组移动端账户页显示已关闭账户PR #4584MonthPicker 新增上/下月按钮PR #4692月份选择器可直接切换相邻月份银行同步设置中可解除账户关联PR #4714Unlink 账户后不再被同步拉取新增 KBCBEKBC_KREDBEBB银行PR #4743列入历史数据受限银行清单桌面应用可调用内部同步服务器命令PR #4847Electron 桌面版允许 UI 直接调用内嵌 sync server 命令Strawberry 信用卡交易金额翻转PR #4857修正该银行流水方向。认证与登录增强ACTUAL_USER_CREATION_MODElogin自动建号25.5.0 为 OpenID/OAuth2 登录新增了ACTUAL_USER_CREATION_MODE环境变量PR #4421。该变量在 load-config.js 中定义默认manual可选manual或loginmanual默认使用 OpenID/OAuth2 认证前必须在 Actual 中手动创建同用户名的账号loginOpenID/OAuth2 用户首次认证时自动在 Actual 创建账号免除管理员预建号步骤。官方文档 oauth-auth.md 对此有完整说明部署 OpenID 场景时按需配置即可。OpenID 首登确认密码与 returnUrl 修复本版本还改进了 OpenID 登录链路均可在发布文档的 Enhancements/Bugfix 中确认首次登录改为确认密码PR #4446OpenID 用户首次登录时要求设置/确认密码而非直接放行修复 returnUrl 问题PR #4836认证回调后的跳转地址恢复正常修复使用 config.json 或环境变量配置时的首登逻辑PR #4902配套新增的配置项还包括ACTUAL_OPENID_DISCOVERY_URL、ACTUAL_OPENID_CLIENT_ID、ACTUAL_OPENID_CLIENT_SECRET、ACTUAL_OPENID_SERVER_HOSTNAME、ACTUAL_OPENID_AUTH_METHODopenid/oauth2、ACTUAL_OPENID_ENFORCE、ACTUAL_TOKEN_EXPIRATION等详见 oauth-auth.md。Bugfix 精选除上述重点修复外25.5.0 的 Bugfix 按模块可归纳为交易与排班修复提前过账的排班交易误用未来排班日期改用当天日期PR #4719修复拆分排班预览的运行余额PR #4881修复交易列表打开新建交易弹窗时的崩溃PR #4812导入重做导入逻辑允许同时接受所有金额选项修复 In/Out 模式与既有拆分列共存时的 UI 卡死PR #4715ofx2json 逻辑中的 HTML 转义 bugPR #4838支持更长时间的 SimpleFIN 交易请求PR #4780自定义报表切换区间或日期范围时持久化过滤器PR #4724新增显示趋势线设置相关 SQL 迁移见 loot-core/migrations移动端修复收入分类不随激活月份变色PR #4774、超支横幅显示上月错误分类PR #4875、隐藏分类组未生效PR #4880侧边栏与偏好侧边栏固定偏好刷新后不保留PR #4733saveGlobalPrefs无法保存假值PR #4837银行同步GoCardless 初始账户链接的错误处理改进PR #4756Commerzbank 收款人正则转义PR #4845桌面端桌面应用加载备份弹窗白屏PR #4853、部分菜单链接失效PR #4860CLI无配置文件时ACTUAL_DATA_DIR环境变量未生效PR #4825其他关闭账户流程未校验转账或分类目标PR #4769模板目标在特定条件下未清除PR #4749开发模式多余警告清理PR #4735。工程维护与内部重构25.5.0 同步完成了一批内部治理工作对贡献者与集成方有实际参考价值React 19 升级PR #4700前端运行栈整体更新测试体系迁移 vitestsync-serverPR #4840、crdtPR #4851、api / desktop-client / eslint-plugin-actualPR #4856、loot-corePR #4859全部迁移到 vitest同时新增 Electron Playwright 测试与 fixturePR #4674、PR #4752服务端处理器拆分将预算文件、认证、加密相关处理器从 main.ts 分别抽到 server/budgetfiles/app.ts、server/auth/app.ts、server/encryption/app.tsPR #4547、PR #4660、PR #4662AQL 增强category_groups 表新增categories查询选项可用q(category_groups).options({ categories: all }).select(*)一并查询关联分类PR #4544IndexedDB 文件转严格 TypeScriptPR #4672loot-core 客户端代码迁移到 desktop-clientPR #4816移除 Electron 中的 ngrok 依赖后续将改为插件化方案PR #4768依赖与工具链升级 vite5.4.8 → 5.4.18、nanoid3.3.7 → 3.3.11、http-proxy-middleware3.0.3 → 3.0.5eslint自动修复接入 lint-staged部分.d.ts转.ts。升级建议服务器端以 Docker 部署的用户升级镜像 tag 至25.5.0即可获得全部新特性想脱离 Docker 快速体验的用户可直接npm install -g actual-app/cli参考 packages/cli/README.md 完成服务器部署与预算数据管理启用 OpenID 登录且希望免手动建号的管理员可配置ACTUAL_USER_CREATION_MODElogin详见 oauth-auth.md迁移到 25.5.0 后建议关注排班交易与自定义报表的修复项历史数据中可能存在的异常如提前过账日期错误、报表过滤器丢失会在新版本得到纠正。本版本所有改动条目均可回溯至发布文档 2025-05-03-release-25-5-0.md仓库内对应源码、迁移脚本与测试为上述功能提供了完整的可验证依据。【免费下载链接】actualA local-first personal finance app项目地址: https://gitcode.com/GitHub_Trending/ac/actual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考