跳转到主要内容

一键运行你自己的 Beancount.io

发布日期 最后更新 阅读需 3 分钟Mike ThriftMike Thrift
一键运行你自己的 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

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

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

你会得到什么,以及花费多少​

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

服务作用月费用(美元)
DashboardWeb 应用及你使用的唯一公开地址$4.90
APIGraphQL、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 令牌、账本、指令和协作者均无限制。

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

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

安全提示: 在创建第一个账户之前,任何发现你 URL 的人都可以认领它。如果有人抢先一步,你可以使用该技术栈的管理令牌移除该账户,重新开放注册。

新自托管部署上的注册页面。表单旁边,页面说明此副本由其所有者运行,账本以纯文本形式存放在 Git 中。

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

bea CLI​

通过 uv tool install beancount-io 或 brew install bex-co/tap/bea 安装或更新 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

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

bea 0.4.1 连接自托管部署:bea cloud login、Enterprise 套餐上的 bea cloud status,以及 bea cloud ledger list。

编码智能体(MCP)​

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

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 查询。

普通 Git​

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

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 地址,密码为个人访问令牌。

不使用 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 的令牌,其前缀,以及创建时间和最后使用时间。

  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 历史记录:

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 提供商)。

有关每个请求何时触发的确切细节,请参阅完整隐私表。

谁在运行这些机器​

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

更愿意在你直接控制的硬件上运行?我们的 Docker 部署可在你拥有的任何服务器上运行完全相同的技术栈。

须知​

  • 默认单用户,团队或家庭使用 OIDC。 创建第一个账户后注册即关闭。要添加其他人,请连接 OpenID Connect 提供商,并在 OIDC_ALLOWED_EMAILS 中列出允许的地址(设置指南)。2FA 由你的身份提供商处理。
  • 按你的时间表更新。 你的技术栈会固定在你部署的版本,直到你选择同步 Blueprint 并重新部署(如何更新)。
  • 备份简单直接。 账本只是 Git 仓库——git clone --mirror 即可备份你的全部历史。账户、令牌和设置存放在托管的 Postgres 中,具有持续备份和时间点恢复(备份指南)。
  • 移动应用支持。 在移动应用的欢迎屏幕上,打开设置,将服务器 URL 指向你的仪表盘地址,然后登录。

如需一站式了解每个步骤,包括更新、备份、密码重置和移除技术栈,请参阅自托管指南。

遇到问题?提交 GitHub issue 或加入 Telegram 聊天。

来源:https://beancount.io/zh/blog/2026/11/18/run-your-own-beancount-io-from-one-button

发布日期: 2026年11月18日

最后更新: 2026年11月19日