TaxHacker：自托管 AI 会计应用完全指南

§1 学习目标

完成本文档后，你将能够：

• ✅ 理解 TaxHacker 的定位与设计理念
• ✅ 掌握 TaxHacker 的核心功能与使用方法
• ✅ 部署和配置 TaxHacker 自托管实例
• ✅ 配置 AI 提供商（OpenAI/Gemini/Mistral）
• ✅ 自定义分类、项目和字段
• ✅ 导出税务报告和数据
• ✅ 进行本地开发

§2 项目概述

2.1 什么是 TaxHacker？

TaxHacker（GitHub 仓库）是一款自托管的 AI 会计应用，专为自由职业者、独立开发者（indie hackers）和小型企业设计，利用现代 AI 技术自动化费用和收入跟踪。

官方描述：

TaxHacker is a self-hosted accounting app designed for freelancers, indie hackers, and small businesses who want to save time and automate expense and income tracking using the power of modern AI.

官网：taxhacker.app

2.2 核心数据

2.3 主要贡献者

2.4 项目定位

TaxHacker 解决的核心问题：

§3 核心功能详解

3.1 AI 文档分析

功能：拍摄收据照片或上传发票 PDF，TaxHacker 自动识别、提取、分类和存储所有信息到结构化数据库。

能力：

支持的 AI 提供商：

支持的文档类型：

• 商店收据
• 餐厅账单
• 发票
• 银行对账单
• 信函
• 手写收据（任何语言、任何货币）

3.2 多货币支持

功能：自动检测文档中的货币并使用历史汇率转换为你的基础货币。

能力：

支持的加密货币：

BTC, ETH, LTC, DOT, 以及其他 10 种主流加密货币。

3.3 可定制分类、项目和字段

功能：创建自定义字段、项目和类别以适应你的特定需求、行业标准或国家要求。

能力：

3.4 自定义 LLM 提示

功能：完全控制 TaxHacker AI 处理文档的方式。为字段、类别和项目编写自定义 AI 提示，或修改内置提示以匹配你的特定需求。

能力：

TaxHacker 100% 可适应和调整以满足你的独特要求——无论是需要从文档中提取电子邮件、地址、项目代码还是任何其他自定义信息。

3.5 数据过滤和导出

功能：处理文档后，轻松以你需要的方式查看、过滤和导出完整的交易历史。

能力：

3.6 自托管模式

功能：通过本地存储和自托管选项保持对财务数据的完全控制。TaxHacker 尊重你的隐私并让你完全拥有你的信息。

能力：

§4 部署与自托管

4.1 Docker 一键部署

curl -O https://raw.githubusercontent.com/vas3k/TaxHacker/main/docker-compose.yml
docker compose up

Docker Compose 包含：

• TaxHacker 应用容器
• PostgreSQL 17 数据库（或连接到现有数据库）
• 启动时自动数据库迁移
• 持久数据存储的卷挂载
• 生产就绪配置

4.2 环境变量配置

4.3 LLM 提供商配置

OpenAI：

OPENAI_MODEL_NAME=gpt-4
OPENAI_API_KEY=your-api-key

Google Gemini：

GOOGLE_MODEL_NAME=gemini-pro
GOOGLE_API_KEY=your-api-key

Mistral：

MISTRAL_MODEL_NAME=mistral-large
MISTRAL_API_KEY=your-api-key

4.4 自定义 Docker 配置

services:
  app:
    image: ghcr.io/vas3k/taxhacker:latest
    ports:
      - "7331:7331"
    environment:
      - SELF_HOSTED_MODE=true
      - UPLOAD_PATH=/app/data/uploads
      - DATABASE_URL=postgresql://postgres:postgres@localhost:5432/taxhacker
    volumes:
      - ./data:/app/data
    restart: unless-stopped

§5 本地开发

5.1 技术栈

5.2 开发环境设置

# 克隆仓库
git clone https://github.com/vas3k/TaxHacker.git
cd TaxHacker

# 安装依赖
npm install

# 设置环境变量
cp .env.example .env
# 编辑 .env 配置
# 确保设置 DATABASE_URL 为 PostgreSQL 连接字符串
# 示例: postgresql://user@localhost:5432/taxhacker

# 初始化数据库
npx prisma generate && npx prisma migrate dev

# 启动开发服务器
npm run dev

访问 http://localhost:7331 查看本地 TaxHacker 实例。

5.3 生产构建

# 构建应用
npm run build

# 启动生产服务器
npm run start

§6 使用指南

6.1 上传和处理文档

1. 上传文档：拍摄收据照片或上传发票 PDF
2. AI 分析：TaxHacker 自动识别和提取数据
3. 分类整理：交易自动分类或手动调整
4. 存储检索：所有内容保存在结构化数据库中

6.2 管理交易

6.3 导出数据

1. 应用过滤：使用日期、类别、项目等过滤
2. 选择格式：CSV 导出
3. 生成报告：创建税务报告
4. 下载存档：完整数据迁移

§7 自定义配置

7.1 创建自定义字段

1. 进入设置 → 自定义字段
2. 点击"添加字段"
3. 填写字段名称和描述
4. 编写 AI 提取提示词
5. 保存并应用到未来文档

7.2 创建自定义类别

1. 进入设置 → 类别
2. 点击"添加类别"
3. 填写类别名称和图标
4. 设置分类规则（可选）
5. 保存

7.3 编写自定义提示词

你是一个专业的发票数据提取助手。请从以下文档中提取：
- 供应商名称
- 交易日期
- 总金额（含税）
- 税额
- 明细项目

如果某字段不存在，请返回 null。

§8 安全与隐私

8.1 数据安全

8.2 自托管优势

§9 故障排除

9.1 常见问题

9.2 日志查看

# Docker 日志
docker compose logs -f app

# 数据库日志
docker compose logs -f db

§10 贡献与支持

10.1 贡献方式

10.2 支持项目

如果你觉得 TaxHacker 对你有帮助，考虑支持它的持续发展！

§11 常见问题

Q1：TaxHacker 支持哪些语言？

支持任何语言的文档，包括收据、发票和手写内容。

Q2：支持哪些货币？

支持 170+ 世界货币和 14 种流行加密货币（BTC, ETH, LTC, DOT 等）。

Q3：可以自托管吗？

可以。通过 Docker Compose 可以轻松自托管在你自己基础设施上。

Q4：数据存储在哪里？

默认存储在本地 PostgreSQL 数据库中，完全由你控制。

Q5：支持哪些 AI 提供商？

目前支持 OpenAI、Google Gemini 和 Mistral。本地 LLM 支持即将推出。

Q6：如何导出数据？

支持 CSV 导出，包含所有附加文档，可以生成税务准备报告。

§12 总结

12.1 核心优势

12.2 适用场景

12.3 项目信息

12.4 相关链接

文档版本 1.0 | 撰写日期：2026-04-01 | 基于 TaxHacker (3.6k Stars, MIT)