پرش به محتوای اصلی

میزبانی خودی Beancount.io روی bex با یک کلیک

Beancount.io را با یک کلیک در فضای کاری bex خودتان مستقر کنید، سپس bea، کلاینت‌های MCP، Git و اپلیکیشن موبایل را متصل کنید، حساب اضافه کنید و پشتیبان بگیرید.

یک کلیک کل پشته Beancount.io را مستقر می‌کند، شامل داشبورد وب، API و سرور MCP، سرویس دفتر کل و دفترهای کل مبتنی بر Git، در یک فضای کاری bex که مالک آن شماست. این راهنما از دکمه شروع می‌شود و به یک دفتر کل کارا می‌رسد. سپس اتصال ابزارها، افزودن حساب‌ها، به‌روزرسانی، پشتیبان‌گیری و حذف پشته را پوشش می‌دهد.

این پشته تحت مجوز MIT است، هیچ محدودیت پلنی اعمال نمی‌کند و ماهانه حدود ۳۳ دلار هزینه میزبانی دارد که به فضای کاری شما صورت‌حساب می‌شود. برای اطلاعیه، نصب Beancount.io شخصی خود با یک کلیک را بخوانید.

استقرار پشته​

Deploy to bex.co

  1. راه‌اندازی. روی Deploy to bex.co بزنید، فضای کاری‌ای را که باید مالک پشته باشد انتخاب کنید، پلن را بررسی و اعمال کنید. تا زمانی که پیش‌نمایش را تأیید نکنید چیزی ساخته نمی‌شود و چیزی برای پر کردن نیست: هر رمزی داخل فضای کاری شما تولید می‌شود.
  2. انتظار برای اولین بیلد. در اجراهای ما ۲۷ تا ۳۰ دقیقه طول کشید و وقتی صف بیلد bex شلوغ است بیشتر. سرویسی که rollout آن ناموفق علامت خورده دوباره تلاش نمی‌شود؛ آن سرویس را از داشبورد bex دوباره مستقر کنید.
  3. تصاحب نمونه خود. نشانی سرویس beancount-dashboard را باز کنید و بلافاصله ثبت‌نام کنید. مرحله تأیید ایمیل وجود ندارد و ثبت‌نام پس از اولین حساب بسته می‌شود.
  4. ساخت دفتر کل. از قالب آغازین شروع کنید یا دفتر کل نمونه را بارگذاری کنید تا نگاهی بیندازید.
هشدار

تا زمانی که اولین حساب وجود ندارد، هر کسی که نشانی داشبورد را پیدا کند می‌تواند آن را بسازد. اگر کسی پیش از شما ثبت‌نام کرد، آن حساب را با توکن مدیر پشته حذف کنید تا ثبت‌نام دوباره باز شود.

ثبت‌نام در یک استقرار خودمیزبان جدید. کنار فرم، صفحه اعلام می‌کند این نسخه توسط صاحبش اداره می‌شود و دفترها متنی ساده در Git هستند.

هر حساب در یک پشته خودمیزبان بالاترین سطح را دریافت می‌کند: دفترهای کل، دستورها، همکاران و استفاده از هوش مصنوعی نامحدودند.

چه چیزی اجرا می‌شود و هزینه‌اش چقدر است​

Blueprint شش منبع در فضای کاری شما می‌سازد (قیمت‌ها از پیش‌نمایش پلن bex در ۲۰۲۶-۱۱-۱۸):

منبع bexکارکردهزینه ماهانه (دلار)
beancount-dashboardاپلیکیشن وب و تنها نشانی عمومی که استفاده می‌کنید۴٫۹۰
beancount-apiGraphQL، REST، سرور MCP و پروکسی Git۴٫۹۰
beancount-ledgerاعتبارسنجی و پرس‌وجوی دفترهای شما (خصوصی، بدون نشانی عمومی)۴٫۹۰
beancount-giteaذخیره هر دفتر کل به‌صورت مخزن Git روی دیسک ۱۰ گیگابایتی (خصوصی)۶٫۶۵
beancount-backend-dbPostgres برای حساب‌ها، توکن‌ها و تنظیمات۴٫۴۱
beancount-cacheKey Value برای نشست‌های ورود و کش‌ها۷٫۲۱
مجموع۳۲٫۹۷

