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

文档

部署文档

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

设计文档

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

开发进度

已完成功能 ✅

核心数据追踪

• 运动记录 - 类型、时长、距离、卡路里、心率追踪，支持 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