OpenBudgeteer 1.11.2 配置参数详解

目标：把 OpenBudgeteer 1.11.2 的全部配置项（数据库连接、Redis 连接、应用设置）讲透：每个参数的取值范围、默认值、生效机制、可验证的效果与踩坑点。核心参数均在真实环境逐项实测验证（2026-10-24），无法实测的部分标注官方文档溯源。

一、环境信息

• 软件版本：OpenBudgeteer 1.11.2（当前最新稳定版，2026-10-23 发布）
• 配置载体：OpenBudgeteer 没有任何配置文件语法要求——全部参数经两种等价途径注入：
  1. 进程环境变量（部署时注入，如 Compose 的 environment: 或系统服务环境）；
  2. 应用根目录下的 .env 文件（官方 Configuration 页："Settings can be defined via Docker environment variables or via .env file which needs to be located in the root folder of the application"）。
• 效果验证载体：应用内置 Info 页（导航 Info，或 /info），直接渲染当前生效的数据库连接要素与版本号；
• 本文实测环境：1.11.2 + MariaDB 11.8 + Redis 8.2，部署形态见《OpenBudgeteer Docker Compose 部署指南》。

二、前置条件

• OpenBudgeteer 已完成部署并可访问 Info 页（未部署先读《OpenBudgeteer Docker Compose 部署指南》）；
• 已有一个可用的 MariaDB/MySQL 或 PostgreSQL 实例，以及一个 Redis 实例（两者均为强制依赖，v1.8.3 移除 SQLite、v1.10 起强制 Redis）；
• 修改参数需要重启 OpenBudgeteer 进程才生效（环境变量与 .env 都是启动期读取，运行期热改无效）。

三、参数查看与修改方式

查看当前生效配置：打开 Info 页，"Current Database Connection" 区域直接展示实际生效的 Provider / Server / Database name / Database user 四要素，页面顶部有 Version: 1.11.2 (Change Log) 版本串。实测抓取 Info 页的渲染结果：

Provider: MariaDB/MySql
Server:   openbudgeteer-mariadb
Database name: openbudgeteer
Database user: openbudgeteer

这是排查"配置到底生效没有"的第一入口——四要素和你预期的一致，说明 CONNECTION_* 生效；不一致，说明环境变量没注入成功或被别处覆盖。

修改配置：改环境变量或 .env 文件后重启应用进程。以 Compose 部署为例：修改 docker-compose.yml 的 environment: 后执行 docker compose up -d --force-recreate（仅 restart 不会重新读取新的 environment 定义）。

Info 页还能看到什么：第三方依赖清单（efcore、Pomelo.EntityFrameworkCore.MySql、StackExchange.Redis、MudBlazor、Blazor-ApexCharts、TinyCsvParser、dotnet-env 等）——其中 dotnet-env 正是 .env 文件加载能力的实现，与官方文档互为印证。

四、参数总览

三组共 14 个参数（官方 Configuration 页 2026-10-24 版全量）：

数据库连接组（CONNECTION_*，7 个）：

Redis 连接组（CONNECTION_REDIS_*，5 个）：

应用设置组（APPSETTINGS_*，2 个）：

缺省默认值表（官方 Configuration 页原文，实测默认行为与其一致）：

五、核心参数分类详解

5.1 CONNECTION_PROVIDER：数据库类型

取值四选一（大小写不敏感，官方示例同时出现 MYSQL 与 mysql 两种写法）：

要点：

