From 4331a07462d888d18822fd11310ce6774c9b554b Mon Sep 17 00:00:00 2001 From: ericwyuan Date: Sat, 12 Sep 2026 23:53:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20docs/=20=E7=9B=AE=E5=BD=95=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=E7=94=B2=E9=AA=A8=E6=96=87=E9=83=A8=E7=BD=B2=E4=BA=8B?= =?UTF-8?q?=E5=AE=9E=EF=BC=88=E4=B8=8A=E4=B8=80=E6=8F=90=E4=BA=A4=E6=BC=8F?= =?UTF-8?q?=E5=8A=A0=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 上一个提交 git add 漏了 docs/，架构/开发/需求/auth-hub 集成文档里的 NAS IP、8124 端口还是旧的，补上。 Co-Authored-By: Claude Sonnet 5 --- docs/ARCHITECTURE.md | 29 +++++++++++++++++------------ docs/AUTH_HUB_INTEGRATION.md | 6 +++--- docs/DEVELOPMENT.md | 5 +++-- docs/REQUIREMENTS.md | 4 ++-- 4 files changed, 25 insertions(+), 19 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5a19a2f..c0ebeaa 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,7 @@ # 项目架构说明 -> 现状（2026-09-02）：后端为 **Python/Flask 单体**，生产部署在 **NAS :8124**。 +> 现状（2026-09-12）：后端为 **Python/Flask 单体**，生产部署在**甲骨文云主机** +> （`garmin.zichuan.xyz`，此前是 NAS :8124，已整体迁移）。 > 早期 Node.js/Express + `server/` 目录的后端已被整体重写为 > `backend/`（Python），本文件描述的是当前实现。 @@ -17,7 +18,7 @@ │ HTTP/JSON + JWT（Bearer）；Copilot 用 SSE ▼ ┌──────────────────────────────────────────────────────────┐ -│ Flask 单体（gunicorn 2w/4t，NAS :8124） │ +│ Flask 单体（gunicorn 2w/4t，甲骨文云主机 :5500） │ │ ┌────────────────────────────────────────────────────┐ │ │ │ 蓝图层 routes/ /api/auth /api/garmin /api/health │ │ │ │ /api/analysis /api/settings │ │ @@ -142,16 +143,20 @@ Copilot: POST /analysis/copilot 走 SSE(stream_chat，失败非流式回退) - **Development 本地**：`npm run dev` = Flask 5000（`BACKEND_PORT` 固定，避开 `PORT` 被 CRA 抢占）+ CRA dev server 3000（proxy → 5000）。SQLite。 -- **Production NAS**：`192.168.50.64` `/volume1/web/garmin-health-lab`，root - 跑 gunicorn `0.0.0.0:8124`（2w/4t，--timeout 300 —— AI 生成可长达分钟级）， - 开机自启 DSM 任务调度器 → `deploy/S99garmin.sh`；MariaDB 10.11 - root@`/run/mysqld/mysqld10.sock`，库 `garmin_health_lab`。 -- **公网**：NAS frpc → 甲骨文 `129.146.26.249:8124`（frp 隧道，重连需数秒）。 -- **一键部署**：`deploy/push.sh`（tar-over-ssh 同步 backend+deploy、清空重推 - `client/build`、sudo 重启、**pid 变化 + health 200 双校验**）；前端先 - `npm run build`。`deploy/start.sh` / `stop.sh` 供手工与开机脚本调用。 -- **auth-hub**：回调注册 LAN `192.168.50.64:8124` 与公网 `129.146.26.249:8124` - 两个地址（client `996aLPw4T5gl-rYZ`）；CORS 白名单含两地址 + localhost。 +- **Production**（甲骨文云主机，`129.146.26.249`）：`/opt/garmin-health-lab`， + `ubuntu` 用户跑 gunicorn `127.0.0.1:5500`（2w/4t，--timeout 300 —— AI 生成 + 可长达分钟级），systemd 单元 `garmin-health-lab.service`（`enabled`， + `Restart=always`）；MariaDB 10.3.39 本机 TCP、独立账号 `garmin`，库 + `garmin_health_lab`。和这台机器上的 ai-gateway/auth-hub/fam-edge 同一套 + 部署约定。此前（2026-09-01~12）部署在 NAS，已整体迁移并下线。 +- **公网**：Caddy 反代 `https://garmin.zichuan.xyz` → `127.0.0.1:5500`， + TLS 自动签发。 +- **一键部署**：`deploy/push_oracle.sh`（ssh key 认证同步 backend、清空重推 + `client/build`、pip install、systemctl restart、**PID 变化 + health 200 + 双校验**）；前端先 `npm run build`。NAS 时代的 `deploy/push.sh` / + `start.sh` / `stop.sh` / `S99garmin.sh` 已废弃，保留仅供参考。 +- **auth-hub**：回调只注册 `https://garmin.zichuan.xyz/auth/callback` + 一条（client `996aLPw4T5gl-rYZ`）；CORS 白名单含该地址 + localhost。 ## 关键设计约束 diff --git a/docs/AUTH_HUB_INTEGRATION.md b/docs/AUTH_HUB_INTEGRATION.md index 4b5895d..902de8e 100644 --- a/docs/AUTH_HUB_INTEGRATION.md +++ b/docs/AUTH_HUB_INTEGRATION.md @@ -12,12 +12,12 @@ | `AUTH_HUB_CLIENT_SECRET` | 对应 secret（**只放 .env，不入库**） | | `AUTH_HUB_REDIRECT_URI` | 回调地址，必须与 auth-hub 侧注册值完全一致 | -## 生产 client（NAS :8124） +## 生产 client（甲骨文云主机，`garmin.zichuan.xyz`；2026-09-12 前是 NAS :8124） - client_id：`996aLPw4T5gl-rYZ` - 在 auth-hub 注册的回调： - - LAN：`http://192.168.50.64:8124/auth/callback` - - 公网（frp）：`http://129.146.26.249:8124/auth/callback` + - `https://garmin.zichuan.xyz/auth/callback`（唯一注册的回调地址；NAS 时代 + 的 LAN / frp 地址已用 `manage_clients remove-redirect-uri` 清掉） - 注意 auth-hub 的 dev 与 prod 是**两套独立数据库、各自注册 client**： 在 dev auth-hub 上创建的 client 不能用于 prod，反之亦然。 diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index f2e446e..d841dcc 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -184,7 +184,8 @@ npm run build # 1. 先出前端产物 入库 + 「只读本地」保证、AI 缓存/队列互斥、调度器、auth-hub 客户端。 - 前端界面回归：本地起后端 + CRA，Chrome headless + CDP 截图比对 （参见 `.workbuddy/memory/` 日志里的做法）。 -- 生产自测入口：NAS `curl http://127.0.0.1:8124/api/health/status`（200）。 +- 生产自测入口：甲骨文云主机 `curl http://127.0.0.1:5500/api/health/status` + （200），或公网 `curl https://garmin.zichuan.xyz/api/health/status`。 ## 环境变量速查（backend/.env） @@ -198,7 +199,7 @@ npm run build # 1. 先出前端产物 | `JWT_EXPIRY_DAYS` | 7 | token 有效期 | | `AUTH_HUB_BASE_URL` | http://129.146.26.249:5300 | SSO 提供方 | | `AUTH_HUB_CLIENT_ID` / `_SECRET` | — | SSO 客户端（生产 996a…） | -| `AUTH_HUB_REDIRECT_URI` | http://129.146.26.249:8124/auth/callback | 回调地址 | +| `AUTH_HUB_REDIRECT_URI` | https://garmin.zichuan.xyz/auth/callback | 回调地址 | | `STATIC_DIR` | backend/static | 前端产物目录（生产 ./static） | | `AI_GATEWAY_BASE_URL` | https://ai.zichuan.xyz/v1 | OpenAI 兼容网关 | | `AI_GATEWAY_TOKEN` | — | 网关 Bearer token | diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index 665ff39..b353b24 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -13,8 +13,8 @@ | # | 需求 | 理解 | 状态 | |---|---|---|---| | 1.1 | 新建项目分析佳明海外账号健康数据 | Gitea 自建仓库，Web 应用 | ✅ | -| 1.2 | 部署到 NAS（192.168.50.64），用 MariaDB | Flask + gunicorn(root, :8124) + NAS MariaDB 10.11（库 `garmin_health_lab`），SQLite 供开发 | ✅ | -| 1.3 | 公网可访问 | NAS frpc 隧道 → 甲骨文公网 `129.146.26.249:8124` | ✅ | +| 1.2 | 部署到甲骨文云主机，用 MariaDB | Flask + gunicorn(ubuntu, systemd, :5500) + 本机 MariaDB 10.3.39（库 `garmin_health_lab`），SQLite 供开发；2026-09-12 从 NAS 迁移 | ✅ | +| 1.3 | 公网可访问 | Caddy 反代 `https://garmin.zichuan.xyz`（自动 TLS），与本机 ai-gateway/auth-hub 同一套约定 | ✅ | | 1.4 | 单元测试 / 界面自测 / 性能测试 | 446 项 pytest；界面用浏览器实测；接口逐个计时 | ✅ | | 1.5 | 一任务一 commit，完成即推送 | 已成为固定流程 | ✅ | | 1.6 | auth-hub 统一登录（SSO） | OAuth2/OIDC，回调注册 LAN + 公网两地址；本地邮箱密码登录已移除 | ✅ |