Salta al contingut principal

Autoallotja Beancount.io a bex amb un clic

Desplega Beancount.io al teu propi espai de treball de bex amb un clic, després connecta bea, clients MCP, Git i l'aplicació mòbil, afegeix comptes i fes còpies de seguretat.

Un clic desplega tota la pila de Beancount.io, incloent-hi el tauler web, l'API i el servidor MCP, el servei de llibres i els teus llibres basats en Git, en un espai de treball de bex que tu posseeixes. Aquesta guia va des del botó fins a un llibre funcional. Després tracta com connectar les teves eines, afegir comptes, actualitzar, fer còpies de seguretat i eliminar la pila.

La pila té llicència MIT, no aplica límits de pla i costa uns $33 al mes en allotjament, facturat al teu espai de treball. Per a l'anunci, llegeix Executa el teu propi Beancount.io amb un sol clic.

Desplega la pila​

Deploy to bex.co

  1. Engega-la. Prem Deploy to bex.co, tria l'espai de treball que ha de posseir la pila, revisa el pla i aplica'l. No es crea res fins que aproves la previsualització, i no hi ha res a omplir: cada secret es genera dins del teu espai de treball.
  2. Espera la primera compilació. Va trigar 27–30 minuts en les nostres execucions, i més quan la cua de compilació de bex està ocupada. Un servei el desplegament del qual està marcat com a fallit no es reintenta; torna a desplegar aquest servei des del tauler de bex.
  3. Reclama la teva instància. Obre l'URL del servei beancount-dashboard i registra't de seguida. No hi ha cap pas de verificació per correu electrònic, i el registre es tanca darrere del primer compte.
  4. Crea un llibre. Comença amb la plantilla inicial, o carrega el llibre d'exemple per fer una ullada.
advertiment

Fins que existeixi el primer compte, qualsevol que trobi l'adreça del tauler pot crear-lo. Si algú es registra abans que tu, elimina aquest compte amb el testimoni d'administrador de la pila per reobrir el registre.

Registre en un nou desplegament autoallotjat. Al costat del formulari, la pàgina diu que aquesta còpia la gestiona el seu propietari i que els llibres són text pla a Git.

Cada compte en una pila autoallotjada obté el nivell més alt: els llibres, les directives, els col·laboradors i l'ús d'IA són il·limitats.

Què s'executa i quant costa​

El Blueprint crea sis recursos al teu espai de treball (preus de la previsualització del pla de bex el 2026-11-18):

Recurs de bexQuè faCost mensual (USD)
beancount-dashboardL'aplicació web, i l'única adreça pública que fas servir4.90
beancount-apiGraphQL, REST, el servidor MCP i el proxy de Git4.90
beancount-ledgerValida i consulta els teus llibres (privat, sense adreça pública)4.90
beancount-giteaEmmagatzema cada llibre com a repositori Git en un disc de 10 GB (privat)6.65
beancount-backend-dbPostgres per a comptes, testimonis i configuracions4.41
beancount-cacheKey Value per a sessions d'inici de sessió i memòries cau7.21
Total32.97

Un proveïdor de models, un servei de correu o un bucket S3 que connectis es factura a part.

Activa les funcions opcionals​

La pila arrenca sense cap integració. Una funció que en necessiti una indica quina configuració falta. Per afegir-ne una, obre el servei beancount-api a bex, afegeix les variables a la pestanya Environment i torna a desplegar el servei. Una variable que afegeixis allà es conserva quan després sincronitzis el Blueprint.

VariablesQuè activen
ANTHROPIC_API_KEY o OPENAI_API_KEYEscaneig de rebuts, categorització i l'assistent. bea ask necessita OPENAI_API_KEY.
TEMP_ASSETS_AWS_S3_* i PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY)Pujada de rebuts i adjunts
SEND_GRID_API_KEYCorreu, com ara enllaços de restabliment de contrasenya
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETInici de sessió a través del teu propi proveïdor d'identitat, i més comptes (vegeu Afegeix més comptes)

