LubeLogger 1.7.4 Docker Compose 部署指南

目标：用官方 Docker Compose 从零把 LubeLogger 1.7.4 跑起来，覆盖镜像选型、启动与首启横幅解读、首次访问与认证启用（Root 用户创建）、数据持久化验证、环境变量与配置文件挂载、升级与常用运维。全部步骤与回显均在 Ubuntu 22.04 宿主上实测（v1.7.4，Web 端口 8131 → 8080）。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64，Linux 5.15）
• Docker：29.9.2，Compose v2（docker compose 子命令可用）
• LubeLogger：v1.7.4（镜像 hargata/lubelogger:v1.7.4，摘要 sha256:483a9d7582c4e6258615fd822b3de4193b4fcc4230d0a92432c6d407faf75af2）
• 运行时：镜像内为 .NET 10 运行时（实测 Microsoft.NETCore.App 10.0.13 / Microsoft.AspNetCore.App 10.0.13）
• 监听端口：容器内固定 8080；宿主映射端口 8131（本机 80/8080 已被占用，故选空闲端口映射，读者可按需改为 80/8080）
• 部署目录：/opt/lubelogger/（本文以该路径书写；数据卷 bind mount 在其下）
• 网络：Compose 项目名 lubelogger-1.7.4-stack，自定义 bridge 网段 10.89.57.0/24

⚠️ 说明：官方 docker-compose.yml 使用 ghcr.io/hargata/lubelogger:latest 与具名卷。本文做两处本地适配并逐处标注：1) 镜像改用 Docker Hub 同名官方仓库 hargata/lubelogger 并锁定 v1.7.4 tag（版本可复现）；2) 端口映射改 8131:8080。其余保持官方原样，读者可按需还原官方值。

二、镜像选型说明

LubeLogger 官方维护两条等价的镜像发布通道：

选型要点：版本锁定优先选 v<版本号> tag（本篇实测 v1.7.4）；两条通道镜像内容一致，按网络可达性任选其一。镜像基于 mcr.microsoft.com/dotnet/aspnet:10.0 构建单层运行时镜像，应用可执行文件为 ./CarCareTracker，容器内固定监听 8080。

三、前置条件

1. 宿主已安装 Docker 与 Compose v2：docker compose version 能正常输出版本；
2. 宿主映射端口（本文 8131）未被占用：ss -ltn | grep 8131 应无输出；
3. 磁盘余量 ≥ 2 GB（镜像约数百 MB + 数据目录）；
4. 可访问 Docker Hub / GHCR（或已配置加速/代理）。

宿主就绪的实测回显：

$ docker compose version
Docker Compose version v2.x
$ ss -ltn | grep 8131
（无输出，端口可用）

四、部署步骤

4.1 建目录并写入 compose 文件

mkdir -p /opt/lubelogger && cd /opt/lubelogger
vi docker-compose.yml

docker-compose.yml 全文（官方模板 + 本文两处适配，均已注释）：

name: lubelogger-1.7.4-stack

services:
  lubelog:
    image: hargata/lubelogger:v1.7.4        # 官方为 ghcr.io/hargata/lubelogger:latest，本文锁定 v1.7.4
    container_name: lubelogger-1-7-4-web
    restart: unless-stopped
    ports:
      - "8131:8080"                          # 宿主端口按实际空闲端口调整
    environment:
      - LC_ALL=en_US.UTF-8                   # 区域与语言（数字/货币/日期格式），可改 zh_CN.UTF-8 等
      - LANG=en_US.UTF-8
      - LUBELOGGER_MOTD=Welcome to LubeLogger demo instance   # 登录页 MOTD，可留空
    volumes:
      - ./data:/App/data                     # 数据目录（数据库+附件+配置），必须持久化
      - ./translations:/App/translations     # 自定义语言包（官方模板建议挂载）
      - ./config:/App/config                 # 旧版配置目录兼容位（官方模板建议挂载）
      - keys:/root/.aspnet/DataProtection-Keys   # 官方模板要求的密钥卷（认证 Cookie 加密键）
    networks:
      lubelog-net:
        ipv4_address: 10.89.57.10

