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

هر حساب در یک پشته خودمیزبان بالاترین سطح را دریافت میکند: دفترهای کل، دستورها، همکاران و استفاده از هوش مصنوعی نامحدودند.
چه چیزی اجرا میشود و هزینهاش چقدر است
Blueprint شش منبع در فضای کاری شما میسازد (قیمتها از پیشنمایش پلن bex در ۲۰۲۶-۱۱-۱۸):
| منبع bex | کارکرد | هزینه ماهانه (دلار) |
|---|---|---|
beancount-dashboard | اپلیکیشن وب و تنها نشانی عمومی که استفاده میکنید | ۴٫۹۰ |
beancount-api | GraphQL، REST، سرور MCP و پروکسی Git | ۴٫۹۰ |
beancount-ledger | اعتبارسنجی و پرسوجوی دفترهای شما (خصوصی، بدون نشانی عمومی) | ۴٫۹۰ |
beancount-gitea | ذخیره هر دفتر کل بهصورت مخزن Git روی دیسک ۱۰ گیگابایتی (خصوصی) | ۶٫۶۵ |
beancount-backend-db | Postgres برای حسابها، توکنها و تنظیمات | ۴٫۴۱ |
beancount-cache | Key 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 بدون bea
روی یک CI runner یا ماشینی بدون bea، Git را با یک توکن دسترسی شخصی وارد کنید:
- ساخت توکن. در داشبورد، Settings → Personal access tokens → New token را باز کنید. آن را بر اساس محل اجرایش نامگذاری کنید (
laptop،nightly-backup)، برای کلون و pull مقدارledger.readرا انتخاب کنید و اگر push میکندledger.writeرا اضافه کنید. برای یک اسکریپت بدون نظارت، آن را به یک دفتر کل محدود کنید و تاریخ انقضا تعیین کنید. توکنbcio_را همین حالا کپی کنید؛ فقط یکبار نمایش داده میشود. - کلون. Git نام کاربری و رمز میپرسد: هر نام کاربری غیرخالی وارد کنید و توکن را بهعنوان رمز بچسبانید. Keychain در macOS و Git Credential Manager در Windows آن را برای دفعه بعد نگه میدارند. در Linux ابتدا یک credential helper روشن کنید، مثلاً
git config --global credential.helper 'cache --timeout=86400'(در حافظه برای یک روز).

در یک اسکریپت، توکن را بیرون از نشانی 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:
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) ارائه میدهد.- فهرست کسانی که میتوانند بپیوندند را در
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 ندارد، بنابراین بهروزرسانی دو مرحله دارد:
- همگامسازی Blueprint برای اعمال تغییرات در تنظیماتش (API مربوط به bex:
POST /v1/blueprints/<id>/sync). - استقرار هر سرویس در 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 بهصورت پیوسته پشتیبان میگیرد و میتواند آن را به وضعیت زمانی پیشین بازیابی کند. بازیابی در یک پایگاه داده جدید انجام میشود، هرگز درجا، بنابراین شما آن پایگاه داده را روی پایگاه داده خود پشته کپی میکنید:
-
در 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ذخیره کنید. اگر اتصال timeout شد، دوباره تلاش کنید. -
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 بپرسید.