Connecta les teves eines​

Fes servir l'adreça del tauler a tot arreu excepte per a Git, que fa servir l'adreça de l'API.

La CLI bea​

Instal·la o actualitza bea amb uv tool install beancount-io o brew install bex-co/tap/bea, i després apunta-la al teu tauler:

export BEA_API_URL=https://<adreça del teu tauler>
export BEA_DASHBOARD_URL=https://<adreça del teu tauler>
bea cloud login            # inicia la sessió a través del navegador
bea cloud ledger list

Totes dues variables prenen l'adreça del tauler, perquè el tauler reenvia el trànsit de l'API. La referència de la CLI de Beancount llista tots els altres comandaments de bea cloud.

Agents de codi a través de MCP​

Afegeix el servidor MCP del desplegament a Claude Code o a qualsevol client MCP:

claude mcp add --transport http beancount \
  https://<adreça del teu tauler>/api-gateway/mcp

Inicia la sessió amb /mcp a Claude Code. La pàgina de consentiment la serveix la teva pròpia instància; tria el llibre que el client pot utilitzar i aprova. Per a un client que envia una capçalera en lloc d'això, crea un testimoni d'accés personal (a continuació) i envia'l com a Authorization: Bearer <token>.

Git sobre HTTPS​

Cada llibre és un repositori Git a https://<adreça de la teva API>/git/<owner>/<ledger>.git. Copia l'adreça exacta del menú Git Clone del llibre. bex no encamina SSH, així que Git funciona sobre HTTPS. En una màquina amb bea, deixa que iniciï la sessió de Git:

bea cloud login            # una vegada, si encara no ho has fet
bea cloud git setup        # ara Git inicia la sessió amb la teva sessió de bea
git clone https://<adreça de la teva API>/git/<owner>/<ledger>.git

Després d'això, git clone, git pull i git push cap a aquest amfitrió no demanen res, i bea cloud logout elimina també l'inici de sessió de Git. bea cloud ledger clone clona per SSH, així que en aquesta pila mostra els comandaments anteriors en lloc de fer-ho.

El menú Git Clone d'un llibre: l'adreça HTTPS de l'API, amb un testimoni d'accés personal com a contrasenya.

Git sense bea​

En un executor de CI o en una màquina sense bea, inicia la sessió de Git amb un testimoni d'accés personal:

  1. Crea un testimoni. Al tauler, obre Settings → Personal access tokens → New token. Anomena'l segons on s'executa (laptop, nightly-backup), tria ledger.read per clonar i fer pull, i afegeix ledger.write si fa push. Per a un script desatès, limita'l a un sol llibre i estableix una caducitat. Copia ara el testimoni bcio_; només es mostra una vegada.
  2. Clona. Git demana un nom d'usuari i una contrasenya: introdueix qualsevol nom d'usuari no buit i enganxa el testimoni com a contrasenya. El Keychain de macOS i el Git Credential Manager de Windows el conserven per a la propera vegada. A Linux, activa primer un assistent de credencials, per exemple git config --global credential.helper 'cache --timeout=86400' (en memòria durant un dia).

Configuració, testimonis d'accés personal: un testimoni amb ledger.read i ledger.write, el seu prefix, i quan es va crear i quan es va fer servir per última vegada.

En un script, mantén el testimoni fora de l'URL remot, on Git el desaria a .git/config, i fora de l'historial de l'intèrpret d'ordres. Passa'l a Git mitjançant un assistent de credencials d'un sol ús:

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://<adreça de la teva API>/git/<owner>/<ledger>.git

El -c credential.helper= buit evita que un assistent emmagatzemat desi el testimoni. Passa totes dues opcions -c a cada git fetch o git push posterior de l'script.

Si Git continua oferint una contrasenya antiga o un testimoni revocat, esborra'l:

printf 'protocol=https\nhost=<adreça de la teva API>\n\n' | git credential reject

L'aplicació mòbil​

