Kresus 0.26.0 配置参数详解

Kresus 0.26.0 的 config.ini 逐参数详解:create:config 生成母本、apply-config 启动回显查生效值、修改-重启-验证全流程实测,六节 28 参数默认值与环境变量映射总览、生产配置模板与常见问题,全部回显逐行实测。

KresusKresus财务记账自托管2026/10/24

Kresus 0.26.0 配置参数详解

目标:逐参数讲透 Kresus 0.26.0 的 config.ini 配置体系——每个参数的取值、默认值、对应环境变量覆盖与实测生效回显,并给出可直接落地的生产配置模板。已在 Ubuntu 22.04.4 LTS + Docker 29.8.1 环境(官方制品 bnjbvr/kresus:0.26.0)实测通过,Woob 3.7、PostgreSQL 16、Node.js v24.22.1,Kresus 运行版本 0.26.0。

一、环境信息

  • 操作系统:Ubuntu 22.04.4 LTS(内核 6.8.0-138-generic,x86_64)
  • Docker:29.8.1;Docker Compose:v5.5.1
  • Kresus:0.26.0(官方制品 bnjbvr/kresus:0.26.0,构建于 2026-10-22)
  • 数据库:PostgreSQL 16;银行同步引擎:Woob 3.7(Python 3.11.2)
  • 配置文件实测路径:运行环境内 /opt/config.ini(由 Compose 挂载),宿主机侧 /opt/kresus/config.ini
  • 部署编排:kresus-0.26.0-stack(Compose 部署过程与回显见《Kresus 0.26.0 Docker Compose 部署指南》,站内 slug nKPwZskR9Fag)

二、前置条件

确认运行环境可用(本篇所有实测均基于该状态):

# 1. 两服务均为运行状态(postgres healthy、kresus up)
docker compose ps

实测回显:

NAME                IMAGE                   COMMAND                  SERVICE    CREATED          STATUS                    PORTS
kresus-0.26.0-app   bnjbvr/kresus:0.26.0    "/entrypoint.sh '/ho…"   kresus     14 minutes ago   Up 13 minutes             0.0.0.0:8146->9876/tcp, [::]:8146->9876/tcp
kresus-0.26.0-db    postgres:16-alpine      "docker-entrypoint.s…"   postgres   14 minutes ago   Up 14 minutes (healthy)   5432/tcp
# 2. Web 服务可访问
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8146/

实测回显:

HTTP 200

配置文件的查找逻辑:Kresus 启动时按 --config 参数指定的路径读取配置;未指定时在生产模式(NODE_ENV=production)下要求显式提供配置文件路径,否则拒绝启动。官方制品的启动命令为 kresus --config /opt/config.ini(入口脚本固定形态),因此本篇实测对象即 /opt/config.ini。

三、参数查看与修改方式

Kresus 配置有三个关键入口,本节全部实测:

3.1 生成最新配置母本:kresus create:config

官方管理文档给出的标准生成方式(输出到 stdout,重定向保存):

# 裸装形态(官方文档原文)
./bin/kresus.js 'create:config' > config.ini

# Docker 形态(本文实测,二进制位于 /home/user/app/bin/kresus)
docker exec kresus-0.26.0-app /home/user/app/bin/kresus create:config > config.ini

实测生成文件为 289 行,含全部六节([kresus]/[woob]/[email]/[notifications]/[logs]/[db])共 28 个参数,每个参数带官方注释(默认值与环境变量覆盖说明)。本篇第四、五章的参数清单即以此母本为基准逐条核对。

3.2 查看生效值:启动日志 apply-config 段

Kresus 每次启动都会把实际生效的全部参数打印到日志([INFO] apply-config 标记)——这是排查「配置没生效」的第一入口。实测回显(首启时全量,首尾完整保留):

[2026-10-23T18:01:52.546] [INFO] apply-config - Running Kresus 0.26.0 with the following parameters:
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DIR = /home/user/data
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_USER_ID = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_USER_LOGIN_HTTP_HEADER = null
[2026-10-23T18:01:52.546] [INFO] apply-config - PORT = 9876
[2026-10-23T18:01:52.546] [INFO] apply-config - HOST = 0.0.0.0
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_SERVER_TIMEOUT = 300
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_PYTHON_EXEC = python3
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_URL_PREFIX =
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_SALT = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_FORCE_DEMO_MODE = false
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_AUTH = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_WOOB_DIR = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_WOOB_SOURCES_LIST = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_TRANSPORT = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_SENDMAIL_BIN = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_FROM = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_HOST = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_PORT = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_USER = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_PASSWORD = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_FORCE_TLS = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_EMAIL_REJECT_UNAUTHORIZED_TLS = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_APPRISE_API_BASE_URL = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_LOG_FILE = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DB_TYPE = postgres
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DB_LOG = error
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DB_SQLITE_PATH = null
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DB_HOST = postgres
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DB_PORT = 5432
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DB_USERNAME = kresus
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DB_PASSWORD = (hidden)
[2026-10-23T18:01:52.546] [INFO] apply-config - KRESUS_DB_NAME = kresus

