这是「Docker 好项目」系列的第 16 期。前面 15 期解决的都是"服务器上的东西"——监控、密码、照片、音乐、文档、链接。这一期换个方向:管钱。市面上记账 App 有个共同特征——你的每一笔消费、每一张卡的余额、每一次工资到账,都在别人家的数据库里。而这恰恰是最不该外流的一类数据。Actual Budget 就是把记账本搬回自己服务器的那种工具。

Actual Budget 效果图

痛点开场

先说说现在记账这件事的几条死路:

  • 数据不是你的。随手记、鲨鱼记账、MoneyWiz 这类 App,数据都在厂商服务器上。厂商被收购、转型、停止服务,你的十年账本就变成一堆截图。更别提"导出"功能——很多 App 只让你导出 CSV,导出来还丢了分类和账户结构
  • 订阅制割韭菜。稍微像样点的记账工具全是月付/年付,一年一两百,功能上你真正用的可能只有 5%
  • 同步靠厂商。多设备同步必须登录厂商账号,手机上的账目数据在别人机器上转一圈
  • 隐私成本为零。消费记录能还原出一个人的作息、住址、健康状况、家庭结构。这类数据交给第三方,只因为它"方便"
  • 老牌桌面记账软件(比如 Money 系列)停更了。功能强、数据本地,但没人维护,新版系统上跑不起来

Actual Budget 的解法不是"再做一个记账 App",而是换一套架构:local-first(本地优先)。你的浏览器里跑着一个完整的 SQLite 数据库,所有计算、筛选、报表都在本地完成;服务器那边只负责同步和存文件。断网照样用,数据同时在你自己机器的浏览器和你自己的服务器上各存一份。

29k+ stars、MIT 协议、728 位贡献者,从 2022 年从原商业版 Actual 的代码基础上开源重建,迭代到现在已经相当成熟。

能力边界

能干什么

  • 信封预算法(envelope budgeting):这是 Actual 的核心方法论。给每个类别分配"本月预算额",花超了从别处挪。跟 YNAB 是同一个流派,而 Actual 是免费的、数据自持的
  • 追踪账户 + 手动记账:信用卡、储蓄、房贷、股票账户都能建;记账支持拆分、转账、自动付款(schedules)、规则批量处理
  • 导入流水:CSV / OFX / QFX / QIF 都能导,还带导入规则(按收款方自动归类、自动打标签),第一次配好之后每月导入就是点一下
  • 银行自动同步(有条件):支持 GoCardless(欧洲)、SimpleFIN(美加)、Pluggy(巴西)、Akahu(新西兰)、EnableBanking。中国境内银行不在支持范围内,国内用户走"手动/CSV 导入"这条路
  • 报表:净值曲线、分类趋势、现金流量、投资绩效……自定义 dashboard,组件随便拖。这块比大多数记账 App 强
  • 多设备同步:服务器 + 网页版 + 移动端 PWA + 桌面版(Win/macOS/Linux)。手机上"添加到主屏幕"就是一个能离线用的 App
  • 端到端加密:可选。开了之后服务器上存的只是密文,"服务器管理员也读不到你的预算"这句话是真的
  • API + CLI:官方 @actual-app/api 可以写脚本自动导流水
  • 多预算文件:一个人可以建多本账(家庭账 / 生意账 / 旅行账),互不干扰
  • 完整备份导出:一键导出全部数据(可加密),不锁定

不干什么

  • 不做多用户共享预算。这是个关键限制:如果你想"我和老婆共用一本账,各用各的账号登录",官方要求你必须先接一个 OpenID Provider(比如 Authentik、Keycloak),用户名从 OIDC 那边取。不接 OIDC 的话,服务器只有一个共享密码,所有人用同一个密码登进去——共享是共享了,但分不清谁是谁
  • 不接国内银行。别指望招行工行的流水自动进来,官方文档里列的五家全是境外机构
  • 不是投资组合追踪器。能看到账户余额和净值曲线,但没有持仓明细、没有行情、没有基金费率计算。要这些出门左转用别的工具
  • 不是发票/税务/企业账。没有发票管理、没有进销存、没有凭证。第 14 期 Paperless-ngx 那套是管文档的,也不是管账的
  • 没有内置告警。它不是监控工具,挂了它自己不会喊——老规矩,交给第 1 期 Uptime Kuma
  • 数据文件不是给人看的。服务器上存的是二进制 blob,你不装 Actual 客户端就打不开它。想"随时用 Excel 打开"的,这个工具不适合你

