Към основното съдържание

Самостоятелно хостване на Beancount.io в bex с едно кликване

Разгърнете Beancount.io в собствения си bex workspace с едно кликване, след което свържете bea, MCP клиенти, Git и мобилното приложение, добавете сметки и направете резервно копие.

С едно кликване се разгръща целият стек на Beancount.io, включително уеб таблото, API-то и MCP сървъра, услугата за регистри и вашите регистри, съхранявани в Git, в bex workspace, който притежавате. Това ръководство води от бутона до работещ регистър. След това обхваща свързването на вашите инструменти, добавянето на сметки, актуализирането, архивирането и премахването на стека.

Стекът е с лиценз MIT, не налага ограничения на плана и струва около $33 на месец за хостинг, таксувани към вашия workspace. За съобщението прочетете Стартирайте своя Beancount.io с едно кликване.

Разгръщане на стека​

Deploy to bex.co

  1. Стартирайте го. Натиснете Deploy to bex.co, изберете workspace-а, който трябва да притежава стека, прегледайте плана и приложете. Нищо не се създава, докато не одобрите прегледа, и няма нищо за попълване: всяка тайна се генерира във вашия workspace.
  2. Изчакайте първото изграждане. В нашите пускове отне 27–30 минути, а по-дълго, когато опашката за изграждане на bex е заета. Услуга, чието разгръщане е маркирано като неуспешно, не се опитва отново; разгърнете тази услуга отново от таблото на bex.
  3. Заявете своята инстанция. Отворете URL адреса на услугата beancount-dashboard и се регистрирайте веднага. Няма стъпка за потвърждение по имейл и регистрацията се затваря след първия акаунт.
  4. Създайте регистър. Започнете от началния шаблон или заредете примерния регистър, за да разгледате.
Предупреждение

Докато не съществува първият акаунт, всеки, който намери адреса на таблото, може да го създаде. Ако някой се регистрира преди вас, премахнете този акаунт с администраторския токен на стека, за да отворите отново регистрацията.

Регистрация в ново самостоятелно хоствано разгръщане. До формуляра страницата казва, че това копие се управлява от своя собственик и книгите са в обикновен текст в Git.

Всеки акаунт в самостоятелно хостван стек получава най-високото ниво: регистрите, директивите, сътрудниците и използването на AI са неограничени.

Какво работи и колко струва​

Blueprint създава шест ресурса във вашия workspace (цени от прегледа на плана на bex на 2026-11-18):

bex ресурсКакво правиМесечна цена (USD)
beancount-dashboardУеб приложението и единственият публичен адрес, който използвате4.90
beancount-apiGraphQL, REST, MCP сървърът и Git проксито4.90
beancount-ledgerВалидира и прави заявки към вашите книги (частен, без публичен адрес)4.90
beancount-giteaСъхранява всеки регистър като Git хранилище на 10 GB диск (частен)6.65
beancount-backend-dbPostgres за акаунти, токени и настройки4.41
beancount-cacheKey Value за сесии за вход и кешове7.21
Общо32.97

Доставчик на модели, имейл услуга или S3 bucket, които свържете, се таксуват отделно.

Включване на незадължителни функции​

Стекът стартира без никаква интеграция. Функция, която се нуждае от такава, казва коя настройка липсва. За да добавите интеграция, отворете услугата beancount-api в bex, добавете променливите в раздела ѝ Environment и разгърнете услугата отново. Променлива, която добавите там, се запазва, когато по-късно синхронизирате Blueprint.

ПроменливиКакво включват
ANTHROPIC_API_KEY или OPENAI_API_KEYСканиране на разписки, категоризиране и асистентът. bea ask се нуждае от OPENAI_API_KEY.
TEMP_ASSETS_AWS_S3_* и PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY)Качване на разписки и прикачени файлове
SEND_GRID_API_KEYИмейли, като връзки за нулиране на парола
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETВход чрез вашия собствен доставчик на идентичност и още акаунти (вижте Добавяне на още акаунти)

Свързване на вашите инструменти​

Използвайте адреса на таблото навсякъде, освен за Git, който използва адреса на API-то.

CLI инструментът bea​

Инсталирайте или актуализирайте bea с uv tool install beancount-io или brew install bex-co/tap/bea, след което го насочете към вашето табло:

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

И двете променливи приемат адреса на таблото, защото таблото препраща API трафика. Справочникът на Beancount CLI изброява всички останали команди на bea cloud.

Кодиращи агенти чрез MCP​

Добавете MCP сървъра на разгръщането към Claude Code или всеки MCP клиент:

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

