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

Кожен акаунт на self-host стеку отримує найвищий рівень: реєстри, директиви, співробітники та використання ШІ необмежені.
Що працює і скільки це коштує
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, якщо він надсилає зміни. Для автоматизованого скрипта обмежте його одним реєстром і встановіть термін дії. Скопіюйте токенbcio_зараз; він показується лише один раз. - Клонуйте. Git запитає ім'я користувача та пароль: введіть будь-яке непорожнє ім'я користувача та вставте токен як пароль. macOS Keychain і 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 у нього та надішліть зміни. Стек відкриває 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, створений кнопкою, не отримує 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. Щоб відновити, видаліть реєстр у панелі, якщо він усе ще в списку, і створіть реєстр із тією самою назвою. Сервер відхиляє примусове надсилання до основної гілки реєстру, тому злийте резервну копію поверх першого коміту нового реєстру, використовуючи токен із 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 докладніше описують кожне налаштування з цього посібника.
Натрапили на проблему? Відкрийте GitHub issue або запитайте в Telegram-чаті Beancount.