ارائه‌دهنده مدل، سرویس ایمیل یا سطل 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 استفاده می‌کند.

خط فرمان 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 همه دستورهای دیگر 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 runner یا ماشینی بدون bea، Git را با یک توکن دسترسی شخصی وارد کنید:

  1. ساخت توکن. در داشبورد، Settings → Personal access tokens → New token را باز کنید. آن را بر اساس محل اجرایش نام‌گذاری کنید (laptop، nightly-backup)، برای کلون و pull مقدار ledger.read را انتخاب کنید و اگر push می‌کند ledger.write را اضافه کنید. برای یک اسکریپت بدون نظارت، آن را به یک دفتر کل محدود کنید و تاریخ انقضا تعیین کنید. توکن bcio_ را همین حالا کپی کنید؛ فقط یک‌بار نمایش داده می‌شود.
  2. کلون. Git نام کاربری و رمز می‌پرسد: هر نام کاربری غیرخالی وارد کنید و توکن را به‌عنوان رمز بچسبانید. Keychain در macOS و Git Credential Manager در Windows آن را برای دفعه بعد نگه می‌دارند. در Linux ابتدا یک credential helper روشن کنید، مثلاً git config --global credential.helper 'cache --timeout=86400' (در حافظه برای یک روز).

تنظیمات، توکن‌های دسترسی شخصی: توکنی با ledger.read و ledger.write، پیشوندش، و زمان ساخت و آخرین استفاده‌اش.

در یک اسکریپت، توکن را بیرون از نشانی remote که Git آن را در .git/config ذخیره می‌کند و بیرون از تاریخچه شل نگه دارید. آن را با یک credential helper یک‌بارمصرف به 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= مانع از آن می‌شود که یک helper ذخیره‌شده توکن را ذخیره کند. هر دو گزینه -c را به هر git fetch یا git push بعدی در اسکریپت هم بدهید.

اگر Git مدام رمز قدیمی یا توکن باطل‌شده را پیشنهاد می‌دهد، آن را پاک کنید:

printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject

اپلیکیشن موبایل​

در صفحه خوش‌آمدگویی اپلیکیشن iOS یا Android، تنظیمات را باز کنید، نشانی سرور را روی نشانی داشبورد بگذارید و وارد شوید.

آوردن دفترهای موجودتان​

یک دفتر کل در داشبورد بسازید، آن را کلون کنید، فایل‌ها یا تاریخچه 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 را به‌عنوان redirect 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 از آن محافظت می‌کند. این توکن می‌تواند به‌عنوان هر کاربری وارد شود، پس با آن مانند یک رمز روت رفتار کنید: آن را بیرون از تاریخچه شل و چت نگه دارید و اگر احتمال افشا وجود دارد آن را بچرخانید.

به‌روزرسانی به نسخه جدیدتر​

پشته تا زمانی که به‌روزرسانی نکنید روی نسخه‌ای که مستقر کرده‌اید می‌ماند. Blueprintی که از دکمه ساخته می‌شود webhook push ندارد، بنابراین به‌روزرسانی دو مرحله دارد:

  1. همگام‌سازی Blueprint برای اعمال تغییرات در تنظیماتش (API مربوط به bex: POST /v1/blueprints/<id>/sync).
  2. استقرار هر سرویس در commit جدید، زیرا تغییرات کد به بیلد نیاز دارند (POST /v1/services/<id>/deploys با commitId).

bex هر بار یک سرویس می‌سازد و API آخر از همه، بنابراین یک rollout کامل می‌تواند بیشتر یک ساعت طول بکشد. پیش از همگام‌سازی یک Blueprint جدیدتر در پشته‌ای که داده دارد، ارتقای پشته‌ای که در حال اجراست را بخوانید و اول پشتیبان بگیرید.

پشتیبان‌گیری و بازیابی​

