# Разверните Beancount.io на bex в один клик

Один клик разворачивает весь стек Beancount.io — веб-панель, API и сервер MCP, сервис журнала и ваши журналы на базе Git — в рабочем пространстве bex, которым вы владеете. Это руководство ведёт от нажатия кнопки до работающего журнала. Затем оно охватывает подключение ваших инструментов, добавление счетов, обновление, резервное копирование и удаление стека.

Стек распространяется по лицензии MIT, не применяет ограничений тарифных планов и стоит около \$33 в месяц за хостинг, который оплачивается вашим рабочим пространством. Об анонсе читайте в [Запустите свой собственный 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**, выберите рабочее пространство, которое должно владеть стеком, проверьте план и примените. Ничего не создаётся, пока вы не одобрите предварительный просмотр, и заполнять нечего: все секреты генерируются внутри вашего рабочего пространства.
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)

Каждый аккаунт на самостоятельно размещённом стеке получает высший уровень: журналы, директивы, соавторы и использование ИИ неограниченны.

## Что запускается и сколько это стоит

Blueprint создаёт шесть ресурсов в вашем рабочем пространстве (цены взяты из предварительного просмотра плана 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 ГБ (приватный) | 6.65 |
| `beancount-backend-db` | Postgres для аккаунтов, токенов и настроек | 4.41 |
| `beancount-cache` | Key Value для сессий входа и кешей | 7.21 |
| **Итого** | | **32.97** |

Провайдер модели, почтовый сервис или S3-бакет, которые вы подключите, оплачиваются отдельно.

## Включите дополнительные функции

Стек загружается без каких-либо интеграций. Функция, которой нужна интеграция, сообщает, какая настройка отсутствует. Чтобы добавить её, откройте сервис `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/ru/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/ru/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. Страница согласия обслуживается вашим собственным экземпляром; выберите журнал, который может использовать клиент, и одобрите. Для клиента, который отправляет заголовок вместо этого, создайте персональный токен доступа (ниже) и отправьте его как `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-раннере или машине без `bea` войдите в Git с помощью персонального токена доступа:

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

![Настройки, персональные токены доступа: токен с ledger.read и ledger.write, его префикс, когда он создан и когда последний раз использовался.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

В скрипте держите токен вне URL удалённого репозитория, где Git сохранил бы его в `.git/config`, и вне истории команд оболочки. Передайте его 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` как 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: держите его вне истории команд оболочки и переписки, и смените его, если он мог утечь.
:::

## Обновитесь до более новой версии

Стек остаётся на развёрнутой вами версии, пока вы его не обновите. Blueprint, созданный с помощью кнопки, не получает webhook push, поэтому обновление состоит из двух шагов:

1. **Синхронизируйте Blueprint**, чтобы применить изменения его настроек (API bex: `POST /v1/blueprints/<id>/sync`).
2. **Разверните каждый сервис на новом коммите**, потому что изменения кода требуют сборки (`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 в главную ветку журнала, поэтому объедините резервную копию поверх первого коммита нового журнала, используя токен с `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`, затем удалите копию.

## Что покидает ваше рабочее пространство

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

- **Проверка утечек паролей:** первые пять символов SHA-1-хеша нового пароля, проверяемые по k-анонимности, так что не раскрываются ни пароль, ни аккаунт.
- **Аватары:** браузер запрашивает изображение у Gravatar по хешу адреса электронной почты пользователя.
- **Ленты:** ленты блога и журнала изменений 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/ru/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) подробнее описывают каждую настройку из этого руководства.

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