常见问题

这里收集了用户最常遇到的问题和解决方案。如果您的问题不在此列表中，请查看 故障排除指南 或 联系我们 。

🚀 安装和部署

Q: 支持哪些操作系统？

A: Snapifit AI 支持以下操作系统：

• Linux: Ubuntu 18.04+, CentOS 7+, Debian 9+
• macOS: 10.15+
• Windows: Windows 10/11 (通过 WSL2 或 Docker Desktop)

Q: 最低系统要求是什么？

A: 推荐配置：

• CPU: 2核心以上
• 内存: 4GB RAM (最低 2GB)
• 存储: 20GB 可用空间 (最低 10GB)
• 网络: 稳定的互联网连接

Q: Docker 部署失败怎么办？

A: 常见解决方案：

1. 检查 Docker 版本

   docker --version  # 需要 20.10+
   docker-compose --version  # 需要 1.29+

2. 检查端口占用

   netstat -tulpn | grep :3000

3. 清理 Docker 缓存

   docker system prune -a

Q: 环境变量配置错误怎么办？

A: 请检查以下配置：

# 正确格式
DATABASE_URL=postgresql://user:pass@localhost:5432/db
 
# 错误格式（有空格）
DATABASE_URL = postgresql://user:pass@localhost:5432/db

🔐 认证和安全

Q: 忘记密码怎么办？

A: 可以通过以下方式重置密码：

1. 使用重置功能: 在登录页面点击”忘记密码”
2. 管理员重置: 联系系统管理员
3. 数据库直接重置:

   UPDATE users SET password = crypt('new_password', gen_salt('bf'))
   WHERE email = 'user@example.com';

Q: API Token 如何管理？

A: Token 管理最佳实践：

• 定期轮换: 建议每 30-90 天更换一次
• 权限最小化: 只授予必要的权限
• 安全存储: 不要在代码中硬编码 Token
• 监控使用: 定期检查 Token 使用情况

Q: 如何启用双因素认证？

A: 在用户设置中启用 2FA：

1. 进入 “账户设置” → “安全设置”
2. 点击 “启用双因素认证”
3. 使用认证应用扫描二维码
4. 输入验证码完成设置

📊 数据和功能

Q: 数据备份提示是什么意思？

A: 关于数据备份：

1. 导出数据: 这个导出数据的提示是之前个人版遗留的。您在某个端侧使用一段时间且未导出的话，就会产生相关的提示。

2. 云同步: 在共享版里，您不用每次都点击，一般不必要特意云同步。

3. 数据安全: 您可以定期导出之前的记录json，以保证数据安全。目前这一版里面没有取消；如果感觉影响使用体验的话，我可以在之后的版本里把这个提示取消，或者把提醒间隔拉大一点。

Q: 目标消耗是怎么计算的？

A: TDEE的计算，这里主要使用三点来估计：

基础代谢率、活动水平、食物热效应

TDEE = 基础代谢率(1) × 日常活动水平系数(2)( 不包括运动，最低 1.2 到最高 1.9 ) + 食物热效应系数(3)(10% 为基准微调) × 每日卡路里摄入

(1) 基础代谢率(BMR)：完全静息状态下维持生命活动所需的最低热量。这里目前根据 Mifflin St-Jeor 方程来进行计算(参与的指标有：年龄、性别、身高和体重等，这里的体重是每日记录的)，也可以在设置里使用其他的算法，以填写体脂率进行计算。

(2) 活动水平：这部分一般占比平常是15%-30%左右，被称为”活动的热效应”，包括一些好统计的(我们进行记录的运动，按理说要加入，但这里分离开了) 和不好统计的(非运动性日常活动热效应)。这里做了每日的自评以评估这个”不好统计”的值，您可以选择一个较为适合自己的选项。不同的自评水平，会乘以一个不同的系数(如久坐不动的时候，乘以1.2，这代表极低的活动水平)。

