这是「Docker 好项目」系列的第 16 期。前面 15 期解决的都是"服务器上的东西"——监控、密码、照片、音乐、文档、链接。这一期换个方向:管钱。市面上记账 App 有个共同特征——你的每一笔消费、每一张卡的余额、每一次工资到账,都在别人家的数据库里。而这恰恰是最不该外流的一类数据。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 是给"想认真记账、又不想把账本交给别人"的人用的。它的门槛不在部署,在于你得接受信封预算这套方法论——那是记账习惯的问题,不是技术问题。
部署前准备
- 一台能跑 Docker 的机器。官方镜像支持 amd64 / arm64,资源占用极低(Node.js + 静态前端,常驻内存几十 MB 到一两百 MB)。2 核 2G 的华为云轻量机器绰绰有余,比第 4 期 Immich 那种"全家桶"轻得多
- 一个域名。注意,这次不是"可选"——是必需。原因见下面的坑:Actual 的网页端依赖
SharedArrayBuffer,而这个特性只在 HTTPS(或 localhost)下才启用。你从局域网用http://192.168.1.10:5006打开,页面会直接报SharedArrayBufferMissing然后卡死。必须上 HTTPS - 想好数据放哪。所有东西都在容器内
/data一个目录里,挂出来即可 - 镜像源:官方只发布在 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 上的操作步骤:
- 左侧 容器 → 编排 → 创建编排,名称填
actual,把上面那份 compose 贴进去 - 先把宿主目录建好:
mkdir -p /opt/1panel/apps/actual/data(1Panel 的编排默认工作目录在/opt/1panel/apps/<编排名>/,用相对路径./data就会落在那一层) - 点部署。第一次会拉镜像,国内机器建议先在 容器 → 镜像 → 拉取 里配好加速地址再拉
- 部署完在 容器 页能看到
actual-server处于healthy(因为 compose 里挂了健康检查)
然后是反向代理,这是本期最关键的一步:
- 网站 → 创建网站 → 反向代理,主域名填
bk.你的域名.com,代理地址填http://127.0.0.1:5006 - 顺手在站点设置里申请 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" 页专门用小节警告过,不是玄学。
首次访问
- 先确认容器起来了、健康检查通过:
curl -s http://127.0.0.1:5006/health
# {"status":"UP"}
# 顺便看版本对不对
curl -s http://127.0.0.1:5006/info
-
浏览器打开
https://bk.你的域名.com。第一次会让你设置服务器密码——这个密码是"进服务器的门禁",跟后面的端到端加密密码是两回事,别搞混(也建议别用同一个) -
登录后,如果你还没建过文件,它会自动建一本空的预算;已经建过的,会列出所有预算文件让你选一个下载
-
进去长这样——左边是账户列表(含 On budget / Off budget 分组),中间是信封预算表,上方是按月份横滑的时间轴:

-
第一件事:点左上角预算名 → 设置里把货币和日期格式改成
CNY/YYYY-MM-DD。默认是美元和MM/DD,国内看着别扭 -
第二件事:加账户。
+ Add account里有三种:On budget(信用卡、储蓄卡、现金——参与预算)、Off budget(房贷、基金、房产——只记净值)、Closed(已注销账户) -
第三件事:手机上装一下。用手机浏览器打开同一个地址,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 → 复盘几条没匹配上的」。
配好规则、导完流水之后,账户页长这样——每行都带分类下拉和"已对账"锁:

2)用信封法做预算,别用"事后分类"
信封预算的精髓是给每类钱分配一个额度,然后从额度里花,而不是先花完再看花到哪去了。做法:月初在预算表里给"餐饮 2000 / 交通 800 / 人情 500"填上数字,花超了必须从别的类别里"挪"(点类别余额就能挪)。这个动作带来的心理约束,是记账 App 做不到的——它逼你做取舍。
3)打开报表,找到自己真正关心的那三个数
Actual 的 Reports 是可拖拽自定义的 dashboard。默认组件里最值得看的:净值(Net Worth)趋势、近 12 个月分类支出、平均月支出。报表页长这样:

别装十个组件——只看"净值曲线"和"近 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 短连接同步,一般不受影响。
踩坑清单
- 不用 HTTPS 就是白屏。
http://IP:5006从别的设备访问,浏览器控制台会报SharedArrayBufferMissing,页面直接起不来。这不是 bug,是浏览器的硬性安全策略。唯一的例外是 localhost :26/26.9这两个 tag 不存在。上游只发完整版本号,写actualbudget/actual-server:26.9会直接 pull 失败- 别乱
add_headerCOOP/COEP。反代层重复设置这两个头,浏览器会因为"策略重复"而整体失效,症状跟第 1 条一模一样。用proxy_hide_header隐藏上游的,再由代理统一设 - 容器以 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) PUID/PGID是无效变量。镜像里没有做 UID 映射的入口脚本,设了也不会生效。这是照抄其他教程最容易白折腾的一条- 端到端加密是单向的。开了关不掉,忘了密码数据永久丢失。开之前先确认你的密钥管理习惯
- 多用户必须接 OpenID。官方文档明确写着 "This feature requires you to have set up an OpenID Provider"。没接 OIDC 的时候,服务器只有一个共享密码,所有登录的人都算同一个人
- 国内服务器别碰 bank sync。GoCardless / SimpleFIN / Pluggy / Akahu / EnableBanking 全在境外,且没有国内银行。硬配不但连不上,还会因为 OAuth 回调失败留一堆报错日志。老老实实用 CSV 导入
ACTUAL_ALLOWED_LOGIN_METHODS默认包含header。header认证方式是给"前面还有一层认证代理"的场景准备的——如果你前面没有认证代理,又设了ACTUAL_TRUSTED_AUTH_PROXIES,等于开后门。个人部署直接收成password- 修改配置后必须重启容器。convict 的 schema 只在进程启动时读一次,改 compose 里的环境变量后不
up -d是不生效的。排查"配置没生效"第一步就开DEBUG: actual:config看日志 - 忘记服务器密码可以救回来,不用重建数据:
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
会提示你输两遍新密码。改完所有已登录设备都要重新登录。
NODE_ENV=production时全局限流 500 次/分钟。批量导入大 CSV 时可能撞上 429,重试即可,别以为是服务挂了- 预算文件不能直接看。
/data/user-files/里是二进制 blob,想读内容只能通过 Actual 客户端或 API。别指望用 SQLite 工具打开它 - 别用
:latest。老话重提——它当前和26.9.0指向同一个 digest,但下个月发新版它就跑了 - 升级前先备份。
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 期。
项目地址
- GitHub:https://github.com/actualbudget/actual
- 官网 / 文档:https://actualbudget.org/("Using a Reverse Proxy" 和 "Enabling SharedArrayBuffer Access" 这两页在部署前务必读一遍)
- 在线演示:https://demo.actualbudget.org/(不用装就能摸一遍,先确认自己能接受信封预算的交互)
- 客户端下载:https://actualbudget.org/download/(Windows / macOS / Linux 桌面版)
- Docker 镜像:
actualbudget/actual-server:26.9.0(只有 Docker Hub 一个源;26.9.0-alpine是 alpine 变体) - 社区:官方 Discord(文档页脚有入口),提问前先搜一遍 troubleshooting 分类