[文档] 代码-文档一致性整理 - README 同步 v3 全量(2.1网络/3模块表/4表结构/5 API含people-clips/6.1历史标注/8部署systemd+Vue3+config/12进度); docs/DEPLOY.md 重写为 v3; 删除过时 start_ui.sh(Streamlit); start_edge.sh 注明 systemd 为准; 补提交 test_motion_notifier

2026-08-22 13:14:38 +08:00
parent 96644599d3
commit 354ff18101
6 changed files with 348 additions and 212 deletions
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -1,11 +1,10 @@
-# 部署指南
+# 部署指南（v3 运动事件驱动架构，2026-08-22 同步）

 ## 1. NAS 端部署 (FAM-Core + FAM-UI + MariaDB)

 ### 1.1 MariaDB
 ```bash
-# 安装 MariaDB (通过 Synology 套件中心)
-# 确认端口 3306 可用
+# 通过 Synology 套件中心安装 MariaDB（10.11），unix_socket=/run/mysqld/mysqld10.sock

 # 执行 DDL
 python3 scripts/init_db.py --host 127.0.0.1 --port 3306 --user root --password <密码>
@@ -13,143 +12,80 @@ python3 scripts/init_db.py --host 127.0.0.1 --port 3306 --user root --password <

 ### 1.2 FAM-Core
 ```bash
-cd /path/to/sentinel-home-ai/fam-core
+cd /volume1/web/sentinel-home-ai/fam-core
 python3 -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt

 # 配置
 cp config/config.yaml.example config/config.yaml
-# 编辑 config.yaml: 数据库密码、Oracle Tailscale IP、token 等
+# 编辑 config.yaml：数据库密码、oracle_sync.base_url/token、motion_notifier（DSM 凭据走 .env）

-# 启动
-./scripts/start_core.sh
-# 或手动: gunicorn -w 1 -b 0.0.0.0:8000 --timeout 120 src.fam_core.app:app
+# 仓库根 .env 提供 DSM_ACCOUNT/DSM_PASSWORD/ORACLE_SYNC_TOKEN（start_core.sh 会 source）
+
+# 启动（含 Oracle-Sync + MotionNotifier 轮询）
+cd /volume1/web/sentinel-home-ai && bash start_core.sh
 ```

-### 1.3 FAM-UI
+### 1.3 FAM-UI（Vue3 SPA，无独立进程）
 ```bash
-cd /path/to/sentinel-home-ai/fam-ui
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-
-# 配置
-cp config/config.yaml.example config/config.yaml
-# 编辑 config.yaml: 数据库连接、FAM-Core 地址
-
-# 启动
-./scripts/start_ui.sh
-# 或手动: streamlit run src/app.py --server.port 8501 --server.address 0.0.0.0
+cd /Users/ericwyuan/Desktop/Work/sentinel-home-ai/fam-ui   # 本地开发机
+npm install
+npm run build          # 产物 fam-ui/dist/
+# 部署 dist 到 NAS（构建产物不入库）：
+tar czf - fam-ui/dist | ssh -p 2222 ericwyuan@192.168.50.64 \
+  'cd /volume1/web/sentinel-home-ai && rm -rf fam-ui/dist && tar xzf -'
+# 浏览器访问 http://192.168.50.64:8000（由 FAM-Core static_app.py 托管，Vue Router history 回退）
 ```

 ## 2. Oracle 端部署 (FAM-Edge + Ollama + FFmpeg)

 ### 2.1 系统依赖
 ```bash
-# FFmpeg
-sudo apt update && sudo apt install -y ffmpeg
+sudo apt update && sudo apt install -y ffmpeg python3-opencv

-# OpenCV 依赖
-sudo apt install -y python3-opencv libopencv-dev
-
-# Ollama
+# Ollama + qwen2.5:7b（纯文本，仅问答兜底）
 curl -fsSL https://ollama.com/install.sh | sh
-systemctl enable ollama
-systemctl start ollama
-
-# 拉取模型
-ollama pull llava-phi3
+systemctl enable ollama && systemctl start ollama
+ollama pull qwen2.5:7b
 ```

-### 2.2 FAM-Edge
+### 2.2 FAM-Edge（systemd 守护）
 ```bash
-cd /path/to/sentinel-home-ai/fam-edge
+cd /opt/fam-edge
 python3 -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt

-# 配置
-cp config/config.yaml.example config/config.yaml
-# 编辑 config.yaml: NAS Tailscale IP、media_token、Gemini API Key
-
-# 设置 Gemini API Key 环境变量
-export GEMINI_API_KEY="your-api-key-here"
-
-# 启动
-./scripts/start_edge.sh
-# 或手动: gunicorn -w 1 -b 0.0.0.0:5000 --timeout 600 src.fam_edge.app:app
-```
-
-### 2.3 模型可行性压测 (阶段一验证)
-```bash
-# 测试 llava-phi3 单张图推理耗时
-ollama run llava-phi3 "描述这张图片" --images /path/to/test.jpg
-
-# 预期:
-# - 单张 ≤ 8 秒 → 可行
-# - 单张 ≤ 30 秒 → 可接受
-# - 单张 > 30 秒 → 需换更小模型或减帧
-```
-
-## 3. Tailscale 组网
-
-```bash
-# NAS 端
-curl -fsSL https://tailscale.com/install.sh | sh
-sudo tailscale up
-
-# Oracle 端
-curl -fsSL https://tailscale.com/install.sh | sh
-sudo tailscale up
-
-# 验证
-# NAS: ping 100.x.x.20 (Oracle Tailscale IP)
-# Oracle: ping 100.x.x.10 (NAS Tailscale IP)
-```
-
-## 4. 开机自启 (可选)
-
-### NAS 端 (使用任务计划)
-```bash
-# Synology DSM -> 控制面板 -> 任务计划 -> 新增 -> 触发的任务 -> 开机
-# 脚本:
-cd /path/to/sentinel-home-ai
-./scripts/start_core.sh &
-./scripts/start_ui.sh &
-```
-
-### Oracle 端 (使用 systemd)
-```bash
-sudo tee /etc/systemd/system/fam-edge.service << 'EOF'
-[Unit]
-Description=FAM-Edge Service
-After=network.target ollama.service
-
-[Service]
-Type=simple
-User=ubuntu
-WorkingDirectory=/path/to/sentinel-home-ai/fam-edge
-Environment=GEMINI_API_KEY=your-api-key
-ExecStart=/path/to/sentinel-home-ai/fam-edge/venv/bin/gunicorn -w 1 -b 0.0.0.0:5000 --timeout 600 src.fam_edge.app:app
-Restart=always
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-EOF
+# 配置：config/config.yaml（素材目录/DB/模型/motion_segment）；.env 提供 ORACLE_SYNC_TOKEN/GEMINI_API_KEY*/NVIDIA_API_KEY

+# systemd 服务（已配置 /etc/systemd/system/fam-edge.service，Restart=always）
 sudo systemctl enable fam-edge
-sudo systemctl start fam-edge
+sudo systemctl restart fam-edge    # 部署代码后必须用 systemctl 重启，勿手动 setsid
 ```

-## 5. 验证清单
+## 3. 代码同步（tar 管道，scp 在 NAS 被禁用）
+
+```bash
+# NAS（fam-core）：仓库根即部署根，直接解包
+tar czf - --exclude=venv --exclude=__pycache__ fam-core | \
+  ssh -p 2222 ericwyuan@192.168.50.64 'tar xzf - -C /volume1/web/sentinel-home-ai'
+
+# Oracle（fam-edge）：/opt/fam-edge 是 fam-edge 根，--strip-components=1 解临时目录再 cp
+tar czf - --exclude=venv --exclude=__pycache__ --exclude=data --exclude=gdrive_videos fam-edge | \
+  ssh ubuntu@129.146.203.203 'mkdir -p /opt/fam-edge/tmp_d && tar xzf - --strip-components=1 -C /opt/fam-edge/tmp_d && \
+  cp -rf /opt/fam-edge/tmp_d/* /opt/fam-edge/ && rm -rf /opt/fam-edge/tmp_d && sudo systemctl restart fam-edge'
+```
+
+## 4. 验证清单

 | 项目 | 命令 | 预期 |
 |------|------|------|
 | NAS MariaDB | `mysql -u root -p -e "SHOW DATABASES"` | 包含 sentinel_home_ai |
 | NAS FAM-Core | `curl http://localhost:8000/health` | `{"status":"ok"}` |
-| NAS FAM-UI | 浏览器访问 `http://192.168.50.64:8501` | Streamlit 页面 |
-| Oracle FAM-Edge | `curl http://localhost:5000/health` | `{"status":"ok"}` |
-| Oracle Ollama | `curl http://localhost:11434/api/tags` | 模型列表含 llava-phi3 |
-| Tailscale | NAS `ping 100.x.x.20` | 通 |
+| NAS 运动监测 | `curl http://localhost:8000/api/ss/status` | `poll_enabled: true, running: true` |
+| NAS FAM-UI | 浏览器访问 `http://192.168.50.64:8000` | Vue3 SPA（时间轴/人物管理/统计） |
+| Oracle FAM-Edge | `curl http://localhost:5000/health` | `{"status":"ok","queue_alive":true}` |
+| Oracle 运动事件 | `sqlite3 /opt/fam-edge/data/oracle.db "SELECT COUNT(*) FROM ss_motion_events"` | >0（NAS 推送） |
+| Oracle 运动片段 | `ls /opt/fam-edge/motion_clips/` | 存在 motion_*.mp4（素材分割产物） |
+| Oracle Ollama | `curl http://localhost:11434/api/tags` | 模型列表含 qwen2.5:7b |