Beaver Habit Tracker v0.10.0 配置参数详解

目标：系统梳理 Beaver Habit Tracker（BeaverHabits）v0.10.0 的全部配置参数——来源、默认值、取值范围、生效方式与实测行为，并给出可直接落地的生产配置模板。BeaverHabits 遵循十二要素（Twelve-Factor）风格，全部配置通过环境变量注入，没有服务端配置文件；参数定义集中在源码 beaverhabits/configs.py 的 Settings 类（基于 pydantic-settings）。本文所有实测均在 Ubuntu 22.04 + BeaverHabits v0.10.0 环境完成，参数定义以 v0.10.0 源码为准（版本查询日期 2026-10-22）。

一、环境信息

二、前置条件

• 已按安装指南部署可运行的 BeaverHabits v0.10.0（源码安装或镜像部署均可，本文示例以源码安装目录 /opt/beaverhabits 与镜像部署目录 /opt/beaverhabits 两种形态给出）；
• 知道自己部署形态对应的配置注入位置：systemd 单元文件（/etc/systemd/system/beaverhabits.service）或 compose 文件（docker-compose.yml）；
• 修改配置前建议先记录当前值，改错导致启动失败时可回滚（所有参数都有代码默认值，删掉自加的配置项即可恢复默认）。

三、参数查看与修改方式

3.1 查看当前生效值

configs.py 在应用启动时实例化全局单例 settings，可直接用项目虚拟环境的 Python 读取任意参数的当前生效值（无需启动服务）：

cd /opt/beaverhabits && .venv/bin/python -c "from beaverhabits.configs import settings; print(\"HABITS_STORAGE=\", settings.HABITS_STORAGE); print(\"MAX_USER_COUNT=\", settings.MAX_USER_COUNT); print(\"JWT_LIFETIME_SECONDS=\", settings.JWT_LIFETIME_SECONDS); print(\"FIRST_DAY_OF_WEEK=\", settings.FIRST_DAY_OF_WEEK); print(\"INDEX_HABIT_DATE_COLUMNS=\", settings.INDEX_HABIT_DATE_COLUMNS)"

实测回显（未注入任何自定义配置时的默认状态）：

HABITS_STORAGE= StorageType.USER_DATABASE
MAX_USER_COUNT= -1
JWT_LIFETIME_SECONDS= 0
FIRST_DAY_OF_WEEK= 0
INDEX_HABIT_DATE_COLUMNS= 5

3.2 修改方式与优先级

按部署形态选择注入位置：

源码安装（systemd 托管）——在单元文件的 [Service] 段加 Environment= 行，每行一个变量，然后重载并重启：

systemctl edit --full beaverhabits   # 或直接编辑 /etc/systemd/system/beaverhabits.service
systemctl daemon-reload
systemctl restart beaverhabits

镜像部署（Docker Compose）——在 docker-compose.yml 的 environment: 段增删变量，然后重建：

docker compose up -d

.env 文件——configs.py 第一行加载逻辑即 dotenv.load_dotenv()，会把工作目录下 .env 文件的内容读入。适合临时验证参数，生产建议统一用 systemd/compose 注入（避免忘记 .env 的存在导致排查困难）。

三者优先级已实测验证：进程环境变量 > .env 文件 > 代码默认值。

cd /opt/beaverhabits && printf "MAX_USER_COUNT=99\n" > .env && .venv/bin/python -c "from beaverhabits.configs import settings; print(\"from .env:\", settings.MAX_USER_COUNT)" && MAX_USER_COUNT=77 .venv/bin/python -c "from beaverhabits.configs import settings; print(\"with env var:\", settings.MAX_USER_COUNT)" && rm .env

实测回显：

from .env: 99
with env var: 77

3.3 生效方式与启动校验

• 所有参数在进程启动时一次性读取，运行中改环境变量不会热生效，必须重启服务进程（systemd restart / compose up -d 重建）；
• 部分参数带启动校验（pydantic field_validator）：TIME_ZONE 非法值会直接阻断启动（见 7.1 节）；REQUIRE_ADMIN_FOR_REGISTRATION=true 而 ADMIN_EMAIL 为空会在启动阶段抛出 RuntimeError（见 7.2 节）。

四、参数总览

