Actual Budget 私人账本:Docker 部署、CSV 导入与同步恢复
固定 Actual 版本,从虚构交易核对导入与双端同步,分清服务密码和账本加密,冷备完整 data 并在空目录恢复。
旧记账应用导出了一份 CSV,换到电脑以后,日期、转账和分类却未必能原样对上。用 Actual Budget 自托管时,先用几笔虚构记录走完导入、跨设备同步和恢复,再放入真实账本,出错时更容易找到是哪一步的问题。
本文使用固定的 Actual 26.10.0,部署个人使用的同步服务,不连接银行或第三方聚合服务。服务器保存同步副本,浏览器也保存本地账本;两处状态需要分别核对,不能因为刷新后还看得到记录,就认定它已经上传成功。
一个账本文件与整台服务的备份不同
浏览器里的本地账本、下载的账本导出和 VPS 上的同步数据,各有用途。本地副本方便离线编辑,导出文件用于另存某份账本,服务端完整副本用于恢复访问设置及已同步文件。同步会传播修改,也可能传播误删,不替代保留历史的独立备份。
本例将容器的 /data 放在 VPS 本地磁盘。其中 server-files 保存服务账号、会话和文件目录等状态,user-files 保存预算文件。账本持续修改会积累同步历史,备份前查看实际占用;不要只按 CSV 文件大小估计长期空间。
先复用有余量的现有 Linux VPS。示例给同步服务设 512 MiB 内存上限,这不是官方最低要求或整机配置保证,系统、其他服务和恢复副本另需余量。个人账本通常不需要为大带宽或住宅 IP 另买机器;更应确认自己的设备能稳定访问、磁盘可持久保存,以及有没有服务器之外的备份位置。
确需新实例时,可比较雨云 RCS 的地区与月付配置,核对计算资源、本地磁盘、续费与备份的完整费用。先完成一份测试账本的同步和恢复,再决定长账期。已有机器足够就继续使用,域名、异地存储和以后可能接入的第三方服务费用另计。
先启动一个私人实例
以下在已安装 Docker Engine 和 Compose 插件的 Linux root shell 中执行。目录用于新实例,不覆盖已有账本。官方同时提供 Docker Hub 与 GHCR 镜像,本例固定 Docker Hub 的 26.10.0 及对应多架构索引摘要,不跟随 nightly 或浮动 latest。
set -eu
umask 077
mkdir -p /srv/actual/data
chmod 700 /srv/actual /srv/actual/data
cd /srv/actual
保存 compose.yaml。只允许密码登录方式,应用端口仅绑定服务器回环地址。
services:
actual:
image: actualbudget/actual-server:26.10.0@sha256:24645e971da6bb1a1f953d6859e307a0b29be1e8b4130a35b3220c209b5b860c
restart: unless-stopped
ports:
- "127.0.0.1:5006:5006"
environment:
ACTUAL_DATA_DIR: /data
ACTUAL_LOGIN_METHOD: password
ACTUAL_ALLOWED_LOGIN_METHODS: password
volumes:
- ./data:/data
mem_limit: 512m
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=80 actual
curl -I http://127.0.0.1:5006/
检查 Docker 的实际端口与数据挂载,再在自己的电脑另开终端,替换 SSH 用户和服务器地址:
ssh -N -L 15006:127.0.0.1:5006 user@your-server
浏览器打开 http://localhost:15006,按首次设置建立服务访问密码,创建一份测试账本。localhost 是本机测试的安全上下文例外,不能将服务器 IP 的普通 HTTP 地址当作等效入口。先保存访问密码,确认退出后可以重新登录,再接正式域名。
域名配置后再开始跨设备同步
Actual 需要浏览器支持 SharedArrayBuffer,同时满足安全上下文和跨源隔离条件。正式入口采用 HTTPS;即使通过 VPN 访问,普通远端 HTTP 地址也不自动满足这些条件。官方同步服务会设置 COOP、COEP 响应头,前面的代理不能把它们移除。
宿主机已有 Caddy 时,在现有配置中加入自己的域名站点块。将下面的示例域名替换为实际地址,确认 DNS、80/443 入站和证书申请条件,验证配置后再重载,不覆盖其他站点。
budget.example.com {
reverse_proxy 127.0.0.1:5006
}
curl -I https://budget.example.com/
检查响应中 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp 是否保留。再用浏览器确认没有 SharedArrayBuffer 或跨源隔离错误,实际创建并打开账本。响应头存在只是其中一项检查,不代表同步已经完成。代理若在另一个容器内,127.0.0.1 指向代理自身,需按已有网络连接应用。
用两个独立浏览器配置或两台设备连接同一正式入口、打开同一份已同步账本。在 A 新增虚构交易并同步,到 B 核对日期、账户、金额和备注;再从 B 改备注,回到 A 确认。无网络时留在本地的修改需要重新联网同步,不要让旧设备在恢复后立刻把旧状态重新推回服务。
CSV 导入先用一个小样本
保留原始 CSV,先复制几条非敏感测试记录。列映射时逐项核对日期格式、金额正负、账户、收款方和备注,尤其是小数点与千位分隔符。先导入一笔收入、一笔支出、一笔退款,以及两个账户之间的一次转账,查看每条记录的实际解释。
把两边账户各导入一次时,转账可能需要匹配,不能只看总行数或总额。重复导入的处理也应先在小样本观察,确认当前格式的识别行为,再迁移历史资料。分类规则先少量建立,检查它会影响哪些记录,避免把格式错误通过批量规则扩散。
记录导入文件名、覆盖日期与目标账户,以便发现重复。保存后在另一个客户端核对几条交易,确认这次导入已同步。导入后的记录仍需与自己的原始凭据核对。
银行自动连接放到后面考虑
首次部署不配置银行同步,可以减少外部凭据和连接服务的依赖。以后需要时,再查看自己地区、银行与连接服务的支持、授权、费用和撤销方法;界面出现选项不等于自己的账户已经可接入。不要把银行密码或令牌写进 Compose、截图或公开日志。
服务访问密码与账本端到端加密密码用途不同。启用 E2EE 后,其他设备下载账本需要对应的加密密码;它应与服务密码分开保存。共享服务访问密码的人仍可能删除服务器上的加密文件,本例按个人实例安排,不用加密代替用户权限。HTTPS 保护传输,E2EE 保护同步到服务器的预算内容,两者不能互相代替。官方说明,本地设备上的预算仍未因此自动加密,银行连接令牌也不在预算 E2EE 的覆盖范围内。
先用测试账本开启加密、从新客户端下载并解锁,再验证导出与恢复。忘记加密密码且没有可用本地副本时,重置服务器访问密码不能解开账本。只有仍持有完整本地数据时,才按官方重置密钥与同步说明处理;先前未加密的导出和备份仍要单独保护。
账本导出之后要实际打开一次
打开测试账本,在设置的 Data 区域选择 Export data,下载到服务器之外的受保护位置。把它导入独立测试环境,核对账户、分类、日期、金额、备注和转账关系。导出文件可能包含可直接读取的预算资料,不能因为原账本启用过加密,就默认下载的文件也受同样保护。
恢复某份旧导出时,要确定哪个副本作为恢复依据。Reset Sync 会把选定客户端的当前文件作为新的同步基础,其他设备尚未同步的修改可能被丢弃;先保留各设备的可用导出,再按官方恢复流程操作,不在仍有未同步资料时随手点击重置。
很大的旧账本可能因为同步历史而导出较大。先留好原副本,再评估官方的重置同步或导出再导入方案;不要只为了缩小文件删掉自己仍需要的交易。本节验证一份账本的导出,不证明整台服务的访问设置也能恢复。
服务端副本采用一致时间点
先让实际使用的客户端完成同步并暂停编辑,再安排维护窗口停止服务,将整个 data、Compose 和可能使用的 .env 一起冷备。尚未上传的本地修改不在服务器副本中;服务启动也不证明账本已经同步。下面脚本在归档失败时尝试启动原服务,半成品保持 .partial 后缀。
set -eu
cd /srv/actual
umask 077
[ -e .env ] || : > .env
chmod 600 .env
mkdir -p /srv/actual-backups
snapshot=$(mktemp -d /srv/actual-backups/cold-XXXXXX)
cid=$(docker compose ps -q actual)
test -n "$cid"
trap 'docker compose start actual >/dev/null' EXIT
docker compose stop -t 60 actual
state=$(docker inspect --format '{{.State.Status}} {{.State.OOMKilled}} {{.State.ExitCode}}' "$cid")
case "$state" in
"exited false 0"|"exited false 143") ;;
*) printf '未确认正常停止,拒绝归档:%s\n' "$state" >&2; exit 1 ;;
esac
tar --numeric-owner -czpf "$snapshot/instance.tar.gz.partial" \
-C /srv/actual compose.yaml .env data
tar -tzf "$snapshot/instance.tar.gz.partial" >/dev/null
mv "$snapshot/instance.tar.gz.partial" "$snapshot/instance.tar.gz"
(cd "$snapshot" && sha256sum instance.tar.gz > SHA256SUMS)
docker compose start actual
trap - EXIT
printf '备份目录:%s\n' "$snapshot"
将完整归档与校验文件加密保存在另一台设备。服务器配置、会话和预算副本都属于私密资料,不把归档放到网站目录。校验值验证文件完整性,仍需实际恢复账本。
把 snapshot 换成实际备份目录,在有余量的测试主机创建新空目录。只解压自己创建的可信归档,不覆盖原 data:
set -eu
snapshot=/srv/actual-backups/cold-实际后缀
(cd "$snapshot" && sha256sum -c SHA256SUMS)
restore=$(mktemp -d /srv/actual-restore.XXXXXX)
tar --numeric-owner -xzpf "$snapshot/instance.tar.gz" -C "$restore"
cd "$restore"
在新目录保存 compose.restore.yaml。副本与原实例使用相同镜像、独立数据,不发布端口并禁用网络,避免误连真实客户端或触发已配置的外部集成。
services:
actual:
image: actualbudget/actual-server:26.10.0@sha256:24645e971da6bb1a1f953d6859e307a0b29be1e8b4130a35b3220c209b5b860c
network_mode: none
restart: "no"
environment:
ACTUAL_DATA_DIR: /data
ACTUAL_LOGIN_METHOD: password
ACTUAL_ALLOWED_LOGIN_METHODS: password
volumes:
- ./data:/data
mem_limit: 512m
保持在该目录启动副本,等日志显示服务就绪,再从容器内部检查首页:
project="actual-recovery-$(basename "$restore" | tr 'A-Z.' 'a-z-')"
docker compose -p "$project" -f compose.restore.yaml up -d
docker compose -p "$project" -f compose.restore.yaml logs --tail=80 actual
docker compose -p "$project" -f compose.restore.yaml exec -T actual node -e \
'fetch("http://127.0.0.1:5006/",{signal:AbortSignal.timeout(10000)}).then(r=>{if(!r.ok)process.exit(1);console.log(r.status)}).catch(()=>process.exit(1))'
无网络副本不能直接从电脑打开。完整恢复验收还需用隔离客户端或容器内的官方同步 API,检查原访问密码、预算文件、账户、交易与加密解锁;不能只比文件数量。要做浏览器验收时,另安排只允许维护者连接、没有外部集成出口的受控环境。缺少业务数据核对时,保持“恢复待验”。
验完在该目录执行 docker compose -p "$project" -f compose.restore.yaml stop,保留恢复材料。正式恢复前暂停原服务和真实客户端同步,明确采用哪个副本,再核对同步状态;不要让旧设备无意间接管恢复结果。
升级前同时保存账本导出、整服务冷备与原镜像标识。在副本检查新版本后,再改正式 Compose 的版本及对应摘要,拉取并重建。数据库或账本格式已经迁移时,回退需要升级前数据与旧镜像配套,不能只换回 tag。
推荐码:KuZhuJi




