Talpinkite Firefly III Managed VPS serveryje: jūsų finansai jūsų serveryje

Ką daro Firefly III

Firefly III yra asmeninių finansų valdymo programa, sukurta talpinti savo serveryje. Ji seka jūsų išlaidas ir pajamas, naudodama biudžetus, kategorijas ir žymas, kad matytumėte, kur dingsta jūsų pinigai. README ją apibūdina kaip visiškai talpinamą savo serveryje ir izoliuotą: ji nesikreipia į jokį išorinį serverį, kol aiškiai to nenurodote.

• Apskaita: dvejybinio įrašo apskaita, turto sąskaitos, įsipareigojimai ir bet kuri norima valiuta.
• Automatizavimas: pasikartojančios operacijos ir jūsų rašomos taisyklės, kurios surūšiuoja kiekvieną operaciją.
• Stebėjimas: biudžetai, taupyklės tikslui pasiekti, pajamų ir išlaidų ataskaitos, diagramos.
• Saugumas: dviejų veiksnių autentifikavimas kiekvienai paskyrai.
• Atvirumas: REST JSON API, apimanti beveik visą programą, ir webhook’ai.

Viename egzemplioriuje gali būti tiek naudotojų, kiek norite, kiekvienas su finansų administravimu, visiškai atskirtu nuo kitų. Dokumentacijoje aprašomas šiuo metu kuriamas modelis, leisiantis bendrai naudotis vienu administravimu.

Ką leidžia AGPL licencija

Firefly III platinama pagal GNU Affero General Public License, 3 versiją arba, jūsų pasirinkimu, bet kurią vėlesnę versiją: tai SPDX identifikatorius AGPL-3.0-or-later jos faile composer.json. Tekste patvirtinamas neribotas leidimas paleisti nepakeistą programą. Todėl projekto paskelbtą atvaizdą galite naudoti sau, savo šeimai ar įmonei, nieko nepirkdami dėl licencijos.

13 straipsnis prideda AGPL būdingą sąlygą: jei programą keičiate, jūsų versija visiems ja nuotoliniu būdu, per tinklą, besinaudojantiems turi suteikti galimybę nemokamai gauti jos šaltinio kodą. Duomenų importavimo įrankiui taikoma ta pati licencija.

Diegimas su Docker Compose

Dokumentacija Docker Compose vadina paprasčiausiu būdu įdiegti Firefly III. Serveryje, kuriame įdiegtas Docker, sukurkite katalogą ir atsisiųskite į jį tris oficialius failus neapdorotus: jų tarpai svarbūs, todėl dokumentacija prašo jų nekopijuoti iš naršyklės.

mkdir firefly-iii && cd firefly-iii
curl -o docker-compose.yml https://raw.githubusercontent.com/firefly-iii/docker/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/firefly-iii/firefly-iii/main/.env.example
curl -o .db.env https://raw.githubusercontent.com/firefly-iii/docker/main/database.env

• docker-compose.yml aprašo tris paslaugas: app, pačią programą, db, MariaDB duomenų bazę, ir cron, suplanuotą užduotį.
• .env saugo Firefly III nustatymus, įskaitant šifravimo raktą ir prieigą prie duomenų bazės.
• .db.env saugo duomenų bazės nustatymus. Palikite abu pavadinimus: Compose failas juos nurodo per env_file.

Nustatymai, kuriuos reikia pakeisti prieš pirmąjį paleidimą

Sugeneruokite dvi 32 simbolių eilutes komanda, nurodyta faile .env: vieną raktui, kitą duomenų bazės slaptažodžiui.

head /dev/urandom | LC_ALL=C tr -dc 'A-Za-z0-9' | head -c 32 && echo

SITE_OWNER=you@example.com
APP_KEY=
DB_PASSWORD=
APP_URL=https://finances.example.com

MYSQL_PASSWORD=

• APP_KEY šifruoja jūsų sesijas. Jis yra lygiai 32 simbolių ilgio, be specialiųjų simbolių, tokių kaip =, #, < ar >, o failas prašo jį laikyti labai saugiai.
• DB_PASSWORD faile .env ir MYSQL_PASSWORD faile .db.env turi tą pačią reikšmę.
• SITE_OWNER: jūsų adresas, rodomas kai kuriose klaidose administratoriais nesantiems naudotojams.
• APP_URL: viešas jūsų egzemplioriaus adresas. Faile paaiškinama, kad jis naudojamas tam tikroms užklausoms patvirtinti ir nuorodoms el. laiškuose sudaryti.
• TZ: jūsų laiko juosta, tz duomenų bazės formatu, kaip rodo failo pavyzdys.

