Vitals

本地优先的综合健康管理应用，整合运动、饮食、睡眠、体重和阅读数据。

功能特性

健康数据追踪

• 运动记录 - 跑步、游泳、骑行、力量训练等，支持时长、距离、心率记录
• 饮食记录 - 三餐及加餐，支持卡路里、蛋白质、碳水、脂肪追踪，AI 智能识别食物
• 睡眠记录 - 入睡/起床时间、睡眠时长、睡眠质量评分
• 体重记录 - 体重、体脂率、肌肉量追踪

阅读习惯追踪

• 阅读记录 - 时长、书名、作者、封面（自动获取）、读后感
• 心情记录 - 5 种表情选择（😄😊😐😔😢）
• 我的书库 - 书籍封面网格展示，按书名归类
• 统计图表 - 阅读时长趋势、心情分布饼图

多用户与认证

• 用户档案 - 姓名、性别、身高、体重、年龄
• BMI 计算 - 自动计算并显示健康状态（偏瘦/正常/偏胖/肥胖）
• 用户切换 - 支持多用户数据隔离
• 数据管理 - 按日期范围或数据类型清除数据
• JWT 认证 - HTTPOnly Cookie + Authorization Header 混合认证
• 记住我 - 可选 1 天或 30 天登录有效期
• 邀请码注册 - 通过邀请码控制用户注册
• 管理员面板 - 用户管理、邀请码管理

数据管理

• 数据导出 - 支持 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 + 设置 Cookie
/api/auth/register	POST	用户注册（需邀请码）
/api/auth/logout	POST	用户登出，清除 Cookie
/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

文档

部署文档

• 云服务器部署指南 - 详细的公网部署步骤

设计文档

• Vitals 设计文档
• 设置页面实现计划
• 阅读模块设计文档
• 公网部署设计文档
• 开发任务清单

开发进度

已完成功能 ✅

核心数据追踪

• 运动记录 - 类型、时长、距离、卡路里、心率追踪，支持 Garmin/Codoon/CSV 导入
• 饮食记录 - 三餐+加餐，营养数据（卡路里/蛋白质/碳水/脂肪），照片上传
• 睡眠记录 - 入睡/起床时间、时长、质量评分(1-5)、深睡时长
• 体重记录 - 体重(kg)、体脂率(%)、肌肉量，趋势分析
• 阅读记录 - 书名、作者、封面(自动获取)、时长、心情(5种表情)、读后感

用户认证与管理

• JWT 认证 - 服务端认证 + Cookie，支持 1 天/30 天过期
• 密码安全 - bcrypt 哈希加密
• 多用户支持 - 用户档案、数据隔离、用户切换
• 邀请码注册 - 控制用户注册，支持有效期设置
• 管理员面板 - 用户管理（启用/禁用/删除）、邀请码管理

Web 应用

• 完整页面 - 登录、注册、管理员、首页、运动、饮食、睡眠、体重、阅读、报告、设置
• 认证中间件 - 保护所有页面（登录/注册除外）
• REST API - 40+ 个接口，完整的 CRUD 操作
• 照片管理 - 饮食照片上传和静态文件服务

数据管理

• 数据导出 - JSON 和 CSV 格式
• 数据导入 - JSON 文件导入（带验证）
• 自动备份 - 数据写入后自动备份，7 天保留策略
• 备份恢复 - 从备份文件恢复数据
• 数据清理 - 按日期范围或数据类型删除，支持预览

AI 集成

• 食物识别 - 阿里通义千问(Qwen VL)、DeepSeek Vision、Claude Vision
• 卡路里估算 - 基于食物描述的营养值计算

数据导入器

• Garmin 导入 - 从 Garmin 设备导入运动数据
• Codoon 导入 - 支持咔豆运动数据导入
• CSV 导入 - 通用 CSV 导入（运动/饮食/睡眠/体重）

报告与分析

• 今日概览 - 所有健康指标汇总
• 本周汇总 - 7 天趋势分析
• 阅读统计 - 时长趋势、心情分布、书库展示
• 图表展示 - 运动趋势、营养统计、睡眠热力图

CLI 工具

• 数据记录 - vitals log 记录各类数据
• 数据查看 - vitals show 显示汇总
• 数据导出 - vitals export 导出 JSON/CSV
• 数据备份 - vitals backup 管理备份

部署

• Docker 支持 - Dockerfile + docker-compose.yml
• 环境变量配置 - 灵活的配置管理
• 健康检查 - Docker 容器健康检查

待完善功能 🚧

高优先级

• 提醒系统完善 - 定时提醒功能已有框架，但系统集成需要完善
• 数据编辑功能 - 目前仅支持删除，需要添加编辑已有记录的功能
• 错误处理优化 - 前端错误提示和异常处理需要更友好

中优先级

• 月度报告 - PDF 报告生成功能（已有框架，需完善）
• 目标设定 - 运动目标、饮食目标、体重目标的设定和追踪
• 数据统计增强 - 更丰富的图表和趋势分析
• 移动端优化 - 响应式设计改进，更好的移动端体验
• 离线支持 - PWA 支持，离线数据缓存

低优先级

• 国际化(i18n) - 多语言支持
• 云同步 - 跨设备数据同步
• 社交功能 - 数据分享、好友挑战
• 智能建议 - 基于数据的个性化健康建议
• Apple Health 集成 - 与 Apple Health 数据同步
• 深色模式 - UI 深色主题支持

已知问题 🐛

• 大量数据时列表加载性能需优化
• 部分页面在小屏幕上布局需要调整
• 书籍封面搜索有时无法找到匹配结果

更新日志

2026-01-22

🔐 混合认证方案优化

• 修改 login/register API 使用 JSONResponse 正确设置 Cookie
• 添加 path="/" 确保 Cookie 在所有路径可用
• 前端同时使用 localStorage token 进行 API 认证
• 修复登录后闪屏返回登录页的问题

✨ 登录功能全面升级

• 服务端认证中间件 - 未登录用户自动重定向到登录页
• HTTPOnly Cookie - 使用 HTTPOnly Cookie 存储 token（比 localStorage 更安全）
• "记住我"功能 - 勾选：30 天有效期，不勾选：1 天有效期
• 登出 API - 新增 /api/auth/logout 接口
• 登录后重定向 - 支持登录后返回原访问页面

🎨 登录/注册页面 UI 升级

• 采用 Neumorphism（新拟态） 设计风格
• 健康主题配色（青色 + 绿色渐变）
• Lora + Raleway 字体组合
• 柔和阴影效果，提升视觉体验

历史版本

• 2026-01-20 - 阅读模块上线（书库、心情追踪、统计图表）
• 2026-01-19 - 设置页面重构（用户档案、数据管理）
• 2026-01-17 - 公网部署支持（JWT 认证、邀请码、管理员面板）
• 2026-01-15 - 第一版发布（核心健康追踪功能）

License

MIT