# 一键运行你自己的 Beancount.io

将整个 Beancount.io 技术栈——Web 应用、API、MCP 服务器以及基于 Git 的账本——部署到你自己的 bex 工作区，大约只需 30 分钟。零配置、无套餐限制、MIT 许可，托管费用约每月 33 美元。



Beancount 让你以纯文本形式完全掌控自己的财务。但围绕这些 `.bean` 文件的软件一直较难掌控：要在账本之上获得 Web UI、CLI 和 AI 智能体端点，要么把你的账本托付给我们的托管服务，要么手动连接六个服务。

从今天起，你可以一键启动一个属于你自己的私有 Beancount.io 实例。

点击 **Deploy to bex.co**，选择拥有该技术栈的工作区，然后批准套餐。无需任何配置——所有密钥都会在你的工作区内自动生成。大约 30 分钟后，你的仪表盘就会上线。创建你的账户后，注册入口随即关闭；除非你通过自己的身份提供商邀请，否则任何人都无法进入。

[![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)

你的账本以标准 Git 仓库的形式存放在工作区的磁盘上。每个接口都严格指向你的地址，而非我们的：Web 仪表盘、`bea` CLI、通过内置 MCP 服务器连接的编码智能体，或普通的 `git`（`bea` 会为你完成认证）。账本、指令或 AI 使用量均无套餐限制，该技术栈不会向 Beancount.io 发送任何分析数据。

可选集成在你需要之前保持关闭：自带模型密钥用于收据扫描、分类和助手；S3 存储桶用于收据上传；或邮件密钥用于密码重置。在你添加它们之前，每项功能只会显示它需要哪项设置——其余一切开箱即用。

## 你会得到什么，以及花费多少

部署会开通六个服务，费用直接计入你的 bex 工作区（价格来自 bex 于 2026-11-18 的套餐预览）：

| 服务 | 作用 | 月费用（美元） |
| --- | --- | --- |
| Dashboard | Web 应用及你使用的唯一公开地址 | $4.90 |
| API | GraphQL、REST、MCP 服务器和 Git 代理 | $4.90 |
| Ledger service | 验证并查询你的账本（私有，无公开地址） | $4.90 |
| Gitea | 将每个账本作为 Git 仓库存储在 10 GB 磁盘上（私有） | $6.65 |
| Postgres | 账户、令牌和设置 | $4.41 |
| Key Value | 登录会话和缓存 | $7.21 |
| **合计** | | **$32.97** |

你连接的任何外部模型提供商、邮件服务或 S3 存储桶，均由这些提供商单独计费。

> **拆除之前请注意：** 删除资源会立即停止计费，**同时也会删除你的数据。** 请务必先克隆你的 Git 账本。

自托管技术栈上的每个账户都会自动获得最高套餐——没有人为上限：

![自托管技术栈上的设置、账单页面：Enterprise 套餐，AI 令牌、账本、指令和协作者均无限制。](/img/blog/run-your-own-beancount-io-from-one-button/no-plan-limits.webp)

## 从一键点击到你的第一个账本

1. **启动技术栈。** 点击 **Deploy to bex.co**（上方，或 [README](https://github.com/bex-co/beancount-io#self-host) 中），选择你的工作区，查看套餐，然后应用。在你批准之前，不会开通任何资源。
2. **等待初始构建。** 在我们的运行中，首次构建需要 27–30 分钟（如果 bex 的构建队列繁忙，则会更久）。如果某个服务显示部署失败，请从 bex 仪表盘触发重新部署。
3. **认领你的实例。** 打开你的仪表盘 URL 并立即注册——没有邮件验证步骤。
4. **创建账本。** 从入门模板全新开始，或加载示例账本进行探索。

> **安全提示：** 在创建第一个账户之前，任何发现你 URL 的人都可以认领它。如果有人抢先一步，你可以使用该技术栈的管理令牌[移除该账户](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)

## 将你的工具指向你自己的地址

### `bea` CLI

通过 `uv tool install beancount-io` 或 `brew install bex-co/tap/bea` 安装或更新 [`bea`](/docs/Basics/bea-cli)，然后将其指向你的仪表盘：

```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
```

两个环境变量使用相同的仪表盘 URL，它会为你代理 API 流量。

![bea 0.4.1 连接自托管部署：bea cloud login、Enterprise 套餐上的 bea cloud status，以及 bea cloud ledger list。](/img/blog/run-your-own-beancount-io-from-one-button/bea-login.webp)

### 编码智能体（MCP）

将 Claude Code 或任何兼容 MCP 的客户端直接连接到你的部署：

```zsh
claude mcp add --transport http beancount \
  https://<your dashboard address>/api-gateway/mcp
```

在 Claude Code 中通过 `/mcp` 登录——OAuth 同意页面由你自己的实例提供。对于通过请求头认证的客户端，请在 **Settings → Personal access tokens** 下生成令牌，并作为 `Authorization: Bearer <token>` 传入。在我们的测试技术栈上，一个 MCP 客户端立即暴露了 47 个工具，并直接对账本运行了 BQL 查询。

![一个 MCP 客户端使用个人访问令牌指向部署自己的地址：47 个工具，以及对账本的一次 BQL 查询。](/img/blog/run-your-own-beancount-io-from-one-button/mcp-client.webp)

### 普通 Git

每个账本都是一个 Git 仓库，位于 `https://<your API address>/git/<owner>/<ledger>.git`（你可以从账本的 **Git Clone** 菜单复制确切 URL）。由于 bex 不路由 SSH，Git 通过 HTTPS 运行——而 `bea` 会为你处理凭据：

```zsh
bea cloud login            # once, if you haven't already
bea cloud git setup        # configures Git to authenticate 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` 不会直接通过 HTTPS 克隆；在没有 SSH 的服务器上，它会为你打印这些命令。）*

![账本的 Git Clone 菜单：API 的 HTTPS 地址，密码为个人访问令牌。](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

#### 不使用 `bea` 的 Git（CI 运行器和脚本）

如果你不想在机器或 CI 运行器上安装 `bea`，可以使用个人访问令牌进行认证——就像 GitHub 一样：

1. **创建令牌。** 前往 **Settings → Personal access tokens → New token**。按其环境命名（`laptop`、`nightly-backup`），选择 `ledger.read` 用于克隆/拉取，如果需要推送则添加 `ledger.write`。对于无人值守的脚本，将其范围限定为单个账本并设置过期日期。立即复制 `bcio_...` 令牌——它只显示一次。

   ![设置、个人访问令牌：一个具有 ledger.read 和 ledger.write 的令牌，其前缀，以及创建时间和最后使用时间。](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

2. **克隆并缓存。** 首次克隆时，输入任意非空字符串作为用户名，并将令牌粘贴为密码。macOS（Keychain）和 Windows（Git Credential Manager）会自动存储它。在 Linux 上，请先启用凭据助手：`git config --global credential.helper store`（以纯文本形式保存在 `~/.git-credentials`）或 `credential.helper 'cache --timeout=86400'`（在内存中保留 24 小时）。

对于脚本和定时备份，通过传入一次性凭据助手，让令牌既不进入远程 URL（从而不会写入 `.git/config`），也不进入你的 shell 历史记录：

```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=` 会阻止本地 Keychain 或 `~/.git-credentials` 缓存该令牌。在脚本中后续的任何 `git fetch` 或 `git push` 都要传入这两个 `-c` 标志。

> **凭据故障排除：** 如果 Git 一直重试旧密码或已撤销的令牌，请用 `printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject` 清除它。基于密码的 Git 认证目前仍然有效，但正在被逐步淘汰。

**迁移现有账本？** 创建一个新账本，将你的文件或 Git 历史合并进去，然后推送。该技术栈以 `main.bean` 作为入口点，因此要么将根文件命名为 `main.bean`，要么用它来 `include` 你现有的文件。

## 什么会离开你的工作区

该技术栈不会向 Beancount.io 发送任何分析或遥测数据，浏览器分析脚本已从构建中完全移除。我们所知的唯一出站请求是：

- **密码泄露检查：** 通过 k-匿名性检查新密码 SHA-1 哈希的前 5 个字符（你的密码和账户均不会暴露）。
- **头像：** 浏览器使用用户电子邮件地址的哈希向 Gravatar 发起请求。
- **订阅源：** 请求 Beancount.io 博客和更新日志订阅源（仅发送语言偏好，不含用户数据）。
- **价格源：** *仅*当你的账本明确包含托管价格 URL 时，才会向 beancount.io 发起请求。
- **你自己的集成：** 发送给你选择加入的服务的数据（LLM 提供商、SendGrid、S3、Plaid 或你的 OIDC 提供商）。

有关每个请求何时触发的确切细节，请参阅[完整隐私表](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private)。

## 谁在运行这些机器

你的服务、磁盘和数据库运行在 bex 的基础设施上，位于你的工作区内，并计入你的账单。完全透明：bex 由 Stargately, Inc. 构建——与 Beancount.io 背后的公司相同——托管受 bex 的[隐私政策](https://bex.co/privacy-policy)和[服务条款](https://bex.co/terms-of-service)约束。托管的 Beancount.io 服务与你的技术栈完全独立，不持有其任何密钥。

更愿意在你直接控制的硬件上运行？我们的 [Docker 部署](https://github.com/bex-co/beancount-io/tree/main/deploy/docker)可在你拥有的任何服务器上运行完全相同的技术栈。

## 须知

- **默认单用户，团队或家庭使用 OIDC。** 创建第一个账户后注册即关闭。要添加其他人，请连接 OpenID Connect 提供商，并在 `OIDC_ALLOWED_EMAILS` 中列出允许的地址（[设置指南](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#more-accounts-your-own-identity-provider)）。2FA 由你的身份提供商处理。
- **按你的时间表更新。** 你的技术栈会固定在你部署的版本，直到你选择同步 Blueprint 并重新部署（[如何更新](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#rolling-out-a-change)）。
- **备份简单直接。** 账本只是 Git 仓库——`git clone --mirror` 即可备份你的全部历史。账户、令牌和设置存放在托管的 Postgres 中，具有持续备份和时间点恢复（[备份指南](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#back-up-and-restore)）。
- **移动应用支持。** 在移动应用的欢迎屏幕上，打开设置，将服务器 URL 指向你的仪表盘地址，然后登录。

如需一站式了解每个步骤，包括更新、备份、密码重置和移除技术栈，请参阅[自托管指南](/docs/self-host-beancount-io)。

遇到问题？提交 [GitHub issue](https://github.com/bex-co/beancount-io/issues) 或加入 [Telegram 聊天](https://t.me/beancount)。