Duomenų bazės slaptažodį pasirinkite prieš pirmąjį paleidimą. Duomenų bazė jį įrašo į savo tomą vos sukurta: pakeitus jį vėliau, jis nebesutampa, o Docker DUK siūlo tik vieną išeitį: pašalinti konteinerius bei tomus ir pradėti iš naujo.

Vietiniu adresu paskelbtas prievadas

Oficialus failas programą paskelbia 80 prievadu visais serverio adresais. Norėdami ją teikti per HTTPS už atvirkštinio tarpinio serverio toje pačioje mašinoje, paslaugoje app pakeiskite šią vienintelę eilutę:

ports:
  - 127.0.0.1:8080:8080

docker compose -f docker-compose.yml up -d --pull=always
docker compose -f docker-compose.yml logs -f

Pirmą kartą paleistas konteineris pats sukuria ir perkelia duomenų bazę. Kai diegimas baigtas, Firefly III žurnale padėkoja, kad ją įdiegėte: pereikite prie atvirkštinio tarpinio serverio.

• Žyma latest seka naujausią stabilią versiją. Žyma, pavyzdžiui, version-6.7.9, užfiksuoja versiją; senas žymas projektas pašalina maždaug po šešių mėnesių.
• Architektūros: atvaizdai kuriami linux/amd64 ir linux/arm64.
• Tomai: firefly_iii_upload laiko priedus, firefly_iii_db duomenų bazę.

Dokumentacija nenurodo atminties dydžio; jos Docker DUK siūlo PHP_MEMORY_LIMIT=512M ar daugiau, jei PHP pritrūksta atminties. Dydis priklauso nuo naudotojų skaičiaus, operacijų apimties ir duomenų importavimo įrankio. Naudojant Managed VPS, papasakokite mums, kaip ketinate naudotis, ir mes rekomenduosime tinkamą dydį.

HTTPS ir atvirkštinis tarpinis serveris

Firefly III konteinerio viduje teikia programą per HTTP 8080 prievadu, o HTTPS įjungiamas priešais esančiame atvirkštiniame tarpiniame serveryje. Programa skaito antraštę X-Forwarded-Proto, kad žinotų, jog lankytojas atvyko per HTTPS, jei tik pasitiki tarpiniu serveriu:

TRUSTED_PROXIES=*

Docker DUK šiuo klausimu aiškus: be TRUSTED_PROXIES=* nuorodos lieka su http, formos ir diagramos nustoja veikti, o CSP saugumo antraštės nesuveikia. Kai prievadas paskelbtas adresu 127.0.0.1, programą pasiekia tik paties serverio tarpinis serveris. Po kiekvieno failo .env pakeitimo sukurkite konteinerį iš naujo:

docker compose up -d --force-recreate app

Su Caddy

Caddy pati gauna Let’s Encrypt sertifikatą, o jos direktyva reverse_proxy numatytai nustato antraštes X-Forwarded-For, X-Forwarded-Proto ir X-Forwarded-Host:

finances.example.com {
  reverse_proxy 127.0.0.1:8080
}

Su Nginx ir Certbot

Šis blokas naudoja diegimo DUK nurodytas antraštes ir buferius, kuriuos DUK siūlo prieš 502 klaidas, kai programa grąžina žetoną ilgoje antraštėje. Jis klausosi 80 prievado, kad HTTPS įdiegtų Certbot:

server {
    listen 80;
    listen [::]:80;
    server_name finances.example.com;

    client_max_body_size 64M;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300s;
    }
}

Tada Certbot įdiegia sertifikatą ir pasirūpina jo atnaujinimu:

sudo certbot --nginx

• Atskiras domeno vardas: teikite Firefly III jos pačios vardu, pavyzdžiui, finances.example.com. DUK pažymi, kad Laravel neapdoroja IPv6 adreso, įrašyto tiesiai į URL.
• 431 klaidos: DUK jas sieja su per maža antraščių dydžio riba tarpiniame serveryje, dėl kurios nepavyksta kai kurie veiksmai, pavyzdžiui, prisijungimas.

