Перейти к основному содержимому

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

Разверните Beancount.io в своём рабочем пространстве bex в один клик, затем подключите bea, клиенты MCP, Git и мобильное приложение, добавьте счета и настройте резервное копирование.

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

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

Разверните стек​

Deploy to bex.co

  1. Запустите. Нажмите Deploy to bex.co, выберите рабочее пространство, которое должно владеть стеком, проверьте план и примените. Ничего не создаётся, пока вы не одобрите предварительный просмотр, и заполнять нечего: все секреты генерируются внутри вашего рабочего пространства.
  2. Дождитесь первой сборки. В наших запусках она занимала 27–30 минут, а дольше — когда очередь сборки bex загружена. Сервис, развёртывание которого помечено как неудачное, не повторяется; разверните этот сервис снова из панели bex.
  3. Займите свой экземпляр. Откройте URL сервиса beancount-dashboard и сразу зарегистрируйтесь. Шага проверки электронной почты нет, а регистрация закрывается после создания первого аккаунта.
  4. Создайте журнал. Начните с шаблона для начинающих или загрузите образец журнала, чтобы осмотреться.
внимание

Пока не существует первого аккаунта, любой, кто найдёт адрес панели, может его создать. Если кто-то зарегистрируется раньше вас, удалите этот аккаунт с помощью администраторского токена стека, чтобы снова открыть регистрацию.

Регистрация в новом самостоятельно размещённом развёртывании. Рядом с формой на странице сказано, что этот экземпляр управляется его владельцем, а книги хранятся в виде простого текста в Git.

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

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

Blueprint создаёт шесть ресурсов в вашем рабочем пространстве (цены взяты из предварительного просмотра плана bex от 2026-11-18):

Ресурс bexЧто он делаетСтоимость в месяц (USD)
beancount-dashboardВеб-приложение и единственный публичный адрес, которым вы пользуетесь4.90
beancount-apiGraphQL, REST, сервер MCP и прокси Git4.90
beancount-ledgerПроверяет и запрашивает ваши книги (приватный, без публичного адреса)4.90
beancount-giteaХранит каждый журнал как репозиторий Git на диске 10 ГБ (приватный)6.65
beancount-backend-dbPostgres для аккаунтов, токенов и настроек4.41
beancount-cacheKey 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 Clone журнала: HTTPS-адрес API с персональным токеном доступа в качестве пароля.

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, его префикс, когда он создан и когда последний раз использовался.

В скрипте держите токен вне 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:

  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 через запятую: адрес ([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, поэтому обновление состоит из двух шагов:

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

  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, затем удалите копию.

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

Стек не отправляет аналитику или телеметрию в 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.

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