Xpenser - oprn-source personal AI-enabled finance tracker

xpenser

xpenser 是一款开源、可自托管的个人财务追踪工具，适合希望通过仪表盘、类别、商家、报告以及 API/MCP 访问来追踪和分析收入与支出的人士。

它源自个人 Telegram 机器人与 Google Sheets 工作流。该项目仍处于早期阶段，并在持续迭代，但已经足够实用，可供运行、查看、扩展、自托管，或用作 Cleverbrush Framework 参考应用。如果你目前在其他地方追踪或分析支出，欢迎反馈 xpenser 是否可以替代或补充现有方案，以及还需要添加哪些功能。

xpenser 也是一款真实场景参考应用，展示了 Cleverbrush Framework 如何通过一套完整的应用，运用以 schema 为先的 TypeScript 技术栈来构建 API 契约、验证、OpenAPI、类型化客户端、React 表单、支持身份验证的端点、可观测性、Telegram 工作流和 MCP 访问。

为什么选择 xpenser

• 将日常财务追踪迁移到结构化应用中，借助仪表盘、类别、商家、报告和可搜索的交易记录进行管理。
• 按类别追踪收入、支出、退款和退货，并记录备注、日期、商家和货币。
• 查看每日、每周、每月、每季度和每年的汇总，了解类别构成和趋势。
• 使用多种交易货币，并通过 Frankfurter 自动换算为默认货币。
• 扫描交易记录、补充商家数据，并在移动端和桌面端顺畅地完成设置工作流。
• 接收可选的每周和每月电子邮件摘要，其中包含由 OpenAI 生成的支出和收入分析。
• 通过 API 密钥、类型化 Node 客户端、MCP 服务和 Telegram 机器人连接外部工具。

截图

仪表盘月视图	交易记录	电子邮件报告、API 密钥和 MCP

基于 Cleverbrush 构建

xpenser 刻意保持精简，便于查看，同时仍能实践贴近生产环境的框架模式：

• packages/contracts 使用 Cleverbrush schema 定义公共契约。
• apps/api 通过 Cleverbrush 服务处理程序、身份验证元数据、OpenAPI、DI、日志记录、追踪和 MCP 暴露该契约。
• packages/client 为生成的 Cleverbrush 客户端封装重试、超时、去重、批处理、缓存标签和 OpenTelemetry 传播功能。
• packages/ui 将 Cleverbrush schema 字段绑定到可复用的 React 表单控件。

如果你是来了解该应用背后的框架模式，请从 Cleverbrush 参考笔记开始。上游框架文档请参阅：

• Cleverbrush Framework 源码
• Cleverbrush Framework 文档
• Cleverbrush Schema 文档

快速开始

先决条件

• Node.js 24
• npm 11
• Docker 和 Docker Compose v2（docker compose）

1. 安装依赖

npm install

2. 创建本地环境文件

cp .env.example .env

.env.example 中的默认值适用于本地开发，并会将应用指向 localhost:5432 上的 PostgreSQL。

如果部署时不应加载 Google Tag Manager，请设置 DISABLE_GTM=1。

3. 构建共享工作区

应用会从本地程序包构建后的 dist 输出中导入内容，因此启动开发服务器前，请先构建一次共享程序包：

npm run build -w @xpenser/contracts
npm run build -w @xpenser/client
npm run build -w @xpenser/ui

4. 启动 PostgreSQL

docker compose up -d postgres

实用检查：

docker compose ps postgres
docker compose logs postgres

5. 启动应用

npm run dev

API 会在启动时运行数据库迁移。

本地 URL：

• Web 应用：http://localhost:3000
• API：http://localhost:4000
• API 健康检查：http://localhost:4000/health
• OpenAPI JSON：http://localhost:4000/openapi.json

身份验证

无需任何外部身份验证提供方即可使用电子邮件/密码登录。以这种方式 创建的账户必须先确认电子邮件，然后才能登录。

只需要一个用户的可自托管部署可以完全跳过账户身份验证：

XPENSER_SINGLE_USER_MODE=1
[email protected]
WEB_API_SERVICE_SECRET=replace-with-at-least-32-characters

在单用户模式下，Web 应用会直接打开已通过身份验证的应用，为配置的电子邮件 创建或重用所有者账户，隐藏登录、注册和营销页面，并保留 Swagger/OpenAPI。 公共 API 和 MCP 端点仍需要 API 密钥或 OAuth；只有受信任的 Web 服务会绕过 账户登录流程。

Google 登录支持两种模式：

• 面向可自托管部署的直接 Google OAuth。
• 面向托管的 Cleverbrush 部署的 Cleverbrush Passport。

使用 GOOGLE_SIGN_IN_MODE 选择模式：

GOOGLE_SIGN_IN_MODE=auto

