Beaver Habit Tracker v0.10.0 介绍与选型指南

目标：面向准备自托管习惯打卡（Habit Tracking）服务的个人与小团队，介绍 Beaver Habit Tracker（BeaverHabits）v0.10.0 的定位、架构、功能与同类竞品差异，并给出量化选型建议。本篇为认知篇，全部数据来自官方仓库与官方文档的联网溯源（来源与查询日期在各节标注），未做本地实测；安装、部署、配置与 API 的实测细节见本专栏后续各篇。

一、环境信息

本篇为联网溯源认知篇，不涉及本地实验环境。所有事实的取证来源与查询日期统一说明如下（查询日期均为 2026-10-22）：

• 项目仓库：GitHub daya0576/beaverhabits（README、releases.atom 发布源、源码文件 pyproject.toml、start.sh、docker/Dockerfile、beaverhabits/configs.py 均按 v0.10.0 标签实查）；
• 版本与发布时间：GitHub Releases（https://github.com/daya0576/beaverhabits/releases.atom）；
• 社区热度：shields.io 徽章（img.shields.io/github/stars/...、img.shields.io/docker/pulls/...）；
• 容器镜像标签：Docker Hub Registry API（hub.docker.com/v2/repositories/daya0576/beaverhabits/tags）；
• 功能清单：官方 Wiki（Environment-variables、API How-to Guide 等页面）；
• 官方在线服务：https://beaverhabits.com（含 Demo 与定价页）。

💡 说明：文中标注「实查」的数据均为上述来源在 2026-10-22 的快照值；社区热度类数字（星数、拉取量）会随时间变化，引用时建议重新取证。

二、软件概述

Beaver Habit Tracker（官方简称 BeaverHabits）是一个「无目标（without Goals）」理念的自托管习惯打卡 Web 应用：它刻意去掉主流习惯应用常见的目标设定、连续打卡压力（Streak 焦虑）与游戏化激励，只保留「今天做了就打个勾」这一件事，并用热力图回顾历史完成情况。项目由开发者 Henry Zhu（GitHub ID：daya0576）创建，采用 BSD-3-Clause 许可证开源（v0.10.0 仓库 LICENSE 文件实查：Copyright (c) 2024, Henry Zhu），首次公开发布于 2024 年 3 月（selfhostyourself.com 组件档案，查询日期 2026-10-22）。

几个关键身份信息（均为 2026-10-22 实查）：

• 最新稳定版本：v0.10.0，发布于 2026-07-30（GitHub Releases 实查，为当前最新 release；此后官方镜像另有 nightly 构建，见下文镜像选型）；
• 技术栈：Python（pyproject.toml 声明 requires-python = ">=3.12,<4.0"）+ NiceGUI（服务端驱动的 Python Web UI 框架）+ FastAPI 生态 + SQLAlchemy 2.0 异步引擎；
• 交付形态：自托管 Docker 镜像（官方主推）、源码部署、官方 SaaS（beaverhabits.com，免费额度 + 付费计划）、Unraid Community Apps、Easypanel 一键模板、Fly.io 部署配置（仓库内置 fly.toml）；
• 社区热度：GitHub Stars 1.8k，Docker 镜像累计拉取 572k（shields.io 徽章实查）；
• 版本节奏：2025-12 至 2026-07 共发布 v0.8.0（2025-12-02）、v0.8.1（2026-01-04）、v0.8.2（2026-02-03）、v0.9.0（2026-02-20）、v0.9.1（2026-05-20）、v0.10.0（2026-07-30）六个稳定版，平均 4-8 周一个版本（releases.atom 实查），维护活跃。

产品理念上需要注意它与其他习惯类应用的分野：BeaverHabits 官方 README 的自我定义只有一句话——"A self-hosted habit tracking app without 'Goals'"。它不提供目标拆解、任务管理、提醒推送（截至 v0.10.0 无内置提醒渠道）等能力；与之相对，它的打卡操作被做到极简（一键勾选、支持回溯补卡），数据完全自有（SQLite 或 JSON 文件落盘）。选型时先确认自己要的是「极简打卡记录」还是「任务/目标管理系统」，这是它最核心的适用边界。

三、核心架构

以下内容基于 v0.10.0 源码实查（pyproject.toml、start.sh、docker/Dockerfile、beaverhabits/main.py、beaverhabits/configs.py、beaverhabits/routes/api.py，查询日期 2026-10-22）。

3.1 技术栈与运行形态

生产启动命令（start.sh prd 分支实查）为：gunicorn beaverhabits.main:app --bind 0.0.0.0:8080 -w 1 -k uvicorn_worker.UvicornWorker --max-requests 10000 --log-level info，监听 8080 端口。官方 Dockerfile 附加了容器健康检查（HEALTHCHECK ... CMD python healthcheck.py，30 秒间隔 / 3 秒超时 / 3 次重试）。

3.2 数据模型与存储三态

BeaverHabits 的存储设计有三种可切换后端（configs.py 的 StorageType 枚举实查），由环境变量 HABITS_STORAGE 控制：