Влезте с /mcp в Claude Code. Страницата за съгласие се предоставя от вашата собствена инстанция; изберете регистъра, който клиентът може да използва, и одобрете. За клиент, който вместо това изпраща header, създайте личен токен за достъп (по-долу) и го изпратете като Authorization: Bearer <token>.

Git през HTTPS​

Всеки регистър е Git хранилище на адрес https://<your API address>/git/<owner>/<ledger>.git. Копирайте точния адрес от менюто Git Clone на регистъра. bex не маршрутизира SSH, така че Git работи през HTTPS. На машина с bea оставете го да впише 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

След това git clone, git pull и git push към този хост не изискват нищо, а bea cloud logout премахва и вписването на Git. bea cloud ledger clone клонира през SSH, така че в този стек отпечатва командите по-горе.

Менюто Git Clone на регистър: HTTPS адресът на API-то, с личен токен за достъп като парола.

Git без bea​

На CI runner или машина без bea впишете Git с личен токен за достъп:

  1. Създайте токен. В таблото отворете Settings → Personal access tokens → New token. Назовете го според мястото, където работи (laptop, nightly-backup), изберете ledger.read за клониране и pull, и добавете ledger.write, ако прави push. За необслужван скрипт го ограничете до един регистър и задайте срок на валидност. Копирайте токена bcio_ сега; той се показва само веднъж.
  2. Клонирайте. Git пита за потребителско име и парола: въведете произволно непразно потребителско име и поставете токена като парола. macOS Keychain и Git Credential Manager в Windows го запазват за следващия път. В Linux първо включете помощник за идентификационни данни, например git config --global credential.helper 'cache --timeout=86400' (в паметта за един ден).

Settings, Personal access tokens: токен с ledger.read и ledger.write, неговия префикс и кога е създаден и използван за последно.

В скрипт дръжте токена далеч от отдалечения URL, където Git би го записал в .git/config, и далеч от историята на shell. Предайте го на Git чрез еднократен помощник за идентификационни данни:

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

Празният -c credential.helper= спира запазен помощник да съхрани токена. Предавайте и двете опции -c на всяко следващо git fetch или git push в скрипта.

Ако Git продължава да предлага стара парола или отменен токен, изчистете го:

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

Мобилното приложение​

На екрана за добре дошли на приложението за iOS или Android отворете настройките, задайте URL адреса на сървъра на адреса на вашето табло и влезте.

Пренасяне на съществуващите ви книги​

Създайте регистър в таблото, клонирайте го, слейте вашите файлове или вашата Git история в него и направете push. Стекът отваря main.bean като входна точка на регистъра, така че назовете основния си файл main.bean или използвайте main.bean, за да include съществуващите си файлове.

Добавяне на още акаунти​

Регистрацията остава затворена след първия акаунт. Повече хора се присъединяват чрез доставчик на OpenID Connect, който свързвате, който също се грижи за тяхното двуфакторно вписване. В раздела Environment на услугата beancount-api:

  1. Задайте OIDC_ISSUER, OIDC_CLIENT_ID и OIDC_CLIENT_SECRET и регистрирайте https://<your dashboard address>/api-gateway/auth/oidc/callback като redirect URI на клиента. Страницата за вход тогава предлага Sign in with, последвано от OIDC_NAME (по подразбиране SSO).
  2. Изброете кой може да се присъедини в OIDC_ALLOWED_EMAILS, разделени със запетаи: адрес ([email protected]), домейн (@example.com) или неговите поддомейни (@*.example.com). Изброен, потвърден адрес получава акаунт и регистър по подразбиране при първото си вписване. Без списъка доставчикът вписва само акаунти, вече свързани с него.

Всеки, когото допуснете, споделя вашия диск и ключ за модел, без ограничения на плана. С доставчик, в който всеки може да се присъедини, изброявайте адреси, а не домейн като @gmail.com.

Нулиране на забравена парола​

Без SEND_GRID_API_KEY страницата за забравена парола казва на потребителя, че сървърът не може да изпраща имейли. Вместо това им издайте еднократна връзка за нулиране от администраторското API. Копирайте ADMIN_TOKEN от раздела Environment на услугата beancount-api и извикайте собствения onbex.co адрес на тази услуга, а не този на таблото:

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]"}'

Изпратете върнатия resetUrl на потребителя по канал, на който се доверявате. Работи веднъж и изтича след час.

Предупреждение

Администраторското API е достъпно за всеки, който може да достигне адреса на API-то, и само ADMIN_TOKEN го пази. Токенът може да впише всеки потребител, така че се отнасяйте към него като към root парола: дръжте го далеч от историята на shell и чатове и го сменете, ако може да е изтекъл.

Актуализиране до по-нова версия​