(3) 食物热效应：是根据您填写的每日活动程度来的，一般是10%左右，这里会在10%的比例上使用AI以精细评估摄入的食物种类，适配食用高蛋白质/咖啡时所产生的更高的食物热效应。

目前的思路是对比 卡路里摄入 与 TDEE(非运动之外的所有日常消耗) + 运动消耗，以推测体重的变化趋势。

Q: 机器测量的数据怎么加入到系统？

A: 关于机器测量的指标：

(1) 体脂率：可以在设置中使用其他的算法进行计算，以提供给TDEE作参考。不过这个指标是没有经过每日记录的，还是建议目前使用体重指标。

(2) 运动数据：运动是可以通过上传图片来记录的，这里是指具体的活动，如跑步多久，做了什么力量训练等APP记录界面。而针对于大部分身体指标相关的内容，在目前的版本里还没增加这个功能。

原因：它可能不太能够给TDEE以参考，而且，它是更当下/即时性的内容，适合用在分析上。

建议使用方式：

• 我们在chat界面，有图像上传功能，这个内容给AI私教，让他更精准的给你运动建议，这个还是很好的。
• 您还可以告诉他”请你在(记忆中）帮我记下这些关键性的数据”。他就会帮你自动记录下有用的部分指标，以给您的这次与之后的对话提供依据，更为量身定制。

Q: 数据备份和恢复怎么做？

A: 数据备份方案：

自动备份:

# 设置定时任务
0 2 * * * /path/to/backup-script.sh

手动备份:

# PostgreSQL 备份
pg_dump snapifit_db > backup_$(date +%Y%m%d).sql
 
# 文件备份
tar -czf uploads_backup.tar.gz uploads/

Q: AI 功能不工作怎么办？

A: 检查以下配置：

1. API Key 配置

   # 检查环境变量
   echo $OPENAI_API_KEY

2. 网络连接

   # 测试 API 连接
   curl -H "Authorization: Bearer $OPENAI_API_KEY" \
        https://api.openai.com/v1/models

3. 配额检查: 登录 OpenAI 控制台检查 API 使用量

Q: 数据导入失败怎么办？

A: 常见导入问题：

• 文件格式: 确保使用支持的格式 (CSV, JSON, Excel)
• 文件大小: 单个文件不超过 10MB
• 数据格式: 检查日期、数字格式是否正确
• 编码问题: 使用 UTF-8 编码

🔧 性能和优化

Q: 应用运行缓慢怎么办？

A: 性能优化建议：

1. 数据库优化

   -- 添加索引
   CREATE INDEX idx_health_logs_user_date ON health_logs(user_id, created_at);
    
   -- 清理旧数据
   DELETE FROM health_logs WHERE created_at < NOW() - INTERVAL '2 years';

2. 缓存配置

   # Redis 缓存
   REDIS_URL=redis://localhost:6379

3. 资源监控

   # 检查系统资源
   htop
   df -h
   free -m

Q: 数据库连接问题怎么解决？

A: 连接问题排查：

1. 检查连接字符串

   # 测试数据库连接
   psql $DATABASE_URL -c "SELECT version();"

2. 检查防火墙设置

   # 检查端口开放
   telnet localhost 5432

3. 检查数据库状态

   # PostgreSQL 状态
   systemctl status postgresql

🆘 获取帮助

Q: 在哪里寻求技术支持？

A: 支持渠道：

• 文档: 查看完整的 用户指南
• GitHub Issues: 提交问题 
• 讨论区: 社区讨论 
• 邮件支持: support@snapifit.ai

Q: 如何报告 Bug？

A: Bug 报告模板：

**Bug 描述**
简要描述遇到的问题
 
**复现步骤**
1. 进入 '...'
2. 点击 '....'
3. 滚动到 '....'
4. 看到错误
 
**预期行为**
描述您期望发生的情况
 
**环境信息**
- OS: [e.g. Ubuntu 20.04]
- Browser: [e.g. Chrome 91]
- Version: [e.g. 1.0.0]