• 没有 SQLite：v1.8.3 起官方移除 SQLite 支持（Release Notes："Breaking change: Dropping support for SQLite"），v1.9 完成清理。别再按旧教程配 SQLite；
• 选定 provider 后，应用首次启动自动建表、升级后自动执行 schema 迁移（官方 Config 页："the required tables and initial data will be created on first startup. Database schema changes after an update will be also applied automatically"）。实测 1.11.2 + MariaDB 首次启动自动创建 12 张表：Account、BankTransaction、Bucket、BucketGroup、BucketMovement、BucketRuleSet、BucketVersion、BudgetedTransaction、ImportProfile、MappingRule、RecurringBankTransaction，外加 __EFMigrationsHistory 迁移记录表；
• 自动建表/迁移仅对 MySQL、MariaDB 明确支持——官方 Config 页原文 "Automated database initialization is supported for MySQL and MariaDB"；PostgreSQL 的官方口径是要求"库和角色已存在且为空"，见 5.2。

5.2 CONNECTION_SERVER / PORT / DATABASE / USER / PASSWORD：连接五要素

• CONNECTION_SERVER：地址或 FQDN。这个值必须在应用进程所在网络环境内可达——它是本组件最常见的故障点：部署编排里的服务别名、外部数据库的域名，两者写错任何一个，应用都会停在 Waiting for database. 阶段无限重试（实测确认该重试行为）。取值示例：192.168.1.100（官方示例）、db.lan.example.com；
• CONNECTION_PORT：省略时按 provider 取默认端口（MySQL/MariaDB 3306、PostgreSQL 5432）；
• CONNECTION_DATABASE：库名有字符集与长度限制——最长 64 字符，允许 0-9、a-z、A-Z、$、_、-，其中 - 在 PostgreSQL 下不允许（官方 Config 页 "Additional comments" 一节）；
• CONNECTION_USER / CONNECTION_PASSWORD：应用对该库需要完全写权限 + 修改 schema 权限（建表/改表），官方建议通过 phpMyAdmin 之类工具建用户时勾选 "Create database with same name and grant all privileges" 与 "Grant all privileges on wildcard name (username_%)"；实测验证：给普通用户授权后应用正常建表运行；
• 五要素生效与否，用 Info 页核对（见"三、参数查看与修改方式"）。

PostgreSQL 专属约束（官方 Config 页）：推荐"一个实例只服务这一个库"的隔离初始化模式，由 PostgreSQL 实例自身初始化出空库与角色；角色必须存在，且对目标库 public schema 有 CREATE 权限。对应的实例侧参数是 POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB。注意这组变量是 PostgreSQL 服务端的初始化参数，不是 OpenBudgeteer 的参数，但两者四要素必须对齐。

5.3 CONNECTION_ROOT_PASSWORD：首次自动建库（实测）

作用：当目标 MySQL/MariaDB 实例上还没有 CONNECTION_DATABASE 指定的库和 CONNECTION_USER 指定的用户时，OpenBudgeteer 首次启动会用 root 身份代为创建。官方 Config 页："The usage of CONNECTION_ROOT_PASSWORD is optional in case user and database for MariaDB or MySQL are not existing and should be created by OpenBudgeteer. The variable is only required for the first startup and can be removed later."

实测验证：给一个只有 root 密码、其余全空的 MariaDB 实例，配好 CONNECTION_ROOT_PASSWORD 后启动应用，随后在数据库侧核对：

SHOW DATABASES;
Database
information_schema
mysql
performance_schema
sys
openbudgeteer

SELECT user, host FROM mysql.user WHERE user='openbudgeteer';
user            host
openbudgeteer   %

SHOW GRANTS FOR 'openbudgeteer'@'%';
Grants for openbudgeteer@%
GRANT USAGE ON *.* TO `openbudgeteer`@`%` DEFINED BY CURRENT USER
GRANT ALL PRIVILEGES ON `openbudgeteer`.* TO `openbudgeteer`@`%`

即应用自动完成了三件事：建库 openbudgeteer、建用户 openbudgeteer@%、授予该库的 ALL PRIVILEGES。应用随后正常建表启动。

使用建议：该参数只在首次启动需要，跑通后即可从配置中移除（官方原文如此），避免 root 密码长期留在部署配置里。若你愿意预先手工建库建用户（或用数据库实例自己的初始化机制），此参数完全不需要。