v0.10.0 Settings 类全部参数如下（默认值取自源码 configs.py）：

另有启动脚本变量 NICEGUI_STORAGE_PATH（start.sh 读取，生产模式默认 .user/.nicegui，用于存放 Web 框架浏览器存储文件，多用户部署时确保该路径落在数据目录内）。

五、核心参数分类详解

5.1 运行模式（ENV、DEBUG）

• ENV（默认 dev）：运行模式。镜像部署无需设置——官方镜像入口 start.sh prd 内部已执行 export ENV=production；源码安装时由 systemd 单元 Environment=ENV=production 注入（安装指南的单元模板已含）。dev 与 production 的差异主要影响页面调试行为与日志形态；
• DEBUG（默认 False）：调试开关，生产保持默认。

5.2 存储参数（HABITS_STORAGE、DATABASE_URL）

HABITS_STORAGE（默认 USER_DATABASE）决定习惯数据存哪，三个取值：

实测 USER_DISK：注册账号并创建一条习惯后，数据目录出现按邮箱命名的 JSON 文件（admin@example.com.json，98 字节），账号库 habits.db 同时存在——即账号与习惯是两套存储，账号始终在 habits.db，HABITS_STORAGE 只管习惯数据。

⚠️ 两种持久化存储互不相通：从 USER_DATABASE 切到 USER_DISK 后旧习惯不可见（页面报 "The habit list data may be broken or missing"），需先在旧存储下调 GET /api/v1/habits/export 导出 JSON、切到新存储后再导入。切换前务必备份数据目录。

DATABASE_URL（默认 sqlite+aiosqlite:///./.user/habits.db）：账号数据库连接串，SQLAlchemy 异步格式。项目同时内置 asyncpg 驱动（连接串前缀 postgresql+asyncpg://），理论上可指向 PostgreSQL；自托管场景默认 SQLite 已足够（账号写入频率低），改动前需自行验证迁移与兼容性，本文不展开。

5.3 认证与用户管控

JWT_SECRET（默认 SECRET）：登录令牌（JWT）签名密钥。默认值是公开的，生产必须改成随机长字符串，否则任何知道本项目的人都能伪造登录令牌。实测生成方式：

openssl rand -hex 32

实测回显：

f90060a4d50f725a05a235fd5fabb95b390e29074d98ef33431c4e613fcb01ed

JWT_LIFETIME_SECONDS（默认 0）：登录令牌有效期。v0.10.0 使用的 fastapi-users 中 lifetime_seconds=0 不会给令牌写入 exp 过期时间——即默认令牌永不过期（源码 fastapi_users/jwt.py：if lifetime_seconds: 才设置 exp）。单用户自托管可保持默认；多人使用建议设为合理值（如 86400 = 1 天）强制定期重新登录。

MAX_USER_COUNT（默认 -1，即不限制）：达到上限后 Web 注册页不可用。实测设为 1（此时已有用户超出限额）：

curl -s -o /dev/null -w "GET /register -> %{http_code}\n" http://127.0.0.1:8080/register

实测回显：

GET /register -> 404

注册页返回 404（页面不再可用），登录页的「Create account」入口同步隐藏。⚠️ 但该限制只作用于 Web 界面：注册 API POST /auth/register 不受 MAX_USER_COUNT 约束，实测在限额状态下通过 API 仍注册成功：

curl -s -X POST http://127.0.0.1:8080/auth/register -H "Content-Type: application/json" -d '{"email":"tester@example.com","password":"q1w2e3r4"}'

实测回显：

{"id":"eb313d54-007a-4001-9504-8c057d918508","email":"tester@example.com","is_active":true,"is_superuser":false,"is_verified":false}

如需严格封网注册，请配合防火墙/反向代理限制 /auth/register 与 /register 路径，或用下一参数的 REQUIRE_ADMIN_FOR_REGISTRATION。

REQUIRE_ADMIN_FOR_REGISTRATION（默认 False）：设为 true 后注册需管理员认证。⚠️ 该项启用时必须同时设置 ADMIN_EMAIL，否则应用启动即失败（源码 main.py 启动检查：ADMIN_EMAIL must be set when REQUIRE_ADMIN_FOR_REGISTRATION is enabled，抛 RuntimeError）。

