ericwyuan/GarminHealthLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4331a07462d888d18822fd11310ce6774c9b554b
GarminHealthLab/CLAUDE.md
ericwyuan 9d6ebbe422 ops: 生产从 NAS 整体迁移到甲骨文云主机 
NAS 局域网 IP 因重启被 DHCP 换过两次，磁盘/网络稳定性都不如已经跑着好几个
生产服务的甲骨文机器。整体搬迁：应用 + 数据库都搬走，NAS 只保留 Gitea（这个
仓库的源码托管，未动）。

## 迁移过程（已核对无损）

- MariaDB：NAS 导出（10.11 源库，处理了只有新版本才有的 `/*M!999999` 注释）
  → 导入甲骨文 MariaDB 10.3.39，**20 张表逐条精确 COUNT(*) 比对完全一致**
- 冻结 NAS（停服务）后又 dump 一次核对，确认期间零数据差异，才继续删库
- NAS `garmin_health_lab` 已 DROP DATABASE，备份在本地
  `~/Desktop/Work/backups/garmin_health_lab_nas_backup_20260912.sql.gz`
- 应用部署到 `/opt/garmin-health-lab`，systemd 单元（`ubuntu` 用户，非
  root），和这台机器上的 ai-gateway/auth-hub 同一套约定
- 公网：`https://garmin.zichuan.xyz`，DNS + Caddy 反代 + 自动 TLS，替代原来
  `NAS frpc → 甲骨文:8124` 那条隧道（已从 NAS 的 frpc.toml 精确删除对应段，
  其它转发未动，改完逐条复检过没打断）
- auth-hub 回调地址换成新域名，NAS/旧端口那几条历史回调已清掉
- AI 网关配置改本地回环（网关现在同机了），触发真实生成验证过

## 一个当场拦下来的风险

甲骨文部署完默认开着自动同步。迁移窗口期两边并行跑时，若两边的调度器同时去
刷新 Garmin 令牌，会撞上按账号计算的 SSO 限流（`GarminHealthLab` 仓库
2026-09-03 那次事故的根因，那次修复花了一整天）。确认账号级 auto_sync 设置
本来是关的、这次算侥幸没撞上——不是设计上的保险，所以迁移期间显式在甲骨文这边
加了 `AUTO_SYNC=false`，直接在运行进程里验证过生效，确认 NAS 已冻结、数据无
缺口后才打开。

## 文档 / 脚本同步

