Перейти до основного вмісту

Власний хостинг 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. Створіть реєстр. Почніть із шаблону для початківців або завантажте зразковий реєстр, щоб роздивитися.
попередження

Доки не існує першого акаунта, будь-хто, хто знайде адресу панелі, може його створити. Якщо хтось зареєструється раніше за вас, видаліть цей акаунт за допомогою адміністративного токена стеку, щоб знову відкрити реєстрацію.

Реєстрація в новому розгортанні self-host. Поруч із формою сторінка повідомляє, що цей екземпляр керується його власником, а книги — це звичайний текст у Git.

Кожен акаунт на self-host стеку отримує найвищий рівень: реєстри, директиви, співробітники та використання ШІ необмежені.

Що працює і скільки це коштує​

Blueprint створює шість ресурсів у вашому робочому просторі (ціни з попереднього перегляду плану 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 ГБ (приватний)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, якщо він надсилає зміни. Для автоматизованого скрипта обмежте його одним реєстром і встановіть термін дії. Скопіюйте токен 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, і подалі від історії оболонки. Передайте його 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 у нього та надішліть зміни. Стек відкриває 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, створений кнопкою, не отримує 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. Щоб відновити, видаліть реєстр у панелі, якщо він усе ще в списку, і створіть реєстр із тією самою назвою. Сервер відхиляє примусове надсилання до основної гілки реєстру, тому злийте резервну копію поверх першого коміту нового реєстру, використовуючи токен із 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 докладніше описують кожне налаштування з цього посібника.

Натрапили на проблему? Відкрийте GitHub issue або запитайте в Telegram-чаті Beancount.

Джерело: https://beancount.io/uk/docs/self-host-beancount-io