Cara Hos Actual Budget pada VPS Sendiri dengan Docker

Perkara yang anda bina

Actual Budget ialah aplikasi belanjawan berasaskan sampul surat yang dihoskan sendiri. Aplikasi ini biasanya menjadi pilihan apabila pengguna mencari alternatif YNAB yang boleh dihoskan sendiri. Pelayan ini terdiri daripada satu bekas, satu volum data dan satu nama HTTPS. Semua fungsi belanjawan biasa berjalan dengan lancar pada VPS terkecil yang boleh disewa, kerana pelayan ini kebanyakannya menyimpan fail dan menyegerakkannya.

Anda perlu memahami seni bina ini sebelum menaip apa-apa. Belanjawan itu sendiri ialah pangkalan data SQLite yang berada dalam pelayar anda dan setiap aplikasi mudah alih. Pelayan yang akan anda pasang ialah titik akhir penyegerakan. Pelayan ini menyimpan senarai akaun, fail belanjawan dan log perubahan yang membolehkan telefon serta komputer riba mempunyai data yang sama. Oleh itu, aplikasi ini masih berfungsi apabila pelayan tidak tersedia. Kehilangan pelayan juga tidak menyebabkan belanjawan hilang selagi satu klien masih menyimpan salinannya.

Mengapa pelayan memerlukan HTTPS

Actual memerlukan HTTPS, dan ini bukan sekadar formaliti. Pelayar hanya mendedahkan Web Crypto API, iaitu antara muka yang digunakan Actual untuk penyulitan hujung ke hujung, dalam konteks selamat seperti yang ditakrifkan oleh spesifikasi. Konteks selamat ialah https:// atau http://localhost. Jika aplikasi dimuatkan daripada http://203.0.113.10:5006 dalam pelayar pada mesin lain, ciri tersebut tidak tersedia kerana pelayar tidak pernah menyerahkannya kepada halaman itu. Binaan mudah alih rasmi juga menolak URL pelayan http:// biasa.

Oleh itu, terdapat dua persediaan yang boleh digunakan. Letakkan sijil sebenar pada nama sebenar di hadapan kontena, seperti yang dilakukan dalam panduan ini. Atau berikan pelayan sijil ditandatangani sendiri menggunakan ACTUAL_HTTPS_KEY dan ACTUAL_HTTPS_CERT, seperti yang didokumenkan oleh projek, kemudian terima amaran pelayar pada setiap peranti. Sijil percuma daripada Let's Encrypt boleh diperoleh dalam masa lima minit, jadi gunakan pilihan pertama.

Pasang 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 menerangkan medan yang digunakan di bawah.

sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/data

Tulis /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

Tiga butiran dalam fail itu penting.

Imej tersebut ialah actualbudget/actual-server:latest, yang diterbitkan oleh projek ke Docker Hub dan dicerminkan di ghcr.io/actualbudget/actual. Terdapat tag latest-alpine untuk mesin berkuasa rendah.

Kontena menulis semua data di bawah /data. Di dalamnya terdapat server-files, yang menyimpan account.sqlite bersama maklumat log masuk dan token sesi anda, serta user-files, yang menyimpan fail belanjawan itu sendiri. Lekapkan laluan tersebut, jika tidak docker compose pull seterusnya akan membuang belanjawan anda. ACTUAL_DATA_DIR boleh memindahkannya, tetapi nilai lalai sudah memadai.

Port hanya diterbitkan pada 127.0.0.1. 5006:5006 tanpa alamat khusus akan menerbitkan port pada setiap antara muka, dan Docker menulis peraturannya sendiri sebelum ufw. Oleh itu, aplikasi akan terbuka kepada Internet walaupun tembok api menetapkan penolakan untuk semua sambungan. Keadaan ini diterangkan dalam sebab port yang diterbitkan Docker memintas ufw. Pengikatan kepada gelung balik bermakna hanya proksi songsang pada pelayan yang sama boleh mencapainya.

Mulakannya:

cd /opt/actual
docker compose up --detach
docker compose logs -f actual

Log menjadi stabil selepas pelayan melaporkan bahawa ia sedang mendengar pada port 5006. Semak secara setempat sebelum anda mengubah DNS:

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

200 bermaksud aplikasi sedang menyediakan perkhidmatan. curl: (7) Failed to connect bermaksud kontena tidak sedang berjalan, manakala docker compose ps akan menunjukkan bahawa kontena telah berhenti. Punca yang lazim ialah masalah keizinan pada volum yang dilekapkan, yang kelihatan sebagai baris EACCES dalam log.

Letakkan sijil dan nama sebenar di hadapan