5.4 CONNECTION_REDIS_*：Redis 连接（v1.10 起强制）

OpenBudgeteer 用 Redis 存放 UI 设置类数据（官方 Config 页："to store certain App settings (e.g. Color themes)"），不是缓存可选件。没配好 Redis 的直接后果：进程反复输出 Waiting for Redis database.、无法完成启动（实测确认）。

五个参数：

• CONNECTION_REDIS_SERVER：Redis 地址，网络可达性要求同 5.2；
• CONNECTION_REDIS_PORT：省略时默认 6379；
• CONNECTION_REDIS_USER / CONNECTION_REDIS_PASSWORD：Redis 6+ ACL 模式的用户名与密码；无 ACL 的裸 Redis 两者都省略；
• CONNECTION_REDIS_PREFIX：键前缀。多套应用共用一个 Redis 时必配，避免键冲突；开启 ACL 时它还有第二个意义：与 ACL 的键模式匹配。

官方给出的 Redis ACL 文件示例（users.acl）：

user openbudgeteer-redis +@all -@dangerous +info ~openbudgeteer:* on >openbudgeteer-redis-pw

拆解该行：用户 openbudgeteer-redis、密码 openbudgeteer-redis-pw、允许所有常规命令但拒绝危险命令组 @dangerous、只允许操作 openbudgeteer:* 前缀的键。此时应用侧的对应配置为：

CONNECTION_REDIS_USER=openbudgeteer-redis
CONNECTION_REDIS_PASSWORD=openbudgeteer-redis-pw
CONNECTION_REDIS_PREFIX=openbudgeteer

三者的匹配关系是硬约束：前缀与 ACL 键模式不一致时，应用对设置的读写会被 Redis 拒绝，表现为 UI 主题等设置无法保存。

5.5 APPSETTINGS_CULTURE：本地化格式

• 类型：BCP 47 语言标签（官方 Config 页："Must be a BCP 47 language tag"）；
• 默认：en-US；
• 作用范围：货币符号、日期格式、数字千分位等渲染格式。如 zh-CN 显示 ¥ 与 2026/10/24 式日期，de-DE 显示 € 与 24.10.2026 式日期；
• 改动后重启进程生效；它不影响已入库数据的存储格式（金额按数值存储，展示层才做格式化）；
• 取值无效时应用会回退默认行为，所以配置后建议在 Info 页与首页（账户余额、交易日期列）各看一眼确认。

5.6 APPSETTINGS_DEMO_DATA：演示数据

• 类型：布尔；默认 false；
• 置 true 时首次启动灌入一整套示例数据。实测 1.11.2 的演示集包含：两个银行账户（Checking account、Savings account，初始余额 $1,255.70 / $1,500.00）、若干桶组与桶（Car Fuel、Groceries、Health Insurance、Rent 等）、数月的历史交易与桶分配记录；
• 它不是一次性开关：只要库里没有账户数据，置 true 的实例启动时就会补演示数据。生产启用请保持 false；
• 清除方式：演示数据就是普通业务数据，可逐条删，或清空库重建（先备份）。

六、生产配置模板

以下两个模板覆盖最常见的两种形态。资源基线实测（1.11.2，四服务空载 + 演示数据）：Web 进程 148.9 MiB、API 进程 83.3 MiB、MariaDB 98.0 MiB、Redis 9.1 MiB，合计约 340 MiB 内存——1 核 1 GB 的家用服务器即可承载，磁盘按每年数万条交易估计 < 100 MB。

模板 A：全家桶单机（自包含，最常见）——Web + API + MariaDB + Redis 同机编排，完整 Compose 文件见《OpenBudgeteer Docker Compose 部署指南》第四节，核心环境变量：

