作者： 如何使用 Docker Compose 自行託管 Actual Budget
本指南詳述在 VPS 上部署 Actual Budget 的完整步驟。包含 Docker Compose 設定、HTTPS 安全上下文要求、資料卷掛載方式以及預算檔案的備份策略，確保您的財務數據同步穩定且安全。
您將建置的內容
Actual Budget 是一款可自行託管的信封預算應用程式，也是許多人尋找可自行託管之 YNAB 替代方案時的首選。該伺服器由一個容器、一個資料儲存卷以及一個 HTTPS 名稱組成。由於伺服器主要負責檔案儲存與同步，因此一般預算需求皆可在最小型的 VPS 上順暢執行。
在輸入任何指令前，了解其架構相當重要。預算本身是一個 SQLite 資料庫，存在於您的瀏覽器與各個行動應用程式中。您即將安裝的伺服器是一個同步端點：它儲存了帳戶清單、預算檔案以及讓手機與筆記型電腦達成一致的變更日誌。這就是為什麼即使伺服器離線，應用程式仍可運作的原因；同時，只要還有一個客戶端保留副本，即使伺服器遺失，您的預算資料也不會遺失。
為什麼伺服器需要 HTTPS
Actual 要求使用 HTTPS，這並非僅是形式。瀏覽器僅在規格定義的「安全上下文」（secure context）中，才會公開 Web Crypto API，而這正是 Actual 用於端對端加密的介面。安全上下文即為 https:// 或 http://localhost。若從其他機器的瀏覽器透過 http://203.0.113.10:5006 載入應用程式，這些功能將無法使用，因為瀏覽器並未將其提供給該頁面。官方的行動裝置版本也會拒絕使用純 http:// 的伺服器網址。
因此，目前有兩種可行的設定方式。第一種是在容器前方配置真實網域名稱與真實憑證，這也是本指南採用的方式。第二種是透過 ACTUAL_HTTPS_KEY 與 ACTUAL_HTTPS_CERT 為伺服器提供自簽憑證（專案文件中已有說明），並接受每個裝置在連線時出現的瀏覽器警告。由於從 Let's Encrypt 取得免費憑證僅需 5 分鐘，建議採取第一種方案。
使用 Docker Compose 安裝 Actual Budget
若伺服器為全新環境，請先安裝 Docker。若您不熟悉 Compose 檔案語法，Docker Compose VPS 基礎指南 涵蓋了下方使用的欄位。
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該檔案中有三個細節至關重要。
映像檔為 actualbudget/actual-server:latest，由專案發布至 Docker Hub 並鏡像於 ghcr.io/actualbudget/actual。針對低功耗機器，另有 latest-alpine 標籤可供使用。
容器會將所有資料寫入 /data。在該目錄內，server-files 存放包含登入資訊與工作階段權杖的 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 代表容器未執行，此時 docker compose ps 將顯示容器已退出。常見原因為掛載磁碟區的權限問題，日誌中會顯示 EACCES 錯誤訊息。
設定憑證與真實網域名稱
將 A 記錄指向 VPS，即 budget.example.com，並等待其解析生效。接著安裝 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 密碼管理器。無需建立使用者帳號。Actual 伺服器設計為單一密碼制，因此共用預算即代表共用該密碼。
接著建立預算檔案。Actual 會詢問是否啟用端對端加密。請選擇是，伺服器將僅儲存密文，這對於租用機器上的財務資料而言是正確的做法。此舉有實質代價：加密密碼永遠不會傳送至伺服器，若遺失密碼，檔案將永久遺失且無法重設。在點擊該畫面繼續前，請務必記下密碼。
請根據銀行目前的數字設定初始餘額，而非匯入多年的歷史資料。信封預算法是從您現有的資金開始規劃，因此沒有歷史資料並不會造成影響。
匯入交易資料
此處誠實比熱情更重要，因為匯入流程是使用者放棄自架預算管理軟體的主要原因。
手動輸入是基礎且永遠有效的方法。對於信封預算制而言，這甚至是核心所在，因為親手輸入消費紀錄才能讓您對支出更有感。
檔案匯入可處理大量資料。Actual 支援 CSV、QIF、OFX 與 QFX 格式，而每家銀行至少都會提供其中一種。請從帳戶畫面針對個別帳戶進行匯入，並設定一次欄位對應，Actual 就會記住該帳戶的版面配置。
系統亦提供自動銀行同步功能，但需要第三方服務協助，因為伺服器無法自行與銀行連線。Actual 支援北美銀行的 SimpleFIN Bridge、歐洲的 Enable Banking、紐西蘭的 Akahu 以及巴西的 Pluggy.ai。GoCardless 目前仍受支援，但不接受新帳戶註冊。您需自行向服務提供商註冊、產生憑證，並將其新增至伺服器。截至 2026 年 7 月，SimpleFIN Bridge 的費用為每年 15 美元，最多可連結 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 會根據新映像檔重建容器，並重新掛載相同的儲存卷，因此資料會保留下來。請同時更新用戶端。伺服器與應用程式的版本應保持相近；若用戶端版本過舊，可能會因版本不符而拒絕同步。在進行重大版本升級前，請務必先進行備份，因為遷移程序會在首次啟動時執行，且無法進行降級。
故障情形與錯誤訊息
應用程式可載入，但同步作業無法完成。 請檢查 nginx 存取日誌中的 413。這代表 client_max_body_size 設定過低。若出現 502，則表示 nginx 運作正常，但容器未啟動。
加密選項遺失，或行動應用程式拒絕該 URL。 頁面未處於安全環境中。網址列會顯示 http://，且 IP 位址或主機名稱並非 localhost。請修正憑證，而非採取繞過方式。
出現預算檔案與此版本不相容的訊息。 用戶端與伺服器版本不一致。請將兩者更新至相同版本並重新載入。
容器陷入重啟迴圈。 請讀取 docker compose logs actual。若 /data 出現權限錯誤，表示容器使用者無法寫入掛載目錄。若出現位址已被使用（address-in-use）錯誤，表示其他程序已佔用 loopback 上的 5006 連接埠。
首次載入速度緩慢。 開啟時，整個預算檔案會下載至瀏覽器。這是一次性的大型傳輸，後續皆為本地讀取。這並非伺服器效能問題，增加 RAM 無法改善此狀況。
FAQ
Actual Budget 是否需要 HTTPS 才能運作？
實際上需要。Actual 的端對端加密使用瀏覽器的 Web Crypto 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 需要多少伺服器資源？
需求極低。容器僅負責提供靜態資源與檔案，預算計算皆在瀏覽器端完成。單核心 vCPU 與 1 GB RAM 即可順暢執行，且包含數年歷史的家庭預算資料目錄僅佔用數十 MB 的空間。磁碟壓力主要來自您的備份與其他容器，而非 Actual 本身。