Halakan rekod A ke VPS, budget.example.com, dan tunggu sehingga rekod itu diselesaikan. Kemudian pasang nginx dan keluarkan sijil. Panduan Certbot pada Ubuntu 24.04 dengan nginx menerangkan proses pengeluaran sijil 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. Fail belanjawan dimuat naik sepenuhnya apabila penyegerakan penuh dilakukan. Nginx menetapkan badan permintaan kepada 1 MB secara lalai. Oleh itu, apabila fail melebihi saiz tersebut, penyegerakan gagal dengan 413 Request Entity Too Large dalam log akses nginx, manakala aplikasi hanya memaparkan ralat penyegerakan umum. Pelayan mempunyai had berasingan: 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. Oleh itu, tetapkan had nginx melebihi nilai yang berkenaan dengan konfigurasi 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/

Persediaan pertama: kata laluan dan fail belanjawan pertama anda

Buka https://budget.example.com dalam pelayar. Skrin pertama meminta anda menetapkan kata laluan pelayan. Kata laluan tunggal itu melindungi seluruh pelayan, jadi jana kata laluan rawak yang panjang dan simpan di tempat yang boleh anda temui semula, seperti pengurus kata laluan Vaultwarden yang dihoskan sendiri. Anda tidak perlu mencipta akaun pengguna. Pelayan Actual direka bentuk dengan satu kata laluan, jadi berkongsi belanjawan bermakna berkongsi kata laluan itu.

Kemudian cipta fail belanjawan. Actual bertanya sama ada penyulitan hujung ke hujung hendak diaktifkan. Pilih ya. Dengan itu, pelayan hanya menyimpan teks sifer, iaitu pilihan yang tepat untuk data kewangan pada mesin sewaan. Terdapat kos sebenar: kata laluan penyulitan tidak pernah sampai ke pelayan. Jika anda kehilangannya, fail itu hilang dan tiada tetapan semula tersedia. Catat kata laluan itu sebelum anda meneruskan dari skrin tersebut.

Tetapkan baki permulaan berdasarkan angka semasa daripada bank anda, bukan dengan mengimport sejarah bertahun-tahun. Penganggaran belanjawan berasaskan sampul berfungsi ke hadapan daripada wang yang anda miliki sekarang, jadi sejarah yang kosong tidak merugikan anda.

Mengimport transaksi

Dalam bahagian ini, kejujuran lebih penting daripada semangat, kerana sokongan import ialah sebab utama orang berhenti menggunakan pengurusan belanjawan yang dihos sendiri.

Kemasukan manual ialah asas dan sentiasa berfungsi. Untuk kaedah sampul surat, kaedah ini boleh dikatakan sebagai tujuannya, kerana menaip pembelian membuatkan anda menyedarinya.

Import fail mengendalikan sebahagian besar transaksi. Actual boleh membaca CSV, QIF, OFX dan QFX, dan setiap bank mengeksport sekurang-kurangnya satu daripada format tersebut. Import setiap akaun daripada skrin akaun, petakan lajur sekali, dan Actual akan mengingati susun atur tersebut untuk akaun itu.

Penyegerakan bank automatik tersedia, tetapi memerlukan perkhidmatan pihak ketiga kerana pelayan tidak boleh berhubung dengan bank dengan sendiri. 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 menerima akaun baharu. Anda perlu mendaftar dengan penyedia tersebut sendiri, menjana kelayakan, kemudian menambahkannya pada pelayan. SimpleFIN Bridge mengenakan bayaran 15 dolar Amerika Syarikat setahun untuk sehingga 25 institusi setakat Julai 2026, manakala penyedia lain menetapkan harga yang berbeza.

Terima dua batasan ini sebelum anda bergantung pada ciri tersebut. Kelayakan API disimpan pada pelayan dan tidak dilindungi oleh penyulitan hujung ke hujung, kerana pelayan perlu menggunakannya. Actual juga tidak melakukan pengundian berkala: penyegerakan dimulakan dengan menekan butang, bukan melalui tugas latar belakang.

Sandaran, kerana fail sahaja

Semua perkara penting disimpan di bawah /opt/actual/data. Tiada langkah eksport dan tiada longgokan pangkalan data untuk diskripkan.

Perangkapnya ialah SQLite. Menyalin account.sqlite semasa pelayan sedang menulis padanya boleh menangkap transaksi yang belum selesai. Anda hanya akan mengetahuinya apabila cuba memulihkan sandaran. Hentikan kontena selama beberapa saat yang diperlukan untuk penyalinan:

cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose start

Jadualkan proses itu menggunakan pendekatan dalam sandaran restic pada VPS, yang merangkumi persediaan repositori, pengekalan dan latihan pemulihan. Jalankan latihan pemulihan. Sandaran yang belum pernah dipulihkan hanyalah anggaran.

Sandaran sisi klien Actual sendiri ialah perkara yang berasingan dan wajar diketahui. Pelayar menyimpan salinan terkini fail belanjawan, yang boleh dicapai daripada menu fail. Ini membolehkan anda memulihkan keadaan apabila anda terpadam kategori secara tidak sengaja, tanpa menyentuh pelayan langsung.

Mengemas kini pelayan

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

