# 在 bex 上一键自托管 Beancount.io

一键即可将整套 Beancount.io 栈——包括 Web 仪表盘、API 与 MCP 服务器、账本服务以及基于 Git 的账本——部署到你自己的 bex 工作区。本指南从点击按钮开始，一路带你走到可用的账本，随后介绍连接工具、添加账户、更新、备份以及移除整套栈。

这套栈采用 MIT 许可证，不受任何套餐限制，托管费用约为每月 33 美元，计入你的工作区。公告详情请阅读[一键运行你自己的 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. **等待首次构建。** 在我们的运行中耗时 27–30 分钟，当 bex 的构建队列繁忙时会更久。某个服务的部署状态标记为失败时不会自动重试；请从 bex 仪表盘重新部署该服务。
3. **认领你的实例。** 打开 `beancount-dashboard` 服务的 URL 并立即注册。过程中没有邮件验证步骤，注册会在首个账户创建后关闭。
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)

自托管栈上的每个账户都享有最高档：账本、指令、协作者和 AI 用量均无限制。

## 运行了哪些服务，费用多少

Blueprint 会在你的工作区中创建六个资源（价格来自 bex 于 2026-11-18 的方案预览）：

| bex 资源 | 作用 | 月费用（美元） |
| --- | --- | --- |
| `beancount-dashboard` | Web 应用，也是你唯一使用的公开地址 | 4.90 |
| `beancount-api` | GraphQL、REST、MCP 服务器和 Git 代理 | 4.90 |
| `beancount-ledger` | 校验和查询你的账本（私有，无公开地址） | 4.90 |
| `beancount-gitea` | 在 10 GB 磁盘上以 Git 仓库形式存储每个账本（私有） | 6.65 |
| `beancount-backend-db` | 用于账户、令牌和设置的 Postgres | 4.41 |
| `beancount-cache` | 用于登录会话和缓存的 Key Value | 7.21 |
| **总计** | | **32.97** |

你连接的模型提供商、邮件服务或 S3 存储桶会另行计费。

## 开启可选功能

这套栈无需任何集成即可启动。需要集成的功能会提示缺少哪个设置。要添加集成，请在 bex 中打开 `beancount-api` 服务，在其 **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 CLI

