作者： 如何在 VPS 自架 Actual Budget
使用 Docker Compose 在 VPS 部署 Actual Budget，了解資料磁碟區、瀏覽器需要 HTTPS 的原因，並完成第一個預算檔、銀行匯入與備份。
建置內容
Actual Budget 是一套自架式信封預算管理應用程式。使用者尋找可自行託管的 YNAB 替代方案時，通常會選擇它。伺服器只需一個容器、一個資料磁碟區，以及一個 HTTPS 網域名稱。一般預算所需的功能，在最小型的 VPS 上也能順暢運作，因為伺服器主要負責儲存檔案與同步資料。
在開始輸入任何指令前，先了解其架構。預算本身是 SQLite 資料庫，存在於瀏覽器和每個行動應用程式中。接下來要安裝的伺服器是同步端點，負責保存帳戶清單、預算檔案，以及讓手機和筆記型電腦保持一致的變更記錄。因此，即使伺服器停止運作，應用程式仍可繼續使用。只要仍有一個用戶端保留副本，即使伺服器遺失，也不會遺失預算資料。
伺服器需要 HTTPS 的原因
Actual 要求使用 HTTPS，這不是形式上的要求。瀏覽器只會在規格所稱的安全內容環境中，提供 Actual 用於端對端加密的 Web Crypto API。安全內容環境是 https:// 或 http://localhost。如果在另一台電腦的瀏覽器中從 http://203.0.113.10:5006 載入應用程式，這些功能就不會存在，因為瀏覽器根本不會將它們提供給該頁面。官方行動版也會拒絕使用純 http:// 的伺服器 URL。
因此，有兩種可行的設定方式。將有效憑證配置在容器前方的正式網域名稱上，這是本指南採用的方式。或者使用 ACTUAL_HTTPS_KEY 和 ACTUAL_HTTPS_CERT，為伺服器提供自簽憑證；專案文件有說明此方式，但每台裝置都會顯示瀏覽器警告。Let's Encrypt 的免費憑證只需 5 分鐘即可取得，因此請採用第一種方式。
使用 Docker Compose 安裝 Actual Budget
如果這台主機是全新環境，請先安裝 Docker。如果你不熟悉 Compose 檔案語法，請參閱 VPS 的 Docker Compose 基礎，其中說明了下方使用的欄位。
sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/data建立 /opt/actual/docker-compose.yml：
services:
actual:
image: actualbudget/actual-server:latest
container_name: actual
restart: unless-stopped
ports:
- '127.0.0.1:5006:5006'
volumes:
- ./data:/data該檔案有 3 個重要細節。
映像檔是 actualbudget/actual-server:latest，由專案發布至 Docker Hub，並在 ghcr.io/actualbudget/actual 提供映像檔。低功耗機器可使用 latest-alpine tag。
容器會將所有內容寫入 /data。其中的 server-files 會保存包含登入資訊與工作階段 token 的 account.sqlite，而 user-files 則保存預算檔案本身。請掛載該路徑，否則下一次 docker compose pull 時，預算資料會遺失。ACTUAL_DATA_DIR 可用來變更此路徑，但使用預設值即可。
連接埠只會發布至 127.0.0.1。直接使用 5006:5006 會在所有介面上發布連接埠；而 Docker 會在 ufw 之前建立自己的規則，因此即使防火牆設定為拒絕所有連線，應用程式仍會暴露在網際網路上。Docker 發布的連接埠為何會繞過 ufw 說明了這項特性。繫結至 loopback 後，只有同一台主機上的反向代理可以連線。
啟動服務：
cd /opt/actual
docker compose up --detach
docker compose logs -f actual伺服器回報正在監聽 port 5006 後，日誌通常就會穩定下來。在修改 DNS 前，先從本機檢查：
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/200 表示應用程式正在提供服務。curl: (7) Failed to connect 表示容器未執行，而 docker compose ps 會顯示容器已結束。最常見的原因是掛載 volume 的權限問題，日誌中會顯示 EACCES 行。
在前端配置憑證與正式名稱
將 A 記錄指向 VPS，budget.example.com，然後等待 DNS 解析完成。接著安裝 nginx 並申請憑證。Ubuntu 24.04 搭配 nginx 的 Certbot 指南完整說明憑證申請流程與續期計時器。
代理區塊：
server {
listen 443 ssl;
http2 on;
server_name budget.example.com;
ssl_certificate /etc/letsencrypt/live/budget.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/budget.example.com/privkey.pem;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:5006;
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;
}
}client_max_body_size 是最容易被遺漏的設定。完整同步時，預算檔案會一次上傳整個檔案。Nginx 預設要求本文大小上限為 1 MB，因此檔案超過此大小後，同步會失敗。nginx access log 會記錄 413 Request Entity Too Large，而應用程式只會顯示一般性的同步錯誤。伺服器本身另有獨立限制：ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB 預設為 20，ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB 預設為 50。因此，請將 nginx 限制設為高於適用的那一項限制。
重新載入並測試：
sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/第一次執行：密碼與第一個預算檔案
在瀏覽器中開啟 https://budget.example.com。第一個畫面會要求你設定伺服器密碼。這組密碼會保護整台伺服器，因此請產生一組長且隨機的密碼，並存放在你之後找得到的位置，例如自架的 Vaultwarden 密碼管理器。你不需要建立使用者帳號。Actual 的伺服器設計上只使用單一密碼，因此分享預算就等於分享該密碼。
接著建立預算檔案。Actual 會詢問是否啟用端對端加密。請選擇啟用，讓伺服器只儲存密文。對於存放在租用機器上的財務資料，這是正確的選擇。代價也很明確：加密密碼不會傳送到伺服器，因此遺失密碼就等於遺失檔案，而且無法重設。請在略過這個畫面前先把密碼記下來。
請根據銀行目前的數字設定起始餘額，不要匯入數年的歷史資料。信封預算制會從你目前擁有的資金開始運作，因此沒有歷史資料並不會造成損失。
匯入交易
這部分需要誠實面對限制，不能只強調優點。匯入體驗是許多人放棄自架預算工具的主要原因。
手動輸入是基本方式，而且永遠可用。對信封預算法來說，這甚至可說是核心，因為輸入一筆消費會讓你注意到這筆支出。
檔案匯入可處理大部分交易。Actual 支援 CSV、QIF、OFX 和 QFX，而每家銀行至少會提供其中一種格式。從帳戶畫面匯入各帳戶的資料，首次設定時對應欄位；Actual 之後會記住該帳戶的欄位配置。
Actual 也支援自動銀行同步，但需要第三方服務，因為伺服器無法自行連線銀行。Actual 支援北美銀行使用 SimpleFIN Bridge、歐洲使用 Enable Banking、紐西蘭使用 Akahu，以及巴西使用 Pluggy.ai。GoCardless 仍受支援，但目前不接受新帳戶。你必須自行向服務提供者註冊、建立憑證，再將憑證加入伺服器。SimpleFIN Bridge 截至 July 2026 的費用為每年 15 US dollars，最多支援 25 家金融機構；其他服務的定價不同。
在依賴這項功能前，先接受兩項限制。API 憑證會存放在伺服器上，不受端對端加密保護，因為伺服器必須使用這些憑證。Actual 也不會定期輪詢：同步必須按下按鈕執行，不是背景工作。
備份，因為只有檔案
所有重要資料都位於 /opt/actual/data 下。不需要匯出，也不需要撰寫資料庫傾印腳本。
唯一需要注意的是 SQLite。在伺服器寫入 account.sqlite 時複製該檔案，可能會擷取尚未完成的交易。直到嘗試還原時，才會發現備份無法使用。請在複製所需的幾秒鐘內停止容器：
cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose start依照 VPS 上的 restic 備份 所述的方法排程備份。該方法涵蓋儲存庫設定、保留原則與還原演練。請執行還原演練。從未還原過的備份，只能算是猜測。
Actual 本身的用戶端備份是另一回事，也值得了解。瀏覽器會保留預算檔案的近期副本，可從檔案選單存取。即使誤刪分類，也能直接使用這些副本，不必接觸伺服器。
更新伺服器
cd /opt/actual
docker compose pull
docker compose up --detachCompose 會使用新映像重新建立容器，並重新掛載相同的 volume，因此資料仍會保留。用戶端也要一併更新。伺服器與應用程式版本應維持接近；若用戶端版本遠舊於伺服器，可能會因版本不相容而拒絕同步。進行主要版本升級前，請先備份，因為服務會在首次啟動時執行遷移，且沒有降級途徑。Actual 對浮動的 latest 標籤較為寬容，因為其狀態是由檔案組成的目錄；但使用實際資料庫的應用程式則不然，而 自行託管 Chatwoot 會說明這類情境所需的固定標籤與升級前傾印流程。
發生問題時的現象與處理方式
應用程式可以載入，但同步作業一直無法完成。 檢查 nginx access log 中的 413。這表示 client_max_body_size 設定過低。若顯示 502，則表示 nginx 已啟動，但容器尚未啟動。
找不到加密選項，或行動應用程式拒絕此 URL。 該頁面不在安全內容環境中。網址列會顯示 http://，且使用 IP 位址或不是 localhost 的主機名稱。請修正憑證，不要採用繞過方式。
顯示預算檔案與此版本不相容的訊息。 用戶端與伺服器版本已經不一致。請將兩者更新至相同版本，然後重新載入。
容器不斷重新啟動。 讀取 docker compose logs actual。/data 發生權限錯誤，表示掛載的目錄無法由容器使用者寫入。若顯示位址已使用錯誤，表示 loopback 上的 5006 已被其他程序佔用。
首次載入速度緩慢。 開啟預算檔案時，整個檔案都會下載至瀏覽器。這是一次大型傳輸，之後由本機讀取。這不是伺服器規模設定問題，增加 RAM 也不會改善。
FAQ
Actual Budget 需要 HTTPS 才能運作嗎？
實務上需要。Actual 的端對端加密使用瀏覽器的 Web Crypto API，而瀏覽器只會在安全環境中提供這項 API，也就是 https:// 或 http://localhost。從其他機器透過未加密的 HTTP 存取時，這些功能無法使用，官方行動應用程式也會拒絕未加密 HTTP 的伺服器 URL。請在正式主機名稱上使用 Let's Encrypt 憑證；如果只會使用桌面瀏覽器，也可以搭配 ACTUAL_HTTPS_KEY 與 ACTUAL_HTTPS_CERT 使用自簽憑證。
Actual 可以自動匯入我的銀行交易嗎？
只能透過由你自行註冊的第三方服務：北美的 SimpleFIN Bridge、歐洲的 Enable Banking、紐西蘭的 Akahu，或巴西的 Pluggy.ai。GoCardless 也受支援，但目前不再接受新帳戶。這些 API 憑證會儲存在你的伺服器上，不受端對端加密保護。同步也必須手動執行，因此你需要按下按鈕，系統不會在背景中輪詢。CSV、QIF、OFX 與 QFX 匯入完全不需要第三方服務。
我確切需要備份哪些內容？
備份掛載的資料目錄，本指南中是 /opt/actual/data。其中包含存放登入資訊與工作階段的 server-files/account.sqlite，以及存放預算檔案的 user-files。複製前請先停止容器，因為複製正在使用中的 SQLite 資料庫可能只會取得部分寫入內容。伺服器上的其他位置不會保存狀態資料。
如果遺失加密密碼，會發生什麼事？
檔案將無法復原。密碼不會傳送到伺服器，這正是端對端加密的目的，因此沒有重設方式，也沒有可用的支援管道。建立檔案時，請立即將密碼儲存在密碼管理器中，並在不依賴同一台伺服器的位置保留一份副本。
Actual Budget 需要多少伺服器資源？
需求非常低。容器負責提供靜態資產與檔案，預算計算則在瀏覽器中執行。1 個共用 vCPU 搭配 1 GB RAM 即可穩定執行；家庭預算若包含數年的歷史資料，資料目錄通常也只有數十 MB。磁碟壓力主要來自備份與其他容器，而不是 Actual。如果你要規劃一台還必須同時執行較耗資源服務的主機，通常會由相片伺服器決定最低規格，因此請先查看 PhotoPrism 和 Immich 實際需要多少 RAM，再選擇方案。