A la pantalla de benvinguda de l'aplicació iOS o Android, obre la configuració, estableix l'URL del servidor a l'adreça del teu tauler i inicia la sessió.

Porta els teus llibres existents​

Crea un llibre al tauler, clona'l, fusiona-hi els teus fitxers o el teu historial de Git i fes push. La pila obre main.bean com a punt d'entrada del llibre, així que anomena el teu fitxer arrel main.bean o fes servir main.bean per include els teus fitxers existents.

Afegeix més comptes​

El registre es manté tancat després del primer compte. Més persones s'uneixen a través d'un proveïdor d'OpenID Connect que connectis, que també gestiona el seu inici de sessió amb doble factor. A la pestanya Environment del servei beancount-api:

  1. Estableix OIDC_ISSUER, OIDC_CLIENT_ID i OIDC_CLIENT_SECRET, i registra https://<adreça del teu tauler>/api-gateway/auth/oidc/callback com a URI de redirecció del client. La pàgina d'inici de sessió oferirà llavors Sign in with seguit de OIDC_NAME (per defecte SSO).
  2. Llista qui pot unir-se a OIDC_ALLOWED_EMAILS, separats per comes: una adreça ([email protected]), un domini (@example.com), o els seus subdominis (@*.example.com). Una adreça verificada i llistada obté un compte i un llibre per defecte la primera vegada que inicia la sessió. Sense la llista, el proveïdor només inicia la sessió dels comptes ja vinculats a ell.

Tothom a qui deixis entrar comparteix el teu disc i la teva clau de model, sense límits de pla. Amb un proveïdor al qual qualsevol pot unir-se, llista adreces en lloc d'un domini com @gmail.com.

Restableix una contrasenya oblidada​

Sense SEND_GRID_API_KEY, la pàgina de contrasenya oblidada indica a l'usuari que el servidor no pot enviar correu. Emet-los un enllaç de restabliment d'un sol ús des de l'API d'administrador. Copia ADMIN_TOKEN de la pestanya Environment del servei beancount-api, i crida a l'adreça onbex.co d'aquell servei, no la del tauler:

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

Envia el resetUrl retornat a l'usuari per un canal de confiança. Funciona una vegada i caduca al cap d'una hora.

advertiment

L'API d'administrador és accessible per qualsevol que pugui arribar a l'adreça de l'API, i només la protegeix ADMIN_TOKEN. El testimoni pot iniciar la sessió com a qualsevol usuari, així que tracta'l com una contrasenya d'arrel: mantén-lo fora de l'historial de l'intèrpret d'ordres i del xat, i rota'l si pot haver quedat exposat.

Actualitza a una versió més nova​

La pila es manté en la versió que vas desplegar fins que l'actualitzis. Un Blueprint creat des del botó no obté cap webhook de push, així que una actualització requereix dos passos:

  1. Sincronitza el Blueprint per aplicar canvis a la seva configuració (API de bex: POST /v1/blueprints/<id>/sync).
  2. Desplega cada servei al nou commit, perquè els canvis de codi necessiten una compilació (POST /v1/services/<id>/deploys amb commitId).

bex compila un servei alhora i l'API es compila l'última, així que un desplegament complet pot trigar gairebé una hora. Abans de sincronitzar un Blueprint més nou en una pila que conté dades, llegeix Actualitzar una pila que ja s'està executant i fes una còpia de seguretat primer.

Fes còpies de seguretat i restaura​

Els llibres són repositoris Git al disc de Gitea. Els comptes, els testimonis d'accés personal i les configuracions viuen al Postgres gestionat. Fes una còpia de seguretat de cadascun a la seva manera.

Llibres​

Un clon mirall és una còpia de seguretat completa dels fitxers i l'historial d'un llibre:

git clone --mirror https://<adreça de la teva API>/git/<owner>/<ledger>.git

