Preskočiť na hlavný obsah

Vlastné hostovanie Beancount.io na bex jedným kliknutím

Nasaďte Beancount.io do svojho bex priestoru jediným kliknutím, potom pripojte bea, MCP klientov, Git a mobilnú aplikáciu, pridajte účty a zálohujte.

Jediné kliknutie nasadí celý balík Beancount.io vrátane webového dashboardu, API a MCP servera, služby pre knihy a vašich kníh uložených v Git, do bex priestoru, ktorý vlastníte. Tento návod vás prevedie od stlačenia tlačidla až k funkčnej knihe. Ďalej sa venuje pripojeniu vašich nástrojov, pridávaniu účtov, aktualizácii, zálohovaniu a odstráneniu balíka.

Balík má licenciu MIT, neuplatňuje žiadne limity plánov a stojí približne $33 mesačne za hosting, účtovaných vášmu priestoru. Oznámenie si prečítate v článku Spustite si vlastné Beancount.io jedným kliknutím.

Nasaďte balík​

Deploy to bex.co

  1. Spustite ho. Stlačte Deploy to bex.co, vyberte priestor, ktorý má balík vlastniť, skontrolujte plán a potvrďte. Nič sa nevytvorí, kým neschválite náhľad, a netreba nič vypĺňať: každé tajomstvo sa vygeneruje vo vašom priestore.
  2. Počkajte na prvé zostavenie. V našich beh m to trvalo 27–30 minút a dlhšie, keď je fronta zostavení v bex zaneprázdnená. Služba, ktorej nasadenie je označené ako zlyhané, sa neopakuje; nasaďte ju znova z bex dashboardu.
  3. Získajte svoju inštanciu. Otvorte URL služby beancount-dashboard a hneď sa zaregistrujte. Neexistuje krok overovania e-mailom a registrácia sa po prvom účte uzavrie.
  4. Vytvorte knihu. Začnite zo štartovacej šablóny alebo načítajte vzorovú knihu, aby ste sa rozhliadli.
varovanie

Kým neexistuje prvý účet, ktokoľvek, kto nájde adresu dashboardu, ho môže vytvoriť. Ak sa niekto zaregistruje pred vami, odstráňte ten účet pomocou admin tokenu balíka, aby sa registrácia znova otvorila.

Registrácia na novom self-hosted nasadení. Vedľa formulára stránka uvádza, že túto kópiu prevádzkuje jej vlastník a knihy sú v Gite ako čistý text.

Každý účet na self-hosted balíku získa najvyššiu úroveň: knihy, direktívy, spolupracujúce osoby a využitie AI sú neobmedzené.

Čo beží a koľko to stojí​

Blueprint vytvorí vo vašom priestore šesť zdrojov (ceny z náhľadu plánu v bex k 2026-11-18):

Zdroj bexČo robíMesačný náklad (USD)
beancount-dashboardWebová aplikácia a jediná verejná adresa, ktorú použijete4,90
beancount-apiGraphQL, REST, MCP server a Git proxy4,90
beancount-ledgerOveruje a dopytuje vaše knihy (súkromná, bez verejnej adresy)4,90
beancount-giteaUkladá každú knihu ako Git repozitár na 10 GB disku (súkromná)6,65
beancount-backend-dbPostgres pre účty, tokeny a nastavenia4,41
beancount-cacheKey Value pre prihlasovacie relácie a cache7,21
Spolu32,97

Poskytovateľ modelu, e-mailová služba alebo S3 bucket, ktoré pripojíte, sa účtujú zvlášť.

Zapnite voliteľné funkcie​

Balík sa spustí bez akékoľvek integrácie. Funkcia, ktorá nejakú potrebuje, uvedie, ktoré nastavenie chýba. Ak ju chcete pridať, otvorte službu beancount-api v bex, pridajte premenné na jej karte Environment a službu znova nasaďte. Premenná, ktorú tam pridáte, zostane zachovaná, keď neskôr synchronizujete Blueprint.

PremennéČo zapnú
ANTHROPIC_API_KEY alebo OPENAI_API_KEYSkenovanie dokladov, kategorizácia a asistent. bea ask potrebuje OPENAI_API_KEY.
TEMP_ASSETS_AWS_S3_* a PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY)Nahrávanie dokladov a príloh
SEND_GRID_API_KEYE-mail, napríklad odkazy na obnovenie hesla
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETPrihlásenie cez vášho vlastného poskytovateľa identity a viac účtov (pozri Pridanie viacerých účtov)