💡 技术拓展：自托管应用的「数据落盘格式」常见三种流派——嵌入式单文件数据库（SQLite，查询/事务强）、纯文件（JSON/CSV，人可直接读改、版本管理友好）、独立数据库服务（PostgreSQL/MySQL，多实例与高并发强）。BeaverHabits 采用「账号库固定 SQLite + 习惯数据可选 SQLite/JSON」的混合式：注册账号、认证令牌始终存于 SQLite（DATABASE_URL 默认 sqlite+aiosqlite:///./.user/habits.db），只有习惯打卡数据受 HABITS_STORAGE 控制。本方案实际默认采用 DATABASE（SQLite），理由是零外部依赖且与账号库同文件便于整体备份；两种后端数据互不相通，切换需先导出再导入（本专栏《配置参数详解》篇有实测说明）。

无论哪种后端，全部用户数据都收敛在 .user/ 目录内——这决定了部署时只需持久化这一个目录（官方 docker run 示例即挂载 -v ./beaver/:/app/.user/）。

3.3 接口与扩展机制

• Web UI：NiceGUI 服务端页面（挂载于根路径），登录页、打卡热力图、统计视图均由服务端 Python 渲染，浏览器仅承担交互；
• REST API：挂载于 /api/v1 前缀（routes/api.py 实查），覆盖习惯的增删改查、打卡记录、排序元数据与全量导出，认证支持 JWT（/auth/login 签发）与长期 API Token；
• 实时同步：v0.10.0 新增认证 WebSocket 端点 /api/v1/sync/ws（Release Notes 实查），为 iOS 原生客户端等第三方端提供打卡指令的确认（ack）与多设备广播（fan-out）；
• 任务调度：内置每日备份调度器（main.py lifespan 实查：ENABLE_DAILY_BACKUP 开启时创建 daily_backup_task 循环任务）；
• 集成生态（README「Derivatives」节实查）：HabitDeck（Stream Deck 实体按键打卡）、Home Assistant Switch（智能家居开关打卡）、CalDAV bridge（把习惯同步为日历任务）、iOS 原生客户端（offline-first）、OpenClaw AI 技能（自然语言管理习惯，v0.9.0 引入）。

四、功能特性

综合官方 README、Wiki 与 v0.8.0 → v0.10.0 发布说明（查询日期 2026-10-22），v0.10.0 的功能面如下：

核心打卡

• 首页按日期列展示习惯矩阵，点击即打卡/取消，支持回溯任意历史日期补卡；
• 热力图（heatmap）视图回顾长期完成情况，可自定义日期列数（INDEX_HABIT_DATE_COLUMNS，默认 5）、日期倒序（INDEX_HABIT_DATE_REVERSE）、周起始日（FIRST_DAY_OF_WEEK）；
• 完成状态可扩展：v0.8.1 起打卡不再只有「完成/未完成」，支持自定义状态（如 skip、failed），v0.9.1 增加完成状态总览页（DEFAULT_COMPLETION_STATUS_LIST 默认 ["yes","no"]）；
• Streak（连续完成）统计与图标自定义、备注（note）标签驱动 streak 定制（v0.8.0/v0.8.1）。

多用户与认证

• 多用户注册/登录（fastapi-users），JWT 会话或长期 API Token（v0.9.0+，菜单位置 Menu → Tools → API Tokens）；
• 可用 MAX_USER_COUNT 限制注册人数、REQUIRE_ADMIN_FOR_REGISTRATION 要求管理员审批注册；
• 三种免密接入：反代透传头（TRUSTED_EMAIL_HEADER，如 Cloudflare Access）、本机免登录邮箱（TRUSTED_LOCAL_EMAIL）、Google One Tap（GOOGLE_ONE_TAP_*）。

数据管理

• 一键导出/导入习惯列表（JSON），API 侧另有 /api/v1/habits/export 全量导出；v0.10.0 增加无损快照导出（面向原生客户端全量同步）；
• 内置每日自动备份（ENABLE_DAILY_BACKUP + DAILY_BACKUP_INTERVAL，默认间隔 86400 秒）。

界面与体验

• 深色模式（DARK_MODE，默认跟随系统 auto）、全局视图页（v0.8.1，可自定义日期范围）、标签筛选（ENABLE_TAG_FILTERS）、星标置顶；
• iOS 添加到主屏幕的 standalone 模式（ENABLE_IOS_STANDALONE，默认开启）；
• 自定义 CSS 注入（v0.9.1 起对注入内容剥离 HTML 标签，修复存储型 XSS）。

明确不做的（截至 v0.10.0，README/Wiki 实查）：无目标/子任务体系、无内置消息提醒渠道（邮件/推送）、无移动端官方安卓应用、无多人共享同一习惯列表的协作模式。

五、快速开始

以下为官方 README 推荐的最小自托管启动方式（Docker 命令原文引自 github.com/daya0576/beaverhabits README，查询日期 2026-10-22；本篇认知篇不含本地实测回显，逐命令实测见本专栏《Ubuntu 22.04 安装指南》与《Docker Compose 部署指南》）。

方式一：单条 docker run（官方原文）：