networks:
  lubelog-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.57.0/24
          gateway: 10.89.57.1

volumes:
  keys:

配置逐项说明：

• LC_ALL/LANG：不配置时启动横幅会打印 WARNING: No Locale or Culture Configured，日期/数字/货币按进程默认区域渲染；这是给 API 与界面统一格式的推荐入口（更细粒度的覆盖见配置详解篇）；
• LUBELOGGER_MOTD：登录页"每日一句"，纯展示项，不配则横幅显示 Not Configured；
• ./data:/App/data：唯一承载全部状态的目录，LiteDB 数据库 cartracker.db、附件、图片、用户/服务器配置 JSON、备份 zip 全在其中；
• keys 具名卷：ASP.NET Core DataProtection 密钥目录，不持久化时容器重建后已签发的登录 Cookie 会全部失效（需重新登录），数据不丢；
• 固定网段与 IP 为可选配置，便于有防火墙/互通要求的场景。

4.2 拉取镜像并启动

cd /opt/lubelogger
docker compose pull
docker compose up -d

实测回显（拉取）：

v1.7.4: Pulling from hargata/lubelogger
Digest: sha256:483a9d7582c4e6258615fd822b3de4193b4fcc4230d0a92432c6d407faf75af2
Status: Downloaded newer image for hargata/lubelogger:v1.7.4

实测回显（启动）：

 Container lubelogger-1-7-4-web Creating
 Container lubelogger-1-7-4-web Created
 Container lubelogger-1-7-4-web Starting
 Container lubelogger-1-7-4-web Started

4.3 状态与首启横幅验证

docker compose ps
docker compose logs lubelog | head -20

实测回显（ps）：

NAME                   IMAGE                       COMMAND              SERVICE   CREATED         STATUS         PORTS
lubelogger-1-7-4-web   hargata/lubelogger:v1.7.4   "./CarCareTracker"   lubelog   8 seconds ago   Up 8 seconds   0.0.0.0:8131->8080/tcp, [::]:8131->8080/tcp

首启横幅（logs，逐行解读见第八节）：

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: Welcome to LubeLogger demo instance
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://[::]:8080
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: /App

（本实例已注入 LC_ALL/LANG 与 LUBELOGGER_MOTD，故横幅无 Locale 警告且 MOTD 已显示；对照含义见第八节。）

Web 就绪验证：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8131/

实测回显：200（认证未启用时直接返回车库页；认证启用后未带 Cookie 访问会 302 跳登录页，见 4.4）。

4.4 首次初始化：启用认证并创建 Root 用户

LubeLogger 默认不启用认证，首次访问无需登录。生产暴露前务必完成本节（多用户模型与权限分层见介绍篇）：

1. 浏览器访问 http://<宿主IP>:8131/，进入 Garage（车库）页；
2. 顶部导航进入 Settings 页；
3. 勾选 Enable Authentication 开关，弹出凭据设置对话框；
4. 输入 Root 用户名与密码（本文演示 admin / q1w2e3r4），点击 Setup，页面跳转登录页；
5. 用该凭据登录。

实测登录接口回显（凭据正确）：

{"success":true,"message":""}

凭据落盘实测（data/config/userConfig.json 关键字段，哈希与 sha256sum 逐位核对一致）：

"EnableAuth": true,
"UserNameHash": "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918",
"UserPasswordHash": "13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9"

启用后未带 Cookie 访问首页的实测表现：

$ curl -s -o /dev/null -w '%{http_code} redirect:%{redirect_url}\n' http://127.0.0.1:8131/
302 redirect:http://127.0.0.1:8131/Login