Executa'l en una màquina on s'hagi executat bea cloud git setup, o amb l'assistent de testimoni de Git sense bea. Per restaurar, elimina el llibre al tauler si encara apareix a la llista i crea'n un amb el mateix nom. El servidor rebutja un push forçat a la branca principal d'un llibre, així que fusiona la còpia de seguretat a sobre del primer commit del nou llibre, fent servir un testimoni amb ledger.write quan no facis servir bea:

git clone https://<adreça de la teva API>/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

La base de dades​

bex fa còpies de seguretat contínues de beancount-backend-db i pot restaurar-la tal com era en un moment anterior. Restaura en una base de dades nova, mai in situ, així que copies aquesta base de dades sobre la pròpia de la pila:

  1. A bex, obre beancount-backend-db, tria Recovery, tria un moment d'almenys deu minuts enrere i restaura. bex crea una base de dades nova amb les dades tal com eren en aquell moment.

  2. Suspèn beancount-api i beancount-gitea, perquè res escrigui mentre restaures.

  3. Copia les dades de tornada amb pg_dump i pg_restore de PostgreSQL 16 (la imatge Docker postgres:16 té tots dos). Fes servir la cadena de connexió externa de beancount-backend-db per a tots dos extrems, i per a la còpia canvia només l'amfitrió pel de la còpia. No facis servir els detalls de connexió que bex mostra per a la còpia; anomenen una base de dades i un usuari que no poden llegir les dades restaurades.

    read -rs DB_URL; export DB_URL   # cadena de connexió externa de beancount-backend-db
    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 informa que potser no pot eliminar les extensions vector i pg_stat_statements; aquests errors són esperats. Si el certificat de la còpia encara s'està emetent, afegeix ?sslmode=verify-full a COPY_URL i desa el CA que bex mostra per a la còpia com a ~/.postgresql/root.crt. Si la connexió es tanca per temps d'espera, torna-ho a provar.

  4. Reprèn beancount-gitea i beancount-api, i després elimina la còpia.

Què surt del teu espai de treball​

La pila no envia cap analítica ni telemetria a Beancount.io, i l'script d'analítica del navegador queda exclòs de la compilació. Les úniques sol·licituds sortints que coneixem són:

  • Comprovacions de filtracions de contrasenyes: els primers cinc caràcters del hash SHA-1 d'una nova contrasenya, comprovats per k-anonimitat, de manera que no es revela ni la contrasenya ni el compte.
  • Avatars: el navegador demana una imatge a Gravatar mitjançant un hash de l'adreça de correu electrònic de l'usuari.
  • Feeds: els feeds del blog i del registre de canvis de Beancount.io, que només reben una preferència d'idioma.
  • Feeds de preus: sol·licituds a beancount.io només quan un llibre inclou un URL de preus gestionat.
  • Les teves integracions: tot el que connectis, com un proveïdor de models, SendGrid, S3, Plaid o el teu proveïdor d'identitat.

La taula de privacitat de PRFAQ006 indica quan s'activa cada sol·licitud. Els teus serveis, disc i base de dades s'executen a la infraestructura de bex, sota la política de privacitat i els termes del servei de bex. bex el construeix Stargately, Inc., l'empresa darrere de Beancount.io; el servei allotjat de Beancount.io és independent de la teva pila i no conté cap dels seus secrets.

Elimina la pila​

advertiment

Eliminar els recursos atura la factura i n'elimina les teves dades. Clona tots els llibres primer.

Fes una còpia de seguretat com s'ha descrit anteriorment, i després elimina els sis recursos a bex, seguits del Blueprint. Per eliminar només el teu propi compte i conservar la pila, elimina'l a Settings → General → Danger Zone, com al servei allotjat; eliminar l'únic compte reobre el registre.

Executa-la al teu propi servidor en lloc d'això​

El desplegament Docker executa la mateixa pila en qualsevol servidor que controlis. Les notes de desplegament de bex cobreixen amb més profunditat cada configuració d'aquesta guia.

Has trobat un entrebanc? Obre un problema a GitHub o pregunta al xat de Telegram de Beancount.

Font: https://beancount.io/ca/docs/self-host-beancount-io