ezbookkeeping 2.1.0 配置参数详解

目标：面向已完成 ezBookkeeping v2.1.0 安装或 Docker Compose 部署、需要精细化调整运行参数的读者，逐节详解官方配置文件 ezbookkeeping.ini 的全部 23 个配置节：默认值、取值范围、生效方式与实测验证结果。所有默认值均取自 v2.1.0 官方发布包内 conf/ezbookkeeping.ini 原文，所有验证性操作均在 Ubuntu 22.04.4 LTS 实测采集。

一、环境信息

v2.1.0 相比 1.x 的配置结构性变化（升级前必读）：原 [llm] 及其子节已更名为 [ai] + 三个独立的 LLM 配置节（[llm_text_recognition]、[llm_image_recognition]、[llm_coding_assistant]），新增 MCP 服务配置节 [mcp]。从 1.x 升级后沿用旧配置会导致 AI 与 MCP 功能配置静默失效，需按新结构重写。

二、前置条件

1. 已按 B1 安装指南或 B2 Compose 部署指南完成 ezBookkeeping 部署并能正常访问；
2. 明确自己的部署形态：裸机/systemd 安装的配置文件位于安装目录 conf/ezbookkeeping.ini；Docker 部署时为挂载进容器的 ini 文件；
3. 若使用环境变量方式管理配置，了解所选编排工具（systemd EnvironmentFile 或 compose environment）；
4. 修改前备份原配置文件（cp conf/ezbookkeeping.ini conf/ezbookkeeping.ini.bak）。

三、参数查看与修改方式

3.1 修改通道一：ini 配置文件

主通道。编辑后重启服务生效（systemd 形态 systemctl restart ezbookkeeping；Compose 形态 docker compose restart）。文件为标准 INI 格式：方括号为节名，# 开头行为注释。

3.2 修改通道二：EBK_ 环境变量覆写

任意配置项都可用 EBK_<节名>_<配置项名> 环境变量覆写（全大写），无需改 ini 文件。实测验证（B2 部署中同时挂载 ini 并设置环境变量）：

environment:
  - "EBK_SERVER_DOMAIN=book.example.com"
  - "EBK_SECURITY_SECRET_KEY=q8Zw7HmTsP5nVcXeR2uYbK4jL6fD0aG1"

启动日志实测输出（节选）："Domain":"book.example.com","RootUrl":"http://book.example.com:8080/"，且 "SecretKeyNoSet":false,"SecretKey":"****"——两项均按环境变量值生效，优先级高于 ini 文件。三个通道的优先级为：环境变量 > ini 文件 > 程序内置默认值。

3.3 验证手段：启动日志配置快照

ezBookkeeping 启动时会把最终生效的全部配置以 JSON 形式打印到日志（敏感项脱敏为 ****），这是核对配置是否生效的第一入口：

docker compose logs | grep "has loaded configuration"
# 或 systemd 形态：
journalctl -u ezbookkeeping | grep "has loaded configuration"

实测输出为一段完整 JSON，字段名即配置项的驼峰形式（如 EnableAPIToken、TokenExpiredTime），逐一对照即可确认。

四、参数总览

v2.1.0 官方配置文件共 23 个配置节：

五、核心参数分类详解

5.1 全局与 Web 服务（[global]、[server]）

secret_key 特殊说明（在 [security] 节，部署第一步就会遇到）：用于密码哈希与会话令牌签名，官方注释明确要求首次运行前必须修改。ini 默认值为空，此时启动日志中 SecretKeyNoSet 会显示为 true（实测字段存在），功能可用但属于官方明示的不安全状态。secret_key 一旦有用户数据后不可更换，否则所有已有用户的密码与会话全部失效。推荐用 ezbookkeeping security gen-secret-key -l 32 生成（实测输出形如 EHzJgpPK6TnvXcR2uYbK4jL6fD0aG1q8Zw7HmTsP5n=）。

5.2 数据库（[database]）

实测启动日志（SQLite 形态，节选）：

[INFO] [database.updateAllDatabaseTablesStructure] user table maintained successfully
[INFO] [database.updateAllDatabaseTablesStructure] account table maintained successfully
[INFO] [database.updateAllDatabaseTablesStructure] transaction table maintained successfully