Pirmoji paskyra ir registracijos

Pirmasis užsiregistravęs naudotojas tampa egzemplioriaus savininku. Saugumo sumetimais registracijos po to užsidaro savaime: dauguma žmonių Firefly III įdiegia tik sau.

1. Atverkite savo HTTPS adresą, vos tik tarpinis serveris atsako, ir susikurkite paskyrą: ji gauna savininko vaidmenį.
2. Savo profilyje įjunkite dviejų veiksnių autentifikavimą ir išsaugokite aštuonis rodomus atsarginius kodus.
3. Norėdami atverti egzempliorių kitiems žmonėms, eikite į /settings, atverkite Firefly III konfigūracijos parinktis, nuimkite žymę nuo registracijas išjungiančios parinkties ir išsaugokite.

• Dviejų veiksnių autentifikavimas remiasi laikrodžiu: DUK nurodo, kad dėl laiko skirtumo tarp telefono ir serverio jis nepavyksta.
• Prisijungimas per jūsų tapatybės teikėją: su AUTHENTICATION_GUARD=remote_user_guard Firefly III pasitiki priešais pastatytu autentifikavimo tarpiniu serveriu, pavyzdžiui, Authelia ar Authentik, kuris perduoda naudotoją antraštėje.
• Prieigos žetonai: OAuth klientai ir asmeniniai API žetonai kuriami profilyje.

Cron užduotis

Kelios funkcijos veikia tik su suplanuota užduotimi: automatiniai biudžetai, pasikartojančios operacijos, prenumeratų įspėjimai ir atnaujinti valiutų kursai. Docker atvaizdas pats cron nevykdo; tam oficialus failas prideda nedidelę paslaugą cron, kuri kreipiasi į programą kasdien 3 val. nakties.

Ji autentifikuojasi statiniu žetonu. Ta pačia komanda sugeneruokite trečią eilutę ir įdėkite ją į .env:

STATIC_CRON_TOKEN=

Šis žetonas yra lygiai 32 simbolių ilgio: 6.7.9 versijos kodas kito ilgio nepriima. Štai paslauga, kaip ją deklaruoja oficialus failas; dvigubas $$ yra tyčinis ir nurodo failo .env eilutes TZ ir STATIC_CRON_TOKEN:

cron:
  image: alpine
  restart: always
  container_name: firefly_iii_cron
  env_file: .env
  init: true
  command: ["sh", "-c", "apk add tzdata && \
    (ln -s /usr/share/zoneinfo/$$TZ /etc/localtime || true) && \
    echo \"0 3 * * * wget -qO- http://app:8080/api/v1/cron/$$STATIC_CRON_TOKEN;echo\" \
    | crontab - && \
    exec crond -f -L /dev/stdout"]
  networks:
    - firefly_iii
  depends_on:
    - app

Vienos užduoties pakanka visiems egzemplioriaus naudotojams. Kad patikrintumėte, ar ji įvykdyta, perskaitykite konteinerio žurnalą: kiekviena užduotis atsiskaito JSON formatu, su job_fired ir job_succeeded.

docker logs firefly_iii_cron

Norint ją paleisti rankiniu būdu, Docker DUK prašo naudoti naudotoją www-data, o ne root: DUK šią klaidą sieja su teisių klaidomis žurnalų failuose:

docker exec --user www-data firefly_iii_core /usr/local/bin/php /var/www/html/artisan firefly-iii:cron --force

MariaDB, PostgreSQL ar SQLite

Oficialiame faile pateikiama MariaDB su atvaizdu mariadb:lts. Firefly III taip pat palaiko PostgreSQL ir SQLite, pasirenkamas kintamuoju DB_CONNECTION faile .env:

DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432

PostgreSQL atveju dokumentacija taip pat nukreipia paslaugą db į atvaizdą postgres, kuris įdiegia PostgreSQL 18, ir prijungia jos tomą prie /var/lib/postgresql. Faile .db.env kintamieji MYSQL_* tampa POSTGRES_USER, POSTGRES_DB ir POSTGRES_PASSWORD.

Šį pasirinkimą padarykite prieš įvesdami pirmąsias operacijas. DUK nurodo, kad pereiti iš vienos duomenų bazės į kitą įmanoma, nors pati Firefly III to nepalaiko, ir kad programos eksportas perkelia ne visus duomenis.

