Cara Host Actual Budget Sendiri di VPS Menggunakan Docker
Ketahui cara memasang Actual Budget di VPS dengan Docker Compose. Panduan ini merangkumi konfigurasi volum data, keperluan HTTPS, import bank, dan strategi sandaran data.
Apa yang anda sedang bina
Actual Budget ialah aplikasi belanjawan berasaskan sampul (envelope budgeting) yang dihoskan sendiri, dan ia merupakan jawapan lazim apabila pengguna mencari alternatif kepada YNAB yang boleh dihoskan sendiri. Pelayan ini terdiri daripada satu kontena, satu volum data, dan satu nama HTTPS. Pelayan ini kebanyakannya menyimpan fail dan menyegerakkannya.
Seni bina ini perlu difahami sebelum anda menaip sebarang arahan. Belanjawan itu sendiri merupakan pangkalan data SQLite yang berada di dalam pelayar web anda dan di dalam setiap aplikasi mudah alih. Pelayan yang bakal anda pasang ialah titik akhir penyegerakan (sync endpoint): ia menyimpan senarai akaun, fail belanjawan, dan log perubahan yang membolehkan telefon serta komputer riba mencapai persetujuan data. Itulah sebabnya aplikasi ini masih berfungsi apabila pelayan tergendala, dan itulah sebabnya kehilangan pelayan tidak menyebabkan belanjawan anda hilang selagi satu klien masih menyimpan salinannya.
Mengapa pelayan memerlukan HTTPS
Actual memerlukan HTTPS, dan ini bukanlah sekadar formaliti. Actual memerlukan ciri pelayar yang dipanggil SharedArrayBuffer untuk berfungsi, dan pelayar hanya mendayakan ciri ini apabila halaman diasingkan secara rentas asal (cross-origin isolated) dalam apa yang dipanggil oleh spesifikasi sebagai konteks selamat (secure context). Konteks selamat ialah https:// atau http://localhost. Jika anda memuatkan aplikasi daripada http://203.0.113.10:5006 dalam pelayar pada mesin lain, pelayar tidak akan memberikan ciri tersebut kepada halaman itu, menyebabkan bajet tidak dimuatkan. Telefon juga tidak terkecuali. FAQ Actual menyatakan bahawa aplikasi iOS rasmi sedang dalam ujian beta dan bersambung ke pelayan anda sendiri, manakala aplikasi Android rasmi masih belum tersedia. Oleh itu, pada kebanyakan telefon, anda menggunakan aplikasi web yang sama, yang dipasang pada skrin utama sebagai Progressive Web App, dan peraturan konteks selamat yang sama tetap terpakai.
Oleh itu, terdapat dua persediaan yang boleh digunakan. Letakkan sijil sebenar pada nama domain sebenar di hadapan kontena, iaitu kaedah yang digunakan dalam panduan ini. Atau, berikan pelayan sijil yang ditandatangani sendiri (self-signed) dengan ACTUAL_HTTPS_KEY dan ACTUAL_HTTPS_CERT, seperti yang didokumentasikan oleh projek tersebut, dan terima amaran pelayar pada setiap peranti. Sijil percuma daripada Let's Encrypt hanya mengambil masa lima minit, jadi pilihlah pilihan pertama.
Memasang Actual Budget dengan Docker Compose
Pasang Docker terlebih dahulu jika pelayan masih baharu. Jika sintaks fail Compose masih baharu bagi anda, panduan asas Docker Compose untuk VPS merangkumi medan yang digunakan di bawah.
sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/dataTulis /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:/dataTiga perincian dalam fail tersebut adalah penting.
Imejnya ialah actualbudget/actual-server:latest, diterbitkan oleh projek tersebut ke Docker Hub dan dicerminkan di ghcr.io/actualbudget/actual. Terdapat tag latest-alpine untuk mesin berkuasa rendah.
Kontena menulis segala-galanya di bawah /data. Di dalamnya anda akan mendapat server-files, yang menyimpan account.sqlite dengan token log masuk dan sesi anda, serta user-files, yang menyimpan fail belanjawan itu sendiri. Lekapkan (mount) laluan tersebut supaya belanjawan anda kekal apabila kontena diganti. ACTUAL_DATA_DIR boleh mengubah lokasinya, tetapi tetapan lalai sudah memadai.
Port diterbitkan pada 127.0.0.1 sahaja. 5006:5006 kosong akan menerbitkan pada setiap antara muka, dan Docker menulis peraturannya sendiri mendahului ufw, jadi aplikasi akan terdedah kepada internet walaupun dengan firewall deny-all. Kejutan ini dijelaskan dalam mengapa port yang diterbitkan Docker memintas ufw. Mengikat pada loopback bermakna hanya reverse proxy pada mesin yang sama boleh mencapainya.
Mulakannya:
cd /opt/actual
docker compose up --detach
docker compose logs -f actualLog akan stabil sebaik sahaja pelayan melaporkan ia sedang mendengar pada port 5006. Semak secara setempat sebelum anda menyentuh DNS:
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/200 bermakna aplikasi sedang beroperasi. curl: (7) Failed to connect bermakna tiada apa-apa yang menerima sambungan pada 127.0.0.1:5006. Jalankan docker compose ps --all, kerana docker compose ps biasa hanya menyenaraikan kontena yang sedang berjalan. Jika kontena menunjukkan status exited, punca biasa ialah masalah kebenaran (permission) pada volum yang dilekapkan, yang boleh dilihat sebagai baris EACCES dalam log.
Letakkan sijil dan nama sebenar di hadapan
Halakan rekod A ke VPS, budget.example.com, dan tunggu sehingga ia selesai diselesaikan (resolve). Kemudian, pasang nginx dan keluarkan sijil tersebut. Panduan Certbot pada Ubuntu 24.04 dengan nginx merangkumi proses pengeluaran dan pemasa pembaharuan sepenuhnya.
Blok proksi:
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 ialah baris yang sering dilupakan oleh pengguna. Penyegerakan harian hanya menghantar perubahan anda, tetapi keseluruhan fail belanjawan akan dimuat naik apabila anda mendaftarkan belanjawan dengan pelayan buat kali pertama dan setiap kali anda menetapkan semula penyegerakan. Nginx menetapkan had lalai badan permintaan (request body) kepada 1 MB, jadi apabila fail melebihi saiz tersebut, muat naik penuh akan gagal dengan 413 Request Entity Too Large dalam log capaian nginx manakala aplikasi hanya memaparkan ralat penyegerakan umum. Pelayan mempunyai hadnya yang tersendiri: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB ditetapkan kepada 20 secara lalai dan ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB ditetapkan kepada 50 secara lalai, jadi tetapkan had nginx melebihi nilai yang berkenaan dengan anda.
Muat semula dan uji:
sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/Jalankan kali pertama: kata laluan dan fail belanjawan pertama anda
Buka https://budget.example.com dalam pelayar web. Skrin pertama meminta anda menetapkan kata laluan pelayan. Kata laluan tunggal itu melindungi keseluruhan pelayan, jadi jana kata laluan rawak yang panjang dan simpan di tempat yang anda boleh temui semula, seperti dalam pengurus kata laluan Vaultwarden yang dihoskan sendiri. Secara lalai, tiada akaun pengguna untuk dicipta: pelayan hanya mempunyai satu kata laluan, jadi berkongsi belanjawan bermakna berkongsi kata laluan tersebut. Log masuk berasingan hanya mungkin jika anda menyambungkan pembekal OpenID, yang disokong oleh Actual untuk persediaan berbilang pengguna.
Kemudian, cipta fail belanjawan. Buka Settings dan klik Enable encryption dalam bahagian Encryption. Aktifkan tetapan ini dan pelayan hanya akan menyimpan teks sifer (ciphertext) untuk data belanjawan anda, yang merupakan langkah tepat bagi data kewangan pada mesin sewaan. Kosnya nyata: kata laluan penyulitan tidak pernah sampai ke pelayan, jadi jika anda kehilangannya dan tiada salinan tempatan belanjawan tersebut, fail itu akan hilang. Jika salinan tempatan masih ada, anda boleh menetapkan semula kunci penyulitan dan menyegerakkan semula. Tulis kata laluan tersebut sebelum anda melangkau skrin itu.
Tetapkan baki permulaan anda berdasarkan angka semasa bank anda dan bukannya mengimport sejarah bertahun-tahun. Belanjawan sampul (envelope budgeting) berfungsi ke hadapan bermula daripada wang yang anda miliki sekarang, jadi sejarah yang kosong tidak menjejaskan fungsi belanjawan anda.
Memasukkan transaksi
Di sinilah kejujuran lebih penting daripada semangat, kerana proses import adalah sebab utama pengguna berhenti menggunakan perisian belanjawan yang dihoskan sendiri (self-hosted).
Kemasukan manual adalah asas dan ia sentiasa berfungsi. Bagi kaedah sampul surat, ini boleh dikatakan sebagai tujuan utamanya, kerana menaip setiap pembelian adalah perkara yang membuatkan anda menyedarinya.
Import fail mengendalikan transaksi pukal. Actual membaca format CSV, QIF, OFX, QFX dan CAMT. Lakukan import bagi setiap akaun daripada skrin akaun, dan petakan lajur apabila fail tersebut adalah CSV.
Penyelarasan bank automatik tersedia, dan ia memerlukan perkhidmatan pihak ketiga kerana pelayan tidak boleh berhubung dengan bank secara sendirian. Actual menyokong SimpleFIN Bridge untuk bank di Amerika Utara, Enable Banking untuk Eropah, Akahu untuk New Zealand, dan Pluggy.ai untuk Brazil. GoCardless masih disokong tetapi tidak lagi menerima akaun baharu. Anda perlu mendaftar sendiri dengan penyedia tersebut, menjana kelayakan (credentials), dan menambahkannya ke pelayan. SimpleFIN Bridge mengenakan bayaran 15 dolar AS setahun ditambah cukai untuk sehingga 25 institusi setakat Oktober 2026, manakala penyedia lain mempunyai harga yang berbeza.
Terdapat dua had yang perlu diterima sebelum anda bergantung pada ciri ini. Kelayakan API disimpan pada pelayan dan tidak dilindungi oleh penyulitan hujung-ke-hujung (end-to-end encryption), kerana pelayan perlu menggunakannya. Selain itu, tiada penyelarasan berlaku semasa Actual ditutup: penyelarasan automatik dimatikan secara lalai, dan sebaik sahaja anda menghidupkannya, ia hanya berjalan semasa aplikasi dibuka, jadi pelayan tidak akan membuat tinjauan (polling) ke bank anda secara sendirian.
Sandaran, kerana ia hanyalah fail
Segala data yang penting bagi anda terletak di bawah /opt/actual/data. Tiada langkah eksport dan tiada dump pangkalan data yang perlu diskripkan.
Satu perangkap yang perlu dielakkan ialah SQLite. Menyalin account.sqlite semasa pelayan sedang menulis kepadanya boleh menyebabkan transaksi yang tidak lengkap disalin, dan anda tidak akan menyedarinya sehingga anda cuba melakukan pemulihan. Hentikan container untuk beberapa saat sementara proses penyalinan berlangsung:
cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose startJadualkan proses ini menggunakan pendekatan dalam sandaran restic pada VPS, yang merangkumi penyediaan repositori, pengekalan dan latihan pemulihan. Lakukan latihan pemulihan tersebut. Sandaran yang tidak pernah dipulihkan hanyalah satu andaian.
Sandaran automatik Actual sendiri adalah perkara berasingan dan perlu diketahui, namun ia hanya wujud dalam aplikasi desktop. Ia menyimpan sehingga 10 salinan terkini fail belanjawan, yang boleh dicapai melalui File > Load Backup. Ini membantu sekiranya anda "tersilap memadam kategori" tanpa perlu menyentuh pelayan langsung. Aplikasi web dalam pelayar tidak menyimpan salinan sedemikian, jadi jika semua orang di rumah menggunakan pelayar, jadualkan sandaran pelayan seperti di atas. Anda juga boleh menyimpan sandaran belanjawan secara manual melalui Settings > Export data.
Mengemas kini pelayan
cd /opt/actual
docker compose pull
docker compose up --detachCompose mencipta semula container daripada imej baharu dan menyambungkan semula volume yang sama, jadi data tidak akan hilang. Kemas kini juga klien anda. Klien yang lebih lama daripada data yang diterima akan berhenti menggunakan perubahan dan memaparkan mesej Update Required. Lakukan sandaran (backup) sebelum mengemas kini, kerana belanjawan yang dibuka dalam versi lebih baharu mungkin tidak serasi dengan klien versi lama. Actual mengesyorkan tag latest yang berubah-ubah (floating), namun ia masih menggunakan pangkalan data SQLite, dan self-hosting Chatwoot menerangkan langkah-langkah penggunaan tag tetap (pinned) serta dump pra-naik taraf yang diperlukan oleh tabiat tersebut.
Apa yang rosak, dan apa yang akan anda lihat
Aplikasi dimuatkan tetapi penyelarasan tidak pernah selesai. Semak log akses nginx untuk 413. Ini bermakna client_max_body_size ditetapkan terlalu rendah. 502 pula bermakna nginx tidak menerima respons yang boleh digunakan daripada upstream. Kebanyakannya berlaku kerana kontena dihentikan atau tidak mendengar pada port 5006, jadi semak docker compose ps --all dan log kontena sebelum melakukan perkara lain.
Aplikasi tidak akan dimuatkan pada peranti lain, atau melaporkan bahawa SharedArrayBuffer tiada. Pastikan halaman tersebut menggunakan HTTPS dan menerima header cross-origin isolation daripada Actual. Jika bar alamat menunjukkan http:// dengan alamat IP atau nama hos yang bukan localhost, betulkan sijil tersebut daripada mencari jalan penyelesaian sementara.
Mesej menyatakan fail bajet tidak serasi dengan versi ini. Fail tersebut telah dibuka dalam versi Actual yang lebih baharu daripada klien yang anda gunakan sekarang. Kemas kini klien kepada sekurang-kurangnya versi tersebut, atau pulihkan sandaran yang diambil sebelum versi baharu mengubah fail itu, kemudian muat semula.
Kontena dimulakan semula secara berulang (loop). Baca docker compose logs actual. Ralat kebenaran (permission error) pada /data bermakna direktori yang dipasang (mounted) tidak boleh ditulis oleh pengguna kontena. Ralat alamat sedang digunakan (address-in-use) bermakna ada proses lain yang sudah menggunakan port 5006 pada loopback.
Muatan pertama terasa perlahan. Keseluruhan fail bajet dimuat turun ke pelayar apabila anda membukanya buat kali pertama pada sesuatu peranti. Itu merupakan satu pemindahan data yang besar, diikuti dengan bacaan setempat. Ini bukan masalah saiz pelayan, dan menambah RAM tidak akan mengubahnya.
FAQ
Adakah Actual Budget memerlukan HTTPS untuk berfungsi?
Ya, secara praktikalnya. Actual memerlukan ciri SharedArrayBuffer pelayar untuk berjalan, dan pelayar hanya mendayakan ciri tersebut dalam konteks selamat, iaitu https:// atau http://localhost. Melalui HTTP biasa daripada mesin lain, aplikasi tidak akan dimuatkan. Aplikasi iOS rasmi sedang dalam ujian beta dan belum ada aplikasi Android rasmi, jadi kebanyakan telefon menggunakan aplikasi web yang sama dan tertakluk kepada peraturan yang sama. (FAQ) Gunakan sijil Let's Encrypt pada hostname sebenar, atau sijil yang ditandatangani sendiri (self-signed) dengan ACTUAL_HTTPS_KEY dan ACTUAL_HTTPS_CERT jika anda boleh menerima amaran sijil pada setiap peranti.
Bolehkah Actual mengimport transaksi bank saya secara automatik?
Hanya melalui perkhidmatan pihak ketiga yang anda daftar sendiri: SimpleFIN Bridge di Amerika Utara, Enable Banking di Eropah, Akahu di New Zealand, atau Pluggy.ai di Brazil. GoCardless disokong tetapi tidak lagi menerima akaun baharu. Kredensial API tersebut disimpan pada pelayan anda dan tidak dilindungi oleh penyulitan hujung-ke-hujung (end-to-end encryption). Penyegerakan automatik dimatikan secara lalai dan, setelah didayakan, ia hanya berjalan semasa Actual dibuka, jadi tiada proses yang meninjau (polling) di latar belakang pelayan. Import CSV, QIF, OFX, QFX dan CAMT tidak memerlukan pihak ketiga sama sekali.
Apakah yang perlu saya sandarkan (backup) sebenarnya?
Direktori data yang dilekapkan (mounted), iaitu /opt/actual/data dalam panduan ini. Ia mengandungi server-files/account.sqlite dengan log masuk dan sesi, serta user-files dengan fail bajet. Hentikan kontena sebelum menyalin, kerana menyalin pangkalan data SQLite yang sedang aktif boleh menyebabkan penulisan separa (partial write). Tiada perkara lain pada pelayan yang menyimpan status (state).
Apakah yang berlaku jika saya kehilangan kata laluan penyulitan?
Jika anda masih mempunyai salinan bajet setempat, anda boleh menetapkan semula kunci penyulitan dan menyegerak semula. Jika anda kehilangan kedua-dua kata laluan dan setiap salinan setempat, fail yang disulitkan itu tidak dapat dipulihkan. Simpan kata laluan dalam pengurus kata laluan sebaik sahaja anda mencipta fail tersebut, dan simpan salinan di tempat yang tidak bergantung pada pelayan yang sama.
Berapakah spesifikasi pelayan yang diperlukan oleh Actual Budget?
Sangat sedikit. Kontena tersebut menghidangkan aset statik dan fail, manakala pengiraan bajet berlaku di dalam pelayar. Tekanan cakera datang daripada sandaran anda dan kontena lain, bukan daripada Actual. Jika anda sedang memilih spesifikasi pelayan yang perlu menjalankan aplikasi yang lebih berat di sampingnya, pelayan foto biasanya menjadi penentu tahap minimum, jadi semak berapa banyak RAM yang sebenarnya diperlukan oleh PhotoPrism dan Immich sebelum anda memilih pelan. Logik yang sama terpakai untuk timbunan media: transkod menentukan pelan, manakala bahagian hadapan pelayar seperti Halcyon, yang menukarkan pustaka Jellyfin menjadi kedai video 90-an yang boleh dilayari memerlukan sumber yang hampir sama sedikit dengan Actual.