用 `uv tool install beancount-io` 或 `brew install bex-co/tap/bea` 安装或更新 [`bea`](https://beancount.io/zh/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
```

两个变量都填仪表盘的地址，因为仪表盘会转发 API 流量。[Beancount CLI 参考](https://beancount.io/zh/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
```

在 Claude Code 中用 `/mcp` 登录。同意页面由你自己的实例提供；选择客户端可以使用的账本并批准。对于改为发送请求头的客户端，请创建个人访问令牌（见下文），并以 `Authorization: Bearer <token>` 形式发送。

### 通过 HTTPS 使用 Git

每个账本都是位于 `https://<your API address>/git/<owner>/<ledger>.git` 的 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 菜单：API 的 HTTPS 地址，密码为个人访问令牌。](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### 不使用 bea 的 Git

在 CI 运行器或没有 `bea` 的机器上，用个人访问令牌为 Git 登录：

1. **创建令牌。** 在仪表盘中打开 **Settings → Personal access tokens → New token**。按它的运行位置命名（`laptop`、`nightly-backup`），选择 `ledger.read` 以克隆和拉取，如果要推送则再加上 `ledger.write`。对于无人值守的脚本，请将其限制为一个账本并设置过期时间。现在就复制 `bcio_` 令牌；它只显示一次。
2. **克隆。** Git 会询问用户名和密码：输入任意非空用户名，并将令牌粘贴为密码。macOS 钥匙串和 Windows 上的 Git Credential Manager 会保存它以供下次使用。在 Linux 上，请先启用凭据助手，例如 `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)

在脚本中，不要让令牌进入远程 URL（Git 会将其存入 `.git/config`），也不要进入 shell 历史。通过一次性凭据助手把它交给 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=` 会阻止已存储的助手保存令牌。脚本中后续每次 `git fetch` 或 `git push` 都要传入这两个 `-c` 选项。

如果 Git 一直提供旧密码或已吊销的令牌，请清除它：

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

### 移动应用

在 [iOS](/beancount-ios) 或 [Android](/beancount-android) 应用的欢迎界面上打开设置，将服务器 URL 设为你的仪表盘地址，然后登录。

## 迁移你已有的账本

在仪表盘中创建一个账本，克隆它，将你的文件或 Git 历史合并进去，然后推送。这套栈将 `main.bean` 作为账本的入口文件，因此请将根文件命名为 `main.bean`，或用 `main.bean` 来 `include` 你已有的文件。

## 添加更多账户

首个账户创建后注册保持关闭。更多人通过你连接的 OpenID Connect 提供商加入，该提供商也负责他们的双因素登录。在 `beancount-api` 服务的 **Environment** 标签页上：

1. 设置 `OIDC_ISSUER`、`OIDC_CLIENT_ID` 和 `OIDC_CLIENT_SECRET`，并注册 `https://<your dashboard address>/api-gateway/auth/oidc/callback` 作为客户端的重定向 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 为其签发一次性重置链接。从 `beancount-api` 服务的 **Environment** 标签页复制 `ADMIN_TOKEN`，并调用该服务自己的 `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` 保护。该令牌能以任何用户身份登录，因此请像对待 root 密码一样对待它：不要让它进入 shell 历史和聊天记录，如果可能已泄露请轮换它。
:::

## 更新到新版本

这套栈会一直停留在你部署的版本，直到你更新它。通过按钮创建的 Blueprint 不会获得推送 webhook，因此更新需要两步：

1. **同步 Blueprint**，以将其设置变更应用上去（bex API：`POST /v1/blueprints/<id>/sync`）。
2. **将每个服务部署到新提交**，因为代码变更需要构建（`POST /v1/services/<id>/deploys`，带 `commitId`）。

bex 一次只构建一个服务，且 API 最后构建，所以一次完整发布可能需要将近一个小时。在将更新的 Blueprint 同步到已有数据的栈之前，请阅读[升级已在运行的栈](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running)，并先做好备份。

## 备份与恢复

账本是 Gitea 磁盘上的 Git 仓库。账户、个人访问令牌和设置位于托管的 Postgres 中。请分别备份它们。

### 账本

镜像克隆是账本文件和历史的完整备份：

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

在一台已运行过 `bea cloud git setup` 的机器上执行它，或使用上文“不使用 bea 的 Git”一节中的令牌助手。要恢复，请先在仪表盘中删除仍在列出的该账本，并创建一个同名账本。服务器会拒绝向账本主分支强制推送，因此请将备份合并到新账本的第一个提交之上，在不使用 `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. 使用 PostgreSQL 16 的 `pg_dump` 和 `pg_restore` 复制数据回来（`postgres:16` Docker 镜像两者都有）。两端都使用 `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` 扩展；这些错误是预期内的。如果副本的证书仍在签发中，请在 `COPY_URL` 后加上 `?sslmode=verify-full`，并将 bex 为副本显示的 CA 保存为 `~/.postgresql/root.crt`。如果连接超时，请重试。
4. 恢复 `beancount-gitea` 和 `beancount-api`，然后删除副本。

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

这套栈不会向 Beancount.io 发送任何分析或遥测数据，浏览器分析脚本也不会被打包进构建中。我们已知的唯一对外请求有：

- **密码泄露检查：** 新密码 SHA-1 哈希的前五个字符，通过 k-匿名机制检查，因此密码和账户都不会泄露。
- **头像：** 浏览器根据用户邮箱地址的哈希向 Gravatar 请求图片。
- **订阅源：** Beancount.io 博客和更新日志的订阅源，仅接收语言偏好。
- **价格源：** 仅当账本包含托管价格 URL 时才请求 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 的基础设施上，受 bex 的[隐私政策](https://bex.co/privacy-policy)和[服务条款](https://bex.co/terms-of-service)约束。bex 由 Beancount.io 背后的公司 Stargately, Inc. 构建；托管的 Beancount.io 服务与你的这套栈相互独立，不持有它的任何密钥。

## 移除这套栈

:::warning
删除资源会停止计费，同时也会一并删除你的数据。请先克隆每个账本。
:::

按上述方式备份，然后在 bex 中删除六个资源，再删除 Blueprint。若只想移除你自己的账户并保留这套栈，请在 **Settings → General → Danger Zone** 下删除它，与[托管服务](https://beancount.io/zh/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 Telegram 群](https://t.me/beancount)中提问。
