ericwyuan/sentinel-home-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 清理已删除的 /api/ss/webhook 端点在文档中的残留描述

Browse Source 
上次 SS Webhook 重构（cf3d145）已经彻底移除了 /api/ss/webhook 接收端点
（motion_bp.py 不再注册该路由），但 README.md 里 5 处描述、鉴权白名单
说明都还停留在"保留为可选低延迟补充"，跟实际代码不符，逐处订正。

顺带更新 vite.config.js 里一句过时注释（还写"生产环境由 fam-core 的
Flask 同源提供"，实际前端已经迁到云服务器 Caddy 托管）。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
ericwyuan
2026-08-28 09:31:41 +08:00
parent 09708bd9a4
commit 3ec79de911
2 changed files with 6 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
README.md
View File

@@ -69,7 +69,7 @@ Orchestrator 视觉阶段按 `fallback` 模式顺序降级：Gemini → NVIDIA N
**网络要点（推送模式）**：
- 服务间通信只有两条出站：**NAS → Oracle 公网 IP:5000**（① `GET /api/oracle/sync` 拉增量 + `POST /api/oracle/people/correct` 命名回推 ② `POST /api/ss/motion` 推送运动侦测事件）。Edge 不需要反向访问 NAS
- **运动事件获取（NAS 轮询驱动）**：FAM-Core MotionNotifier 每 60s 轮询本机 Surveillance Station 事件列表 API（`SYNO.SurveillanceStation.EventCenter.Event`），增量推送 Oracle。`/api/ss/webhook` 端点在代码中保留为可选低延迟补充（SS 行動規則 Webhook 未配置则不触发）。若启用 SS Webhook，目标地址改为云服务器公网 `http://129.146.26.249/api/ss/webhook?token=ORACLE_SYNC_TOKEN`。
- **运动事件获取（NAS 轮询驱动）**：FAM-Core MotionNotifier 每 60s 轮询本机 Surveillance Station 事件列表 API（`SYNO.SurveillanceStation.EventCenter.Event`），增量推送 Oracle。**2026-08-25 起 `/api/ss/webhook` 接收端点已彻底移除**（`motion_bp.py` 不再注册该路由），轮询是唯一路径，不再保留 Webhook 可选补充。
- Oracle 端 Ollama 端口 11434 不对外暴露；聊天请求 NAS → FAM-Edge `/api/edge/chat/ask`（保持不变的对外契约）→ **FAM-Edge 转发到同机的 AI-Gateway :5100**（`/v1/chat/completions`，OpenAI 兼容协议，Bearer token 鉴权）→ NVIDIA/Gemini/Ollama 降级链。AI-Gateway 自己对外监听 0.0.0.0:5100（Bearer token 鉴权 fail-closed），供其他项目直接接入，不止服务本系统
- Tailscale 两节点已安装在线，但 NAS tailscaled 为 userspace 模式且防火墙端口不通，暂走公网 IP
@@ -116,7 +116,7 @@ Orchestrator 视觉阶段按 `fallback` 模式顺序降级：Gemini → NVIDIA N
#### 2.2.1 运动监测链路（v3，NAS 轮询驱动）
摄像头动作事件由 **NAS 端 MotionNotifier 轮询 Surveillance Station 事件列表**获取（简单稳定，事件不遗漏；Webhook 端点在代码中保留为可选低延迟补充）：
摄像头动作事件由 **NAS 端 MotionNotifier 轮询 Surveillance Station 事件列表**获取（简单稳定，事件不遗漏；2026-08-25 起 Webhook 接收端点已彻底移除，轮询是唯一路径）：
Surveillance Station (NAS 本机)
│ SYNO.SurveillanceStation.EventCenter.Event method=List
@@ -177,7 +177,7 @@ Orchestrator 视觉阶段按 `fallback` 模式顺序降级：Gemini → NVIDIA N
| Chat-Handler | `chat_handler/chat_handler.py` | `/api/chat/ask` 查 `sync_events` 拼上下文 → 经 Oracle `/api/edge/chat/ask` 问答（FAM-Edge 转发到独立 AI-Gateway 服务，接口契约不变）→ 写 chat_history |
| Member-Manager | `member_manager/member_manager.py` | `/api/member/unnamed` / `/api/member/list` / `/api/member/name` / `/api/member/merge`；命名/合并回推 Oracle 并即时拉回本地镜像 |
| MotionNotifier | `motion_notifier/motion_notifier.py` | **轮询主路径**（`poll_enabled=true`）：每 `poll_interval_sec`(60s) 查 SS `EventCenter.Event.List`（camera_ids/event_types=10）→ 增量推送 Oracle `/api/ss/motion`；游标存 MariaDB（重启续用/补推停机期间事件，失败批次不前进）；心跳线程定期空 POST 证明链路存活；启动时拉取 SS 摄像头「名→id」映射并配置兜底 |
| Motion-BP | `motion_bp.py` | `POST /api/ss/webhook` 可选低延迟补充（SS 行動規則 Webhook 未配置则不触发，兼容 JSON/表单/单条/数组）→ 映射 → 推送 Oracle；`GET /api/ss/status` 查询状态 |
| Motion-BP | `motion_bp.py` | **2026-08-25 起不再提供 `/api/ss/webhook` 接收端点**（轮询是唯一路径）；`GET /api/ss/status` 查询 MotionNotifier 状态 |
| UI-API | `ui_api.py` | `/api/ui/*` 只读接口（videos/stats/people/people-clips/attention-events/named-members/model-stats/service-status），供 Vue 前端渲染 |
| 公共层 | `db_layer.py` / `config_loader.py` / `logger.py` | PyMySQL 连接（unix_socket）；同步镜像 CRUD；`get_sync_people_clips()` 人物→运动片段查询；文件日志 |
@@ -329,7 +329,6 @@ chat_history 独立表（问答上下文摘要留存）
| `/api/member/list` | GET | 全部人物（label + canonical_name + 是否命名） |
| `/api/member/name` | POST | 命名：`{"label","canonical_name"}` → 回推 Oracle 并即时拉回本地镜像 |
| `/api/member/merge` | POST | 合并：`{"source","target"}` → 将 source 并入 target 身份（统一 canonical_name） |
| `/api/ss/webhook` | POST | **可选 + 免登录**：接收 Surveillance Station Webhook（参数 `event_time`/`device_name`/`event_name`/`server_name`/`thumbnail_url`），映射后推送 Oracle `/api/ss/motion`（SS 行動規則未配置则不触发；SS 推送无法携带登录态故列入白名单） |
| `/api/ss/status` | GET | 运动监测状态：`poll_enabled` / `camera_loaded` / `camera_map` / `pushed_total` / `last_error` / 心跳 |
| `/api/ui/videos` | GET | 运动片段会话列表（`?date=&page=`；**只返回 `motion_` 前缀或有事件的会话**，0 段素材不展示） |
| `/api/ui/videos/<id>` | GET | 会话详情：`{video, events[]}`（事件含 person_list_json / person_appearances_json / is_attention_event） |
@@ -549,7 +548,7 @@ task_id=289（30s 测试片段）全链路打通：推送 5.7MB → Edge 分析
> - `3000` → NAS Gitea、`8500` → NAS WordPress(8088)、**`8000` → NAS FAM-Core（本系统）**
> - 前端入口 `http://129.146.26.249/`（Caddy 托管 FAM-UI，/api 经 frp 隧道反代回 NAS FAM-Core :8000），**需登录**（见 §5.2 `/api/login`）
>
> **登录校验（2026-08-22 新增，2026-08-23 改为 fail-closed）**：FAM-Core 全站拦截（`auth.py`）——页面未登录 302 `/login`（内置深色登录页，SPA 零改动），`/api/*` 未登录 401；凭据 `FAM_AUTH_USER`/`FAM_AUTH_PASS`（NAS `.env` 配置，**无硬编码默认值**——这两个变量跟 NAS SSH 密码是同一个值，公网入口不能有"没配置就退回已知密码"的兜底，`.env` 没配好这两项时直接拒绝所有登录）；白名单免登录：`/login` `/api/login` `/api/logout` `/api/auth/check` `/health` `/api/ss/webhook` `/assets/*`。登录态为进程内 token + HttpOnly cookie（**2 小时**），过期或重启 fam-core 需重新登录。
> **登录校验（2026-08-22 新增，2026-08-23 改为 fail-closed）**：FAM-Core 全站拦截（`auth.py`）——页面未登录 302 `/login`（内置深色登录页，SPA 零改动），`/api/*` 未登录 401；凭据 `FAM_AUTH_USER`/`FAM_AUTH_PASS`（NAS `.env` 配置，**无硬编码默认值**——这两个变量跟 NAS SSH 密码是同一个值，公网入口不能有"没配置就退回已知密码"的兜底，`.env` 没配好这两项时直接拒绝所有登录）；白名单免登录：`/login` `/api/login` `/api/logout` `/api/auth/check` `/health` `/assets/*`（`/api/ss/webhook` 已随端点一起移除，2026-08-25）。登录态为进程内 token + HttpOnly cookie（**2 小时**），过期或重启 fam-core 需重新登录。
> Oracle 部署方式：本地 git 提交 push Gitea → tar 管道到 `/opt/fam-edge`（`--strip-components=1` 解临时目录再 cp，避免动 data/venv/gdrive_videos）。**AI-Gateway 是独立 git 仓库**（http://192.168.50.64:3000/ericwyuan/ai-gateway，见 §10.4），同样 tar 管道部署到 `/opt/ai-gateway`，互不影响。