一句话:Actual Budget 是给"想认真记账、又不想把账本交给别人"的人用的。它的门槛不在部署,在于你得接受信封预算这套方法论——那是记账习惯的问题,不是技术问题。

部署前准备

  1. 一台能跑 Docker 的机器。官方镜像支持 amd64 / arm64,资源占用极低(Node.js + 静态前端,常驻内存几十 MB 到一两百 MB)。2 核 2G 的华为云轻量机器绰绰有余,比第 4 期 Immich 那种"全家桶"轻得多
  2. 一个域名。注意,这次不是"可选"——是必需。原因见下面的坑:Actual 的网页端依赖 SharedArrayBuffer,而这个特性只在 HTTPS(或 localhost)下才启用。你从局域网用 http://192.168.1.10:5006 打开,页面会直接报 SharedArrayBufferMissing 然后卡死。必须上 HTTPS
  3. 想好数据放哪。所有东西都在容器内 /data 一个目录里,挂出来即可
  4. 镜像源:官方只发布在 Docker Hub,镜像名 actualbudget/actual-server

关于 tag,这期我实测了一遍(v26.9.0,2026-09-01 发布):

tag 结果
26 404,不存在
26.9 404,不存在
26.9.0 200(digest sha256:59cab86c…)
latest 200,与 26.9.0 digest 完全相同
latest-alpine / 26.9.0-alpine 200(另一份镜像)

跟第 8 期 Navidrome、第 12 期 Miniflux、第 15 期 linkding 是同一类:只发完整版本号 + latest,不滚动次/主版本 tag。所以必须钉全量 26.9.0,写 :26 或 :26.9 都会直接 pull 失败。

顺带说一句版本号的怪事:Actual 从 25.x 起改用类似 CalVer 的 年.月.补丁 方案(26.9.0 = 2026 年 9 月那版),所以别被"26"这个数字吓到以为是什么大版本跳跃。.github/workflows 里发版是自动的,基本每月一版。

变体怎么选:

变体 基础镜像 适合
26.9.0(默认,无后缀) node:24-bookworm-slim 推荐。glibc,兼容性最好
26.9.0-alpine alpine:3.23 镜像更小,但 musl libc 偶发原生模块问题,生产没必要省这几百 MB

docker run 一行版

mkdir -p /opt/actual/data

docker run -d \
  --name actual-server \
  -p 127.0.0.1:5006:5006 \
  -v /opt/actual/data:/data \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  actualbudget/actual-server:26.9.0

装完浏览器开 http://127.0.0.1:5006(只在本机、只走 localhost 时 HTTP 才被允许,因为 localhost 也算 secure context),会提示你设置服务器密码。设完就能用了。

几个必须知道的点:

  • -v …:/data 是唯一要挂的卷。预算文件、账号数据库、配置全在里面。这个目录丢了 = 账本没了
  • 端口映射成 127.0.0.1:5006 是留给反向代理的姿势。因为强制 HTTPS,不建议直接 -p 5006:5006 暴露公网——那样你只能走 HTTP,而 HTTP 下网页端根本跑不起来
  • 镜像里没有 HEALTHCHECK(我查了镜像 config,Healthcheck 字段是 null),官方 compose 是自己挂了一个健康检查脚本。想要 1Panel 里显示 healthy,用下面那份 compose
  • 容器以 root 运行。这是官方镜像一个不太好看的地方:Dockerfile 里创建了 actual 用户(UID/GID 1001),也 chown 了 /data,但最后并没有 USER actual 指令。我拉了镜像 config 确认,User 字段是 null → 默认 root。好处是不会写文件权限问题,坏处是 /data 里的文件都是 root 所有(见踩坑清单)

docker-compose 推荐版

