Один клик разворачивает весь стек Beancount.io — веб-панель, API и сервер MCP, сервис журнала и ваши журналы на базе Git — в рабочем пространстве bex, которым вы владеете. Это руководство ведёт от нажатия кнопки до работающего журнала. Затем оно охватывает подключение ваших инструментов, добавление счетов, обновление, резервное копирование и удаление стека.
Стек распространяется по лицензии MIT, не применяет ограничений тарифных планов и стоит около $33 в месяц за хостинг, который оплачивается вашим рабочим пространством. Об анонсе читайте в Запустите свой собственный Beancount.io в один клик.
Разверните стек
- Запустите. Нажмите Deploy to bex.co, выберите рабочее пространство, которое должно владеть стеком, проверьте план и примените. Ничего не создаётся, пока вы не одобрите предварительный просмотр, и заполнять нечего: все секреты генерируются внутри вашего рабочего пространства.
- Дождитесь первой сборки. В наших запусках она занимала 27–30 минут, а дольше — когда очередь сборки bex загружена. Сервис, развёртывание которого помечено как неудачное, не повторяется; разверните этот сервис снова из панели bex.
- Займите свой экземпляр. Откройте URL сервиса
beancount-dashboardи сразу зарегистрируйтесь. Шага проверки электронной почты нет, а регистрация закрывается после создания первого аккаунта. - Создайте журнал. Начните с шаблона для начинающих или загрузите образец журнала, чтобы осмотреться.
Пока не существует первого аккаунта, любой, кто найдёт адрес панели, может его создать. Если кто-то зарегистрируется раньше вас, удалите этот аккаунт с помощью администраторского токена стека, чтобы снова открыть регистрацию.

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

В скрипте держите токен вне URL удалённого репозитория, где Git сохранил бы его в .git/config, и вне истории команд оболочки. Передайте его 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:
- Задайте
OIDC_ISSUER,OIDC_CLIENT_IDиOIDC_CLIENT_SECRETи зарегистрируйтеhttps://<your dashboard address>/api-gateway/auth/oidc/callbackкак URI перенаправления клиента. Тогда страница входа предложит Sign in with, а затемOIDC_NAME(по умолчаниюSSO). - Перечислите, кому можно присоединиться, в
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: держите его вне истории команд оболочки и переписки, и смените его, если он мог утечь.
Обновитесь до более новой версии
Стек остаётся на развёрнутой вами версии, пока вы его не обновите. Blueprint, созданный с помощью кнопки, не получает webhook push, поэтому обновление состоит из двух шагов:
- Синхронизируйте Blueprint, чтобы применить изменения его настроек (API bex:
POST /v1/blueprints/<id>/sync). - Разверните каждый сервис на новом коммите, потому что изменения кода требуют сборки (
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 в главную ветку журнала, поэтому объедините резервную копию поверх первого коммита нового журнала, используя токен с 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 и может восстановить её на момент более раннего времени. Восстановление выполняется в новую базу данных, никогда на месте, поэтому скопируйте эту базу данных обратно поверх собственной базы стека:
-
В bex откройте
beancount-backend-db, выберите Recovery, выберите время не менее десяти минут назад и восстановите. bex создаёт новую базу данных с данными на этот момент. -
Приостановите
beancount-apiиbeancount-gitea, чтобы ничто не писало во время восстановления. -
Скопируйте данные обратно с помощью
pg_dumpиpg_restoreиз PostgreSQL 16 (образ Dockerpostgres: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.dumppg_restoreсообщит, что не может удалить расширенияvectorиpg_stat_statements; эти ошибки ожидаемы. Если сертификат копии всё ещё выдаётся, добавьте?sslmode=verify-fullкCOPY_URLи сохраните CA, который bex показывает для копии, как~/.postgresql/root.crt. Если соединение истекает по времени, повторите попытку. -
Возобновите
beancount-giteaиbeancount-api, затем удалите копию.
Что покидает ваше рабочее пространство
Стек не отправляет аналитику или телеметрию в Beancount.io, а скрипт аналитики браузера исключён из сборки. Единственные исходящие запросы, о которых мы знаем:
- Проверка утечек паролей: первые пять символов SHA-1-хеша нового пароля, проверяемые по k-анонимности, так что не раскрываются ни пароль, ни аккаунт.
- Аватары: браузер запрашивает изображение у Gravatar по хешу адреса электронной почты пользователя.
- Ленты: ленты блога и журнала изменений 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 подробнее описывают каждую настройку из этого руководства.
Возникла проблема? Откройте issue на GitHub или спросите в чате Beancount в Telegram.