CONNECTION_PROVIDER=mariadb
CONNECTION_SERVER=<编排内数据库服务名>
CONNECTION_PORT=3306
CONNECTION_DATABASE=openbudgeteer
CONNECTION_USER=openbudgeteer
CONNECTION_PASSWORD=<强密码>
CONNECTION_REDIS_SERVER=<编排内 Redis 服务名>
APPSETTINGS_CULTURE=zh-CN
APPSETTINGS_DEMO_DATA=false

模板 B：复用已有外部数据库与 Redis——只部署应用本身，指向现网实例（适合已有统一数据库服务器、Redis 中间件的家庭机房）：

CONNECTION_PROVIDER=postgresql
CONNECTION_SERVER=db.lan.example.com
CONNECTION_PORT=5432
CONNECTION_DATABASE=openbudgeteer
CONNECTION_USER=openbudgeteer
CONNECTION_PASSWORD=<强密码>
CONNECTION_REDIS_SERVER=redis.lan.example.com
CONNECTION_REDIS_USER=openbudgeteer-redis
CONNECTION_REDIS_PASSWORD=<Redis 密码>
CONNECTION_REDIS_PREFIX=openbudgeteer
APPSETTINGS_CULTURE=zh-CN

模板 B 注意三点：PostgreSQL 侧先按 5.2 建好空库与角色；Redis 侧按 5.4 配好 ACL（前缀与键模式一致）；此时不再需要 CONNECTION_ROOT_PASSWORD（它只对 MySQL/MariaDB 的自动建库生效）。

七、常见问题

Q1：改了环境变量，应用行为没变？

环境变量与 .env 都是启动期读取，改完必须重启进程。Compose 部署下用 docker compose up -d --force-recreate（只 restart 不会应用新的 environment 定义）。重启后到 Info 页核对四要素是否已变成新值。

Q2：.env 文件和环境变量同时存在，谁优先？

官方文档对优先级没有明确说明（.env 加载由 dotnet-env 库实现，惯例上显式环境变量优先于 .env 文件，但这属于 .NET 生态通用行为而非本组件承诺）。稳妥做法：单一来源——要么全走环境变量，要么全走 .env，不要两边都配。实测中未同时配置，无法给出实测优先级结论，特此说明。

Q3：应用一直 Waiting for Redis database.？

CONNECTION_REDIS_SERVER 不可达（拼写错误、网络不通、Redis 未启动）。先确认地址可达，再检查是否需要 ACL 参数。实测中该阶段为无限重试，修好后重启进程即恢复。

Q4：Waiting for database. 反复出现？

数据库连接五要素有误或数据库未就绪。按顺序核对：数据库进程在跑 → CONNECTION_SERVER 可达 → 用户名/密码与数据库侧授权一致 → 库存在（或使用 CONNECTION_ROOT_PASSWORD 自动建库路径，见 5.3）。

Q5：想用中文界面，改哪个参数？

APPSETTINGS_CULTURE=zh-CN（重启生效）。注意它只控制格式化（货币/日期/数字），界面文案本身以应用内置翻译为准，并未提供中文翻译包——日期变成 2026/10/24 但菜单仍是英文是正常现象。

Q6：演示数据怎么清掉换成正式使用？

APPSETTINGS_DEMO_DATA 改回 false 只是阻止再次生成，已生成的数据要手动清：最干净的办法是备份后清空数据库（或删除数据卷）重建空库，再以 false 重启应用。

八、参考链接

• 官方 Configuration 文档（本文参数的权威来源，2026-10-24 核对）：https://theaxelander.github.io/latest/config/
• 官方 Install 文档：https://theaxelander.github.io/latest/install/
• GitHub Releases（SQLite 移除、Redis 强制等破坏性变更出处）：https://github.com/TheAxelander/OpenBudgeteer/releases
• 站内延伸：《OpenBudgeteer 1.11.2 介绍与选型指南》、《OpenBudgeteer Docker Compose 部署指南》、《OpenBudgeteer 1.11.2 API 使用详解》