Pripojte svoje nástroje​

Všade používajte adresu dashboardu okrem Gitu, ktorý používa adresu API.

CLI nástroj bea​

Nainštalujte alebo aktualizujte bea pomocou uv tool install beancount-io alebo brew install bex-co/tap/bea a potom ho nasmerujte na svoj dashboard:

export BEA_API_URL=https://<your dashboard address>
export BEA_DASHBOARD_URL=https://<your dashboard address>
bea cloud login            # signs in through your browser
bea cloud ledger list

Obe premenné používajú adresu dashboardu, pretože dashboard preposiela prevádzku API. Referencia Beancount CLI uvádza všetky ostatné príkazy bea cloud.

Kódovací agenti cez MCP​

Pridajte MCP server nasadenia do Claude Code alebo akéhokoľvek MCP klienta:

claude mcp add --transport http beancount \
  https://<your dashboard address>/api-gateway/mcp

Prihláste sa pomocou /mcp v Claude Code. Stránku súhlasu poskytuje vaša vlastná inštancia; vyberte knihu, ktorú môže klient používať, a schváľte. Pre klienta, ktorý posiela hlavičku, vytvorte osobný prístupový token (nižšie) a pošlite ho ako Authorization: Bearer <token>.

Git cez HTTPS​

Každá kniha je Git repozitár na adrese https://<your API address>/git/<owner>/<ledger>.git. Skopírujte presnú adresu z ponuky Git Clone danej knihy. bex nesmeruje SSH, preto Git beží cez HTTPS. Na počítači s bea ho nechajte prihlásiť Git:

bea cloud login            # once, if you haven't already
bea cloud git setup        # Git now signs in with your bea session
git clone https://<your API address>/git/<owner>/<ledger>.git

Potom sa git clone, git pull a git push na tento hostiteľ nič nepýtajú a bea cloud logout odstráni aj prihlásenie Gitu. bea cloud ledger clone klonuje cez SSH, preto na tomto balíku vypíše vyššie uvedené príkazy.

Ponuka Git Clone knihy: HTTPS adresa API s osobným prístupovým tokenom ako heslom.

Git bez bea​

Na CI runneri alebo počítači bez bea prihláste Git osobným prístupovým tokenom:

  1. Vytvorte token. V dashboarde otvorte Settings → Personal access tokens → New token. Pomenujte ho podľa miesta, kde beží (laptop, nightly-backup), vyberte ledger.read na klonovanie a sťahovanie a ak nahráva, pridajte ledger.write. Pre automatizovaný skript ho obmedzte na jednu knihu a nastavte expiráciu. Skopírujte si token bcio_ teraz; zobrazí sa len raz.
  2. Klonujte. Git sa spýta na používateľské meno a heslo: zadajte akékoľvek neprázdne používateľské meno a vložte token ako heslo. macOS Keychain a Git Credential Manager vo Windows si ho ponechajú na nabudúce. V Linuxe najprv zapnite credential helper, napríklad git config --global credential.helper 'cache --timeout=86400' (v pamäti na jeden deň).

Settings, Personal access tokens: token s ledger.read a ledger.write, jeho prefix a kedy bol vytvorený a naposledy použitý.

V skripte držte token mimo URL vzdialeného repozitára, kde by ho Git uložil do .git/config, a mimo histórie shellu. Odovzdajte ho Gitu cez jednorazový credential helper:

read -rs BEANCOUNT_TOKEN; export BEANCOUNT_TOKEN
helper='!f() { echo username=token; echo "password=$BEANCOUNT_TOKEN"; }; f'
git -c credential.helper= -c credential.helper="$helper" \
  clone --mirror https://<your API address>/git/<owner>/<ledger>.git

Prázdny -c credential.helper= zabráni uloženému helperu uložiť token. Obe možnosti -c pridávajte ku každému ďalšiemu git fetch alebo git push v skripte.

Ak Git stále ponúka staré heslo alebo odvolaný token, vymažte ho:

printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject

Mobilná aplikácia​

Na uvítacej obrazovke aplikácie pre iOS alebo Android otvorte nastavenia, nastavte URL servera na adresu svojho dashboardu a prihláste sa.

Preneste svoje existujúce knihy​

