如何在 VPS 自架 Actual Budget

建置內容

Actual Budget 是一套自架式信封預算管理應用程式。使用者尋找可自行託管的 YNAB 替代方案時，通常會選擇它。伺服器只需一個容器、一個資料磁碟區，以及一個 HTTPS 網域名稱。一般預算所需的功能，在最小型的 VPS 上也能順暢運作，因為伺服器主要負責儲存檔案與同步資料。

在開始輸入任何指令前，先了解其架構。預算本身是 SQLite 資料庫，存在於瀏覽器和每個行動應用程式中。接下來要安裝的伺服器是同步端點，負責保存帳戶清單、預算檔案，以及讓手機和筆記型電腦保持一致的變更記錄。因此，即使伺服器停止運作，應用程式仍可繼續使用。只要仍有一個用戶端保留副本，即使伺服器遺失，也不會遺失預算資料。

伺服器需要 HTTPS 的原因

Actual 確實需要 HTTPS，這不是形式上的要求。Actual 實際需要一項名為 SharedArrayBuffer 的瀏覽器功能才能運作，而瀏覽器只有在頁面處於規格所稱的安全內容環境中、完成跨來源隔離時，才會啟用這項功能。安全內容環境是 https:// 或 http://localhost。如果在另一台電腦的瀏覽器中從 http://203.0.113.10:5006 載入應用程式，瀏覽器就不會將這項功能提供給頁面，因此 budget 無法載入。手機不例外。Actual 的 FAQ 表示，官方 iOS 應用程式目前處於 beta 測試階段，可連線到你自己的伺服器；目前尚無官方 Android 應用程式。因此，在大多數手機上，你會使用相同的 Web 應用程式，將它安裝到主畫面作為 Progressive Web App，而相同的安全內容環境規則仍然適用。

因此，有 2 種可行的設定方式。將有效憑證放在容器前方的正式網域名稱上，這就是本指南採用的方式。或者，使用 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 標籤。

容器會將所有內容寫入 /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

伺服器回報正在監聽 5006 埠後，日誌通常就會穩定下來。在修改 DNS 前，先從本機檢查：

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/

200 表示應用程式正在提供服務。curl: (7) Failed to connect 表示 127.0.0.1:5006 上沒有任何服務接受連線。請執行 docker compose ps --all，因為單獨使用 docker compose ps 只會列出正在執行的容器。如果容器顯示為 exited，常見原因是掛載磁碟區的權限問題；日誌中會出現 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 存取日誌會記錄 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 密碼管理器。預設不需要建立使用者帳戶：伺服器只有一組密碼，因此共用預算就等於共用這組密碼。只有連接 OpenID provider 後，才能使用個別登入，Actual 支援這類多使用者設定。

接著建立預算檔案。Actual 會詢問是否啟用端對端加密。請選擇啟用，伺服器只會儲存密文；對存放在租用機器上的財務資料而言，這是正確的選擇。代價是確實存在的：加密密碼不會傳送到伺服器，因此遺失密碼後，檔案也會遺失，而且無法重設。請在離開該畫面前先將密碼記下來。

請依照銀行目前的餘額設定起始餘額，不要匯入多年的歷史資料。信封預算制會從你目前擁有的資金開始向前規劃，因此沒有歷史資料也不會造成損失。

匯入交易

這部分必須據實說明，因為匯入功能是許多人放棄自架預算管理的主要原因。

手動輸入是基本方式，而且一定可用。對信封預算法而言，這甚至可說是核心，因為輸入每筆消費能讓你注意到自己的支出。

檔案匯入可處理大部分交易。Actual 支援 CSV、QIF、OFX、QFX 和 CAMT，而每家銀行至少會匯出其中一種格式。請從帳戶畫面逐一匯入各帳戶的資料；如果檔案是 CSV，請對應欄位。

Actual 支援自動同步銀行資料，但需要第三方服務，因為伺服器無法自行與銀行通訊。Actual 支援北美銀行使用 SimpleFIN Bridge、歐洲使用 Enable Banking、紐西蘭使用 Akahu，以及巴西使用 Pluggy.ai。GoCardless 仍受支援，但目前不接受新帳戶。你必須自行向服務提供者註冊、產生憑證，再將憑證加入伺服器。截至 2026 年 10 月，SimpleFIN Bridge 每年收取 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 內建的自動備份是另一回事，也值得了解，但只有桌面應用程式提供這項功能。它會保留最多 10 份最近的預算檔案副本，可從 File > Load Backup 開啟。即使不接觸伺服器，也能處理「不小心刪除了分類」這類情況。瀏覽器中的網頁應用程式不會保留這些副本。因此，如果家中所有人都使用瀏覽器，上述伺服器備份就是你唯一擁有的備份。

更新伺服器

cd /opt/actual
docker compose pull
docker compose up --detach