auto 会在配置了 AUTH_GOOGLE_ID 和 AUTH_GOOGLE_SECRET 时使用直接 Google OAuth。如果未设置这两个变量，则仅在 配置了所有 Passport 变量时使用 Passport。如果未配置任何身份验证提供方， Google 登录按钮会隐藏，但电子邮件/密码登录仍然可用。

使用 GOOGLE_SIGN_IN_MODE=direct 要求使用直接 Google OAuth， 使用 GOOGLE_SIGN_IN_MODE=passport 要求使用 Passport，或使用 GOOGLE_SIGN_IN_MODE=disabled，即使已提供凭据也隐藏 Google 登录。

直接 Google OAuth

在 Google Cloud Console 中创建 OAuth 2.0 客户端：

• 应用类型：Web 应用
• 已获授权的 JavaScript 来源：你的公共 APP_URL
• 已获授权的重定向 URI：${APP_URL}/authjs/callback/google

使用默认 APP_URL 进行本地开发时，请使用：

http://localhost:3000/authjs/callback/google

使用 Auth.js 标准 Google 变量配置 Web 应用：

APP_URL=https://xpenser.example.com
AUTH_URL=https://xpenser.example.com/authjs
NEXTAUTH_URL=https://xpenser.example.com/authjs
NEXTAUTH_SECRET=replace-with-at-least-32-characters
AUTH_SECRET=replace-with-the-same-value-as-NEXTAUTH_SECRET
GOOGLE_SIGN_IN_MODE=auto
AUTH_GOOGLE_ID=your-google-oauth-client-id
AUTH_GOOGLE_SECRET=your-google-oauth-client-secret

Google 账户必须具有经过验证的电子邮件地址。如果已存在电子邮件地址相同的 本地电子邮件/密码账户，Google 登录会被拒绝，而不会静默关联账户。

Cleverbrush Passport

Passport 是 Cleverbrush 的私有身份验证代理。除非运行自己的兼容 Passport 服务， 否则可自托管部署应使用直接 Google OAuth。

使用以下配置两个服务：

GOOGLE_SIGN_IN_MODE=passport
PASSPORT_BASE_URL=https://auth.cleverbrush.com
PASSPORT_PROJECT=xpenser
PASSPORT_ENVIRONMENT=production
PASSPORT_PUBLIC_KEY=

PASSPORT_PUBLIC_KEY 是可选的。为空时，API 会获取 <PASSPORT_BASE_URL>/.well-known/public-key 并缓存在内存中。如果已设置， 请使用经过 base64 编码的 PEM 公钥。

完整 Docker 运行

如需接近生产环境的本地运行，请构建并启动完整的 Compose 堆栈：

docker compose up --build

这会启动 docker-compose.yml 中定义的容器化 Web 应用、API、PostgreSQL、 Swagger UI 和可观测性服务。

完整 Docker URL：

• Web 应用：http://localhost:3000
• 公共 API 代理：http://localhost:3000/api
• 应用 Swagger UI：http://localhost:3000/api-docs/swagger
• Compose Swagger UI 容器：http://localhost:8090
• SigNoz：http://localhost:8080

对于公共部署，请将反向代理置于 Web 应用前面，并将 APP_URL 设置为公共源。 API 服务在 Docker 网络中保持私有，Next 应用通过 /api 暴露该服务。

对于规模较小的公共部署，请以 docker-compose.prod.yml 为起点，并提供 JWT_SECRET、WEB_API_SERVICE_SECRET 和 TELEGRAM_BOT_SERVICE_SECRET 的 生产环境密钥。常规账户身份验证部署还需要 NEXTAUTH_SECRET 和 AUTH_SECRET；单用户部署可以将它们留空。

可选集成

除非配置相应的提供方凭据，否则默认的 .env.example 会关闭外部集成：

• OpenAI 邮件洞察：设置 OPENAI_API_KEY、OPENAI_REPORT_MODEL、 RESEND_API_KEY、EMAIL_FROM、EMAIL_REPORTS_ENABLED=1 和 EMAIL_REPORTS_SCHEDULER_ENABLED=1。
• Telegram 机器人工作流：设置 TELEGRAM_BOT_TOKEN、TELEGRAM_BOT_USERNAME 和 TELEGRAM_BOT_SERVICE_SECRET。
• 供应商信息补充：设置 BRANDFETCH_API_KEY 或 BRANDFETCH_CLIENT_ID，然后 启用 VENDOR_ENRICHMENT_ENABLED=1。
• Google 登录：按照上文所述配置直接 Google OAuth，或将其关闭并使用电子邮件/密码账户。
• 应用内反馈：将 FEEDBACK_WEBHOOK_URL 设置为 HTTP 或 HTTPS n8n webhook。 此值为空时，经过身份验证的顶部菜单表单会保持隐藏，从而让可自托管部署 可以选择是否启用此集成。

公共 API