⚠️ 排障实录：Setup 完成后立即用 curl 登录出现过一次 {"success":false,"message":"Invalid Login Credentials"}，几秒后重试即成功——原因是配置文件以 reloadOnChange 方式挂入配置系统，文件监听重载存在秒级时滞；浏览器操作自然间隔内不会遇到。遇到时先等几秒再试，若持续失败核对 data/config/userConfig.json 是否已生成且 EnableAuth 为 true。

新用户注册为邀请制：Root 用户登录后经右上角用户菜单进入 Admin Panel → Manage Tokens 生成注册令牌（配置 SMTP 后可自动发邮件，否则手动转交），受邀人在登录页 Register 链接凭令牌注册。SMTP 配置见配置详解篇。

五、数据持久化说明

5.1 状态目录布局

./data:/App/data 挂载后的实测布局：

data/
├── cartracker.db         # LiteDB 主库（车辆、记录、用户、令牌）
├── config/
│   ├── userConfig.json   # 用户级配置（认证开关、root 哈希）
│   └── serverConfig.json # 服务器配置（/setup 写入：SMTP/OIDC/区域等）
├── documents/  images/  temp/  themes/  translations/

5.2 重启后数据保持实测

录入数据 → docker compose down && up -d → 登录与数据复查，实测链路：

docker compose down
docker compose up -d

实测回显（down）：

 Container lubelogger-1-7-4-web Stopping
 Container lubelogger-1-7-4-web Stopped
 Container lubelogger-1-7-4-web Removed