Duomenų importavimo įrankis

Firefly III Data Importer yra atskiras įrankis, su savo diegimu ir savo atnaujinimais; jo 2.3.5 versija išleista 2026 m. rugsėjo 23 d. Jis importuoja CSV ir CAMT.053 failus, taip pat gali gauti operacijas iš jūsų bankų per trečiųjų šalių duomenų teikėjus, kurių kiekvienas turi savo sąlygas.

Oficiali Docker saugykla jį pateikia antrame faile, docker-compose-importer.yml, kuris išlaiko tas pačias paslaugas ir prideda importer. Jo nustatymai dedami į failą .importer.env, paimtą iš importavimo įrankio .env.example. Teikite jį atskiru domeno vardu, su vietiniu adresu paskelbtu prievadu ir antru tarpinio serverio bloku: DUK prašo jo nedėti į pakatalogį.

FIREFLY_III_URL=http://app:8080
VANITY_URL=https://finances.example.com
TRUSTED_PROXIES=*

• FIREFLY_III_URL: vidinis programos adresas, kurį importavimo įrankis pasiekia per Docker tinklą.
• VANITY_URL: viešas Firefly III adresas, kurį žino jūsų naudotojai.
• OAuth klientas: savo Firefly III profilyje sukurkite klientą, kurio grįžtamojo iškvietimo URL yra importavimo įrankio adresas su /callback gale, ir nuimkite žymę „Confidential“. Tada importavimo įrankis paprašo jo kliento ID.
• Keli naudotojai: palikite FIREFLY_III_ACCESS_TOKEN tuščią ir išlaikykite FIREFLY_III_URL; tada kiekvienas naudotojas prie importavimo įrankio prisijungia savo paskyra.

El. laiškai: SMTP konfigūracija

Numatytai MAIL_MAILER=log įrašo laiškus į žurnalus, užuot juos siuntęs. Kad gautumėte pranešimus, pavyzdžiui, prenumeratų įspėjimus, sukonfigūruokite siuntimą faile .env. Dokumentacija prašo visada pakeisti MAIL_FROM ir SITE_OWNER, kitaip joks el. laiškas nebus išsiųstas.

Simafri VPS serveryje siuntimas vyksta per autentifikuotą SMTP persiuntimo serverį 587 prievadu: tai gali būti jau turimos pašto paskyros adresas arba Simafri Suite.

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_FROM=finances@example.com
MAIL_USERNAME=finances@example.com
MAIL_PASSWORD=account_password
MAIL_ENCRYPTION=tls

• MAIL_ENCRYPTION priima null, ssl, starttls arba tls, priklausomai nuo jūsų teikėjo; 6.7.9 versijos kodas, kai reikšmė tuščia, naudoja tls.
• Bandymas: puslapis /settings/notifications išsiunčia bandomąjį el. laišką, kai konteineris sukurtas iš naujo.
• Kiti kanalai: pranešimai taip pat gali būti siunčiami į Slack, o į Discord ar Mattermost per jų webhook URL su /slack gale.

Atsarginės kopijos

Firefly III neturi integruotos atsarginių kopijų procedūros: dokumentacija rekomenduoja pačios sistemos įrankius ir pabrėžia, kad programos eksporto funkcija nėra atsarginė kopija. Su Docker štai ką reikia išsaugoti:

Duomenų bazė, paslaugai veikiant

Su MariaDB mariadb-dump eksportuoja duomenų bazę nestabdydamas paslaugos; jo parinktis --single-transaction pateikia nuoseklią InnoDB lentelių kopiją jų neužrakindama. Paleista iš Compose failo katalogo, komanda prieigos duomenis nuskaito iš konteinerio aplinkos:

docker exec firefly_iii_db sh -c 'mariadb-dump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > firefly-$(date +%F).sql

Su PostgreSQL tas pats principas taikomas per pg_dump:

docker exec firefly_iii_db sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > firefly-$(date +%F).sql

Suplanuokite šį eksportą serveryje bent kartą per dieną ir retkarčiais išvalykite kaupiamus failus.

Tomai, sustabdžius paslaugą

Dokumentacija kiekvieną tomą archyvuoja vienkartiniu konteineriu. Docker Compose prie tomų pavadinimų prideda projekto pavadinimo priešdėlį, numatytai tai katalogo pavadinimas: prieš archyvuodami patikrinkite tikslius pavadinimus.