💡 说明:日志中值为 null 表示该参数未设置(走内置默认);敏感参数密码回显为 (hidden),日志安全。注意 HOST = 0.0.0.0 与 KRESUS_DIR = /home/user/data 并非来自 config.ini,而是官方制品的内置环境变量默认值——这正是第六章「环境变量优先级」的实证。

3.3 修改并验证:改 config.ini → 重启 → 复查回显

以 server_timeout(内置 HTTP 服务超时秒数,默认 300)为例做完整实测闭环:

# 1. 修改参数(300 → 600)
sed -i 's/^server_timeout=300$/server_timeout=600/' /opt/kresus/config.ini
grep -n 'server_timeout' /opt/kresus/config.ini

实测回显:

13:server_timeout=600
# 2. 重启应用(INI 仅在启动时读取,必须重启生效)
docker compose restart kresus

实测回显:

 Container kresus-0.26.0-app  Stopping
 Container kresus-0.26.0-app  Started
# 3. 复查生效值与 HTTP 状态
docker logs kresus-0.26.0-app --since 6m 2>&1 | grep -E 'SERVER_TIMEOUT|Running Kresus'
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8146/

实测回显:

[2026-10-23T18:15:28.134] [INFO] apply-config - Running Kresus 0.26.0 with the following parameters:
[2026-10-23T18:15:28.135] [INFO] apply-config - KRESUS_SERVER_TIMEOUT = 600
HTTP 200

server_timeout=600 已生效且服务正常。验证后已将演示配置回滚为默认 300。

四、参数总览

config.ini 共六节 28 个参数(与 create:config 母本逐一对应),速查表如下:

节参数默认值环境变量覆盖作用
kresusdatadir$HOME/.kresusKRESUS_DIR数据目录
kresususerid自动生成KRESUS_USER_ID绑定用户 ID
kresususer_login_http_header空KRESUS_USER_LOGIN_HTTP_HEADER反代预认证登录头
kresusport9876PORT监听端口
kresushost127.0.0.1HOST监听地址
kresusserver_timeout300KRESUS_SERVER_TIMEOUT内置 HTTP 服务超时秒数
kresuspython_execpython3KRESUS_PYTHON_EXECWoob 调用的 Python 解释器
kresusurl_prefix空KRESUS_URL_PREFIX子路径部署前缀
kresussalt空KRESUS_SALT导出内容加解密盐值
kresusforce_demo_modefalseKRESUS_FORCE_DEMO_MODE强制演示模式
kresusauth空KRESUS_AUTH应用层 HTTP Basic Auth
woobsrcdir空(系统 Python 环境)KRESUS_WOOB_DIRWoob 核心目录
woobsources_list空(自动生成)KRESUS_WOOB_SOURCES_LIST模块源列表文件路径
emailtransport空(不发邮件)KRESUS_EMAIL_TRANSPORT邮件通道(sendmail/smtp)
emailsendmail_bin系统默认KRESUS_EMAIL_SENDMAIL_BINsendmail 可执行文件路径
emailfrom空KRESUS_EMAIL_FROM发件人地址
emailhost空KRESUS_EMAIL_HOSTSMTP 服务器地址
emailport空KRESUS_EMAIL_PORTSMTP 端口(25/587/465)
emailuser匿名KRESUS_EMAIL_USERSMTP 认证用户名
emailpassword空KRESUS_EMAIL_PASSWORDSMTP 认证密码
emailforce_tlsfalseKRESUS_EMAIL_FORCE_TLS强制 TLS
emailreject_unauthorized_tlstrueKRESUS_EMAIL_REJECT_UNAUTHORIZED_TLS拒绝自签证书
notificationsappriseApiBaseUrl空KRESUS_APPRISE_API_BASE_URLApprise-API 服务地址
logslog_filedatadir/kresus.logKRESUS_LOG_FILE日志文件路径
dbtype空(必填)KRESUS_DB_TYPE数据库类型(postgres/sqlite)
dblogerrorKRESUS_DB_LOGSQL 日志级别
dbsqlite_path空KRESUS_DB_SQLITE_PATHSQLite 数据库文件路径
dbhostlocalhostKRESUS_DB_HOST数据库主机/Unix 套接字目录
dbport5432KRESUS_DB_PORT数据库端口
dbusername空KRESUS_DB_USERNAME数据库用户名
dbpassword空KRESUS_DB_PASSWORD数据库密码
dbnamekresusKRESUS_DB_NAME数据库名