Compose 會以新映像檔重新建立容器，並重新掛載相同的 volume，因此資料仍會保留。也請一併更新用戶端。用戶端版本若早於其接收的資料版本，便會停止套用變更，並顯示「需要更新」訊息。進行主要版本升級前，請先備份，因為資料遷移會在首次啟動時執行，而且無法降級。Actual 對浮動的 latest 標籤較為寬容，因為它的狀態是由檔案組成的目錄；但內含實際資料庫的應用程式則不然。自行架設 Chatwoot 說明了應使用固定標籤，以及這種情況所需的升級前傾印作業。

哪些地方會故障，以及你會看到的現象

應用程式可以載入，但同步永遠無法完成。 檢查 nginx access log 是否出現 413。這表示 client_max_body_size 設定過低。若出現 502，則表示 nginx 未從 upstream 取得可用的回應。最常見的原因是容器已停止，或未監聽 5006，因此應先檢查 docker compose ps --all 和容器 log。

應用程式無法在其他裝置上載入，或顯示缺少 SharedArrayBuffer。 此頁面不在安全環境中。網址列會顯示 http://，其中包含 IP 位址或不是 localhost 的主機名稱。請修正憑證，不要以繞過方式處理。

顯示預算檔案與此版本不相容的訊息。 這個檔案是以比目前使用中的 client 更新版本 Actual 開啟的。請將 client 更新至至少相同版本，或還原在較新版本處理該檔案之前建立的備份，然後重新載入。

容器不斷循環重新啟動。 讀取 docker compose logs actual。若 /data 發生權限錯誤，表示掛載的目錄無法由容器使用者寫入。若發生 address-in-use 錯誤，表示 loopback 上的 5006 已被其他程式占用。

第一次載入速度緩慢。 開啟預算檔案時，整個檔案都會下載至瀏覽器。這是一次大型傳輸，之後由本機讀取。這不是伺服器規模設定問題，增加 RAM 也不會改善速度。

FAQ

Actual Budget 需要 HTTPS 才能運作嗎？

實務上需要。Actual 必須使用瀏覽器的 SharedArrayBuffer 功能才能執行，而瀏覽器只會在安全環境中啟用該功能，也就是 https:// 或 http://localhost。若從其他機器透過純 HTTP 存取，應用程式將無法載入。官方 iOS app 正在進行 beta 測試，目前尚無官方 Android app，因此大多數手機會使用相同的 Web app，也會受到相同規則限制。（FAQ）請在正式網域名稱上使用 Let's Encrypt 憑證；如果能接受每台裝置都顯示憑證警告，也可以搭配 ACTUAL_HTTPS_KEY 和 ACTUAL_HTTPS_CERT 使用自簽憑證。

Actual 可以自動匯入我的銀行交易嗎？

只能透過自行註冊的第三方服務匯入：北美的 SimpleFIN Bridge、歐洲的 Enable Banking、紐西蘭的 Akahu，或巴西的 Pluggy.ai。GoCardless 受支援，但目前不接受新帳戶。這些 API 憑證會儲存在你的伺服器上，不受端對端加密保護。自動同步預設為關閉；啟用後，也只會在 Actual 開啟期間執行，因此伺服器不會在背景輪詢。CSV、QIF、OFX、QFX 和 CAMT 匯入完全不需要第三方服務。

我確切需要備份哪些內容？

需要備份掛載的資料目錄，本指南中的路徑是 /opt/actual/data。其中包含 server-files/account.sqlite，內有登入資訊與工作階段；也包含 user-files，內有預算檔案。複製前請先停止容器，因為複製正在使用中的 SQLite 資料庫可能會擷取到未完成的寫入內容。伺服器上的其他位置不會保存狀態資料。

如果遺失加密密碼，會發生什麼事？

檔案將無法復原。密碼不會傳送到伺服器，這正是端對端加密的目的，因此無法重設，也沒有支援管道。建立檔案後，請立即將密碼儲存在密碼管理器中，並在不依賴同一台伺服器的位置保留一份副本。

Actual Budget 需要多少伺服器資源？

非常少。容器只負責提供靜態資產與檔案，預算計算則在瀏覽器中執行。1 個共享 vCPU 搭配 1 GB RAM 即可穩定執行；一般家庭預算使用數年歷史資料時，資料目錄大小通常維持在數十 MB。磁碟壓力主要來自備份與其他容器，而不是 Actual。如果你要規劃一台還必須同時執行較耗資源服務的主機，通常會由相片伺服器決定最低規格，因此請先確認 PhotoPrism 和 Immich 實際需要多少 RAM，再選擇方案。同樣的原則也適用於媒體服務堆疊：方案規格取決於轉碼需求，而像 能將 Jellyfin 媒體庫轉成可瀏覽的 90 年代錄影帶店的 Halcyon 這類瀏覽器前端，資源需求大致和 Actual 一樣低。