docker volume ls
docker compose stop
docker run --rm -v "firefly-iii_firefly_iii_db:/tmp" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -czvf /backup/firefly_db.tar /tmp
docker run --rm -v "firefly-iii_firefly_iii_upload:/tmp" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -czvf /backup/firefly_upload.tar /tmp
docker compose start

Klaidingai parašytas tomo pavadinimas nesukelia klaidos: Docker tuo pavadinimu sukuria tuščią tomą ir jį archyvuoja, o tai perrašo ankstesnę atsarginę kopiją. Dokumentacija prašo prieš kiekvieną archyvavimą patikrinti, ar tomas egzistuoja.

Laikykite .env ir šių archyvų kopiją už serverio ribų, šifruotą, nes joje yra raktas ir duomenų bazės prieigos duomenys. Padėti serverio diske, šie failai patenka ir į jo naktines atsargines kopijas.

Atkūrimas

Dokumentacija tomą atkuria atvirkštine komanda, sustabdžius paslaugą; priedų tomas atkuriamas tokiu pačiu būdu:

docker run --rm -v "firefly-iii_firefly_iii_db:/recover" -v "$HOME/backups/firefly:/backup" \
    ubuntu tar -xvf /backup/firefly_db.tar -C /recover --strip 1

SQL eksportas įkeliamas atgal į veikiančią duomenų bazę:

docker exec -i firefly_iii_db sh -c 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < firefly-YYYY-MM-DD.sql

Taip pat atkurkite .env su jo APP_KEY, tada paleiskite iš naujo ir atverkite savo sąskaitas. Dokumentacija tai kartoja po kiekvieno metodo: pirmas dalykas, kurį reikia padaryti su atsargine kopija, yra ją atkurti ir taip įsitikinti, kad ji veikia.

Atnaujinimai ir perkėlimai

Firefly III atsinaujina pati, net nuo tokių senų versijų kaip 4.7, ir konteinerio paleidimo metu perkelia savo duomenų bazę. Dokumentacija įspėja, kad kai kurie atnaujinimai pašalina ar išvalo duomenis, ir prašo prieš kiekvieną iš jų sukurti duomenų bazės bei tomų atsarginę kopiją, ypač tarp pagrindinių versijų. Iš Compose failo katalogo:

docker compose stop
docker compose pull
docker compose -f docker-compose.yml up -d --remove-orphans

• Tempas: nuo 6.7.0, išleistos 2026 m. rugsėjo 14 d., iki 6.7.9, išleistos 2026 m. spalio 11 d., per keturias savaites pasirodė dešimt versijų. Sekite versijų pastabas: nuo 6.7.8 programos langas apibendrina pagrindinius įdiegtos versijos pakeitimus.
• 6.7.0 versija atnešė naują sąsają; jos taisyklių išraiškų variklis numatytai išjungtas ir vėl įjungiamas /settings.
• Compose failas: jei jį atsisiunčiate iš naujo, patikrinkite jame deklaruotą duomenų bazės versiją. Dokumentacija įspėja, kad nauja pagrindinė MariaDB versija gali neperimti senosios tomo.
• Nepavykęs perkėlimas: nuo 6.4.19 php artisan correction:rollback-single-migration pašalina paskutinį perkėlimo įrašą neliesdama duomenų, tada php artisan migrate jį paleidžia iš naujo, konteinerio viduje.
• Pasirašytos versijos: projektas pasirašo savo versijas, kurias galite patikrinti jo PGP raktu.

Importavimo įrankis atnaujinamas tokiu pačiu būdu, pagal jo dokumentaciją su docker compose rm -f tarp sustabdymo ir atvaizdų atsisiuntimo.

Kas ką daro Managed VPS serveryje

Talpinant savo serveryje, be programos reikia prižiūrėti ir patį serverį. Naudojant Managed VPS, mūsų komandos perima serverį ir proaktyviai stebi jūsų egzempliorių; Firefly III lieka jūsų programa su savo nustatymais ir jūsų finansiniais duomenimis.

Jei norite, kad mūsų komandos įsikištų į pačią programą, ši paslauga apmokestinama valandomis arba fiksuota kaina, o skaičiavimas pateikiamas prieš įsikišimą.