Стекът остава на версията, която сте разгърнали, докато не го актуализирате. Blueprint, създаден от бутона, не получава push webhook, така че актуализацията изисква две стъпки:

  1. Синхронизирайте Blueprint, за да приложите промени към настройките му (bex API: POST /v1/blueprints/<id>/sync).
  2. Разгърнете всяка услуга на новия commit, защото промените в кода се нуждаят от изграждане (POST /v1/services/<id>/deploys с commitId).

bex изгражда една услуга наведнъж и API-то се изгражда последно, така че пълното разгръщане може да отнеме почти час. Преди да синхронизирате по-нов Blueprint в стек, който съдържа данни, прочетете Актуализиране на стек, който вече работи и първо направете резервно копие.

Резервно копие и възстановяване​

Регистрите са Git хранилища на диска на Gitea. Акаунтите, личните токени за достъп и настройките живеят в управлявания Postgres. Правете резервно копие на всяко по свой начин.

Регистри​

Огледален клонинг е пълно резервно копие на файловете и историята на регистъра:

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

Изпълнете го на машина, на която е изпълнено bea cloud git setup, или с помощника за токени от Git без bea. За да възстановите, изтрийте регистъра в таблото, ако все още е изброен, и създайте такъв със същото име. Сървърът отказва принудителен push към основния клон на регистър, така че слейте резервното копие върху първия commit на новия регистър, като използвате токен с ledger.write, когато не използвате bea:

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

Базата данни​

bex прави непрекъснато резервно копие на beancount-backend-db и може да го възстанови както е било в по-ранен момент. Възстановява в нова база данни, никога на място, така че копирате тази база данни обратно върху собствената на стека:

  1. В bex отворете beancount-backend-db, изберете Recovery, изберете време поне преди десет минути и възстановете. bex създава нова база данни с данните към този момент.

  2. Сппрете beancount-api и beancount-gitea, за да не пише нищо, докато възстановявате.

  3. Копирайте данните обратно с pg_dump и pg_restore от PostgreSQL 16 (Docker образът postgres:16 съдържа и двете). Използвайте външния низ за връзка на beancount-backend-db за двата края, а за копието сменете само хоста с този на копието. Не използвайте данните за връзка, които bex показва за копието; те назовават база данни и потребител, които не могат да четат възстановените данни.

    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 съобщава, че може да не успее да премахне разширенията vector и pg_stat_statements; тези грешки се очакват. Ако сертификатът на копието все още се издава, добавете ?sslmode=verify-full към COPY_URL и запазете CA, който bex показва за копието, като ~/.postgresql/root.crt. Ако връзката изтече, опитайте отново.

  4. Възобновете beancount-gitea и beancount-api, след което изтрийте копието.

Какво напуска вашия workspace​

Стекът не изпраща анализи или телеметрия към Beancount.io, а скриптът за анализи в браузъра е изключен от изграждането. Единствените изходящи заявки, за които знаем, са:

  • Проверки за изтекли пароли: първите пет знака от SHA-1 хеша на нова парола, проверени чрез k-анонимност, така че нито паролата, нито акаунтът се разкриват.
  • Аватари: браузърът пита Gravatar за изображение по хеш на имейл адреса на потребителя.
  • Емисии: емисиите на блога и changelog на Beancount.io, които получават само предпочитание за език.
  • Емисии с цени: заявки към beancount.io само когато регистър включва управляван URL за цени.
  • Вашите интеграции: каквото и да свържете, като доставчик на модели, SendGrid, S3, Plaid или вашия доставчик на идентичност.

Таблицата за поверителност в PRFAQ006 казва кога се задейства всяка заявка. Вашите услуги, диск и база данни работят върху инфраструктурата на bex, под политиката за поверителност и условията за ползване на bex. bex е създаден от Stargately, Inc., компанията зад Beancount.io; хостваната услуга Beancount.io е отделна от вашия стек и не съдържа нито една от неговите тайни.

Премахване на стека​

Предупреждение

Изтриването на ресурсите спира фактурата и изтрива данните ви заедно с тях. Първо клонирайте всеки регистър.

Направете резервно копие, както е описано по-горе, след което изтрийте шестте ресурса в bex, последвани от Blueprint. За да премахнете само своя акаунт и да запазите стека, изтрийте го под Settings → General → Danger Zone, както при хостваната услуга; изтриването на единствения акаунт отваря отново регистрацията.

Стартиране на собствен сървър вместо това​

Docker разгръщането стартира същия стек на всеки сървър, който контролирате. Бележките за разгръщане в bex обхващат всяка настройка в това ръководство по-подробно.

Срещнахте проблем? Отворете GitHub issue или попитайте в чата на Beancount в Telegram.

Източник: https://beancount.io/bg/docs/self-host-beancount-io