💡 说明:上表「默认值」一列取自官方母本注释(; Can be removed; defaults to ... 行);「环境变量覆盖」一列取自母本注释(; Overridden by the ... 行),并经启动日志回显核对(3.2 节,如 PORT/HOST/KRESUS_DB_PORT 等实测值与表中一致)。

五、核心参数分类详解

以下按节逐参数详解,全部结合官方母本说明与本文实测环境回显。

5.1 [kresus] 节:核心行为(11 项)

datadir(默认 $HOME/.kresus,覆盖变量 KRESUS_DIR) Kresus 存放附加数据的目录(银行抓取模块数据、日志等),必须对运行用户可写。Docker 形态由制品默认值接管:启动日志回显 KRESUS_DIR = /home/user/data,即数据目录固定为 /home/user/data(对应 Compose 挂载的 ./data 持久化卷)。

userid(默认自动生成,覆盖变量 KRESUS_USER_ID) 由 kresus create-user 命令获得的用户 ID;多用户共享同一数据库时用于区分数据。单用户实例留空即可,Kresus 自动生成(实测首次启动日志:Default user "user" is set with id 1 (admin: true))。多用户创建与删除操作见《Kresus 0.26.0 常用 CLI 命令详解》。

user_login_http_header(默认空,覆盖变量 KRESUS_USER_LOGIN_HTTP_HEADER) 配合反向代理「预认证」使用:设为某个 HTTP 头名(如 YunoHost 环境的 YNH_USER)后,Kresus 从该头读取登录名并匹配对应用户,实现代理层单点登录。普通自建形态留空。

port(默认 9876,覆盖变量 PORT) 监听端口。官方建议不要直接暴露在 80 端口,应挂反向代理。实测 Docker 编排形态回显 PORT = 9876,Compose 侧映射 8146:9876。

host(默认 127.0.0.1,覆盖变量 HOST) 监听地址。裸装默认仅回环;Docker 编排形态制品内置 HOST=0.0.0.0(实测回显 HOST = 0.0.0.0),否则端口映射无法访问——这是 Docker 编排与裸装行为差异点之一。

server_timeout(默认 300,覆盖变量 KRESUS_SERVER_TIMEOUT) 内置 HTTP 服务(express)超时秒数。官方注释强调必须保持较大值:银行抓取是同步阻塞请求,部分银行模块取数很慢。修改生效全流程实测见 3.3 节(300→600 回显 KRESUS_SERVER_TIMEOUT = 600)。

python_exec(默认 python3,覆盖变量 KRESUS_PYTHON_EXEC) 调用 Woob 使用的 Python 解释器名/路径。制品内实测回显 KRESUS_PYTHON_EXEC = python3(Python 3.11.2)。裸装环境若使用虚拟环境,这里填虚拟环境内的 python 绝对路径。

url_prefix(默认空,覆盖变量 KRESUS_URL_PREFIX) 子路径部署前缀:设 money 则 Kresus 挂在 example.com/money 之下服务,适合与主站共域。需要反向代理配套转发规则;独立子域名部署留空。

salt(默认空,覆盖变量 KRESUS_SALT) 导出内容加解密使用的盐值,官方建议至少 16 字符随机串。设了盐的实例导出的数据文件需同盐才能解密导入——盐丢失即导出件不可解。不常做导出/导入可留空。

force_demo_mode(默认 false,覆盖变量 KRESUS_FORCE_DEMO_MODE) 强制演示模式:实例整体锁定在演示数据态,禁止绑定真实银行账户。官方注释特别警告:开关切换可能触发数据丢失;且即便不设置,任何人也能在界面里进入演示模式体验(设置项只影响「能否离开」)。公开演示站才建议启用。

auth(默认空,覆盖变量 KRESUS_AUTH) 应用层 HTTP Basic Auth:填 用户名:密码 格式字符串即启用。Kresus 无内置登录体系(官方文档明确警告),此项是小团队/家庭场景最便捷的访问控制补丁。实测未设置时回显 KRESUS_AUTH = null;若通过环境变量设置,回显值不变但请求需携带 Basic 凭据。

5.2 [woob] 节:银行同步引擎(2 项)

