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

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

این پشته تحت مجوز MIT است، هیچ محدودیت پلنی اعمال نمی‌کند و ماهانه حدود ۳۳ دلار هزینه میزبانی دارد که به فضای کاری شما صورت‌حساب می‌شود. برای اطلاعیه، [نصب Beancount.io شخصی خود با یک کلیک](/blog/2026/11/18/run-your-own-beancount-io-from-one-button) را بخوانید.

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

[![Deploy to bex.co](/img/blog/run-your-own-beancount-io-from-one-button/deploy-to-bex.svg)](https://dashboard.bex.co/deploy?repo=https://github.com/bex-co/beancount-io&path=bex.yaml)

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

:::warning
تا زمانی که اولین حساب وجود ندارد، هر کسی که نشانی داشبورد را پیدا کند می‌تواند آن را بسازد. اگر کسی پیش از شما ثبت‌نام کرد، [آن حساب را با توکن مدیر پشته حذف کنید](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#13-someone-signed-up-before-me-what-now) تا ثبت‌نام دوباره باز شود.
:::

![ثبت‌نام در یک استقرار خودمیزبان جدید. کنار فرم، صفحه اعلام می‌کند این نسخه توسط صاحبش اداره می‌شود و دفترها متنی ساده در Git هستند.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

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

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

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`](https://beancount.io/fa/docs/Basics/bea-cli) را با `uv tool install beancount-io` یا `brew install bex-co/tap/bea` نصب یا به‌روزرسانی کنید، سپس آن را به داشبورد خود نشانه بگیرید:

```zsh
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](https://beancount.io/fa/docs/bea-cli-reference) همه دستورهای دیگر `bea cloud` را فهرست می‌کند.

### عامل‌های کدنویسی از طریق MCP

سرور MCP این استقرار را به Claude Code یا هر کلاینت MCP اضافه کنید:

```zsh
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 را وارد کند:

```zsh
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، با یک توکن دسترسی شخصی به‌عنوان رمز.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### 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، پیشوندش، و زمان ساخت و آخرین استفاده‌اش.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

در یک اسکریپت، توکن را بیرون از نشانی remote که Git آن را در `.git/config` ذخیره می‌کند و بیرون از تاریخچه شل نگه دارید. آن را با یک credential helper یک‌بارمصرف به Git بسپارید:

```zsh
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 مدام رمز قدیمی یا توکن باطل‌شده را پیشنهاد می‌دهد، آن را پاک کنید:

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

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

در صفحه خوش‌آمدگویی اپلیکیشن [iOS](/beancount-ios) یا [Android](/beancount-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` با کاما جدا کنید: یک نشانی (`alice@example.com`)، یک دامنه (`@example.com`) یا زیردامنه‌هایش (`@*.example.com`). نشانی فهرست‌شده و تأییدشده اولین‌بار که وارد می‌شود یک حساب و یک دفتر کل پیش‌فرض می‌گیرد. بدون این فهرست، ارائه‌دهنده فقط حساب‌های از پیش متصل به خود را وارد می‌کند.

همه کسانی که راه می‌دهید دیسک و کلید مدل شما را به اشتراک می‌گذارند، بدون محدودیت پلن. با ارائه‌دهنده‌ای که هر کسی می‌تواند عضو آن شود، به‌جای دامنه‌ای مثل `@gmail.com` نشانی‌ها را فهرست کنید.

## بازنشانی رمز فراموش‌شده

بدون `SEND_GRID_API_KEY`، صفحه فراموشی رمز به کاربر می‌گوید سرور نمی‌تواند ایمیل بفرستد. به‌جای آن از API مدیر برایشان یک پیوند بازنشانی یک‌بارمصرف صادر کنید. `ADMIN_TOKEN` را از تب **Environment** سرویس `beancount-api` کپی کنید و نشانی `onbex.co` خودِ آن سرویس را فراخوانی کنید، نه نشانی داشبورد را:

```zsh
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":"user@example.com"}'
```

`resetUrl` بازگردانده‌شده را از کانالی که به آن اعتماد دارید برای کاربر بفرستید. یک‌بار کار می‌کند و پس از یک ساعت منقضی می‌شود.

:::warning
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 جدیدتر در پشته‌ای که داده دارد، [ارتقای پشته‌ای که در حال اجراست](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) را بخوانید و اول پشتیبان بگیرید.

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

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

### دفترهای کل

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

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

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

```zsh
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 برای کپی نشان می‌دهد استفاده نکنید؛ آن‌ها پایگاه داده و کاربری را نام می‌برند که نمی‌توانند داده بازیابی‌شده را بخوانند.

   ```zsh
   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](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) می‌گوید هر درخواست چه زمانی ارسال می‌شود. سرویس‌ها، دیسک و پایگاه داده شما روی زیرساخت bex اجرا می‌شوند، تحت [سیاست حریم خصوصی](https://bex.co/privacy-policy) و [شرایط خدمات](https://bex.co/terms-of-service) bex. bex توسط Stargately, Inc.، شرکتی که پشت Beancount.io است، ساخته شده؛ سرویس میزبانی‌شده Beancount.io جدا از پشته شماست و هیچ‌یک از رمزهای آن را نگه نمی‌دارد.

## حذف پشته

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

همان‌طور که بالا توضیح داده شد پشتیبان بگیرید، سپس شش منبع را در bex حذف کنید و در ادامه Blueprint را. برای حذف فقط حساب خودتان و نگه‌داشتن پشته، آن را زیر **Settings → General → Danger Zone** حذف کنید، مانند [سرویس میزبانی‌شده](https://beancount.io/fa/docs/request-to-delete-account)؛ حذف تنها حساب، ثبت‌نام را دوباره باز می‌کند.

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

[استقرار Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) همان پشته را روی هر سروری که کنترل می‌کنید اجرا می‌کند. [یادداشت‌های استقرار bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) هر تنظیم در این راهنما را با عمق بیشتری پوشش می‌دهند.

به مشکلی برخوردید؟ یک [GitHub issue](https://github.com/bex-co/beancount-io/issues) باز کنید یا در [چت تلگرام Beancount](https://t.me/beancount) بپرسید.
