自托管
本文说明如何在自有服务器上使用 Docker Compose 部署 Beancount-Trans，使数据与运行环境完全由您掌控。适合熟悉 Linux 与 Docker 的读者。
Compose 架构一览
主栈使用预构建镜像 dhr2333/beancount-trans-frontend:latest、dhr2333/beancount-trans-backend:latest，由下列服务组成：
| 服务 | 镜像要点 | 作用 |
|---|---|---|
beancount-trans-frontend | 前端 Nginx | 对外映射 38001→80；静态前端根路径 /；将 /admin、/api 反代至后端（与前端仓库 conf/nginx.conf 一致） |
beancount-trans-backend | 后端 Django | 启动时执行 migrate 与 docker_start.sh；挂载 ./Beancount-Trans-Backend/Assets 与命名卷 collectstatic（与前端共享 Django 静态资源） |
worker | 同后端镜像 | Celery Worker：账单解析等异步任务 |
beancount-trans-beat | 同后端镜像 | Celery Beat：定时任务（如过期解析确认、Fava 容器清理等），调度器为 django_celery_beat.schedulers:DatabaseScheduler |
beancount-trans-postgres | postgres:18.3-alpine | 数据库；宿主机 65432→5432 |
beancount-trans-redis | redis:8.6.1-alpine | 缓存与 Celery broker；requirepass 由 .env 中 TRANS_REDIS_PASSWORD 提供；默认不映射宿主机端口 |
beancount-trans-minio | minio/minio | 对象存储；39000（S3 API）、39001（控制台） |
beancount-trans-minio-init | minio/mc | 一次性初始化：创建存储桶后退出 |
beancount-trans-fava-admin | dhr2333/beancount-trans-assets:latest | 静态 Fava 示例（admin）；多用户时的增删改见 「新增用户」 |
先决条件
| 项目 | 要求 | 检查命令 |
|---|---|---|
| 操作系统 | 建议使用主流 Linux 发行版 | cat /etc/os-release |
| Docker | Docker Engine ≥ 20.10 | docker --version |
| Docker Compose | Compose 插件 v2+ | docker compose version |
| 硬件 | 建议 ≥ 2 核 CPU、4GB 内存、20GB 磁盘（含镜像与数据卷） | free -h、df -h |
| 网络 | 可拉取镜像；对外访问需放行端口（默认 Web 38001 等） | — |
未安装 Docker？
请优先按 Docker 官方文档安装（不同发行版步骤不同）：
安装后执行：
docker --version
docker compose version
最短路径：启动一套可访问的环境
1. 获取代码与子模块
主仓库通过子模块挂载后端资源目录（Compose 中的 ./Beancount-Trans-Backend/Assets）。至少初始化后端子模块，否则宿主机目录不完整：
git clone https://github.com/dhr2333/Beancount-Trans.git
cd Beancount-Trans
git submodule update --init Beancount-Trans-Backend
若您需要完整开发目录，可改为：
git submodule update --init --recursive
2. 下载预训练模型
当前目录为仓库根目录（含
docker-compose.yaml）。预置镜像不含权重，需本机拉取到固定路径。
git clone https://huggingface.co/google-bert/bert-base-chinese ./Beancount-Trans-Backend/pretrained_models/bert-base-chinese
3. 准备环境变量文件
Compose 使用根目录下的 .env：
cp .env.example .env
自托管部署可暂用示例值，但建议继续阅读 「生产与安全」 章节，修改密钥与访问控制。
4. 启动服务
在仓库根目录（存在 docker-compose.yaml 的目录）执行：
docker compose up -d
首次启动会拉取镜像并创建命名数据卷（PostgreSQL、Redis、MinIO 等），数据默认持久保存在 Docker 卷中。
5. 初始化
请在首次部署（或 docker compose down -v 清库后）手动初始化：
docker compose exec beancount-trans-backend python manage.py init_official_templates
若执行
docker compose down -v会删除卷内数据，请谨慎使用-v。
6. 访问
将 your-server-ip 换为服务器 IP 或域名：
- Web 应用：
http://your-server-ip:38001 - 后台管理：
http://your-server-ip:38001/admin - API 文档：
http://your-server-ip:38001/api/docs
默认登录账户：用户名 admin，密码 123456（生产环境首次登录后建议立即修改密码）。
生产与安全
修改 .env 中的敏感项
务必替换或强化至少以下项。完整 环境变量 见 参考。
DJANGO_SECRET_KEY：随机长字符串（示例中有生成命令）。DJANGO_DEBUG=False：关闭调试；并按注释配置DJANGO_ALLOWED_HOSTS、CSRF_TRUSTED_ORIGINS、CORS_ALLOWED_ORIGINS，以便从域名或其它设备访问。TRANS_POSTGRESQL_PASSWORD、TRANS_REDIS_PASSWORD、MINIO_ACCESS_KEY、MINIO_SECRET_KEY：不要使用默认弱口令。
自托管无短信时的登录策略
.env.example 建议：将 PHONE_BINDING_REQUIRED=False、SMS_ENABLED=False，以便使用用户名/邮箱与密码登录；验证码邮件可配置 SMTP，不配置时验证码会输出到后端日志（见 .env.example 中邮箱一节）。
数据保存在哪里
- 数据库 / Redis / MinIO：由 Compose 中定义的 命名卷 持久化（卷名以
beancount-trans-为前缀，见docker-compose.yaml底部volumes）。 - 用户解析产物与账本文件：宿主机目录
./Beancount-Trans-Backend/Assets（与容器内 Django 资源路径一致），请纳入备份策略。
新增用户
自托管默认只有 admin。需多人共用时，在 Django 管理后台 创建普通用户即可：
- 浏览器打开
http://your-server-ip:38001/admin，使用admin或您已有的超级用户登录。 - 进入 用户（Users） → 增加用户，设置用户名与密码。
若需要再增加一名超级用户（可登录 /admin），可在宿主机执行：
docker compose exec beancount-trans-backend python manage.py createsuperuser
新用户若要在平台内打开 Fava 账本报表，在建户后还须完成下面几步：
- 编辑
docker-compose.yaml：复制现有 Fava 服务块（可参考beancount-trans-fava-admin），将admin改为新用户的用户名，并修改container_name、ports、volumes，使挂载为./Beancount-Trans-Backend/Assets/<用户名>:/Assets。 - 编辑
.env：在FAVA_STATIC_USER_MAP中增加一项，键与后端解析一致（一般为 用户名；存在 Git 时也可能用repo_name），值为浏览器能打开的完整 URL（如http://宿主机IP:5002）。
接入 AI 客户端（MCP）
平台内置 MCP 服务，把当前用户的账本以只读方式提供给 Claude Code、Cursor 等支持 MCP 的 AI 客户端。本节只讲部署与配置，客户端侧的操作步骤与可用能力见 接入 AI 客户端。
服务与路由
- Compose 中的
beancount-trans-mcp与后端共用同一镜像，以第二个进程监听容器内 8001，端点路径为/mcp（Streamable HTTP，单 JSON 响应、无会话）。 - 前端 Nginx 已把
/mcp及 OAuth 相关路径（/.well-known/*、/authorize、/token等）反代到 MCP 服务与后端，因此对外仍只需暴露 38001 一个端口。
环境变量
.env 中至少配置以下项（完整说明见 .env.example 的「MCP 服务（AI 客户端接入）」一节）：
MCP_RESOURCE_SERVER_URL=http://your-domain.com:38001/mcp
MCP_ISSUER_URL=http://your-domain.com:38001
MCP_ALLOWED_HOSTS=your-domain.com:38001
MCP_ALLOWED_ORIGINS=http://your-domain.com:38001
未配置 MCP_RESOURCE_SERVER_URL 时服务不校验访问令牌（仅适合本地调试），生产必须配置。MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS 需包含客户端实际访问的域名与端口，否则请求会因 Host 校验失败返回 400。客户端使用自定义回调 scheme（如 Cursor）时，还需在 MCP_OAUTH_REDIRECT_URI_SCHEMES 中追加该 scheme。
客户端接入
平台侧配置完成后，在客户端中把端点地址填为 http://your-domain.com:38001/mcp，并附上访问令牌即可。令牌的两种取得方式（个人访问令牌 / OAuth 2.1）与完整配置步骤见 接入 AI 客户端。
常用运维命令
# 停止（不删除卷）
docker compose down
# 后台启动
docker compose up -d
# 首次部署（或 down -v 后）手动初始化
docker compose exec beancount-trans-backend python manage.py init_official_templates
# 重启某一服务
docker compose restart beancount-trans-backend
# 查看日志
docker compose logs -f
docker compose logs -f beancount-trans-backend
故障排除
容器反复重启或无法连接数据库
查看后端与数据库日志：docker compose logs beancount-trans-backend。常见原因包括 .env 中数据库主机名/密码与 Postgres 服务不一致、卷权限异常等。
复用自有 PostgreSQL
- 在自有实例上创建
beancount-trans空库。 .env：TRANS_POSTGRESQL_HOST、TRANS_POSTGRESQL_PORT、TRANS_POSTGRESQL_DATABASE、TRANS_POSTGRESQL_USER、TRANS_POSTGRESQL_PASSWORD指向该实例（HOST须为容器内可解析且可连通的地址）。docker-compose.yaml：删除或注释beancount-trans-postgres；在beancount-trans-backend、worker、beancount-trans-beat上移除对beancount-trans-postgres的depends_on。docker compose up -d重启栈；首次启动仍会执行migrate建表。
部署流程一览
下一步
- HTTP API（线上）：Beancount-Trans API；自托管：
http://<主机>:38001/api/docs/（端口随映射而定）。 - 源码与问题反馈：Beancount-Trans 主仓库及 Issues。
- 环境变量说明：请参考 参考 章节。