srcdir(默认空=系统 Python 环境,覆盖变量 KRESUS_WOOB_DIR) Woob 核心所在目录。留空表示 Woob 已在 PYTHON_PATH(官方制品内为 pip 全局安装的 Woob 3.7,实测 pip show woob 回显 Name: woob / Version: 3.7);裸装若把 Woob 装在用户目录或虚拟环境,这里指向其顶层目录。

sources_list(默认空=自动生成,覆盖变量 KRESUS_WOOB_SOURCES_LIST) 模块仓库源列表文件路径。留空时 Kresus 在 KRESUS_DIR/woob-data/sources.list 自动生成(默认官方仓库源);指向自有源可实现离线/私有模块分发。

5.3 [email] 节:邮件通道(8 项)

transport(默认空=不发邮件,覆盖变量 KRESUS_EMAIL_TRANSPORT) 邮件传输方式,二选一:sendmail(依赖系统 sendmail 可执行程序,仅需配 sendmail_bin)或 smtp(需完整 SMTP 凭据)。实测未配置时启动日志提示 No emailer found, skipping reports management.——Kresus 的日报与告警邮件均不发送,但其余功能不受影响。

sendmail_bin(默认系统路径,覆盖变量 KRESUS_EMAIL_SENDMAIL_BIN) sendmail 可执行文件路径,仅 transport=sendmail 时有意义。

from(覆盖变量 KRESUS_EMAIL_FROM) 发件人地址。官方注释提醒:确保域名 DNS(SPF/DKIM)配置正确,否则邮件会进垃圾箱。

host / port(覆盖变量 KRESUS_EMAIL_HOST / KRESUS_EMAIL_PORT) SMTP 服务器地址与端口;端口官方注释给出惯例值:25(服务器互投)、587(客户端提交)、465(非标准但常用)。

user / password(默认匿名,覆盖变量 KRESUS_EMAIL_USER / KRESUS_EMAIL_PASSWORD) SMTP 认证凭据;留空走匿名连接(仅内网中继可用)。

force_tls(默认 false,覆盖变量 KRESUS_EMAIL_FORCE_TLS) 强制 TLS 直连(SMTPS);默认走 STARTTLS(可用则升级加密)。

reject_unauthorized_tls(默认 true,覆盖变量 KRESUS_EMAIL_REJECT_UNAUTHORIZED_TLS) 证书校验开关;设 false 允许自签证书(自建 SMTP 中继内网常见需求),公网 SMTP 建议保持 true。

5.4 [notifications] 节:Apprise 推送(1 项)

