Kresus (夜间构建版) Docker 镜像文档

镜像概述和主要用途

概述

Kresus 是一款开源、自托管的个人财务管理工具，专注于隐私保护与数据自主掌控。本镜像为 Kresus 的夜间构建版本（Nightly Build），包含最新开发阶段的功能特性，适用于希望体验前沿功能的用户。作为自由软件（GPL 许可），其核心设计目标是让用户安全管理财务数据，避免依赖第三方云服务。

主要用途

跟踪多账户银行交易历史记录
实时查看总余额及各账户收支情况
通过标签对支出进行分类与分析
自主管理财务数据，确保隐私与数据安全

核心功能和特性

核心功能

银行交易跟踪：自动或手动导入银行交易记录，支持历史数据回溯与实时更新
余额汇总：直观展示所有关联账户的总余额及明细
支出标签分类：通过自定义标签对交易进行分类，快速识别消费***惯（如“餐饮”“交通”“娱乐”等）
数据本地化存储：自托管模式下，所有财务数据存储在用户自有服务器，避免第三方数据泄露风险

特性

开源自由：源代码完全开放，支持用户审计与二次开发
跨平台兼容：基于 Web 技术构建，支持主流浏览器访问
轻量化部署：通过 Docker 容器化部署，简化环境配置
夜间构建特性：包含最新开发功能（如实验性银行接口适配、UI 优化等），适合功能测试

使用场景和适用范围

适用场景

个人财务管理：用户独立管理日常收支、跟踪储蓄目标
隐私敏感用户：拒绝将财务数据上传至第三方云服务，需本地化存储的场景
多账户管理者：需集中查看银行、、电子等多账户资金状况的用户
开发者测试：开发人员验证新功能兼容性或贡献代码时的测试环境

适用范围

个人用户（主要目标群体）
小型家庭或团队（共享财务管理需求）
技术爱好者（熟悉 Docker 及自托管部署的用户）

使用方法和配置说明

前提条件

已安装 Docker Engine（20.10+ 版本推荐）
已安装 Docker Compose（可选，用于多容器部署）
服务器需开放 HTTP 端口（默认 3000，可自定义）

Docker 快速启动（`docker run`）

通过以下命令快速启动 Kresus 夜间构建容器，数据将持久化至本地目录：

bash
docker run -d \
  --name kresus-nightly \
  -p 3000:3000 \  # 端口映射（主机端口:容器端口）
  -v /path/to/local/data:/app/data \  # 数据持久化（替换为本地实际路径）
  -e NODE_ENV=development \  # 夜间构建推荐使用开发环境模式
  -e KRESUS_LOG_LEVEL=info \  # 日志级别（可选：debug/info/warn/error）
  kresus/nightly:latest  # 镜像名称（需确认实际镜像标签）

启动后，通过 http://<主机IP>:3000 访问 Kresus 界面，首次使用需完成初始化配置（如创建管理员账户、添加银行账户等）。

Docker Compose 部署

创建 docker-compose.yml 文件，配置如下（支持更复杂的环境变量与依赖管理）：

yaml
version: '3.8'
services:
  kresus:
    image: kresus/nightly:latest
    container_name: kresus-nightly
    restart: unless-stopped  # 容器异常退出后自动重启
    ports:
      - "3000:3000"  # 自定义主机端口可修改左侧值（如 "8080:3000"）
    volumes:
      - /path/to/local/data:/app/data  # 替换为本地数据目录，确保读写权限
    environment:
      - NODE_ENV=development  # 夜间构建环境标识
      - KRESUS_PORT=3000  # 容器内服务端口（默认 3000，与容器端口映射一致）
      - KRESUS_DATA_DIR=/app/data  # 容器内数据存储路径（需与 volumes 挂载路径对应）
      - LOG_LEVEL=info  # 日志输出级别
    networks:
      - kresus-net  # 自定义网络（可选，用于隔离容器网络）

networks:
  kresus-net:
    driver: bridge

启动命令：

bash
docker-compose up -d

配置参数与环境变量

参数/环境变量	说明	默认值
`-p <host>:3000`	端口映射，主机端口需开放防火墙规则	无（需手动指定）
`-v /local:/app/data`	数据持久化目录，存储用户配置、交易记录等核心数据	无（需手动挂载）
`NODE_ENV`	运行环境标识，夜间构建推荐设为 `development`	`production`
`KRESUS_PORT`	容器内服务监听端口，需与 `-p` 映射的容器端口一致	3000
`KRESUS_DATA_DIR`	容器内数据存储路径，需与 `-v` 挂载的容器路径一致	`/app/data`
`LOG_LEVEL`	日志输出级别：`debug`（详细调试）、`info`（常规信息）、`warn`（警告）、`error`（错误）	`info`

注意事项

夜间构建特性：本镜像为开发阶段产物，可能包含未稳定功能或兼容性问题，不建议用于生产环境核心财务数据管理，推荐测试或非关键场景使用。
数据备份：定期备份 -v 挂载的本地数据目录，避免容器故障导致数据丢失。
安全配置：生产环境使用时，建议通过反向代理（如 Nginx）启用 HTTPS，避免明文传输财务数据。
更新策略：夜间构建版本需定期拉取最新镜像以获取功能更新，更新前建议备份数据。
依赖说明：默认使用 SQLite 数据库（轻量嵌入式），如需高并发或多用户场景，可通过环境变量配置 PostgreSQL 等外部数据库（参考 Kresus ***文档）。