在 Settings -> Preferences -> API keys 中创建 API 密钥。此 API 密钥可用作 curl 的 Bearer 令牌，也可与类型化 Node 客户端搭配使用：

curl -X POST "$APP_URL/api/transactions" \
  -H "Authorization: Bearer $XPENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categoryId":1,"amount":12.34,"currency":"USD","effect":"normal","occurredAt":"2026-05-13T12:00:00.000Z"}'

import { createXpenserClient } from '@xpenser/client';

const client = createXpenserClient({
    baseUrl:
        process.env.XPENSER_API_BASE_URL ??
        'http://localhost:3000/api',
    getToken: () => process.env.XPENSER_API_KEY ?? null
});

await client.transactions.create({
    body: {
        categoryId: 1,
        amount: 12.34,
        currency: 'USD',
        effect: 'normal',
        occurredAt: new Date()
    }
});

常规交易可省略 effect，或将其设为 normal。对于支出类别中的退款，或 收入类别中的付款撤销和拒付，请使用 effect: 'reversal'；输入的金额保持为正数，报表 会从相应类别中扣除该金额。

也接受 X-API-Key: $XPENSER_API_KEY。

MCP 服务

xpenser 为 AI Agent 在 /api/mcp 提供 MCP Streamable HTTP 端点。使用 Settings -> Preferences -> API keys 中的同一个 API 密钥作为 Bearer 令牌。MCP 工具可以读取和管理 API 密钥所有者的供应商、类别和交易，因此应将 MCP 访问视为可访问完整账户数据。 请为 MCP 客户端使用专用 API 密钥，并在不再需要访问权限时撤销该密钥：

{
  "mcpServers": {
    "xpenser": {
      "type": "streamable-http",
      "url": "https://xpenser.example.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${XPENSER_API_KEY}"
      }
    }
  }
}

MCP 服务为当前用户、供应商、类别、交易、仪表板摘要和统计信息提供工具。供应商候选项搜索和 信息补充可能会调用已配置的供应商信息补充提供方。

开发命令

npm run lint
npm run typecheck
npm test
npm run test:e2e

数据库辅助命令：

npm run db:run -w @xpenser/api
npm run db:validate -w @xpenser/api
docker compose stop postgres
docker compose down
docker compose down -v

db:validate 为只读操作，用于检查实时数据库架构是否与 Cleverbrush ORM 实体一致。

在 GitHub PR 环境之外运行 e2e 测试套件时，必须设置 PLAYWRIGHT_BASE_URL。

类型化查询集成测试需要一个专用的 PostgreSQL 数据库，名称为 xpenser_queries（切勿将其指向应用数据）：

docker run --name xpenser-query-tests -d -p 127.0.0.1:55437:5432 \
  -e POSTGRES_DB=xpenser_queries -e POSTGRES_USER=xpenser_test \
  -e POSTGRES_PASSWORD=xpenser_test postgres:16-alpine
# Wait until PostgreSQL is ready before running the suite.
docker exec xpenser-query-tests pg_isready -U xpenser_test -d xpenser_queries
QUERY_TEST_DATABASE_URL=postgres://xpenser_test:[email protected]:55437/xpenser_queries \
  npm run test:queries:integration
docker stop xpenser-query-tests

该测试套件会对测试夹具进行类型检查，在随机架构中运行应用迁移，然后仅删除该架构。测试内容包括联接投影、 聚合解码、授权、编号分页、筛选、扫描摘要、预加载排序，以及有界的信息补充查询次数。它还会在合成数据上比较查询 计划；执行时间仅供诊断，并非生产环境基准。该测试套件也会在 PR 的 Lint and test 检查中运行。

它还会验证由 PostgreSQL 支持的收据任务和定期报表计划，包括工作线程恢复、重试限制、原子扫描结果和进度授权。 生命周期、保留策略、交付保证和部署指南，请参阅后台任务。

贡献

欢迎贡献。适合入门的方向包括文档、自托管指南、框架参考说明、UI 润色、API 示例和小型的 产品改进。

• 提交 PR 前请阅读 CONTRIBUTING.md。
• 使用 issue 提交可执行的错误报告和功能请求。
• 使用 GitHub Discussions 进行提问、分享想法和讨论 Cleverbrush 学习内容。
• 修改 API 时，保持 Cleverbrush 合约、端点元数据和处理程序树一致。

项目状态

xpenser 仍处于早期阶段，注重实用性，并会持续迭代。目前尚未获得显著的用户认可；欢迎就产品契合度、README 清晰度、自托管和 MCP 工作流提供反馈。我们的目标是让 xpenser 作为一款个人财务应用持续发挥作用，同时保持足够清晰，帮助开发者了解 Cleverbrush 全栈项目如何协同运作。

xpenser 目前不提供银行同步、预算规划、净资产跟踪、原生移动应用或成熟的数据导入流程。

许可证

xpenser 基于 MIT 许可证发布。