重启后实测：登录接口仍返回 {"success":true,"message":""}，此前录入的车辆与记录完好，cartracker.db 与 config/*.json 均在宿主 ./data 下。注意：若未挂载 keys 卷，容器重建后旧登录 Cookie 会因 DataProtection 密钥更换而失效（重新登录即可，数据不受影响）。

5.3 备份与恢复

• 页面路径：Root 用户登录 → Settings → Make Backup / Restore Backup（仅 Root 可用）；
• API 路径：GET /api/makebackup（Basic 认证），实测返回 "/temp/db_backup_2026-10-30-14-36-22.zip"；
• 备份 zip 实测清单：config/userConfig.json + data/cartracker.db——一个 zip 即完整可恢复状态；
• zip 落在容器 /App/data/temp/，即宿主 ./data/temp/，可另行异地保存。

六、环境变量表

以下为 LubeLogger 支持的环境变量全项（官方文档「Environment Variables」+ 源码核对，v1.7.4）：

⚠️ 排障提示：网上旧资料流传的 LCUBE_LOGLEVEL、LCUBE_SENTRY_ENABLED、LCUBE_SMTP_ENABLED 等变量在 v1.7.4 中不存在（官方文档与源码均无），注入后无任何效果，属无效配置；本机实测曾误注入并被启动横幅证伪，请以本表为准。

七、配置参数说明

环境变量只是配置入口之一。启动横幅是配置生效与否的"总仪表"，三种典型状态实测对照：

除环境变量外，两份 JSON 配置由 Settings 页（/setup 服务器配置器）可视化维护并直接落盘到 data/config/，改完重启进程生效。逐项含义、优先级与生产模板详见《LubeLogger 1.7.4 配置参数详解》。

八、配置文件挂载

官方 compose 建议挂载三个目录/卷，实测职责如下：

data/config/serverConfig.json 是服务器设置的唯一落盘文件（含 SMTP、OIDC、Postgres 连接串、区域覆盖），由 /setup 页写入；其中个别条目（如 Postgres 连接串）可勾选 Skip 留给环境变量注入，避免明文入库。

九、等价 docker run

不使用 Compose 时的等价单命令（与 4.1 compose 语义一致）：

docker run -d \
  --name lubelogger-1-7-4-web \
  --restart unless-stopped \
  -p 8131:8080 \
  -e LC_ALL=en_US.UTF-8 \
  -e LANG=en_US.UTF-8 \
  -e LUBELOGGER_MOTD=Welcome \
  -v /opt/lubelogger/data:/App/data \
  -v /opt/lubelogger/translations:/App/translations \
  -v /opt/lubelogger/config:/App/config \
  -v lubelogger-keys:/root/.aspnet/DataProtection-Keys \
  hargata/lubelogger:v1.7.4

启动后同样以 curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8131/ 验证（实测 200）。多实例长期维护仍建议用 Compose（声明式、可复制）。

十、常用运维命令

cd /opt/lubelogger
docker compose ps                     # 实例状态与端口映射
docker compose logs -f lubelog        # 跟踪日志（横幅与运行日志）
docker compose stop                   # 停止（保留容器）
docker compose up -d                  # 启动/变更后重建
docker compose down                   # 停止并删除容器（data 目录在宿主，不受影响）

升级流程（官方 Upgrade 文档：先备份、核对卷挂载、再 pull+up）：

curl -s -u admin:q1w2e3r4 http://127.0.0.1:8131/api/makebackup   # 1. 先备份（实测返回 /temp/db_backup_*.zip）
docker compose pull                                              # 2. 拉新镜像
docker compose up -d                                             # 3. 重建容器（数据卷不变）

版本回退：把 compose 中 image tag 改回旧版本号后 docker compose up -d；数据目录兼容性以官方 Release Notes 为准，大版本降级前务必用备份 zip 演练恢复。

十一、常见问题（FAQ）

Q1：启动失败，日志报 Failed to bind to address http://[::]:8080: address already in use？ 容器内 8080 被占即进程被重复拉起（本机排障时曾误在容器内手动二次启动 ./CarCareTracker 复现该报错）。正常单容器部署不会遇到；若遇到，确认只有一个入口进程（docker compose ps 只有一个实例）。

Q2：/swagger 打不开（404）？ LubeLogger 没有部署 Swagger UI，接口文档页固定在 /api（实测 74 个端点的交互式文档）。认证启用后 /api 同样需要登录或 Basic 认证（未带凭据实测 401）。

Q3：启用认证后第一次登录就失败（Invalid Login Credentials）？ 见 4.4 排障实录：配置文件 reloadOnChange 有秒级时滞，等几秒重试；持续失败再核对 data/config/userConfig.json 的 EnableAuth 与哈希字段。

Q4：受邀用户点 Register 收不到注册令牌？ SMTP 未配置（横幅 SMTP Not Configured）。两条路：配置 SMTP（/setup 或 MailConfig__* 环境变量，配置详解篇有逐项说明）；或管理员在 Admin Panel 生成令牌后手动转交。LUBELOGGER_OPEN_REGISTRATION=true 可放开自助取令牌，仅在可信网络使用。

Q5：忘记 Root 密码怎么办？ 有管理权限的处理：直接改宿主 data/config/userConfig.json——把 EnableAuth 置 false 重启即回到免认证状态，再从 Settings 页重新设置凭据；或持有备份 zip 时经 Restore Backup 恢复旧凭据。

Q6：镜像拉取慢或失败？ 按「官方源 → 加速/代理」降级：优先直连 Docker Hub（本实测环境直连成功）；不通则配置镜像加速或代理后再 docker compose pull。GHCR 通道 ghcr.io/hargata/lubelogger 与 Docker Hub 内容等价，可互换。

十二、参考链接

• 官方 Getting Started：https://docs.lubelogger.com/Installation/Getting%20Started （查询日期 2026-10-30）
• 官方 Upgrade Guide：https://docs.lubelogger.com/Installation/Upgrade （查询日期 2026-10-30）
• 官方 Environment Variables：https://docs.lubelogger.com/Advanced/Environment%20Variables （查询日期 2026-10-30）
• 仓库 compose 模板：https://github.com/hargata/Lubelog/blob/main/docker-compose.yml
• 相关文档：《LubeLogger 介绍与选型指南》《LubeLogger 1.7.4 配置参数详解》《LubeLogger 1.7.4 REST API 使用详解》