生产建议：个人/小团队自托管 SQLite 完全够用（单文件备份方便）；多人共享或多实例部署换 MySQL/PostgreSQL，此时修改 type/host/name/user/passwd 五项即可。

5.3 邮件（[mail]）

实测排障实录：enable_smtp=false 时执行邮件测试命令，实测报错为 SMTP server is not enabled——该报错是配置门拦截，并非网络问题；改为 enable_smtp=true 后（SMTP 服务器故意未启动），报错变为 dial tcp 127.0.0.1:25: connect: connection refused，证明配置门已通过、问题转移为网络连通性。两段报错的差异可用于快速定位"没配置"还是"连不上"。

5.4 日志（[log]）

5.5 附件对象存储（[storage]）

5.6 AI 能力（[ai] 与三个 LLM 节）

[ai] 是功能总开关，三个 LLM 节提供各能力的模型接入：

三个 LLM 节结构完全一致，llm_provider 支持 9 种：openai、openai_compatible、openai_responses_compatible、anthropic、anthropic_compatible、openrouter、ollama、lm_studio、google_ai。每个 provider 有专属的 key/url/model_id 三件套，共用 enable_thinking（off/low/medium/high/xhigh/on 六档，按 provider 支持度不同）、request_timeout（默认 60000ms）、proxy（默认 system）、skip_tls_verify（默认 false）。不使用 AI 能力时保持全部默认（关闭）即可，无资源开销。

5.7 UUID 与防重复提交（[uuid]、[duplicate_checker]）

5.8 定时任务（[cron]）

实测启动日志可见对应任务注册：job "RemoveExpiredTokens" has been registered、job "CreateScheduledTransaction" has been registered。

5.9 安全与会话（[security]）

enable_api_token 实测排障实录：默认 false 时，已登录用户请求生成 API 令牌实测报错 api token is not enabled；将 enable_api_token 改为 true 并重启后，签发成功，且 GET /api/v1/tokens/list.json 返回的令牌记录中 tokenType: 8（API 令牌类型码）可查。生产开启时建议同时配置 api_token_allowed_remote_ips 收紧来源。

5.10 认证方式（[auth]）

5.11 用户与注册（[user]）

default_feature_restrictions 的 20 项能力编码（官方注释原文）：1 更新密码、2 更新邮箱、3 更新基本资料、4 更新头像、5 登出其他会话、6 启用两步验证、7 关闭两步验证、8 找回密码、9 导入交易、10 导出交易、11 清空数据、12 同步应用设置、13 MCP 访问、14 AI 图片识别记账、15 OAuth2 登录、16 解绑三方登录、17 生成 API 令牌、18 AI 文本识别记账、19 上传自定义图标、20 AI 生成图表脚本。

实测验证（配合 CLI 工具对单用户设置限制 -t 17,13 后）：该用户请求生成 API 令牌实测报错 you are not permitted to perform this action，限制即时生效。注意语义是"限制清单"——填 17 表示禁止该用户生成 API 令牌。

5.12 数据导入导出（[data]）

5.13 提示与通知（[tip]、[notification]）

5.14 地图服务（[map]）

交易可记录地理位置，地图服务用于展示：

国内部署建议：map_provider = amap 并按需选择 internal_proxy 校验方式（密钥保留在服务端，前端不暴露）。

5.15 汇率数据源（[exchange_rates]）

多币种记账且服务器无法直连欧洲央行时，改用 user_custom 或配置 proxy。

5.16 MCP 服务与开发者选项（[mcp]、[developer]）

六、生产配置模板

6.1 模板一：个人/小团队 SQLite 单机（资源占用最低，实测空闲内存 8.8MB）

[global]
mode = production

[server]
protocol = http
http_addr = 0.0.0.0
http_port = 8080
domain = book.example.com
root_url = https://book.example.com/

[database]
type = sqlite3
db_path = data/ezbookkeeping.db
auto_update_database = true

[mail]
enable_smtp = true
smtp_host = smtp.example.com:465
smtp_user = no-reply@example.com
smtp_passwd = <SMTP密码>
from_address = ezBookkeeping <no-reply@example.com>

[log]
mode = console file
level = info
log_file_rotate = true
log_file_max_size = 104857600
log_file_max_days = 30