services:
  actual-server:
    image: actualbudget/actual-server:26.9.0
    container_name: actual-server
    restart: unless-stopped
    ports:
      - "127.0.0.1:5006:5006"      # 只绑本机,对外交给反向代理上 HTTPS
    volumes:
      - ./data:/data               # 账本 + 配置全在这,备份就备它
    environment:
      TZ: Asia/Shanghai
      # 按需打开:
      # ACTUAL_LOGIN_METHOD: password
      # ACTUAL_ALLOWED_LOGIN_METHODS: password          # 只允许密码登录,把 header 认证关掉
      # DEBUG: actual:config                            # 排障时看配置有没有被正确读到
    healthcheck:
      test: ["CMD-SHELL", "node scripts/health-check.js"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 20s

这份基本就是官方 compose(packages/sync-server/docker-compose.yml)改写而来,只做了三处调整:tag 从 latest 钉成 26.9.0、端口从 5006:5006 收到 127.0.0.1:5006、加了时区。健康检查脚本和参数是官方原样的——它内部就是 fetch(http://<hostname>:<port>/health),看返回的 status 是不是 "UP"。

没有数据库容器、没有 Redis、没有 broker。单容器 + 一个数据目录,这是它比第 4 期 Immich、第 14 期 Paperless-ngx 省心得多的地方。

配置项逐项解释

下面的默认值全部来自 v26.9.0 源码 packages/sync-server/src/load-config.js(convict schema)实测:

变量 默认值 说明 / 为什么这么写
ACTUAL_DATA_DIR 存在 /data 就用 /data,否则用程序目录 数据根目录。镜像里 /data 一定存在,所以不用设它,挂卷就行
ACTUAL_CONFIG_PATH 无 配置文件路径。默认找 <程序目录>/config.json,找不到再找 /data/config.json。注意:这个变量不能在 config.json 里写(得先靠它找到 config.json)
ACTUAL_PORT 5006 容器内监听端口。改它要同步改 compose 的映射
ACTUAL_HOSTNAME :: 监听地址,默认双栈(IPv6 + IPv4)。别改成 127.0.0.1——那样容器内健康检查能过,但宿主机映射进来的流量会被拒
ACTUAL_SERVER_FILES /data/server-files 这里放 account.sqlite:服务端密码的哈希、预算文件清单、当前会话 token
ACTUAL_USER_FILES /data/user-files 预算文件本体(二进制 blob)。多本账就是多个文件
ACTUAL_LOGIN_METHOD password 默认认证方式。可选 password / header / openid
ACTUAL_ALLOWED_LOGIN_METHODS password,header,openid 允许哪些方式。只想用密码登录就写 password,把 header 关掉更安全(header 模式靠一个 HTTP 头就能登录,配错了等于没密码)
ACTUAL_TRUSTED_PROXIES 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7, ::1/128 信任的反代网段,用于识别真实客户端 IP(速率限制靠它)。反代跑在宿主机上、容器走 bridge 网络时,默认值刚好覆盖 Docker 网段,一般不用动
ACTUAL_TRUSTED_AUTH_PROXIES 跟随上面 允许用 HTTP 头认证的来源。如果你开了 header 登录方式,务必收窄这里
ACTUAL_TOKEN_EXPIRATION never 会话 token 有效期。可选 never / openid-provider / 毫秒数。嫌"永不过期"不放心可以设 604800000(7 天)
ACTUAL_USER_CREATION_MODE manual 多用户场景下新用户怎么进来。manual 要管理员在 User Directory 里手动加。只在接了 OpenID 时才有意义
ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB 20 单次同步包体积上限(application/actual-sync)。账本再大也不到这个量级,一般不动
ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB 50 开了端到端加密后同步包的上限,比上面那个宽松
ACTUAL_UPLOAD_FILE_SIZE_LIMIT_MB 20 其他上传接口的通用上限(比如导入 CSV)
ACTUAL_HTTPS_KEY / ACTUAL_HTTPS_CERT 空 让 Node 自己起 TLS。建议别用——交给反向代理更省事(证书续期、HSTS、日志都在一层处理)
ACTUAL_OPENID_* 空 OpenID 那一整套(discovery URL / client_id / client_secret / server_hostname / auth method)。想做多用户就必须填这些
ACTUAL_OPENID_ENFORCE false 强制走 OpenID。适用于"我不想让任何人用密码登"的场景
ACTUAL_CORS_PROXY_ENABLED false 给前端插件用的 CORS 代理端点(/cors-proxy)。默认关着,公网部署别开——那等于开放一个任意 URL 转发器
ACTUAL_GITHUB_TOKEN 空 访问 GitHub API 的 token。只有接了 GitHub 相关的插件才用得上
TZ 无(镜像只设了 NODE_ENV=production) Node 读系统时区。不改的话容器日志时间戳差 8 小时,排查问题时对不上账

另外两个不是环境变量、但一定要知道的:

  • PUID / PGID 完全无效。镜像里没有入口脚本做 chown(ENTRYPOINT 直接就是 tini),跟第 8 期 Navidrome、第 9 期 changedetection.io 是同一个坑。想非 root 运行只能用 compose 的 user: 指令,并且必须先把宿主目录 chown 成对应 UID
  • 运行时的速率限制是写死的:NODE_ENV=production(镜像里已设)时,app.ts 会启用 express-rate-limit,60 秒窗口 500 次。正常使用碰不到,批量导数据时可能触发——那时看日志会见 429

1Panel 面板怎么搞

先说结论:1Panel 应用商店里没有 Actual Budget。我拉了 1Panel-dev/appstore 仓库(dev 分支,共 265 个应用)逐个过滤,actual / budget 都是零命中。所以这次只能走编排路线。

1Panel 上的操作步骤:

  1. 左侧 容器 → 编排 → 创建编排,名称填 actual,把上面那份 compose 贴进去
  2. 先把宿主目录建好:mkdir -p /opt/1panel/apps/actual/data(1Panel 的编排默认工作目录在 /opt/1panel/apps/<编排名>/,用相对路径 ./data 就会落在那一层)
  3. 点部署。第一次会拉镜像,国内机器建议先在 容器 → 镜像 → 拉取 里配好加速地址再拉
  4. 部署完在 容器 页能看到 actual-server 处于 healthy(因为 compose 里挂了健康检查)

然后是反向代理,这是本期最关键的一步:

  1. 网站 → 创建网站 → 反向代理,主域名填 bk.你的域名.com,代理地址填 http://127.0.0.1:5006
  2. 顺手在站点设置里申请 Let's Encrypt 证书、打开 HTTPS 强制跳转

⚠️ 这里有个 1Panel 特有的注意点。1Panel 的反向代理片段落在:

/opt/1panel/www/sites/<域名>/proxy/root.conf

默认透传是没问题的(Actual 自己会设 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp)。但如果你在 1Panel 里另外配了「安全 Header」、或者手抖在反代片段里 add_header 了这两个头,就会变成双份头——而"重复的 require-corp"会让浏览器直接判定安全策略无效,页面报 SharedArrayBufferMissing 然后白屏。

真遇到这个情况,在反代片段里这么写(先隐藏上游的,再由 Nginx 统一设):

location ^~ / {
    proxy_pass http://127.0.0.1:5006;
    # 防止与上游重复设置这两个头
    proxy_hide_header Cross-Origin-Embedder-Policy;
    proxy_hide_header Cross-Origin-Opener-Policy;
    add_header Cross-Origin-Embedder-Policy "require-corp" always;
    add_header Cross-Origin-Opener-Policy "same-origin" always;
    add_header Origin-Agent-Cluster "?1" always;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

改完在 1Panel 里重载 OpenResty 即可。这一段官方文档在 "Using a Reverse Proxy" 页专门用小节警告过,不是玄学。

首次访问

  1. 先确认容器起来了、健康检查通过:
curl -s http://127.0.0.1:5006/health
# {"status":"UP"}

# 顺便看版本对不对
curl -s http://127.0.0.1:5006/info
  1. 浏览器打开 https://bk.你的域名.com。第一次会让你设置服务器密码——这个密码是"进服务器的门禁",跟后面的端到端加密密码是两回事,别搞混(也建议别用同一个)

  2. 登录后,如果你还没建过文件,它会自动建一本空的预算;已经建过的,会列出所有预算文件让你选一个下载

  3. 进去长这样——左边是账户列表(含 On budget / Off budget 分组),中间是信封预算表,上方是按月份横滑的时间轴:

Actual Budget 预算主界面

  1. 第一件事:点左上角预算名 → 设置里把货币和日期格式改成 CNY / YYYY-MM-DD。默认是美元和 MM/DD,国内看着别扭

  2. 第二件事:加账户。+ Add account 里有三种:On budget(信用卡、储蓄卡、现金——参与预算)、Off budget(房贷、基金、房产——只记净值)、Closed(已注销账户)

  3. 第三件事:手机上装一下。用手机浏览器打开同一个地址,Safari「添加到主屏幕」/ Chrome「安装应用」,之后就是一个能离线用的 PWA。注意:手机上同样必须走 HTTPS,否则一样白屏

最小可用配置

1)把"导入 + 自动归类"这套流程配起来(最值钱的一步)

国内没有银行直连,所以主力工作流是:从银行 App/网银导出 CSV → 导入 Actual → 规则自动归类。先建规则,再导数据,顺序别反:

Payee contains "滴滴出行"   →  Category = 交通 / 打车
Payee contains "美团"       →  Category = 餐饮
Payee contains "工资"       →  Category = 收入 / 工资
Amount > 1000 且 Payee contains "转账" →  Category = 内部转账

规则(Rules)是 Actual 里回报率最高的功能。花十分钟配十条,之后每月导入就是「选文件 → 点 Import → 复盘几条没匹配上的」。

配好规则、导完流水之后,账户页长这样——每行都带分类下拉和"已对账"锁:

Actual Budget 账户流水页

2)用信封法做预算,别用"事后分类"

信封预算的精髓是给每类钱分配一个额度,然后从额度里花,而不是先花完再看花到哪去了。做法:月初在预算表里给"餐饮 2000 / 交通 800 / 人情 500"填上数字,花超了必须从别的类别里"挪"(点类别余额就能挪)。这个动作带来的心理约束,是记账 App 做不到的——它逼你做取舍。

3)打开报表,找到自己真正关心的那三个数