TRUSTED_LOCAL_EMAIL（默认空）：设置后该邮箱视为可信用户，访问站点免登录直达，适合内网单用户场景。实测设为 admin@example.com 后：

curl -s -o /dev/null -w "GET / -> %{http_code}\n" http://127.0.0.1:8080/
curl -s -o /dev/null -w "GET /login -> %{http_code}\n" http://127.0.0.1:8080/login

实测回显：

GET / -> 200
GET /login -> 307

首页直接 200（不再跳登录页），/login 反而 307（登录/注册页在可信模式下被禁用，此模式下 GET /register 同样 307）。注意：该邮箱必须是已注册账号。

TRUSTED_EMAIL_HEADER（默认空）：反向代理可信身份头，配合 TRUSTED_LOCAL_EMAIL 的多用户形态（如 Authelia/ProxyAuth 注入 X-Forwarded-Email）。自托管单用户用不到。

RESET_PASSWORD_TOKEN_SECRET（默认空）：密码重置令牌密钥，配置 SMTP 邮件功能时需一并设置。RESET_PASSWORD_TOKEN_LIFETIME_SECONDS（默认 3600）：重置令牌有效期 1 小时。

NICEGUI_STORAGE_SECRET（默认 dev）：Web 框架浏览器存储的加密密钥，生产建议与 JWT_SECRET 一同更换。

5.4 时区与本地化

TIME_ZONE（默认空）：全局时区，IANA 名称。为空时每个用户跟随各自浏览器时区；设置后覆盖所有用户的时区判定（多用户共服时慎用）。实测非法值直接阻断启动（启动日志关键段）：

    settings = Settings()
pydantic_core._pydantic_core.ValidationError: 1 validation error for Settings
  Value error, Invalid TIME_ZONE 'Bad/Zone'. Must be a valid IANA timezone name (e.g. 'America/New_York', 'Europe/London', 'Asia/Tokyo'). [type=value_error, input_value='Bad/Zone', input_type=str]
[2026-10-22 17:08:43 +0000] [6075] [ERROR] Worker (pid:6076) exited with code 3.
[2026-10-22 17:08:43 +0000] [6075] [ERROR] Reason: Worker failed to boot.

FIRST_DAY_OF_WEEK（默认 0）：每周起始日，0=周一 … 6=周日（源码默认 calendar.MONDAY）。

ALIGN_TODAY_TO_DAY_OF_WEEK（默认 None）：把「今天」在网格中对齐到指定周几（0-6），用于整周视图对齐；不设置即跟随真实日期。

DARK_MODE（默认 None）：None 跟随系统深浅色，True 强制深色，False 强制浅色。

5.5 首页与交互定制

以下参数控制习惯网格与交互行为，逐项实测有效（改后重启刷新页面可见）：

• INDEX_HABIT_DATE_COLUMNS（默认 5）：首页网格的日期列数。实测设 7（一周正好 7 天）启动正常、网格变 7 列，是官方 README 示例同款配置；
• INDEX_HABIT_NAME_COLUMNS（默认 5）：名称列在移动端换行时的列数；
• INDEX_HABIT_DATE_REVERSE（默认 False）：日期列倒序显示；
• INDEX_SHOW_HABIT_COUNT（默认 False）：显示习惯总数；
• INDEX_SHOW_HABIT_STREAK（默认 False）：显示连续打卡天数；
• HABIT_SHOW_EVERY_DAY_STREAKS（默认 False）：逐日 streak 统计；
• ENABLE_TAG_FILTERS（默认 True）：标签筛选开关；
• TAG_SELECTION_MODE（默认 MULTI）：习惯打标签时单选（SINGLE）或多选（MULTI）；
• DAILY_NOTE_MAX_LENGTH（默认 1024）：打卡备注字数上限；
• DEFAULT_COMPLETION_STATUS_LIST（默认 ["yes", "no"]）：打卡状态列表，v0.9.1 起支持自定义状态（如 ["done","partial","skip"]），需 JSON 数组格式注入；
• ENABLE_IOS_STANDALONE（默认 True）：iOS「添加到主屏幕」全屏模式支持，保持默认。

5.6 备份参数

