Vitals
本地优先的综合健康管理应用，整合运动、饮食、睡眠、体重和阅读数据。
功能特性
健康数据追踪
- 运动记录 - 跑步、游泳、骑行、力量训练等，支持时长、距离、心率记录
- 饮食记录 - 三餐及加餐，支持卡路里、蛋白质、碳水、脂肪追踪，AI 智能识别食物
- 睡眠记录 - 入睡/起床时间、睡眠时长、睡眠质量评分
- 体重记录 - 体重、体脂率、肌肉量追踪
阅读习惯追踪
- 阅读记录 - 时长、书名、作者、封面（自动获取）、读后感
- 心情记录 - 5 种表情选择（😄😊😐😔😢）
- 我的书库 - 书籍封面网格展示，按书名归类
- 统计图表 - 阅读时长趋势、心情分布饼图
多用户与认证
- 用户档案 - 姓名、性别、身高、体重、年龄
- BMI 计算 - 自动计算并显示健康状态（偏瘦/正常/偏胖/肥胖）
- 用户切换 - 支持多用户数据隔离
- 数据管理 - 按日期范围或数据类型清除数据
- JWT 认证 - 安全的 Token 认证机制
- 邀请码注册 - 通过邀请码控制用户注册
- 管理员面板 - 用户管理、邀请码管理
数据管理
- 数据导出 - 支持 JSON/CSV 格式导出
- 数据导入 - 从 JSON 文件导入数据
- 自动备份 - 数据写入后自动备份
- 备份恢复 - 支持从备份文件恢复数据
提醒功能
- 定时提醒 - 体重、睡眠、运动、饮食提醒
- 系统通知 - 支持 macOS/Linux/Windows 系统通知
数据可视化
- 今日概览 - 运动、饮食、睡眠、体重、阅读汇总
- 本周报告 - 趋势分析和统计图表
- 详细报告 - 各项数据的深度分析
快速开始
Docker 部署（推荐）
# 1. 复制环境变量模板
cp .env.example .env
# 2. 编辑 .env 文件，设置管理员密码和 JWT 密钥
vim .env
# 3. 启动服务
docker-compose up -d
# 4. 访问 http://localhost:8080
本地开发
# 安装依赖
pip install -e .
# 设置环境变量
export ADMIN_USERNAME=admin
export ADMIN_PASSWORD=your_password
export JWT_SECRET=$(openssl rand -hex 32)
# 启动服务
uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080
访问 http://localhost:8080 即可使用 Web 界面。
页面导航
/- 首页（今日概览）/login- 登录页面/register- 注册页面（需邀请码）/admin- 管理员面板/exercise- 运动记录/meal- 饮食记录/sleep- 睡眠记录/weight- 体重记录/reading- 阅读记录/report- 健康报告/settings- 设置页面
API 接口
认证
| 端点 | 方法 | 说明 |
|---|---|---|
/api/auth/login |
POST | 用户登录，返回 JWT Token |
/api/auth/register |
POST | 用户注册（需邀请码） |
/api/auth/me |
GET | 获取当前用户信息 |
管理员
| 端点 | 方法 | 说明 |
|---|---|---|
/api/admin/users |
GET | 获取所有用户列表 |
/api/admin/users/{id}/disable |
POST | 禁用用户 |
/api/admin/users/{id}/enable |
POST | 启用用户 |
/api/admin/users/{id} |
DELETE | 删除用户 |
/api/admin/invites |
GET | 获取邀请码列表 |
/api/admin/invites |
POST | 创建邀请码 |
/api/admin/invites/{id} |
DELETE | 删除邀请码 |
用户管理
| 端点 | 方法 | 说明 |
|---|---|---|
/api/users |
GET | 获取所有用户 |
/api/users |
POST | 创建新用户 |
/api/users/active |
GET | 获取当前活跃用户 |
/api/users/{id} |
GET | 获取指定用户 |
/api/users/{id} |
PUT | 更新用户信息 |
/api/users/{id} |
DELETE | 删除用户 |
/api/users/{id}/activate |
POST | 设置活跃用户 |
数据管理
| 端点 | 方法 | 说明 |
|---|---|---|
/api/data/preview-delete |
POST | 预览删除数量 |
/api/data/clear |
POST | 执行数据删除 |
运动
| 端点 | 方法 | 说明 |
|---|---|---|
/api/exercises |
GET | 获取运动记录 |
/api/exercise |
POST | 添加运动记录 |
/api/exercise/{id} |
DELETE | 删除单条运动记录 |
/api/exercises/stats |
GET | 运动统计 |
饮食
| 端点 | 方法 | 说明 |
|---|---|---|
/api/meals |
GET | 获取饮食记录 |
/api/meal |
POST | 添加饮食记录 |
/api/meal/{id} |
DELETE | 删除单条饮食记录 |
/api/meals/nutrition |
GET | 营养统计 |
/api/food/recognize |
POST | AI 识别食物 |
睡眠
| 端点 | 方法 | 说明 |
|---|---|---|
/api/sleep |
GET | 获取睡眠记录 |
/api/sleep |
POST | 添加睡眠记录 |
/api/sleep/{id} |
DELETE | 删除单条睡眠记录 |
体重
| 端点 | 方法 | 说明 |
|---|---|---|
/api/weight |
GET | 获取体重记录 |
/api/weight |
POST | 添加体重记录 |
/api/weight/{id} |
DELETE | 删除单条体重记录 |
阅读
| 端点 | 方法 | 说明 |
|---|---|---|
/api/reading |
GET | 获取阅读记录（支持 ?days=N） |
/api/reading |
POST | 添加阅读记录 |
/api/reading/{id} |
DELETE | 删除阅读记录 |
/api/reading/today |
GET | 今日阅读摘要 |
/api/reading/stats |
GET | 阅读统计 |
/api/books/search |
GET | 搜索书籍封面（OpenLibrary） |
汇总
| 端点 | 方法 | 说明 |
|---|---|---|
/api/today |
GET | 今日概览 |
/api/week |
GET | 本周汇总 |
命令行使用
数据记录
# 记录体重
vitals log weight 72.5 --fat 18.5
# 记录饮食
vitals log meal 午餐 "燕麦+鸡蛋+牛奶"
# 记录睡眠
vitals log sleep 23:30 07:00 --quality 4
# 记录运动
vitals log exercise 跑步 30min --distance 5km
数据查看
# 查看今日概览
vitals show today
# 查看本周汇总
vitals show week
# 设置个人信息
vitals config set --age 28 --gender male --height 175 --weight 72
数据导出与导入
# 导出所有数据为 JSON
vitals export json ~/backup.json
# 导出运动数据为 CSV
vitals export csv --type exercise ~/exercise.csv
# 从 JSON 导入数据
vitals export import-json ~/backup.json
数据库备份
# 创建备份
vitals backup create
# 列出所有备份
vitals backup list
# 恢复备份
vitals backup restore ~/.vitals/backups/vitals_20260122_120000.db
# 清理旧备份（保留最近 7 天）
vitals backup cleanup --days 7
定时提醒
# 设置体重提醒（每天 07:00）
vitals remind set weight --time 07:00
# 列出所有提醒
vitals remind list
# 禁用/启用提醒
vitals remind disable weight
vitals remind enable weight
# 测试系统通知
vitals remind test
# 设置定时任务（macOS）
vitals remind setup
安装
pip install -e .
环境变量
| 变量 | 必填 | 说明 |
|---|---|---|
ADMIN_USERNAME |
是 | 管理员用户名（首次启动时创建） |
ADMIN_PASSWORD |
是 | 管理员密码 |
JWT_SECRET |
是 | JWT 签名密钥（建议用 openssl rand -hex 32 生成） |
VITALS_DB_PATH |
否 | 数据库路径（默认 ~/.vitals/vitals.db） |
DASHSCOPE_API_KEY |
否 | 阿里云通义千问 API Key，用于 AI 食物识别 |
DEEPSEEK_API_KEY |
否 | DeepSeek API Key，用于 AI 食物识别 |
技术栈
- 后端: Python, FastAPI, SQLite
- 前端: HTML, CSS, JavaScript, Chart.js
- 认证: JWT (PyJWT), bcrypt
- 部署: Docker, Docker Compose
- AI: 阿里云通义千问 / DeepSeek (食物识别)
- 外部 API: OpenLibrary (书籍封面搜索)
设计系统
| 元素 | 值 |
|---|---|
| Primary | #3B82F6 |
| Secondary | #60A5FA |
| CTA | #F97316 |
| Background | #F8FAFC |
| Text | #1E293B |
| Headings | Lora |
| Body | Raleway |
| Style | Vibrant & Block-based |
项目结构
vitals/
├── src/vitals/
│ ├── core/
│ │ ├── models.py # 数据模型（User, Invite, Exercise, Meal...）
│ │ ├── database.py # 数据库操作
│ │ ├── auth.py # JWT 认证、密码哈希
│ │ ├── backup.py # 数据库备份
│ │ ├── export.py # 数据导出导入
│ │ ├── report.py # 健康报告生成
│ │ └── calories.py # 卡路里计算
│ ├── vision/
│ │ ├── analyzer.py # 食物识别分析器
│ │ └── providers/ # AI 提供商（通义千问、DeepSeek）
│ ├── importers/ # 数据导入器（Garmin、Codoon、CSV）
│ ├── web/
│ │ └── app.py # FastAPI 应用
│ └── cli.py # 命令行工具
├── tests/ # 测试文件
├── docs/
│ ├── context/ # 开发上下文
│ └── plans/ # 设计文档
├── Dockerfile # Docker 镜像配置
├── docker-compose.yml # Docker Compose 配置
├── .env.example # 环境变量模板
├── pyproject.toml # Python 项目配置
└── README.md
文档
部署文档
- 云服务器部署指南 - 详细的公网部署步骤
设计文档
开发进度
已完成功能
- P1-1 运动页面 - 运动记录列表、统计图表、数据录入
- P1-2 饮食页面 - 饮食记录、营养统计、日历视图
- P1-3 睡眠/体重页面 - 睡眠趋势、体重曲线、BMI 计算
- P1-4 Web 数据录入 - 所有数据类型的表单录入
- P1-5 AI 智能识别 - 通义千问/DeepSeek 食物识别
- P2-1 数据导出 - JSON/CSV 格式导出
- P2-2 自动备份 - 数据库备份与恢复
- P3-1 定时提醒 - 系统通知、定时任务
- 公网部署 - JWT 认证、邀请码注册、管理员面板、Docker 部署
License
MIT