Actual 的 Reports 是可拖拽自定义的 dashboard。默认组件里最值得看的:净值(Net Worth)趋势、近 12 个月分类支出、平均月支出。报表页长这样:

Actual Budget 报表页

别装十个组件——只看"净值曲线"和"近 12 个月分类支出"两个就够,剩下的都是自我感动。

4)把自动付款(Schedules)用起来

房租、房贷、宽带、订阅费这类固定支出全部建成 Schedule,绑定到对应类别。好处有两个:一是它会在 Calendar 里提前标出"这笔钱要走了",二是到期自动生成待确认交易,你只需要核对金额。

5)考虑开端到端加密(但要看清代价)

设置里可以给预算文件加一层端到端加密:开启后数据在离开你的设备之前就加密,服务器上存的只是密文。

Settings → Encryption → Enable encryption

开之前必须知道三件事:

  • 忘了加密密码 = 数据永久丢失。官方原话,没有任何后门可以恢复
  • 这是单向操作,开了就关不掉。想退回未加密文件只能走"导出 → 新建未加密文件 → 导入"
  • 加密只覆盖预算数据,不覆盖银行同步令牌。bank sync 的凭据是明文存在服务器上的

对个人自托管用户来说,服务器是你自己的,加密带来的实质收益有限、丢失风险却是实打实的。我的建议是:先不开,但把「设置 → 导出」当常规操作,定期导一份加密备份。