[storage]
type = local_filesystem
local_filesystem_path = storage/

[cron]
enable_remove_expired_tokens = true
enable_create_scheduled_transaction = true

[security]
secret_key = <gen-secret-key 生成，一旦确定不可更换>
trusted_proxy_ips = 10.0.0.0/8,127.0.0.0/8,192.168.0.0/16
enable_api_token = false

[auth]
enable_internal_auth = true
enable_two_factor = true

[user]
enable_register = false
avatar_provider = internal

[data]
enable_export = true
enable_import = true

[exchange_rates]
data_source = euro_central_bank

适用场景：1-10 人自用，磁盘占用为 SQLite 单文件（实测 21 万字节量级），无外部数据库依赖。

6.2 模板二：多人 MySQL/PostgreSQL 共享

在模板一基础上替换 [database] 节：

[database]
type = mysql
host = 10.89.71.2:3306
name = ezbookkeeping
user = ezbookkeeping
passwd = <数据库密码>
max_idle_conn = 2
max_open_conn = 20
conn_max_lifetime = 14400
auto_update_database = true

PostgreSQL 部署将 type 改为 postgres 并按需加 ssl_mode = require。多实例（如双机热备）时必须同步设置 [uuid] server_id 为不同值（0-255）。

七、常见问题

Q1：生成 API 令牌报 api token is not enabled

[security] enable_api_token 默认 false。改为 true 并重启服务后重新生成即可；若仍报 you are not permitted to perform this action，则是该用户被 default_feature_restrictions 或管理员单独设置了能力限制（编码 17），由管理员解除。

Q2：邮件相关功能报 SMTP server is not enabled

[mail] enable_smtp 默认 false 的配置门拦截。改为 true 后若报 dial tcp ...: connect: connection refused，则进入网络层排查（SMTP 地址/端口/防火墙）。两段报错差异是判断"未配置"与"连不上"的依据。

Q3：首次启动后登录用户全部失效 / 升级迁移后密码错误

secret_key 与建号时不一致所致。secret_key 确定后不可更换；迁移部署必须把旧实例的 secret_key 一并迁移（ini 或 EBK_SECURITY_SECRET_KEY 环境变量均可）。

Q4：反向代理后日志与限流记录到的全是代理 IP

[security] trusted_proxy_ips 未包含代理的来源地址。默认值仅覆盖常见私网段，若代理不在这些网段（如容器自定义网段），把代理 IP 所在 CIDR 加入并重启。

Q5：从 1.x 升级后 AI/MCP 配置不生效

v2.1.0 将 [llm] 配置节更名为 [ai] + 三个独立 LLM 节，并新增 [mcp] 节（Breaking Change）。旧节名会被忽略但不报错，需按第五章 5.6/5.16 节的新结构重写。

Q6：注册接口报 parameter "categories" is required

注册请求必须携带预置分类（网页端自动带上）。API/脚本注册时补上 categories 数组即可，每个分类组还需至少一个二级分类，原因见 B2 部署指南 Q2 的实测说明。

Q7：改了配置不生效

三种可能：① 改的是容器内路径而非挂载的宿主文件；② 用了环境变量覆写，其优先级高于 ini，ini 的修改被环境变量压住；③ 未重启服务。排查顺序：先看启动日志 has loaded configuration 的 JSON 快照，确认进程实际读到的值，再回溯两个通道。

八、参考链接

1. 官方配置文档：https://ezbookkeeping.mayswind.net/configuration
2. v2.1.0 官方默认配置文件（GitHub）：https://github.com/mayswind/ezbookkeeping/blob/2.1.0/conf/ezbookkeeping.ini
3. 站内关联阅读：《ezbookkeeping 2.1.0 介绍与选型指南》、《Ubuntu 22.04 安装 ezbookkeeping 2.1.0 指南》、《ezbookkeeping 2.1.0 Docker Compose 部署指南》、《ezbookkeeping 2.1.0 常用 CLI 命令与工具详解》

以上默认值逐项对照 v2.1.0 官方发布包内 conf/ezbookkeeping.ini 原文（807 行），验证性操作均在 Ubuntu 22.04.4 LTS 实测采集，实测日期 2026-10-23。