sentinel-home-ai/docs/DEPLOY.md

部署指南（v3 运动事件驱动架构，2026-08-22 同步）

1. NAS 端部署 (FAM-Core + MariaDB；FAM-UI 见 §1.3，部署在云服务器)

1.1 MariaDB

# 通过 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 <密码>

1.2 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_sync.base_url/token、motion_notifier（DSM 凭据走 .env）

# 仓库根 .env 提供 DSM_ACCOUNT/DSM_PASSWORD/ORACLE_SYNC_TOKEN/AUTH_HUB_*（start_core.sh 会 source）

# 登录改接 auth-hub 统一登录（2026-08-31），先在 auth-hub 侧注册本站点 client：
#   ssh 到 auth-hub 所在 Oracle 主机，cd /opt/auth-hub
#   python -m auth_hub.manage_clients create "FAM-Core" "http://129.146.26.249/api/auth/callback"
#   输出的 client_id/client_secret 明文只显示这一次，立即抄进 .env
# 仓库根 .env 补齐四项（缺任一项 fam-core 直接拒绝所有登录，fail closed）：
#   AUTH_HUB_ISSUER=http://129.146.26.249:5300
#   AUTH_HUB_CLIENT_ID=<上一步输出>
#   AUTH_HUB_CLIENT_SECRET=<上一步输出>
#   AUTH_HUB_REDIRECT_URI=http://129.146.26.249/api/auth/callback   # 必须跟注册时的 redirect_uri 逐字符一致

# 启动（含 Oracle-Sync + MotionNotifier 轮询）
cd /volume1/web/sentinel-home-ai && bash start_core.sh

1.3 FAM-UI（Vue3 SPA，托管于云服务器 Caddy :80）

cd /Users/ericwyuan/Desktop/Work/sentinel-home-ai/fam-ui   # 本地开发机
npm install
npm run build          # 产物 fam-ui/dist/
# 部署 dist 到云服务器（Caddy 静态目录，/api 经 frp 隧道反代回 NAS）：
tar czf - fam-ui/dist | ssh -i ~/.ssh/oracle_new ubuntu@129.146.26.249 \
  'sudo tar xzf - --strip-components=2 -C /var/www/fam-ui && sudo chown -R ubuntu:ubuntu /var/www/fam-ui'
# 浏览器访问 http://129.146.26.249/（Caddy 托管，/api/* 反代 NAS fam-core）

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

2.1 系统依赖

sudo apt update && sudo apt install -y ffmpeg python3-opencv

# Ollama + qwen2.5:7b（纯文本，仅问答兜底）
curl -fsSL https://ollama.com/install.sh | sh
systemctl enable ollama && systemctl start ollama
ollama pull qwen2.5:7b

2.2 FAM-Edge（systemd 守护）

cd /opt/fam-edge
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 配置：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 restart fam-edge    # 部署代码后必须用 systemctl 重启，勿手动 setsid

3. 代码同步（tar 管道，scp 在 NAS 被禁用）

# 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.26.249 '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 运动监测	curl http://localhost:8000/api/ss/status	poll_enabled: true, running: true
云服务器 FAM-UI	浏览器访问 http://129.146.26.249/（Caddy 托管）	未登录被 302 到 auth-hub 登录页；登录（审批过的 auth-hub 账号）后跳回展示 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