docker run -d --name beaverhabits \
  -u $(id -u):$(id -g) \
  -e HABITS_STORAGE=USER_DISK \
  -v ./beaver/:/app/.user/ \
  -p 8080:8080 \
  daya0576/beaverhabits:latest

方式二：Docker Compose（官方原文，建议显式固定版本标签 0.10.0，见第七节选型建议）：

services:
  beaverhabits:
    container_name: beaverhabits
    user: 1000:1000 # User permissions of your docker or default user.
    environment:
      - HABITS_STORAGE=USER_DISK
      - TRUSTED_LOCAL_EMAIL=your@email.com # Skip authentication
      - INDEX_HABIT_DATE_COLUMNS=5
      - ENABLE_IOS_STANDALONE=true
    volumes:
      - ./beaver/:/app/.user/
    ports:
      - 8080:8080
    restart: unless-stopped
    image: daya0576/beaverhabits:latest

启动后浏览器访问 http://<服务器IP>:8080，首次进入会出现注册/登录页（官方 README 与 Demo 站行为）；注册首个账号即管理员可开始创建习惯。官方 README 特别提示：容器内进程以非特权用户运行以提升安全性，需保证宿主机挂载目录属主 UID 与容器内 UID 一致，否则会遇到写入权限问题（官方讨论区 discussions/31 收录了该问题的处理方式）。

💡 说明：若只想先体验产品形态，官方提供在线 Demo（https://beaverhabits.com/demo，README 实查），无需部署即可感受打卡交互；确认适用后再自托管。

六、适用场景与限制

适合的场景

1. 个人「每日必做清单」打卡：晨跑、喝水、背单词、服药提醒记录等少量固定习惯（默认 MAX_HABIT_COUNT=5 亦暗示单用户习惯数量的小而美定位）；
2. 数据自有的隐私敏感用户：全部数据落在自己服务器的一个目录，可自行备份、迁移、用脚本二次加工；
3. 有一台常开小主机/NAS（Unraid 有官方应用市场入口）且想要零依赖轻量服务的用户：单容器 + 单目录挂载 + 512MB 级内存即可运行；
4. 想把打卡动作嵌入已有自动化的用户：REST API + API Token + WebSocket 同步，可对接 Stream Deck、Home Assistant、iOS 快捷指令等（生态衍生项目均基于此）。

限制与不适合

1. 需要目标体系、周期任务管理、提醒推送的，它功能面刻意克制，应选任务管理类工具（如 Vikunja、Leantime 一类）或游戏化激励的 Habitica；
2. 团队多人协作打卡（共享同一习惯、互相监督）没有内建支持；
3. 单机 SQLite/JSON 存储 + 单 worker 运行形态决定了它面向个人/小家庭规模，不适合大用户量并发场景；
4. 无官方中文界面语言包之外的本地化定制渠道（界面语言以官方发布为准，选型前建议先在 Demo 站确认语言与交互习惯）。

七、同类选型对比

习惯追踪赛道里，自托管 Web 服务与移动端应用定位差异明显。下表选取三个有代表性的同类项目，量化维度均取自各官方仓库（星数与版本为 shields.io 徽章实查，查询日期 2026-10-22；Loop Habit Tracker 为移动端应用，经 Play/F-Droid 分发，无 GitHub release 产物）：

如何选型（「如果…则…」建议）

• 如果你要「极简、数据自有、能进homelab」的打卡服务，且可能用 API 联动其他设备 → BeaverHabits：三者的交集定位，唯一同时满足自托管 Web + 极简 + 开放 API 的；
• 如果你需要「激励体系」才能坚持（角色升级、任务奖励、惩罚机制）→ Habitica：游戏化做得最完整，代价是部署与维护重量显著上升；
• 如果你只有安卓手机、不需要跨设备与自托管 → Loop Habit Tracker：本地应用体验最好，但没有 Web 与 API 能力；
• 如果你需要完整的任务/项目管理而非习惯打卡 → 三者都不合适，应考察任务管理类自托管产品。

社区活跃度方面（2026-10-22 实查）：BeaverHabits 的版本节奏（近 8 个月 6 个稳定版）与其 572k 的镜像拉取量在同类轻量自托管项目中处于活跃水平；Habitica 体量与社区规模更大但产品形态更重；选型时建议再核对各仓库近三个月的提交与 issue 响应情况，热度数字仅作参考。

八、参考链接

• 官方仓库：https://github.com/daya0576/beaverhabits
• 官方在线服务与 Demo：https://beaverhabits.com / https://beaverhabits.com/demo
• 发布历史：https://github.com/daya0576/beaverhabits/releases
• 官方 Wiki（环境变量/API 指南/iOS 客户端）：https://github.com/daya0576/beaverhabits/wiki
• 官方镜像：https://hub.docker.com/r/daya0576/beaverhabits
• REST API 使用实测：本专栏《Beaver Habit Tracker v0.10.0 API 使用详解》
• 部署实测：本专栏《Ubuntu 22.04 安装 Beaver Habit Tracker v0.10.0 指南》、《Beaver Habit Tracker v0.10.0 Docker Compose 部署指南》
• 配置参考：本专栏《Beaver Habit Tracker v0.10.0 配置参数详解》