• ENABLE_DAILY_BACKUP（默认 False）：应用内置定时备份开关。开启后应用按 DAILY_BACKUP_INTERVAL（默认 86400 秒 = 1 天）周期把数据导出到数据目录。自托管更稳的做法是外部 cron/timer 对数据目录做快照（见部署指南的备份章节），两者可并用。

5.7 SaaS 与集成类参数（自托管一般不用）

以下参数服务官方 SaaS 实例（beaverhabits.com）或可选集成，自托管保持默认即可：

• APP_URL：站点对外地址，源码中把密码重置链接拼为 APP_URL 下的 /reset-password?token= 路径。仅在启用密码重置邮件时需要设为你的对外地址；
• SMTP_EMAIL_USERNAME / SMTP_EMAIL_PASSWORD：发送密码重置邮件的 SMTP 凭据。源码 send_email() 写死连接 smtp.gmail.com:465（SMTP_SSL），即目前仅支持 Gmail 账号 + 应用专用码，其他邮箱服务不可用；
• SENTRY_DSN、HIGHLIGHT_KEY、HIGHLIGHT_IO_PROJECT_ID、UMAMI_ANALYTICS_ID、UMAMI_SCRIPT_URL：错误追踪与访问统计的第三方上报，留空即不上报；
• ENABLE_PLAN、MAX_HABIT_COUNT、PADDLE_*（6 项）：SaaS 订阅计费（Paddle 支付）相关，自托管无计费场景；
• GUI_MOUNT_PATH（默认 /gui）、DEMO_MOUNT_PATH（默认 /demo）：官方 SaaS 的管理/演示页挂载路径，自托管保持默认；
• GOOGLE_ONE_TAP_CLIENT_ID / GOOGLE_ONE_TAP_ENABLED / GOOGLE_ONE_TAP_CALLBACK_URL：Google One Tap 一键登录，需要 Google Cloud 凭据，默认关闭。

六、生产配置模板

单用户/小团队自托管场景的推荐配置模板，按部署形态二选一。

模板要点：更换两个密钥；显式固定时区；习惯数据选一种存储方式并坚持使用；无需求不开启注册管控。内存量级参考：单 worker gunicorn 进程实测常驻约 145–160MB（systemd 单元实测 Memory: 145.0M，镜像部署 docker stats 实测 156.8MiB）；磁盘以数据目录为主（初始 habits.db 94208 字节，习惯数据增长缓慢，一般 <10MB/年/用户量级）。

systemd 形态（/etc/systemd/system/beaverhabits.service 的 [Service] 段）：

[Service]
User=beaver
Group=beaver
WorkingDirectory=/opt/beaverhabits
Environment=ENV=production
Environment=HABITS_STORAGE=USER_DATABASE
Environment=TIME_ZONE=Asia/Shanghai
Environment=JWT_SECRET=f90060a4d50f725a05a235fd5fabb95b390e29074d98ef33431c4e613fcb01ed
Environment=NICEGUI_STORAGE_SECRET=d850857417fa8021042fde5fcd005a54f659ffb78588f9b73925fe253f5c2b6b
Environment=NICEGUI_STORAGE_PATH=/opt/beaverhabits/.user/.nicegui
ExecStart=/opt/beaverhabits/.venv/bin/gunicorn beaverhabits.main:app --bind 0.0.0.0:8080 -w 1 -k uvicorn_worker.UvicornWorker --max-requests 10000 --log-level info
Restart=on-failure
RestartSec=5

应用并验证：

systemctl daemon-reload && systemctl restart beaverhabits && systemctl is-active beaverhabits

实测回显：

active

Docker Compose 形态（docker-compose.yml）：

name: beaver-habit-tracker-0100-stack
services:
  beaverhabits:
    image: daya0576/beaverhabits:0.10.0
    container_name: beaverhabits
    user: "1000:1000"
    environment:
      - HABITS_STORAGE=USER_DISK
      - TIME_ZONE=Asia/Shanghai
      - JWT_SECRET=f90060a4d50f725a05a235fd5fabb95b390e29074d98ef33431c4e613fcb01ed
      - NICEGUI_STORAGE_SECRET=d850857417fa8021042fde5fcd005a54f659ffb78588f9b73925fe253f5c2b6b
      - INDEX_HABIT_DATE_COLUMNS=7
    volumes:
      - ./beaver/:/app/.user/
    ports:
      - "8080:8080"
    restart: unless-stopped

