LubeLogger 1.7.4 配置参数详解

目标：把 LubeLogger 1.7.4 的全部配置入口与参数讲透——环境变量、data/config/ 两份 JSON、内置默认值三者的分工与优先级，认证/SMTP/区域/API 格式/存储后端等核心参数的分类详解与实测验证，并给出两种规模的生产配置模板。全部参数与回显在 Ubuntu 22.04 实机（v1.7.4）上验证。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• LubeLogger：v1.7.4（.NET 运行时 10.0.13，自带 Kestrel Web 服务器，监听 8080）
• 数据目录：/opt/lubelogger/data/（进程工作目录下的 data/，含 cartracker.db 与 config/*.json）
• 实测配置状态：认证已启用（Root 用户 admin，SHA256 哈希落盘）、SMTP 未配置、区域 en_US.UTF-8
• 验证手段：启动横幅、data/config/*.json 落盘内容、/api/version、/api/whoami、REST API 响应格式对比

二、前置条件

1. 已有可运行的 LubeLogger 1.7.4 实例（从零部署见《LubeLogger 1.7.4 Docker Compose 部署指南》，独立可执行包部署方式同样适用本篇）；
2. 能查看启动日志（横幅是配置生效的第一验证点）；
3. 能读写数据目录 data/config/（修改配置的落盘通道）；
4. 修改配置前建议先做一次备份：Root 用户在 Settings → Make Backup，或 curl -u admin:q1w2e3r4 http://127.0.0.1:8131/api/makebackup（实测返回 "/temp/db_backup_2026-10-30-14-36-22.zip"）。

三、参数查看与修改方式

3.1 三级配置入口与优先级

LubeLogger 的配置系统是标准 ASP.NET Core 配置管道叠加两级文件源，装配顺序（源码实测核对）：

1. 内置 appsettings.json（全部参数的出厂默认值）；
2. 环境变量（同名键覆盖默认值，形如 MailConfig__EmailServer）；
3. data/config/userConfig.json（用户/实例级，Settings 页写入，reloadOnChange: true）；
4. data/config/serverConfig.json（服务器级，/setup 写入，reloadOnChange: true）。

后加载者覆盖先加载者，即：data/config/ 两份 JSON > 环境变量 > appsettings.json 默认值。reloadOnChange 意味着 JSON 改动被进程自动感知（实测秒级生效，认证凭据写入后立即登录曾观察到一次未及时生效，等几秒重试即可——详见《LubeLogger 1.7.4 Docker Compose 部署指南》FAQ）。

⚠️ 区域例外：官方文档明确 Locale 相关改动必须重启进程（数据目录里的 locale 覆盖是启动时读一次并设置进程级 CultureInfo，不热生效）。

3.2 参数在哪里看

3.3 配置文件实测内容

启用认证后的 data/config/userConfig.json 完整实测（注释为后加说明，原文件无注释）：

{
  "UseDarkMode": false,
  "UseSystemColorMode": false,
  "EnableCsvImports": false,
  "UseMPG": false,
  "UseDescending": false,
  "EnableAuth": true,                    // 认证总开关（Settings 页勾选后落盘）
  "HideZero": false,
  "UseUKMPG": false,
  "UseThreeDecimalGasCost": false,
  "UseThreeDecimalGasConsumption": false,
  "UseMarkDownOnSavedNotes": false,
  "EnableAutoReminderRefresh": false,
  "EnableAutoOdometerInsert": false,
  "EnableAutoFillOdometer": false,
  "EnableShopSupplies": false,
  "EnableExtraFieldColumns": false,
  "HideSoldVehicles": false,
  "AutomaticDecimalFormat": false,
  "PreferredGasUnit": "",
  "PreferredGasMileageUnit": "",
  "UseUnitForFuelCost": false,
  "ShowCalendar": false,
  "ShowVehicleThumbnail": false,
  "ShowSearch": false,
  "DisableAutoZoom": false,
  "EnablePersistentDialog": false,
  "UseGridInMobile": false,
  "EnableNotesColumnWrap": false,
  "UserColumnPreferences": [],
  "UserNameHash": "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918",
  "UserPasswordHash": "13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9",
  "UserLanguage": "en_US",
  "UserTheme": "",
  "VisibleTabs": [8,0,1,2,4,3,5,6],
  "DefaultTab": 8,
  "TabOrder": [8,9,10,0,1,4,2,7,3,6,12,13,5]
}

关键项解读：EnableAuth 是认证总开关；UserNameHash/UserPasswordHash 是 Root 凭据的 SHA256 哈希（实测两值分别等于 SHA256("admin") 与 SHA256("q1w2e3r4")，用 printf 'admin' | sha256sum 可逐位核对）；VisibleTabs/TabOrder/DefaultTab 控制导航页签与顺序（8=Garage 等）。服务器级配置（SMTP/OIDC/Postgres）在 serverConfig.json，由 /setup 维护，逐项见下文各分类。

四、参数总览

全部配置项按域分类（v1.7.4，官方 Environment Variables 文档 + 源码 appsettings.json/ConfigHelper 核对）：

⚠️ 无效变量警示：LCUBE_LOGLEVEL、LCUBE_SENTRY_*、LCUBE_SMTP_ENABLED、LCUBE_ADDRESS 等 LCUBE_ 前缀变量是旧版/网络讹传，v1.7.4 源码与官方文档均不存在，注入无效果（本机实测注入后横幅无任何变化）。排障时先确认变量名在上表内。

五、核心参数分类详解

5.1 认证与 Root 用户（EnableAuth / UserNameHash / UserPasswordHash）

认证总开关与 Root 凭据。实测启用链路：Settings 页勾选 Enable Authentication → 弹窗输入 admin / q1w2e3r4 → 点击 Setup → userConfig.json 写入 EnableAuth: true 与两段 SHA256 哈希 → 登录页生效。

实测验证（登录接口与哈希核对）：

$ curl -s -X POST http://127.0.0.1:8131/Login/Login \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    --data 'userName=admin&password=q1w2e3r4&isPersistent=false'
{"success":true,"message":""}

$ printf 'admin' | sha256sum
8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918  -
$ printf 'q1w2e3r4' | sha256sum
13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9  -

要点：

• 哈希算法为无盐 SHA256，环境变量形态（UserNameHash/UserPasswordHash）与文件形态等价，取其一即可；
• EnableAuth=false（默认）时整个实例免登录，仅建议完全内网时使用；
• Root 用户与普通用户/Admin 的权限差异见介绍篇三层权限表；官方建议日常使用另建的 Admin 用户，把 Root 留给备份/用户管理；
• 关闭认证：Root 登录后 Settings 页取消勾选，或直接把 userConfig.json 的 EnableAuth 改回 false 后重启。

5.2 注册控制（DisableRegistration / LUBELOGGER_OPEN_REGISTRATION）

LubeLogger 用户注册是邀请制：Root/Admin 在 Admin Panel 生成单次有效的注册令牌（与邮箱绑定），受邀人凭令牌在 Register 页完成注册。

• DisableRegistration（默认 false）：置 true 后登录页不显示 Register 链接，服务器拒绝注册请求；
• LUBELOGGER_OPEN_REGISTRATION（默认 false）：允许任何人自助生成注册令牌（令牌仍需邮箱接收），仅在 SMTP 正常且受众可控时开启。

实测边界（SMTP 未配置时）：登录页 Register 链接可见，但直接提交注册会返回 {"success":false,"message":"Invalid Token"}——令牌只能来自管理员生成或自助生成后经邮件送达，无 SMTP 时无法自动送达，需手动转交令牌。

5.3 SMTP 邮件（MailConfig__*）

SMTP 只服务两类邮件：注册令牌、找回密码令牌（提醒邮件走 Webhook/独立发送接口，不依赖此项）。

横幅实测对照（同一镜像、不同注入组合的启动日志首 7 行）：

# 未注入任何 SMTP 变量
LubeLogger 1.7.4
Website: https://lubelogger.com
Documentation: https://docs.lubelogger.com
GitHub: https://github.com/hargata/lubelog
SMTP Not Configured
Message Of The Day: Not Configured
WARNING: No Locale or Culture Configured for LubeLogger, Check Environment Variables

# 仅注入 MailConfig__EmailServer=smtp.example.com / EmailFrom / Port=587
LubeLogger 1.7.4
Website: https://lubelogger.com
Documentation: https://docs.lubelogger.com
GitHub: https://github.com/hargata/lubelog
SMTP Configured for smtp.example.com
Message Of The Day: Not Configured
WARNING: No Locale or Culture Configured for LubeLogger, Check Environment Variables

横幅只证明"变量已读取"，真实投递需在 /setup 的 SMTP 区完成发信测试。生产凭据建议经环境变量注入且不要写进 serverConfig.json（/setup 保存的值会明文落盘）。

5.4 区域与格式（LC_ALL / LANG / LUBELOGGER_LOCALE_OVERRIDE）

区域决定数字、货币、日期的渲染格式，同时直接影响 API 响应格式（见 5.5）。三个入口：

• LC_ALL/LANG：进程级 locale，最通用（实测 en_US.UTF-8 注入后横幅 Locale 警告消失）；
• LUBELOGGER_LOCALE_OVERRIDE：进程启动时构造 CultureInfo 并设为默认线程区域，等价于 locale 但不依赖系统 locale 包；
• LUBELOGGER_LOCALE_DT_OVERRIDE：单独覆盖日期格式（如用 en_US 的数字/货币 + ISO-8601 日期）。

⚠️ 区域改动必须重启进程生效（官方文档明示，启动时一次性读取）。

5.5 API 输出格式（LUBELOGGER_INVARIANT_API / culture-invariant 请求头）

默认 API 响应与区域敏感：数字与日期都返回字符串且按进程区域格式化。两种等价开关：

• 环境变量 LUBELOGGER_INVARIANT_API=true（实例级，全局生效）；
• 请求头携带 culture-invariant（无需值，单请求生效）。

实测对比（同一条加油记录，同实例）：

# 不带 invariant 头：全字符串 + 区域格式日期
[{"vehicleId":"1","id":"1","date":"10/25/2026","odometer":"15500",
  "fuelConsumed":"42.5","cost":"312.25","isFillToFull":"True",
  "missedFuelUp":"False", ...}]

# 带 culture-invariant 头：类型保真 + ISO 日期
[{"vehicleId":1,"id":1,"date":"2026-10-25","odometer":15500,
  "fuelConsumed":42.5,"cost":312.25,"isFillToFull":true,
  "missedFuelUp":false, ...}]

建议：程序化消费 API 一律带 invariant（变量或请求头任选），避免区域迁移导致解析断裂。逐端点调用见《LubeLogger 1.7.4 REST API 使用详解》。

5.6 存储后端（LiteDB 默认 / POSTGRES_CONNECTION）

默认存储是 LiteDB 单文件数据库 data/cartracker.db：零配置、备份即拷贝（实测备份 zip 内即 config/userConfig.json + data/cartracker.db 两项）。注入 POSTGRES_CONNECTION=<连接串>（形如 Host=addr:port;Username=u;Password=p;Database=db;）后，下一次启动全部数据访问切换到 PostgreSQL（自动建表）。

切换与回迁实测要点（官方 Postgres 文档核对 + 备份机制实测）：

• 连接串可在 /setup 配置并勾选 Skip（值不入 serverConfig.json，留给环境变量注入）；
• 切 PG 后内置备份只覆盖图片/文档/服务器配置，数据库备份自行负责；
• LiteDB ⇄ PG 双向迁移工具固定在 /migration（仅提供了 PG 连接时可用）：Import to Postgres 选择备份 zip 解出的 cartracker.db 导入；Export from Postgres 导出 cartracker.db 放回备份 zip 恢复；
• 代码层证据：进程启动时"LiteDB is always injected even if user uses Postgres"——LiteDB 引擎常驻，仅数据访问层切换。

5.7 OIDC 单点登录（OpenIDConfig__*）

对接任意 OIDC 提供方（Keycloak/Authentik/Auth0 等），标准键组：Name/ClientId/ClientSecret/AuthURL/TokenURL/RedirectURL（必须 HTTPS，路径固定 <域名>/Login/RemoteAuth）/Scope（通常 email）/UserInfoURL（部分提供方必需）/ValidateState/UsePKCE/DisableRegularLogin（隐藏本地登录、强制跳转 IdP，需配 LogOutURL）。另有两个 root 相关项：EnableRootUserOIDC=true + DefaultReminderEmail=<root邮箱> 时，IdP 返回该邮箱的会话直接映射为 Root 用户。配置同样可在 /setup 图形化完成。

5.8 站点杂项（MOTD / Logo / 附件白名单 / Webhook 等）

六、生产配置模板

6.1 单用户/家庭模板（2C4G 小主机，20GB 磁盘，局域网或 TLS 反代后）

# 环境变量（部署入口注入）
LC_ALL=zh_CN.UTF-8
LANG=zh_CN.UTF-8
LUBELOGGER_MOTD=家庭车辆台账
# EnableAuth 保持默认 false：仅内网可信环境可免认证

// data/config/userConfig.json（Settings 页勾选项，节选）
{ "EnableAuth": false, "UseMPG": false, "UserLanguage": "zh_CN" }

要点：免认证仅在纯内网；对外暴露必须 5.1 开启认证并前置 TLS。

6.2 多用户小型车队模板（4C8G，SSD，对外经 TLS 反代）

# 环境变量
LC_ALL=zh_CN.UTF-8
LANG=zh_CN.UTF-8
LUBELOGGER_MOTD=车队维保台账
LUBELOGGER_DOMAIN=https://fleet.example.com
LUBELOGGER_INVARIANT_API=true            # 若有程序化 API 消费方
LUBELOGGER_AUTO_EVENTS=true              # 到期提醒自动触发
MailConfig__EmailServer=smtp.example.com
MailConfig__EmailFrom=fleet@example.com
MailConfig__Port=587
# SMTP 凭据与 PG 连接串建议走 secrets/环境注入，不落 serverConfig.json

// data/config/userConfig.json（节选）
{ "EnableAuth": true }

要点：对外必开认证 + TLS；注册保持邀请制（默认），LUBELOGGER_OPEN_REGISTRATION 不要开启；数据量到几十万条记录级或需要 DBA 备份体系时切 PostgreSQL（POSTGRES_CONNECTION），并理解切换后内置备份不再覆盖库记录。

七、常见问题（FAQ）

Q1：注入了环境变量但行为没变？ 三步定位：① 横幅核对（SMTP/MOTD/Locale 三项状态是最直观的生效指示器）；② 变量名是否在上文总览表内（LCUBE_* 系列均无效，实测证伪）；③ 是否被 data/config/ 覆盖——JSON 优先级高于环境变量，读出 serverConfig.json/userConfig.json 对应键核对。

Q2：改了 locale 但日期还是老格式？ 区域参数仅进程启动时读取一次，必须重启进程；若要"数字/货币 en_US + 日期 ISO-8601"混合格式，用 LUBELOGGER_LOCALE_DT_OVERRIDE 单独覆盖日期。

Q3：/setup 保存的 SMTP 密码安全吗？ /setup 会把值明文写入 data/config/serverConfig.json（含在 Settings 页制作的备份 zip 内）。生产建议：SMTP/PG 凭据走环境变量注入，/setup 中对连接串类条目勾选 Skip。

Q4：备份 zip 里为什么没有 serverConfig.json？ 实测（v1.7.4）备份 zip 含 config/userConfig.json 与 data/cartracker.db；服务器配置的备份与恢复随版本实现而异，涉及整实例迁移时，请把 data/ 目录整体拷贝（本就只有 cartracker.db 与两个 JSON）。

Q5：认证开了但想临时回到免认证排查问题？ Root 在 Settings 页取消勾选；Root 密码丢失时直接编辑 data/config/userConfig.json 把 EnableAuth 置 false 并重启进程，重设凭据后再打开。操作前先按第二节做备份。

八、参考链接

• 官方 Environment Variables：https://docs.lubelogger.com/Advanced/Environment%20Variables （查询日期 2026-10-30）
• 官方 Server Settings（/setup 配置器）：https://docs.lubelogger.com/Installation/Server%20Settings （查询日期 2026-10-30）
• 官方 Authentication：https://docs.lubelogger.com/Installation/Authentication （查询日期 2026-10-30）
• 官方 Postgres：https://docs.lubelogger.com/Advanced/Postgres （查询日期 2026-10-30）
• 相关文档：《LubeLogger 介绍与选型指南》《LubeLogger 1.7.4 Docker Compose 部署指南》《LubeLogger 1.7.4 REST API 使用详解》