告警 / 通知配置

Actual Budget 没有任何内置通知系统——它不会因为"这个月餐饮花超了"给你发消息,也不会因为服务器挂了给你发消息。所以这一节要说的是"外部怎么兜住它"。

1)活着吗 → Uptime Kuma(第 1 期)

加一个 HTTP(s) 监控:

URL:      https://bk.你的域名.com/health
期望状态:200
间隔:    60s

这个端点无需鉴权(容器健康检查脚本用的就是它),是最干净的判据。别把 Uptime Kuma 和 Actual 放同一台机器上还互相监控——老规矩,监控链路要独立。

顺带可以加一个"关键字"监控盯 /info,返回的 JSON 里有版本号,万一镜像哪天被回滚你能立刻发现。

2)预算本身要不要提醒?——用规则 + 报表代替

Actual 没有"超预算提醒",但你可以用规则(Rules)在数据层做标记,比如给某类交易自动打上特定 Payee 前缀,然后建一个"只看这些"的自定义报表,每周扫一眼。想要更主动的,官方 @actual-app/api 能读数据,自己写个脚本跑 cron、超阈值调第 13 期 ntfy 推一条,是完全可行的——但那是"你写代码",不是"它自带功能",别指望开箱就有。

3)备份失败要能知道

真正的风险不是服务挂了,是你以为在备份、其实备份早就断了。见下一节,备份脚本里必须加失败告警。

反向代理与 HTTPS

这一节对 Actual 来说是强制项,不是优化项。