دفترهای کل مخزن‌های Git روی دیسک Gitea هستند. حساب‌ها، توکن‌های دسترسی شخصی و تنظیمات در Postgres مدیریت‌شده قرار دارند. هر یک را به روش خودش پشتیبان بگیرید.

دفترهای کل​

کلون mirror یک پشتیبان کامل از فایل‌ها و تاریخچه دفتر کل است:

git clone --mirror https://<your API address>/git/<owner>/<ledger>.git

آن را روی ماشینی اجرا کنید که bea cloud git setup روی آن اجرا شده، یا با helper توکن از Git بدون bea. برای بازیابی، اگر دفتر کل هنوز فهرست شده آن را در داشبورد حذف کنید و یکی با همان نام بسازید. سرور push اجباری به شاخه اصلی یک دفتر کل را رد می‌کند، پس پشتیبان را روی اولین commit دفتر کل جدید ادغام کنید و وقتی از bea استفاده نمی‌کنید توکنی با ledger.write به کار ببرید:

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 ذخیره کنید. اگر اتصال timeout شد، دوباره تلاش کنید.

  4. beancount-gitea و beancount-api را از تعلیق خارج کنید، سپس کپی را حذف کنید.

چه چیزی از فضای کاری شما خارج می‌شود​

پشته هیچ آنالیتیکس یا تله‌متری‌ای به Beancount.io نمی‌فرستد و اسکریپت آنالیتیکس مرورگر از بیلد حذف شده است. تنها درخواست‌های خروجی که می‌شناسیم این‌ها هستند:

  • بررسی نشت رمز: پنج کاراکتر اول هش SHA-1 رمز جدید، که با k-anonymity بررسی می‌شود، بنابراین نه رمز و نه حساب افشا نمی‌شود.
  • آواتارها: مرورگر تصویری را بر اساس هش نشانی ایمیل کاربر از Gravatar می‌خواهد.
  • فیدها: فیدهای وبلاگ و تغییرات Beancount.io، که فقط یک ترجیح زبانی دریافت می‌کنند.
  • فیدهای قیمت: درخواست‌ها به beancount.io فقط وقتی یک دفتر کل نشانی قیمت مدیریت‌شده را شامل می‌شود.
  • یکپارچه‌سازی‌های شما: هر چیزی که متصل کنید، مانند ارائه‌دهنده مدل، SendGrid، S3، Plaid یا ارائه‌دهنده هویت.

جدول حریم خصوصی در PRFAQ006 می‌گوید هر درخواست چه زمانی ارسال می‌شود. سرویس‌ها، دیسک و پایگاه داده شما روی زیرساخت bex اجرا می‌شوند، تحت سیاست حریم خصوصی و شرایط خدمات bex. bex توسط Stargately, Inc.، شرکتی که پشت Beancount.io است، ساخته شده؛ سرویس میزبانی‌شده Beancount.io جدا از پشته شماست و هیچ‌یک از رمزهای آن را نگه نمی‌دارد.

حذف پشته​

هشدار

حذف منابع صورت‌حساب را متوقف و داده‌های شما را همراه آن‌ها حذف می‌کند. ابتدا هر دفتر کل را کلون کنید.

همان‌طور که بالا توضیح داده شد پشتیبان بگیرید، سپس شش منبع را در bex حذف کنید و در ادامه Blueprint را. برای حذف فقط حساب خودتان و نگه‌داشتن پشته، آن را زیر Settings → General → Danger Zone حذف کنید، مانند سرویس میزبانی‌شده؛ حذف تنها حساب، ثبت‌نام را دوباره باز می‌کند.

به‌جای آن روی سرور خودتان اجرا کنید​

استقرار Docker همان پشته را روی هر سروری که کنترل می‌کنید اجرا می‌کند. یادداشت‌های استقرار bex هر تنظیم در این راهنما را با عمق بیشتری پوشش می‌دهند.

به مشکلی برخوردید؟ یک GitHub issue باز کنید یا در چت تلگرام Beancount بپرسید.

منبع: https://beancount.io/fa/docs/self-host-beancount-io