Vytvorte knihu v dashboarde, naklonujte ju, zlúčte do nej svoje súbory alebo svoju Git históriu a odošlite. Balík otvára main.bean ako vstupný bod knihy, preto svoj koreňový súbor pomenujte main.bean alebo cez main.bean zahrňte (include) svoje existujúce súbory.

Pridanie viacerých účtov​

Registrácia zostáva po prvom účte uzavretá. Ďalší ľudia sa pripájajú cez poskytovateľa OpenID Connect, ktorého pripojíte, a ten zabezpečuje aj ich dvojfaktorové prihlásenie. Na karte Environment služby beancount-api:

  1. Nastavte OIDC_ISSUER, OIDC_CLIENT_ID a OIDC_CLIENT_SECRET a zaregistrujte https://<your dashboard address>/api-gateway/auth/oidc/callback ako redirect URI klienta. Prihlasovacia stránka potom ponúkne Sign in with nasledované OIDC_NAME (predvolene SSO).
  2. Uveďte, kto sa môže pripojiť, v OIDC_ALLOWED_EMAILS, oddelené čiarkami: adresa ([email protected]), doména (@example.com) alebo jej subdomény (@*.example.com). Uvedená overená adresa získa pri prvom prihlásení účet a predvolenú knihu. Bez zoznamu poskytovateľ prihlási len účty už prepojené s ním.

Každý, koho pustíte dnu, zdieľa váš disk a kľúč modelu bez limitov plánov. Pri poskytovateľovi, ku ktorému sa môže pripojiť ktokoľvek, uvádzajte adresy namiesto domény, ako napríklad @gmail.com.

Obnovenie zabudnutého hesla​

Bez SEND_GRID_API_KEY stránka pre zabudnuté heslo používateľovi oznámi, že server nemôže poslať e-mail. Vydajte mu namiesto toho jednorazový odkaz na obnovenie cez admin API. Skopírujte ADMIN_TOKEN z karty Environment služby beancount-api a volajte vlastnú adresu tejto služby v onbex.co, nie adresu dashboardu:

read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<your API address>/api/admin/password-reset-link" \
  -H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Vrátený resetUrl pošlite používateľovi cez kanál, ktorému dôverujete. Platí len raz a vyprší po hodine.

varovanie

Admin API je dostupné komukoľvek, kto sa dostane na adresu API, a chráni ho samotný ADMIN_TOKEN. Token sa môže prihlásiť ako ktorýkoľvek používateľ, preto s ním zaobchádzajte ako s root heslom: držte ho mimo histórie shellu a chatu a ak mohol uniknúť, vymeňte ho.

Aktualizácia na novšie vydanie​

Balík zostáva na verzii, ktorú ste nasadili, kým ho neaktualizujete. Blueprint vytvorený tlačidlom nedostane push webhook, preto má aktualizácia dva kroky:

  1. Synchronizujte Blueprint, aby sa zmeny jeho nastavení prejavili (bex API: POST /v1/blueprints/<id>/sync).
  2. Nasaďte každú službu na novom commite, pretože zmeny kódu vyžadujú zostavenie (POST /v1/services/<id>/deploys s commitId).

bex zostavuje jednu službu naraz a API sa zostavuje ako posledné, preto celé nasadenie môže trvať takmer hodinu. Skôr než synchronizujete novší Blueprint do balíka, ktorý obsahuje dáta, prečítajte si Aktualizácia už bežiaceho balíka a najprv zálohujte.

Zálohovanie a obnova​

Knihy sú Git repozitáre na disku Gitea. Účty, osobné prístupové tokeny a nastavenia žijú v spravovanom Postgres. Každé zálohujte vlastným spôsobom.

Knihy​

Mirror klon je úplná záloha súborov a histórie knihy:

git clone --mirror https://<your API address>/git/<owner>/<ledger>.git

Spustite ho na počítači, kde prebehol bea cloud git setup, alebo s tokenovým helperom z časti Git bez bea. Na obnovenie vymažte knihu v dashboarde, ak je stále uvedená, a vytvorte knihu s rovnakým názvom. Server odmietne vynútený push do hlavnej vetvy knihy, preto zálohu zlúčte navrch prvého commitu novej knihy a ak nepoužívate bea, použite token s ledger.write:

git clone https://<your API address>/git/<owner>/<ledger>.git restore
cd restore
git fetch ../<ledger>.git main
git merge --allow-unrelated-histories -X theirs -m "Restore from backup" FETCH_HEAD
git push origin HEAD

Databáza​

bex zálohuje beancount-backend-db priebežne a dokáže ju obnoviť do stavu z určitého skoršieho času. Obnovuje do novej databázy, nikdy na mieste, preto túto databázu skopírujete späť cez vlastnú databázu balíka:

  1. V bex otvorte beancount-backend-db, zvoľte Recovery, vyberte čas aspoň pred desiatimi minútami a obnovte. bex vytvorí novú databázu s dátami k tomu času.

  2. Pozastavte beancount-api a beancount-gitea, aby počas obnovy nič nezapisovalo.

  3. Skopírujte dáta späť pomocou pg_dump a pg_restore z PostgreSQL 16 (Docker obraz postgres:16 má oba). Pre oba konce použite externý reťazec pripojenia beancount-backend-db a pri kopírovaní zmeňte len hostiteľa na hostiteľa kópie. Nepoužívajte údaje pripojenia, ktoré bex zobrazuje pre kópiu; označujú databázu a používateľa, ktorí nedokážu čítať obnovené dáta.

    read -rs DB_URL; export DB_URL   # beancount-backend-db's external connection string
    COPY_URL="${DB_URL/@<database host>/@<copy host>}"
    pg_dump -Fc --no-owner --no-privileges "$COPY_URL" > backend.dump
    pg_restore --clean --if-exists --no-owner --no-privileges -d "$DB_URL" backend.dump

    pg_restore hlási, že nemusí vedieť odstrániť rozšírenia vector a pg_stat_statements; tieto chyby sú očakávané. Ak sa certifikát kópie ešte vydáva, pridajte ?sslmode=verify-full k COPY_URL a uložte CA, ktoré bex zobrazuje pre kópiu, ako ~/.postgresql/root.crt. Ak pripojenie vyprší, skúste to znova.

  4. Obnovte beancount-gitea a beancount-api a potom kópiu vymažte.

Čo opúšťa váš priestor​

Balík neposiela Beancount.io žiadnu analytiku ani telemetriu a skript analytiky v prehliadači je zo zostavenia vynechaný. Jediné odchádzajúce požiadavky, o ktorých vieme, sú:

  • Kontroly úniku hesiel: prvých päť znakov SHA-1 hashu nového hesla, kontrolovaných metódou k-anonymity, takže sa neprezradí ani heslo, ani účet.
  • Avatary: prehliadač žiada Gravatar o obrázok podľa hashu e-mailovej adresy používateľa.
  • Kanály: kanály blogu a changelogu Beancount.io, ktoré dostanú len jazykovú preferenciu.
  • Kanály s cenami: požiadavky na beancount.io len vtedy, keď kniha obsahuje spravovanú URL s cenami.
  • Vaše integrácie: čokoľvek, čo pripojíte, napríklad poskytovateľa modelu, SendGrid, S3, Plaid alebo poskytovateľa identity.

Tabuľka súkromia v PRFAQ006 uvádza, kedy sa každá požiadavka spustí. Vaše služby, disk a databáza bežia na infraštruktúre bex, podľa zásad ochrany súkromia a podmienok služby bex. bex stavia Stargately, Inc., spoločnosť za Beancount.io; hostovaná služba Beancount.io je oddelená od vášho balíka a nedrží žiadne jeho tajomstvá.

Odstránenie balíka​

varovanie

Vymazanie zdrojov zastaví účtovanie a vymaže s ním aj vaše dáta. Najprv naklonujte každú knihu.

Zálohujte podľa vyššie uvedeného postupu a potom vymažte šesť zdrojov v bex a nakoniec Blueprint. Ak chcete odstrániť len svoj vlastný účet a balík zachovať, vymažte ho v časti Settings → General → Danger Zone, ako na hostovanej službe; vymazaním jediného účtu sa registrácia znova otvorí.

Namiesto toho to spustite na vlastnom serveri​

Docker nasadenie spúšťa ten istý balík na akomkoľvek serveri, ktorý ovládate. Poznámky k nasadeniu na bex podrobnejšie pokrývajú každé nastavenie v tomto návode.

Narazili ste na problém? Otvorte GitHub issue alebo sa spýtajte v Beancount Telegram chate.

Zdroj: https://beancount.io/sk/docs/self-host-beancount-io