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
- 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.
- 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.
- Získajte svoju inštanciu. Otvorte URL služby
beancount-dashboarda hneď sa zaregistrujte. Neexistuje krok overovania e-mailom a registrácia sa po prvom účte uzavrie. - Vytvorte knihu. Začnite zo štartovacej šablóny alebo načítajte vzorovú knihu, aby ste sa rozhliadli.
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.

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-dashboard | Webová aplikácia a jediná verejná adresa, ktorú použijete | 4,90 |
beancount-api | GraphQL, REST, MCP server a Git proxy | 4,90 |
beancount-ledger | Overuje a dopytuje vaše knihy (súkromná, bez verejnej adresy) | 4,90 |
beancount-gitea | Ukladá každú knihu ako Git repozitár na 10 GB disku (súkromná) | 6,65 |
beancount-backend-db | Postgres pre účty, tokeny a nastavenia | 4,41 |
beancount-cache | Key Value pre prihlasovacie relácie a cache | 7,21 |
| Spolu | 32,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_KEY | Skenovanie 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_KEY | E-mail, napríklad odkazy na obnovenie hesla |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | Prihlá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 listObe 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/mcpPrihlá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>.gitPotom 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.

Git bez bea
Na CI runneri alebo počítači bez bea prihláste Git osobným prístupovým tokenom:
- Vytvorte token. V dashboarde otvorte Settings → Personal access tokens → New token. Pomenujte ho podľa miesta, kde beží (
laptop,nightly-backup), vyberteledger.readna klonovanie a sťahovanie a ak nahráva, pridajteledger.write. Pre automatizovaný skript ho obmedzte na jednu knihu a nastavte expiráciu. Skopírujte si tokenbcio_teraz; zobrazí sa len raz. - 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ň).

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>.gitPrá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 rejectMobilná 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:
- Nastavte
OIDC_ISSUER,OIDC_CLIENT_IDaOIDC_CLIENT_SECRETa zaregistrujtehttps://<your dashboard address>/api-gateway/auth/oidc/callbackako redirect URI klienta. Prihlasovacia stránka potom ponúkne Sign in with nasledovanéOIDC_NAME(predvoleneSSO). - 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.
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:
- Synchronizujte Blueprint, aby sa zmeny jeho nastavení prejavili (bex API:
POST /v1/blueprints/<id>/sync). - Nasaďte každú službu na novom commite, pretože zmeny kódu vyžadujú zostavenie (
POST /v1/services/<id>/deploysscommitId).
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>.gitSpustite 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 HEADDatabá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:
-
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. -
Pozastavte
beancount-apiabeancount-gitea, aby počas obnovy nič nezapisovalo. -
Skopírujte dáta späť pomocou
pg_dumpapg_restorez PostgreSQL 16 (Docker obrazpostgres:16má oba). Pre oba konce použite externý reťazec pripojeniabeancount-backend-dba 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.dumppg_restorehlási, že nemusí vedieť odstrániť rozšíreniavectorapg_stat_statements; tieto chyby sú očakávané. Ak sa certifikát kópie ešte vydáva, pridajte?sslmode=verify-fullkCOPY_URLa uložte CA, ktoré bex zobrazuje pre kópiu, ako~/.postgresql/root.crt. Ak pripojenie vyprší, skúste to znova. -
Obnovte
beancount-giteaabeancount-apia 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
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.