CLAUDE.md 明确写过"部署位置会变，排障前先查、不要凭记忆"——这次是第二次踩中
同一类问题（上次是"NAS 有没有生产环境"判断错），所以把 CLAUDE.md / PROGRESS.md
/ README.md / docs/* 里的部署事实全部更新，NAS 时代的 `deploy/` 脚本加废弃
说明保留参考、不删除，新增 `deploy/push_oracle.sh`（当场跑通一次真实部署）。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-12 23:53:15 +08:00

174 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Garmin Health Lab — 项目指南
佳明（Garmin）健康数据分析平台：同步 Garmin Connect 数据，做多维度健康分析、
可视化与 AI 解读（晨报 / 趋势归因 / Copilot）。
> **阅读顺序**：先读本文件（协作约定与现状速览）→ [PROGRESS.md](PROGRESS.md)
> （功能与部署进度，**排查前必读**）→ [README.md](README.md)（API 与使用）→
> [docs/](docs/)（架构 / 开发 / 需求）。判断"部署在哪里、跑没跑、什么版本"时
> 一律以 `PROGRESS.md` 和 `deploy/` 脚本为准，**不要凭记忆断言**。
## 技术栈（现状，2026-09）
- **后端**：Python 3.10+ / Flask（应用工厂），Gunicorn 生产运行。原 Node/Express
后端早已重写为 Python，仓库中**不存在 `server/` 目录**。
- **前端**：React 18 + TypeScript，用 **CRA（react-scripts）**构建，UI 组件库为
**Framework7 9**（`framework7-react`，iOS 主题）+ Recharts 图表。根目录
`package.json` 是 npm workspaces（含 `client`）。
- **数据库**：可插拔数据层（`backend/db.py`），`DB_TYPE` 切换——
本地开发 SQLite（`backend/data/health.db`，默认）；生产 MariaDB（甲骨文云主机
本机，`garmin_health_lab` 库，连接配置见该机 `/opt/garmin-health-lab/backend/.env`）。
- **认证**：**auth-hub SSO**（OAuth2/OIDC，`services/auth_hub_client.py`），
本地邮箱密码注册/登录已移除；应用内 JWT 由后端签发。
- **AI**：自建 ai-gateway（OpenAI 兼容，`https://ai.zichuan.xyz/v1`）为唯一上游
（NVIDIA 推理模型，单次生成可达 2~5 分钟）；生产 `AI_MODEL_CHAIN=gateway`。
## 目录结构
```
GarminHealthLab/
├── backend/ # Flask 后端（当前唯一后端）
│ ├── app.py # 应用工厂：装配蓝图 + 静态 UI + scheduler/jobs
│ ├── wsgi.py # Gunicorn 入口
│ ├── config.py # 集中配置（读 backend/.env）
│ ├── auth.py # JWT 签发/校验 + require_auth
│ ├── db.py # 可插拔数据层（SQLite ↔ MariaDB）+ 幂等迁移
│ ├── routes/ # API 蓝图（blueprint）
│ │ ├── auth.py # /api/auth auth-hub SSO: callback / logout / refresh / auth-hub/start
│ │ ├── garmin.py # /api/garmin 绑定/同步/MFA/退出/活动详情/同步详情
│ │ ├── health.py # /api/health 摘要/睡眠/心率/运动/身体成分/血氧/设备/挑战等
│ │ ├── analysis.py # /api/analysis 趋势/建议/briefing/trend-insight/copilot/insight
│ │ └── settings.py # /api/settings 个人资料/单位/同步频率/评分依据
│ ├── services/ # 业务逻辑（纯函数/无 Flask 依赖，可单测）
│ │ ├── garmin.py # Garmin API 同步核心（限流退避 24h 写 DB）
│ │ ├── garmin_auth.py # Garmin OAuth 登录 + MFA 会话
│ │ ├── garmin_extras.py # 身体成分/血压/血氧/设备/徽章等扩展数据
│ │ ├── scheduler.py # 后台自动同步（DB 锁，多 worker 只跑一次）
│ │ ├── ai.py / coach.py / insights.py / jobs.py # AI 教练 + 生产者/消费者队列
│ │ ├── analysis.py / health.py / fitness_age.py / settings.py
│ │ └── auth_hub_client.py / scopes.py
│ ├── data/ # SQLite（本地开发，git 忽略）
│ ├── static/ # 前端构建产物（生产由 Flask 同端口提供）
│ ├── tests/ # pytest 测试（446+ 项）
│ └── .env.example # 环境变量样例（真实 .env 不提交）
├── client/ # React 前端（CRA + Framework7）
│ ├── src/pages/ # 今日/健康/趋势/运动/设置/每日/睡眠/指标详情等页面
│ ├── src/components/ # AI 晨报 / Copilot 浮窗 / 趋势归因 / Screen 骨架
│ ├── src/lib/ # day.ts（本地日期）/ metrics.ts（指标注册表）
│ ├── src/features.ts # 功能开关（FEATURES.ai）
│ └── .env.production # REACT_APP_API_URL=/api（同源，防 Network Error）
├── deploy/ # push_oracle.sh 现役；其余（S99garmin/start/stop/
│ # push/deploy）是 NAS 时代脚本，已废弃保留参考
├── docs/ # 架构 / 开发 / 需求文档
├── PROGRESS.md # 进度与部署事实（排查必读）
└── README.md # 项目说明 + API 文档
```
## 常用命令
```bash
# 后端依赖（首次）：在 backend/ 下建 .venv 并装 requirements-dev.txt
npm run setup:backend
# 同时起前后端开发（backend:5000 由 BACKEND_PORT 固定；client CRA 代理到 5000）
npm run dev
# 单独起后端 / 前端 / 测试 / 类型检查 / 构建
npm run dev:backend
npm run dev:client
npm run test # backend/.venv/bin/python -m pytest（446+ 项）
npm run typecheck
npm run build # client/react-scripts build → client/build/
# 冒烟测试（后端单测入口）
cd backend && .venv/bin/python tests/smoke.py
```
## 部署（生产 = 甲骨文云主机，2026-09-12 起；此前是 NAS，已下线）
- **位置**：`129.146.26.249` `/opt/garmin-health-lab`，**`ubuntu` 用户**跑
gunicorn `127.0.0.1:5500`（2 workers / 4 threads / --timeout 300），
systemd 单元 `garmin-health-lab.service`（`enabled`，随机器开机自启，
`Restart=always`）。和这台机器上其它服务（ai-gateway / auth-hub / fam-edge）
同一套约定：`/opt/<项目>` 下独立部署 + 独立 venv + Caddy 按子域名反代。
- **公网**：`https://garmin.zichuan.xyz` → Caddy → `127.0.0.1:5500`。
DNS（腾讯云 DNSPod，A 记录）与 TLS（Caddy 自动签发）都已配好。
~~旧的 `http://129.146.26.249:8124`~~ 已下线（走 NAS frpc 转发，隧道已拆）。
- **一键部署**：本地 `./deploy/push_oracle.sh`（tar 经 ssh key 认证同步
backend + 清空重推 client/build + pip install + systemctl restart，
**校验 main PID 变化 + health 200**）。前置：先 `npm run build`。
`deploy/push.sh` / `start.sh` / `stop.sh` / `S99garmin.sh` / `deploy.sh`
是 NAS 时代的脚本，已废弃保留仅供参考。
- **DB**：甲骨文本机 MariaDB 10.3.39（`127.0.0.1:3306`），独立账号
`garmin`（**注意**：`garmin@localhost` 与 `garmin@127.0.0.1` 是两个不同账号，
必须同密码建两份，否则 TCP 连接用的是另一个密码），库 `garmin_health_lab`。
和其它项目（`chat_relay`、`zhongyuan`）共用同一个 MariaDB 实例，各自独立库
独立账号。**这台机器磁盘 96% 已满**，改动前留意剩余空间。
- **AI 网关**：`AI_GATEWAY_BASE_URL` 现在是**本地回环** `http://127.0.0.1:5100/v1`
（不再经 Caddy/公网 —— 网关和这个服务同机了）。
- **auth-hub**：client `996aLPw4T5gl-rYZ`；回调只保留
`https://garmin.zichuan.xyz/auth/callback` 一条（NAS/旧公网端口那几条已用
`manage_clients remove-redirect-uri` 清掉）。改注册用
`/opt/auth-hub` 下 `PYTHONPATH=/opt/auth-hub/src venv/bin/python -m
auth_hub.manage_clients`。
- **NAS 现状**：`garmin_health_lab` 库已 `DROP DATABASE`（备份在本地
`~/Desktop/Work/backups/garmin_health_lab_nas_backup_20260912.sql.gz`，
20 张表逐条精确计数核对过一致后才删的），`S99garmin.sh` 开机项已移除，
frpc 配置里 `garmin-health` 转发段已删（`gitea`/`wordpress`/`fam-core`/
`nexusai` 那几条没动——**Gitea 还在 NAS 上，这个仓库的 git remote 仍然指
向它**，这次迁移只搬了应用和数据，没搬源码托管）。
- **部署/排障前**：先读 `PROGRESS.md` 与 `deploy/` 脚本确认事实（曾经凭旧记忆
断言"无线上环境"而误判，后来又把"生产在 NAS"当成默认事实——**两次都错在
没有先查，部署位置是会变的**）。
## 关键约定与坑（写代码/改样式前看）
1. **日期一律本地日历日期**，别用 `toISOString()`（UTC，UTC+8 每天前 8 小时
查的是昨天）。前端统一走 `client/src/lib/day.ts`。
2. **阈值全部来自公开参考值，AI 只解读不定阈值**（设计原则，勿破）。
3. **Framework7 全局 `button { width: 100% }`** 会把任何 `<button>` 拉满父容器
——自定义组件里的按钮要显式 `width: auto`（Copilot 浮窗 ✕/发送按钮曾因此
错位，见 `Copilot.css` 注释）。F7 `.navbar .left/.right` 的 frosted pill 也
需在 `f7theme.css` 覆盖。
4. **同步限流**：真正把账号打进 429 的是 **SSO 换令牌端点**，不是数据端点。
`refresh_oauth2()` 刷出来的新令牌**必须写回 DB**（`_persist_token`）——不写回
的话，每次客户端缓存过期（15 分钟）、每个 gunicorn worker、每次部署重启，都会
从库里读回同一个过期令牌再换一次，而这个端点按账号限流、能封几小时。
2026-09-03 排查一整天的根因就是这个。
**窗口内每次尝试都会延长封锁**（实测：一次同步把截止时间从 00:41 推到 15:26）。
所以 `sync_status.rate_limit_source` 区分 `sso` / `data`：只有 sso 冷却会拒绝
动作，且只拒绝「刷新令牌」和「重新绑定」这两个真的会打登录端点的操作——库里
令牌没过期就照常同步。**重新输账号密码换新令牌解决不了**：`garth.login()` 是
同一个端点、更重的流程，限流按账号计，换设备换网络都绕不开。用户可用 force
推翻我们自己猜的 24 小时。
数据端点另有节流：所有调用经 `services/garmin_throttle.py` 的代理，默认间隔
0.5s + 单次预算 1200 次（依据见该文件顶部）。
429 退避 24h，`rate_limited_until` 以 **DB 为准**（多 worker 内存不一致会卡死
守卫），且只作**信息**不作闸门；`_is_rate_limited` 沿异常 `__cause__` 链识别
RetryError 里的 429。
5. **AI 生成慢**：网关上游推理模型单次 2~5 分钟，晨报走后台生成 + 轮询，
接口超时/流式不可靠见 `services/ai.py` 的非流式回退；生产队列并发
`AI_JOB_CONCURRENCY=2`（共享网关，太高会把别家打成 502）。
6. **迁移幂等**：`db.py` 的 `init_db()` 会被多 worker 并发调用，所有
`ALTER/CREATE` 必须幂等（`CREATE TABLE IF NOT EXISTS` + 先查列再加列）。
7. **不要提交**：`.env`、构建产物 `client/build`、SQLite 数据、`.workbuddy/`、
`.claude/`（已在 .gitignore）。改代码后同步 `backend/static/` 用 deploy 流程。
8. **一任务一 commit**，完成即推送 NAS Gitea（origin 就是 Gitea）。
## 测试
- pytest（446+ 项）覆盖：设置吸附/校验、身体年龄、运动详情列存解析、Garmin
同步入库与只读本地保证、AI 缓存/队列、调度器等。改后端先跑
`npm run test`（或 `cd backend && .venv/bin/python -m pytest`）。
- 前端无单测框架，用 Chrome headless + CDP 截图做界面回归（见每日日志）。
## 下一步 / 已知问题
- 看 `PROGRESS.md` 的待办区与 `docs/REQUIREMENTS.md`。
- 双后端 SQL 注意：**MariaDB 的 CAST 不支持 TEXT 目标类型**（SQLite 支持）——写跨库
查询不要用 `CAST(x AS TEXT)`，两侧都是字符串时直接比较即可（曾导致 refill_backlog
活动分支在 NAS 上 1064 刷屏，commit 617c832 已修）。
- 双后端 SQL 注意：**MariaDB 的 `trigger` 是保留字，SQLite 却允许它做列名**——本地
pytest 全绿也不代表生产可用（首次部署 `sync_history` 即 1064 起服务失败）。跨库建表
列名避免 `trigger`，用 `trigger_kind` 之类替代（commit 5e6fc01）。
Reference in New Issue View Git Blame Copy Permalink