appriseApiBaseUrl(默认空,覆盖变量 KRESUS_APPRISE_API_BASE_URL) Apprise-API 服务的基础地址(如 http://localhost:8000/)。配置后 Kresus 的通知经 Apprise 推送到 Telegram、钉钉、Slack 等数十种渠道。这是不依赖邮件的告警通路,注意此服务需另行部署(Apprise-API 为独立项目)。

5.5 [logs] 节:日志(1 项)

log_file(默认 datadir/kresus.log,覆盖变量 KRESUS_LOG_FILE) 日志文件路径。实测 Docker 形态日志落在数据目录:/home/user/data/kresus.log(宿主机侧对应 ./data/kresus.log,实测可见文件随运行持续增长)。需要接入集中日志采集时可重定向到专用路径。

5.6 [db] 节:数据库(8 项)

type(必填,覆盖变量 KRESUS_DB_TYPE) 数据库类型,仅 postgres 与 sqlite 两档。官方注释明确:PostgreSQL 推荐且强支持;SQLite「强烈不推荐」(strongly discouraged)用于生产——因无法妥善处理部分数据库迁移,仅供开发。实测回显 KRESUS_DB_TYPE = postgres。

log(默认 error,覆盖变量 KRESUS_DB_LOG) SQL 日志级别三档:all(记录每条查询含出错查询)/ error(默认,只记出错查询)/ none(不记录)。排障 SQL 问题时临时切 all,长期保持 error。实测回显 KRESUS_DB_LOG = error。

sqlite_path(仅 sqlite 必填,覆盖变量 KRESUS_DB_SQLITE_PATH) SQLite 数据库文件路径,需对运行用户可写。postgres 形态下忽略。

host(postgres 必填,默认 localhost,覆盖变量 KRESUS_DB_HOST) 数据库主机地址,亦支持传「Unix 套接字目录」(套接字文件名由标准 postgres 命名与端口号推算)。实测 Compose 网络内回显 KRESUS_DB_HOST = postgres(服务名直连)。

port(postgres 必填,默认 5432,覆盖变量 KRESUS_DB_PORT) 数据库端口;即使用 Unix 套接字也要设置(用于推算套接字文件名)。实测回显 KRESUS_DB_PORT = 5432。

username / password(postgres 必填,覆盖变量 KRESUS_DB_USERNAME / KRESUS_DB_PASSWORD) 数据库凭据。实测回显用户名 KRESUS_DB_USERNAME = kresus;密码回显 KRESUS_DB_PASSWORD = (hidden)(日志不泄明文)。

name(postgres 必填,默认 kresus,覆盖变量 KRESUS_DB_NAME) 数据库名。实测回显 KRESUS_DB_NAME = kresus。

六、生产配置模板

以下为本文实测环境可直接复用的生产模板(Docker/Compose 形态挂载为 /opt/config.ini,权限 600;裸装形态按注释提示调整路径):

[kresus]
; 数据目录:Docker 形态由制品默认 KRESUS_DIR 接管,留空;裸装建议显式指定
datadir=
; 单用户实例,留空自动生成
userid=
; 反代预认证头,普通部署留空
user_login_http_header=
; 监听端口与地址:Docker 形态由制品默认 PORT/HOST 接管;裸装建议保持默认 127.0.0.1 并挂反代
port=
host=
; 银行抓取同步阻塞,超时保持 300 秒以上
server_timeout=300
python_exec=python3
; 子路径部署才设置,如 money
url_prefix=
; 导出加解密盐值,至少 16 字符随机串;需导出导入的场景务必设置并妥善保管
salt=
; 公开演示站才启用;切换可能导致数据丢失
force_demo_mode=
; 无内置认证,公网部署启用 Basic Auth(格式 用户名:密码)
auth=admin:q1w2e3r4

[woob]
; 制品内置 Woob(pip 全局),留空;裸装指向 Woob 顶层目录
srcdir=
; 模块源列表留空自动生成于 KRESUS_DIR/woob-data/sources.list
sources_list=

[email]
; 邮件告警按需启用(sendmail 或 smtp),留空不发邮件
transport=
sendmail_bin=
from=
host=
port=
user=
password=
force_tls=
reject_unauthorized_tls=

[notifications]
; Apprise-API 地址,需另行部署 Apprise-API 服务
appriseApiBaseUrl=

[logs]
; 留空落 datadir/kresus.log
log_file=

[db]
; 生产固定 postgres;SQLite 仅开发
type=postgres
log=error
sqlite_path=
; Docker 形态填 Compose 服务名;裸装默认 localhost
host=postgres
port=5432
username=kresus
password=q1w2e3r4
name=kresus

⚠️ 提醒:auth=admin:q1w2e3r4 与数据库口令 q1w2e3r4 均为本文演示环境的测试口令,落地生产时必须替换为强口令,并保持 config.ini 权限 600。

七、常见问题(FAQ)

Q1:启动报配置文件权限错误? 生产模式校验 config.ini 权限,报错含 should be at most readable by its owner and group, writable by its owner 字样。处理:chmod 600 config.ini 后重启。Docker 编排形态下官方入口脚本会在每次启动时自动收紧权限(实测运行环境内回显 -rw------- 1 user user /opt/config.ini),因此该报错主要出现在裸装形态。

Q2:改了 config.ini 不生效? INI 仅在启动时读取,改完必须重启进程(docker compose restart kresus)。验证生效值直接看启动日志 apply-config 段(3.3 节实测流程)。若 config.ini 与环境变量同时设置,环境变量优先——优先级排查见第六章模板注释与第四章总览表。

Q3:SQLite 可以用在生产吗? 官方明确不建议(strongly discouraged):无法妥善处理部分数据库迁移,仅供开发。生产部署请使用 PostgreSQL(官方管理文档称其为「唯一完全兼容且适合生产」的数据库)。

Q4:为什么日志里 HOST 是 0.0.0.0,而 config.ini 的 host 留空? Docker 制品内置了 HOST=0.0.0.0 环境变量默认值,环境变量覆盖 config.ini 同名项(实测回显见 3.2 节)。裸装环境无此变量时走 config.ini 默认 127.0.0.1。这是 Docker 制品与裸装部署行为差异的典型例子。

Q5:邮件告警没有发出? 确认 transport 是否设置(留空即不发邮件,实测启动日志提示 No emailer found, skipping reports management.);smtp 形态需完整配齐 host/port/user/password/from;内网自建 SMTP 且用自签证书时需 reject_unauthorized_tls=false。

Q6:salt 忘了会导致什么? 导出的数据文件用 salt 加密,盐值丢失后旧导出文件无法解密导入。若需要周期导出备份,把 salt 写入配置并纳入密钥管理。

八、参考链接