为什么必须 HTTPS:Actual 的前端在浏览器里跑一个真正的 SQLite(WASM),这需要 SharedArrayBuffer;而 SharedArrayBuffer 出于安全考虑只在 secure context(HTTPS 或 localhost)下可用,同时还要求响应头里有:

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy:    same-origin

Actual 的服务端自己会设这两个头,所以正常情况你不用管。你要管的是"别把这两个头搞成两份"——这是官方文档里唯一用加粗警告标出来的反代坑。

用第 2 期 Nginx Proxy Manager:

  • Forward Hostname / IP:127.0.0.1,Port:5006,Scheme:http
  • 勾上 Block Common Exploits,开 SSL,申请 Let's Encrypt
  • 不要在 NPM 的 "Advanced" 里再手动 add_header 那两个 COOP/COEP 头——NPM 会透传上游的,重复就坏事

用 1Panel 自带反向代理:见上文「1Panel 面板怎么搞」第 5–6 步,需要兜底就用那段带 proxy_hide_header 的配置。

Caddy 一行流(最省心):

bk.你的域名.com {
    reverse_proxy 127.0.0.1:5006
}

Caddy 不会重复设上游已有的头,这个场景下它是最不容易出错的选项。

安全提醒:账本类数据的敏感度在家用自托管服务里排前三。公网暴露至少要齐这几样——强密码、HTTPS、ACTUAL_ALLOWED_LOGIN_METHODS=password(关掉 header 认证)、别开 ACTUAL_CORS_PROXY_ENABLED。想在服务器前面再加一层认证(Cloudflare Access、Authelia)也可以,但注意加完认证之后要考虑它对 WebSocket 和长连接的影响——Actual 用的是普通 HTTP 短连接同步,一般不受影响。

踩坑清单

  1. 不用 HTTPS 就是白屏。http://IP:5006 从别的设备访问,浏览器控制台会报 SharedArrayBufferMissing,页面直接起不来。这不是 bug,是浏览器的硬性安全策略。唯一的例外是 localhost
  2. :26 / 26.9 这两个 tag 不存在。上游只发完整版本号,写 actualbudget/actual-server:26.9 会直接 pull 失败
  3. 别乱 add_header COOP/COEP。反代层重复设置这两个头,浏览器会因为"策略重复"而整体失效,症状跟第 1 条一模一样。用 proxy_hide_header 隐藏上游的,再由代理统一设
  4. 容器以 root 运行,/data 里的文件都是 root 所有。查过镜像 config,User 是 null——Dockerfile 建了 actual 用户(1001)却没用它。想非 root 运行要自己加 user: "1001:1001",并且先 chown -R 1001:1001 /opt/actual/data,否则容器起不来(写不进 /data/server-files/account.sqlite)
  5. PUID / PGID 是无效变量。镜像里没有做 UID 映射的入口脚本,设了也不会生效。这是照抄其他教程最容易白折腾的一条
  6. 端到端加密是单向的。开了关不掉,忘了密码数据永久丢失。开之前先确认你的密钥管理习惯
  7. 多用户必须接 OpenID。官方文档明确写着 "This feature requires you to have set up an OpenID Provider"。没接 OIDC 的时候,服务器只有一个共享密码,所有登录的人都算同一个人
  8. 国内服务器别碰 bank sync。GoCardless / SimpleFIN / Pluggy / Akahu / EnableBanking 全在境外,且没有国内银行。硬配不但连不上,还会因为 OAuth 回调失败留一堆报错日志。老老实实用 CSV 导入
  9. ACTUAL_ALLOWED_LOGIN_METHODS 默认包含 header。header 认证方式是给"前面还有一层认证代理"的场景准备的——如果你前面没有认证代理,又设了 ACTUAL_TRUSTED_AUTH_PROXIES,等于开后门。个人部署直接收成 password
  10. 修改配置后必须重启容器。convict 的 schema 只在进程启动时读一次,改 compose 里的环境变量后不 up -d 是不生效的。排查"配置没生效"第一步就开 DEBUG: actual:config 看日志
  11. 忘记服务器密码可以救回来,不用重建数据:
docker exec -it actual-server /bin/sh node /app/src/scripts/reset-password.js
# 或者等价的短路径(镜像里 src/scripts 是指向 scripts 的软链)
docker exec -it actual-server node scripts/reset-password.js