两个模板中的密钥值仅为格式示例，请用 openssl rand -hex 32 现场生成自己的值，不要照抄本文。

七、常见问题

7.1 设置 TIME_ZONE 后服务起不来

现象：启动日志出现 pydantic_core._pydantic_core.ValidationError: 1 validation error for Settings、Invalid TIME_ZONE 'Bad/Zone'. Must be a valid IANA timezone name，随后 Worker (pid:6076) exited with code 3.、Reason: Worker failed to boot.（systemd 表现为反复重启，compose 表现为 Restarting）。

原因与处理：TIME_ZONE 只接受合法 IANA 时区名（Asia/Shanghai、America/New_York 这类，可用 timedatectl list-timezones 查询本机可用值），任意自造值都会在启动校验阶段被拒。改回合法值重启即可。

7.2 开启 REQUIRE_ADMIN_FOR_REGISTRATION 后启动报 RuntimeError

现象：启动日志出现 RuntimeError: ADMIN_EMAIL must be set when REQUIRE_ADMIN_FOR_REGISTRATION is enabled。

原因：v0.10.0 在启动阶段强制校验该组合（源码 main.py），开启注册管控必须指定管理员邮箱。

处理：补一条 Environment=ADMIN_EMAIL=admin@example.com（值需为已注册账号），重启；或去掉 REQUIRE_ADMIN_FOR_REGISTRATION 恢复默认。

7.3 MAX_USER_COUNT 设了上限，注册页打不开但 API 还能注册

现象：设 MAX_USER_COUNT=1 后 GET /register 返回 404，但直接 POST /auth/register 依然成功。

原因：该限制只作用于 Web 界面（隐藏注册入口、注册页返回 404），注册 API 不校验此值（实测见 5.3 节）。

处理：需要彻底关闭注册时，用防火墙/反向代理拦截 /register 与 /auth/register 路径，或开启 REQUIRE_ADMIN_FOR_REGISTRATION + ADMIN_EMAIL。

7.4 切换 HABITS_STORAGE 后旧习惯不见了

现象：从默认 USER_DATABASE 切到 USER_DISK（或反向）后，登录成功但习惯列表为空/报 "The habit list data may be broken or missing"。

原因：两套存储完全独立，切换不会自动迁移数据（见 5.2 节）。

处理：切回原存储确认数据还在；如确需切换，先在旧存储下调 GET /api/v1/habits/export 导出 JSON，切到新存储后导入。操作前备份数据目录。

7.5 .env 文件里的配置没生效 / 行为诡异

现象：明明写了 .env，systemd/compose 注入的却是另一个值；或反过来。

原因：优先级为进程环境变量 > .env 文件 > 代码默认值（实测见 3.2 节），两处同时配置时 .env 会被环境变量覆盖。

处理：生产环境只保留一种注入渠道（推荐 systemd/compose），删除多余的 .env 文件；用 3.1 节的方法读取 settings 确认实际生效值。

7.6 JWT_SECRET 一直用默认值有风险吗

有。默认值 SECRET 是公开源码的一部分，持有默认密钥的攻击者可自签发合法登录令牌，直接绕过认证。生产部署务必替换为随机值（openssl rand -hex 32），替换后所有已登录会话失效、需重新登录，属预期行为。同理建议一并更换 NICEGUI_STORAGE_SECRET。

八、参考链接

• 参数定义源码（v0.10.0）：https://github.com/daya0576/beaverhabits/blob/v0.10.0/beaverhabits/configs.py
• 环境变量 Wiki：https://github.com/daya0576/beaverhabits/wiki/Env
• GitHub 仓库：https://github.com/daya0576/beaverhabits
• 组件介绍与选型：《Beaver Habit Tracker v0.10.0 介绍与选型指南》
• 源码安装与 systemd 托管：《Ubuntu 22.04 安装 Beaver Habit Tracker v0.10.0 指南》
• Docker Compose 部署：《Beaver Habit Tracker v0.10.0 Docker Compose 部署指南》
• REST API（导出/导入习惯数据）：《Beaver Habit Tracker v0.10.0 API 使用详解》