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

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

Стекът е с лиценз MIT, не налага ограничения на плана и струва около \$33 на месец за хостинг, таксувани към вашия workspace. За съобщението прочетете [Стартирайте своя Beancount.io с едно кликване](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

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

[![Deploy to bex.co](/img/blog/run-your-own-beancount-io-from-one-button/deploy-to-bex.svg)](https://dashboard.bex.co/deploy?repo=https://github.com/bex-co/beancount-io&path=bex.yaml)

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

:::warning
Докато не съществува първият акаунт, всеки, който намери адреса на таблото, може да го създаде. Ако някой се регистрира преди вас, [премахнете този акаунт с администраторския токен на стека](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#13-someone-signed-up-before-me-what-now), за да отворите отново регистрацията.
:::

![Регистрация в ново самостоятелно хоствано разгръщане. До формуляра страницата казва, че това копие се управлява от своя собственик и книгите са в обикновен текст в Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

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

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

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

| bex ресурс | Какво прави | Месечна цена (USD) |
| --- | --- | --- |
| `beancount-dashboard` | Уеб приложението и единственият публичен адрес, който използвате | 4.90 |
| `beancount-api` | GraphQL, REST, MCP сървърът и Git проксито | 4.90 |
| `beancount-ledger` | Валидира и прави заявки към вашите книги (частен, без публичен адрес) | 4.90 |
| `beancount-gitea` | Съхранява всеки регистър като Git хранилище на 10 GB диск (частен) | 6.65 |
| `beancount-backend-db` | Postgres за акаунти, токени и настройки | 4.41 |
| `beancount-cache` | Key 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`](https://beancount.io/bg/docs/Basics/bea-cli) с `uv tool install beancount-io` или `brew install bex-co/tap/bea`, след което го насочете към вашето табло:

```zsh
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](https://beancount.io/bg/docs/bea-cli-reference) изброява всички останали команди на `bea cloud`.

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

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

```zsh
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:

```zsh
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-то, с личен токен за достъп като парола.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### 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, неговия префикс и кога е създаден и използван за последно.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

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

```zsh
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 продължава да предлага стара парола или отменен токен, изчистете го:

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

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

На екрана за добре дошли на приложението за [iOS](/beancount-ios) или [Android](/beancount-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`, разделени със запетаи: адрес (`alice@example.com`), домейн (`@example.com`) или неговите поддомейни (`@*.example.com`). Изброен, потвърден адрес получава акаунт и регистър по подразбиране при първото си вписване. Без списъка доставчикът вписва само акаунти, вече свързани с него.

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

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

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

```zsh
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":"user@example.com"}'
```

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

:::warning
Администраторското 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 в стек, който съдържа данни, прочетете [Актуализиране на стек, който вече работи](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) и първо направете резервно копие.

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

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

### Регистри

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

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

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

```zsh
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 показва за копието; те назовават база данни и потребител, които не могат да четат възстановените данни.

   ```zsh
   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](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) казва кога се задейства всяка заявка. Вашите услуги, диск и база данни работят върху инфраструктурата на bex, под [политиката за поверителност](https://bex.co/privacy-policy) и [условията за ползване](https://bex.co/terms-of-service) на bex. bex е създаден от Stargately, Inc., компанията зад Beancount.io; хостваната услуга Beancount.io е отделна от вашия стек и не съдържа нито една от неговите тайни.

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

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

Направете резервно копие, както е описано по-горе, след което изтрийте шестте ресурса в bex, последвани от Blueprint. За да премахнете само своя акаунт и да запазите стека, изтрийте го под **Settings → General → Danger Zone**, както при [хостваната услуга](https://beancount.io/bg/docs/request-to-delete-account); изтриването на единствения акаунт отваря отново регистрацията.

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

[Docker разгръщането](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) стартира същия стек на всеки сървър, който контролирате. [Бележките за разгръщане в bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) обхващат всяка настройка в това ръководство по-подробно.

Срещнахте проблем? Отворете [GitHub issue](https://github.com/bex-co/beancount-io/issues) или попитайте в [чата на Beancount в Telegram](https://t.me/beancount).