会提示你输两遍新密码。改完所有已登录设备都要重新登录。

  1. NODE_ENV=production 时全局限流 500 次/分钟。批量导入大 CSV 时可能撞上 429,重试即可,别以为是服务挂了
  2. 预算文件不能直接看。/data/user-files/ 里是二进制 blob,想读内容只能通过 Actual 客户端或 API。别指望用 SQLite 工具打开它
  3. 别用 :latest。老话重提——它当前和 26.9.0 指向同一个 digest,但下个月发新版它就跑了
  4. 升级前先备份。docker compose pull && docker compose up -d 会自动跑数据库迁移(src/migrations.ts),迁移是一向前的,降级回旧镜像可能读不了新格式

备份

数据全在 /data 一个目录里,备份就备它:

# 1) 停容器(SQLite 在写入时裸拷有风险)
docker compose stop actual-server

# 2) 整目录打包
tar czf actual-data-$(date +%F).tar.gz -C /opt/actual data

# 3) 起回来
docker compose start actual-server

更推荐的做法:用 Actual 自己的导出。登录网页端 → 设置 → Export,导出一个 .zip(可选加密)。这条路径的好处是格式稳定、跨版本可用,即使哪天服务端 schema 变了也能导入回去。

自动化脚本(放在华为云机器上,接第 13 期 ntfy 做失败告警):

#!/usr/bin/env bash
set -euo pipefail

DATA=/opt/actual/data
DEST=/backup/actual/$(date +%F)
NTFY=https://ntfy.你的域名.com/actual-alerts

mkdir -p "$DEST"

# 停容器保证一致性(几秒钟的事)
docker stop actual-server >/dev/null
if tar czf "$DEST/actual-data.tar.gz" -C "$(dirname "$DATA")" "$(basename "$DATA")"; then
  docker start actual-server >/dev/null
  echo "备份完成 $(date '+%F %T'),大小 $(du -h "$DEST/actual-data.tar.gz" | cut -f1)"
else
  docker start actual-server >/dev/null
  # 备份失败必须喊出来,否则你永远不知道备份早就断了
  curl -s -d "Actual Budget 备份失败:$(date '+%F %T')" "$NTFY" >/dev/null
  exit 1
fi

# 只留最近 14 份
find /backup/actual -maxdepth 1 -type d -mtime +14 -exec rm -rf {} +

恢复:新机器上把 data/ 解出来挂上去,起容器即可。如果换了域名,登录后重新选一次预算文件就行——账户密码在 data/server-files/account.sqlite 里,跟着一起恢复。

异地副本:备份躺在同一块盘上等于没备份。第 14 期那台飞牛 NAS(或者任意对象存储)都可以作为落点,一条 rsync 或 rclone 就够。

小结

适合谁

  • 想认真管钱、又不想把消费记录交给第三方的人。这是它的第一性价值
  • YNAB 用户想省钱:信封预算法是同一套方法论,Actual 免费且数据自持
  • 已经有自托管环境的人:单容器、一个数据目录、几百 MB 内存,接进现有栈几乎零成本
  • 多设备用户:手机 PWA 无网可用,桌面 App 也在,同步靠自己的服务器
  • 要写自动化的人:官方 API + CLI,能把流水导入、报表输出全脚本化

不适合谁

  • 想"打开就能用"、不愿意改记账习惯的人。信封预算需要你每月做一次分配动作,不做的话它就只是个流水记录器
  • 指望银行流水自动进来的人。国内没有对接,这个是硬伤
  • 需要多人分账协作的(比如夫妻各记各的)。不上 OpenID 就只有共享密码,分不清人
  • 需要发票、报税、企业账的。定位不同,别硬套
  • 只想看"这个月花了多少"的人。为了这么简单一件事跑一个服务器不划算,手机自带记账就够

到这里,本系列第 16 期。回头看这套自托管地图已经成型:Uptime Kuma 看门、NPM 开门、Vaultwarden 管钥匙、Immich 管照片、Navidrome 管音乐、Miniflux 管订阅、ntfy 管推送、Paperless-ngx 管纸、linkding 管链接、Actual Budget 管钱。十个小服务,合起来是一套完全不打折、也不受制于人的个人基础设施——而且它们之间还能互相咬合,比如这期的健康检查交给第 1 期、备份告警交给第 13 期。

项目地址