Compose mencipta semula kontena daripada imej baharu dan memasang semula volum yang sama, jadi data kekal. Kemas kini klien juga. Versi pelayan dan aplikasi perlu kekal hampir sama. Klien yang jauh lebih lama daripada pelayan mungkin enggan menyegerak dan memaparkan mesej ketidakpadanan versi. Buat sandaran sebelum peningkatan versi utama kerana migrasi dijalankan pada permulaan pertama dan tiada laluan untuk menurunkan versi.

Perkara yang rosak dan perkara yang akan anda lihat

Aplikasi dimuatkan tetapi penyegerakan tidak pernah selesai. Semak log akses nginx untuk 413. Itu bermaksud client_max_body_size ditetapkan terlalu rendah. 502 pula bermaksud nginx sedang berjalan tetapi container tidak.

Pilihan penyulitan tiada, atau aplikasi mudah alih menolak URL tersebut. Halaman itu bukan dalam konteks selamat. Bar alamat akan memaparkan http:// dengan alamat IP atau nama hos yang bukan localhost. Betulkan sijil itu dan jangan gunakan penyelesaian sementara.

Mesej menyatakan fail bajet tidak serasi dengan versi ini. Versi klien dan pelayan sudah berbeza. Kemas kini kedua-duanya kepada release yang sama, kemudian muat semula.

Container dimulakan semula secara berulang. Baca docker compose logs actual. Ralat kebenaran pada /data bermaksud direktori yang dipasang tidak boleh ditulis oleh pengguna container. Ralat alamat sedang digunakan bermaksud sesuatu yang lain sudah menggunakan 5006 pada loopback.

Pemuatan pertama terasa perlahan. Keseluruhan fail bajet dimuat turun ke pelayar apabila anda membukanya. Pemindahan besar itu berlaku sekali, kemudian bacaan dibuat secara setempat. Ini bukan masalah saiz pelayan, dan menambah RAM tidak akan mengubahnya.

FAQ

Adakah Actual Budget memerlukan HTTPS untuk berfungsi?

Ya, dalam amalan. Penyulitan hujung ke hujung Actual menggunakan Web Crypto API pelayar, dan pelayar hanya menyediakan API itu dalam konteks selamat, iaitu https:// atau http://localhost. Melalui HTTP biasa dari mesin lain, ciri tersebut tidak tersedia, dan aplikasi mudah alih rasmi menolak URL pelayan HTTP biasa. Gunakan sijil Let's Encrypt pada nama hos sebenar, atau sijil ditandatangani sendiri dengan ACTUAL_HTTPS_KEY dan ACTUAL_HTTPS_CERT jika anda hanya menggunakan pelayar desktop.

Bolehkah Actual mengimport transaksi bank saya secara automatik?

Hanya melalui perkhidmatan pihak ketiga yang anda daftarkan sendiri: SimpleFIN Bridge di Amerika Utara, Enable Banking di Eropah, Akahu di New Zealand, atau Pluggy.ai di Brazil. GoCardless disokong tetapi tidak menerima akaun baharu. Bukti kelayakan API tersebut disimpan pada pelayan anda dan tidak dilindungi oleh penyulitan hujung ke hujung. Penyegerakan juga dilakukan secara manual, jadi anda perlu menekan butang dan tiada proses yang membuat tinjauan di latar belakang. Import CSV, QIF, OFX dan QFX langsung tidak memerlukan pihak ketiga.

Apakah yang sebenarnya perlu saya sandarkan?

Direktori data yang dipasang, iaitu /opt/actual/data dalam panduan ini. Direktori itu mengandungi server-files/account.sqlite dengan maklumat log masuk dan sesi, serta user-files dengan fail belanjawan. Hentikan kontena sebelum menyalin, kerana menyalin pangkalan data SQLite yang sedang aktif boleh menangkap penulisan separa. Tiada apa-apa lagi pada pelayan menyimpan keadaan.

Apakah yang berlaku jika saya kehilangan kata laluan penyulitan?

Fail itu tidak dapat dipulihkan. Kata laluan tidak pernah sampai ke pelayan, dan itulah tujuan utama penyulitan hujung ke hujung. Oleh itu, tiada fungsi tetapan semula dan tiada saluran sokongan untuk pemulihan. Simpan kata laluan itu dalam pengurus kata laluan sebaik sahaja anda mencipta fail, dan simpan satu salinan di lokasi yang tidak bergantung pada pelayan yang sama.

Berapakah sumber pelayan yang diperlukan oleh Actual Budget?

Sangat sedikit. Kontena ini menyediakan aset dan fail statik, manakala pengiraan belanjawan berlaku dalam pelayar. Satu vCPU dikongsi dengan 1 GB RAM boleh menjalankannya tanpa masalah, dan direktori data untuk belanjawan isi rumah dengan sejarah selama beberapa tahun kekal dalam lingkungan puluhan megabait. Penggunaan ruang cakera berpunca daripada sandaran anda dan kontena lain, bukan daripada Actual.