Vitals
本地优先的综合健康管理应用，整合运动、饮食、睡眠、体重和阅读数据。
功能特性
健康数据追踪
- 运动记录 - 跑步、游泳、骑行、力量训练等，支持时长、距离、心率记录
- 饮食记录 - 三餐及加餐，支持卡路里、蛋白质、碳水、脂肪追踪，AI 智能识别食物图片和文字
- 睡眠记录 - 入睡/起床时间、睡眠时长、睡眠质量评分
- 体重记录 - 体重、体脂率、肌肉量追踪
阅读习惯追踪
- 阅读记录 - 时长、书名、作者、封面（自动获取）、读后感
- 心情记录 - 5 种表情选择（😄😊😐😔😢）
- 我的书库 - 书籍封面网格展示，按书名归类
- 统计图表 - 阅读时长趋势、心情分布饼图
多用户与认证
- 用户档案 - 姓名、性别、身高、体重、年龄
- BMI 计算 - 自动计算并显示健康状态（偏瘦/正常/偏胖/肥胖）
- 用户切换 - 支持多用户数据隔离
- 用户配置隔离 - 每个用户独立的配置数据
- 数据管理 - 按日期范围或数据类型清除数据
- JWT 认证 - HTTPOnly Cookie + Authorization Header 混合认证
- 记住我 - 可选 1 天或 30 天登录有效期
- 邀请码注册 - 通过邀请码控制用户注册
- 管理员面板 - 用户管理、邀请码管理、API Key 管理
数据管理
- 数据导出 - 支持 JSON/CSV 格式导出
- 数据导入 - 从 JSON 文件导入数据
- 自动备份 - 数据写入后自动备份
- 备份恢复 - 支持从备份文件恢复数据
提醒功能
- 定时提醒 - 体重、睡眠、运动、饮食提醒
- 系统通知 - 支持 macOS/Linux/Windows 系统通知
数据可视化
- 今日概览 - 运动、饮食、睡眠、体重、阅读汇总，深色科技风格仪表盘
- 本周报告 - 趋势分析和统计图表
- 详细报告 - 各项数据的深度分析
Apple Health 集成
- 步数同步 - 自动同步 Apple Health 步数数据到首页仪表盘
快速开始
Docker 部署（推荐）
# 1. 复制环境变量模板
cp .env.example .env
# 2. 编辑 .env 文件，设置 JWT 密钥
vim .env
# 3. 启动服务
docker-compose up -d
# 4. 访问 http://localhost:8888
# 默认管理员账号: admin / admin123
本地开发
# 安装依赖
pip install -e .
# 设置 MySQL 环境变量
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=vitals
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=vitals
# 设置 JWT 密钥
export JWT_SECRET=$(openssl rand -hex 32)
# 启动服务
uvicorn vitals.web.app:app --host 0.0.0.0 --port 8080
访问 http://localhost:8080 即可使用 Web 界面。
注意: 默认管理员账号为
admin/admin123，请在首次登录后及时修改密码。
页面导航
/- 首页（今日概览）/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/admin/api-keys |
GET | 获取所有 API Key 状态 |
/api/admin/api-keys/{provider} |
GET | 获取指定 API Key（明文） |
/api/admin/api-keys/{provider} |
PUT | 设置 API Key |
/api/admin/api-keys/{provider} |
DELETE | 删除 API Key |
用户管理
| 端点 | 方法 | 说明 |
|---|---|---|
/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/bmi/analysis |
GET | BMI 分析（当前/目标体重、达成预估） |
饮食
| 端点 | 方法 | 说明 |
|---|---|---|
/api/meals |
GET | 获取饮食记录 |
/api/meal |
POST | 添加饮食记录 |
/api/meal/{id} |
DELETE | 删除单条饮食记录 |
/api/meals/nutrition |
GET | 营养统计 |
/api/food/recognize |
POST | AI 识别食物 |
/api/nutrition/recommendations |
GET | 营养建议（TDEE目标、缺口分析、配餐建议） |
睡眠
| 端点 | 方法 | 说明 |
|---|---|---|
/api/sleep |
GET | 获取睡眠记录 |
/api/sleep |
POST | 添加睡眠记录 |
/api/sleep/{id} |
DELETE | 删除单条睡眠记录 |
/api/sleep/assessment |
GET | 睡眠评估（状态分析、健康影响、建议） |
体重
| 端点 | 方法 | 说明 |
|---|---|---|
/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 .
环境变量
| 变量 | 必填 | 说明 |
|---|---|---|
MYSQL_HOST |
是 | MySQL 服务器地址（默认 localhost） |
MYSQL_PORT |
否 | MySQL 端口（默认 3306） |
MYSQL_USER |
是 | MySQL 用户名 |
MYSQL_PASSWORD |
是 | MySQL 密码 |
MYSQL_DATABASE |
是 | MySQL 数据库名（默认 vitals） |
MYSQL_ROOT_PASSWORD |
是 | MySQL root 密码（Docker 部署时需要） |
JWT_SECRET |
是 | JWT 签名密钥（建议用 openssl rand -hex 32 生成） |
DASHSCOPE_API_KEY |
否 | 阿里云通义千问 API Key（可通过 Web 管理界面配置） |
DEEPSEEK_API_KEY |
否 | DeepSeek API Key（可通过 Web 管理界面配置） |
ANTHROPIC_API_KEY |
否 | Anthropic API Key（可通过 Web 管理界面配置） |
API Key 管理: AI 相关的 API Key 支持通过 Web 管理界面配置（管理员设置页），数据库配置优先于环境变量。
默认管理员账号: admin / admin123（请在首次登录后修改）
技术栈
- 后端: Python, FastAPI, MySQL 8.0
- 前端: HTML, CSS, JavaScript, Chart.js
- 认证: JWT (PyJWT), bcrypt
- 部署: Docker, Docker Compose
- AI: 阿里云通义千问 / DeepSeek (食物识别)
- 外部 API: OpenLibrary (书籍封面搜索)
设计系统
首页仪表盘（深色科技风格）
| 元素 | 值 |
|---|---|
| Background | #0a0a0f (深空黑) |
| Card Background | rgba(255,255,255,0.03) (玻璃态) |
| Primary Accent | #00d4ff (科技青) |
| Secondary Accent | #7c3aed (霓虹紫) |
| Text Primary | #ffffff |
| Text Secondary | rgba(255,255,255,0.6) |
| Border | rgba(255,255,255,0.1) |
| Glow Effect | 0 0 20px rgba(0,212,255,0.3) |
其他页面
| 元素 | 值 |
|---|---|
| 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 # MySQL 数据库操作（连接池管理、API Key 管理）
│ │ ├── auth.py # JWT 认证、密码哈希
│ │ ├── backup.py # 数据库备份
│ │ ├── export.py # 数据导出导入
│ │ ├── report.py # 健康报告生成
│ │ └── calories.py # 卡路里计算（本地数据库 + AI 智能识别）
│ ├── vision/
│ │ ├── analyzer.py # 食物识别分析器
│ │ └── providers/ # AI 提供商（通义千问、DeepSeek）
│ ├── importers/ # 数据导入器（Garmin、Codoon、CSV）
│ ├── web/
│ │ └── app.py # FastAPI 应用
│ └── cli.py # 命令行工具
├── scripts/
│ └── migrate_sqlite_to_mysql.py # SQLite 到 MySQL 迁移脚本
├── tests/ # 测试文件
├── docs/
│ ├── context/ # 开发上下文
│ └── plans/ # 设计文档
├── Dockerfile # Docker 镜像配置
├── docker-compose.yml # Docker Compose + MySQL 配置
├── .env.example # 环境变量模板
├── pyproject.toml # Python 项目配置
└── README.md
文档
部署文档
- 云服务器部署指南 - 详细的公网部署步骤
设计文档
开发进度
已完成功能 ✅
核心数据追踪
- 运动记录 - 类型、时长、距离、卡路里、心率追踪，支持 Garmin/Codoon/CSV 导入
- 饮食记录 - 三餐+加餐，营养数据（卡路里/蛋白质/碳水/脂肪），照片上传
- 睡眠记录 - 入睡/起床时间、时长、质量评分(1-5)、深睡时长
- 体重记录 - 体重(kg)、体脂率(%)、肌肉量，趋势分析
- 阅读记录 - 书名、作者、封面(自动获取)、时长、心情(5种表情)、读后感
用户认证与管理
- JWT 认证 - 服务端认证 + Cookie，支持 1 天/30 天过期
- 密码安全 - bcrypt 哈希加密
- 多用户支持 - 用户档案、数据隔离、用户切换
- 用户配置隔离 - 每个用户独立的配置数据（身高、体重、目标等）
- 邀请码注册 - 控制用户注册，支持有效期设置
- 管理员面板 - 用户管理（启用/禁用/删除）、邀请码管理、API Key 管理
Web 应用
- 完整页面 - 登录、注册、管理员、首页、运动、饮食、睡眠、体重、阅读、报告、设置
- 认证中间件 - 保护所有页面（登录/注册除外）
- REST API - 40+ 个接口，完整的 CRUD 操作
- 照片管理 - 饮食照片上传和静态文件服务
数据管理
- 数据导出 - JSON 和 CSV 格式
- 数据导入 - JSON 文件导入（带验证）
- 自动备份 - 数据写入后自动备份，7 天保留策略
- 备份恢复 - 从备份文件恢复数据
- 数据清理 - 按日期范围或数据类型删除，支持预览
AI 集成
- 食物图片识别 - 阿里通义千问(Qwen VL)、DeepSeek Vision、Claude Vision
- 食物文字智能识别 - 本地数据库优先匹配，识别失败自动调用 AI 标准化
- 卡路里估算 - 基于食物描述的营养值计算
- API Key 管理 - Web 界面管理 AI API Key，数据库存储优先于环境变量
数据导入器
- Garmin 导入 - 从 Garmin 设备导入运动数据
- Codoon 导入 - 支持咔豆运动数据导入
- CSV 导入 - 通用 CSV 导入（运动/饮食/睡眠/体重）
报告与分析
- 今日概览 - 所有健康指标汇总
- 本周汇总 - 7 天趋势分析
- 阅读统计 - 时长趋势、心情分布、书库展示
- 图表展示 - 运动趋势、营养统计、睡眠热力图
- BMI 健康分析 - BMI 刻度条、目标体重达成预估
- 营养建议系统 - TDEE 目标计算、缺口分析、配餐建议
- 睡眠健康评估 - 状态评估、健康影响警告/益处提示
CLI 工具
- 数据记录 -
vitals log记录各类数据 - 数据查看 -
vitals show显示汇总 - 数据导出 -
vitals export导出 JSON/CSV - 数据备份 -
vitals backup管理备份
部署
- Docker 支持 - Dockerfile + docker-compose.yml
- 环境变量配置 - 灵活的配置管理
- 健康检查 - Docker 容器健康检查
- MySQL 数据库 - MySQL 8.0 连接池，支持数据迁移
移动端 H5 适配
- 响应式布局 - 所有页面适配移动端屏幕（768px/400px 断点）
- 底部 Tab 导航 - 移动端专属底部导航栏，支持"更多"菜单
- 触控优化 - 按钮和交互元素符合 44px/48px 触控标准
- iOS 安全区域 - 支持 iPhone 刘海屏和底部横条
- 全页面适配 - 登录/注册、首页、运动、饮食、睡眠、体重、阅读、报告、设置、管理页面
待完善功能 🚧
高优先级
- 提醒系统完善 - 定时提醒功能已有框架，但系统集成需要完善
- 数据编辑功能 - 目前仅支持删除，需要添加编辑已有记录的功能
- 错误处理优化 - 前端错误提示和异常处理需要更友好
中优先级
- 月度报告 - PDF 报告生成功能（已有框架，需完善）
- 目标设定 - 运动目标、饮食目标、体重目标的设定和追踪
- 数据统计增强 - 更丰富的图表和趋势分析
- 移动端优化 - 响应式设计改进，全部页面已适配移动端
- 离线支持 - PWA 支持，离线数据缓存
低优先级
- 国际化(i18n) - 多语言支持
- 云同步 - 跨设备数据同步
- 社交功能 - 数据分享、好友挑战
- 智能建议 - 基于数据的个性化健康建议
- Apple Health 集成 - 步数数据同步到首页仪表盘
- 深色模式 - UI 深色主题支持
已知问题 🐛
- 大量数据时列表加载性能需优化
- 书籍封面搜索有时无法找到匹配结果
数据迁移
从 SQLite 迁移到 MySQL
如果你有旧版本的 SQLite 数据需要迁移，可以使用迁移脚本：
# 1. 确保 MySQL 服务已启动并配置好环境变量
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=vitals
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=vitals
# 2. 运行迁移脚本（默认从 ~/.vitals/vitals.db 读取）
python scripts/migrate_sqlite_to_mysql.py
# 或指定 SQLite 数据库路径
VITALS_DB_PATH=/path/to/old/vitals.db python scripts/migrate_sqlite_to_mysql.py
迁移脚本会自动处理：
- 用户数据（users）
- 运动记录（exercise）
- 饮食记录（meal）
- 睡眠记录（sleep）
- 体重记录（weight）
- 阅读记录（reading）
- 邀请码（invites）
- 配置数据（config）
更新日志
2026-01-27
📊 健康模块智能分析增强
- BMI 健康分析 - 运动页面新增 BMI 分析卡片
- BMI 状态刻度条（偏瘦/正常/偏重/肥胖）
- 目标体重设定与达成预估
- 基于 TDEE-摄入+运动 的智能计算
- 营养建议系统 - 饮食页面新增营养状况卡片
- 每日营养进度条（热量/蛋白质/碳水/脂肪）
- 基于 TDEE 的个性化目标计算
- 营养缺口分析与配餐建议
- 7 天趋势图增加建议摄入参考线
- 睡眠健康评估 - 睡眠页面新增健康评估卡片
- 睡眠状态刻度条（偏少/不足/理想/过多）
- 睡眠不足警告卡片（认知/身体/情绪/运动影响）
- 睡眠充足益处卡片（健康益处提示）
- 趋势图动态着色（理想区间绿色标记）
2026-01-26
🎨 首页仪表盘深色科技风格改造
- 全新视觉风格 - 深空黑背景 + 玻璃态卡片 + 霓虹光效
- 科技感配色 - 科技青(#00d4ff) + 霓虹紫(#7c3aed) 双色调
- 动态效果 - 卡片悬停光晕、数据呼吸动画、渐变边框
- 信息密度优化 - 紧凑布局，一屏展示更多健康数据
🍎 Apple Health 步数同步
- 步数数据集成 - 首页仪表盘展示 Apple Health 同步的步数
- 自动同步 - 支持从 Apple Health 导入每日步数数据
2026-01-24
🔑 API Key 数据库管理
- 集中存储 - AI API Key（通义千问、DeepSeek、Anthropic）存储在数据库
- Web 管理界面 - 管理员可在设置页面配置 API Key
- 优先级机制 - 数据库配置优先于环境变量
- 安全显示 - API Key 列表仅显示掩码，支持查看/编辑/删除
👤 用户配置隔离
- Config 表迁移 - 添加 user_id 字段，复合主键 (user_id, key)
- 数据归属 - 现有配置数据归属 ID=1 用户
- 完全隔离 - 每个用户独立的配置数据，新用户不再看到其他用户信息
🍽️ 食物文字智能识别
- 本地优先 - 使用内置食物数据库快速匹配（~100 种常见食物）
- AI 增强 - 本地无法识别时自动调用通义千问 AI 标准化食物描述
- 智能回退 - 无 API Key 时仅使用本地估算，不影响基本功能
2026-01-23
🗄️ MySQL 数据库迁移
- 数据库切换 - 从 SQLite 迁移到 MySQL 8.0
- 连接池支持 - 使用 MySQL 连接池管理，提升性能
- Docker 集成 - docker-compose 自动配置 MySQL 服务
- 数据迁移脚本 - 提供 SQLite 到 MySQL 的数据迁移工具
- 类型兼容性修复 - 添加
_parse_datetime、_parse_date、_parse_time辅助函数，处理 MySQL 返回原生类型
🔒 用户权限增强
- API 权限控制 -
/api/users非管理员仅返回自己，/api/users/{id}非管理员只能查询自己（否则 403） - 导航栏隐藏 - 非管理员用户隐藏「管理」入口
📱 移动端 H5 全页面适配
- 登录/注册页面 - 移动端布局优化，触摸目标符合标准
- 首页 Dashboard - 卡片布局适配，底部导航栏
- 运动/饮食页面 - 表格转卡片列表，表单输入增大
- 睡眠/体重/阅读页面 - 响应式布局，48px 输入框
- 报告页面 - 按钮触摸目标优化(48px)，底部导航
- 设置页面 - 响应式布局，支持手机浏览
- 管理页面 - 表格改为卡片列表(data-label)
- 底部 Tab 导航 - 固定底部导航栏 + "更多"菜单
- iOS 安全区域 - 支持刘海屏和底部横条
🌐 网络访问
- 绑定地址优化 - 默认绑定
0.0.0.0，支持局域网访问和移动端真机测试
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