91 lines
5.6 KiB
Markdown
91 lines
5.6 KiB
Markdown
# Sense M1/M2 接入骨架
|
||
|
||
本目录是 YoVision Sense 的 M1/M2 接入骨架。数据库保存期望态，ONVIF 和 MediaMTX 通过端口隔离；M1 默认使用 SQLite，T-009 增加 PostgreSQL 双 schema 生产路径。默认关闭真实 ONVIF，显式设置 `SENSE_ONVIF_MODE=standard` 后才启用标准 SOAP/WS-Security 适配器。T-006 的真实样机结论仅覆盖已批准的精确海康基线，不能据此宣称多品牌兼容。
|
||
|
||
## 常用命令
|
||
|
||
```powershell
|
||
cd Sense
|
||
go mod download
|
||
go generate ./internal/mtx
|
||
go test ./...
|
||
go vet ./...
|
||
go build -o bin/sense-api.exe ./cmd/sense-api
|
||
go run ./cmd/sense-api
|
||
```
|
||
|
||
Unix 将构建产物改为 `bin/sense-api`。服务默认监听 `127.0.0.1:8080`，SQLite 默认写入 `Sense/data/sense.db`，MediaMTX 控制 API 默认是 `http://127.0.0.1:9997`。当前运行代码只有 `/healthz` 与 `/readyz`；Sense Control API v1 虽已冻结，但 HTTP handler 和认证尚未实现。
|
||
|
||
常用环境变量：
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `SENSE_HTTP_ADDR` | `127.0.0.1:8080` | HTTP 监听地址 |
|
||
| `SENSE_ALLOW_NON_LOOPBACK` | `false` | 显式允许监听非回环地址；只应在可信网络及外部认证/防火墙就绪后开启 |
|
||
| `SENSE_DB_DRIVER` | `sqlite` | `sqlite` 或 `postgres`；生产切换必须显式选择 `postgres` |
|
||
| `SENSE_DB_DSN` | `file:data/sense.db` | 所选 driver 的私有 DSN；不得写入日志、文档或仓库，PostgreSQL 密码优先由 `PGPASSFILE`/环境密钥提供 |
|
||
| `SENSE_MEDIAMTX_URL` | `http://127.0.0.1:9997` | MediaMTX 控制 API；不得包含 userinfo |
|
||
| `SENSE_RECONCILE_INTERVAL` | `5s` | 对账周期 |
|
||
| `SENSE_PROBE_INTERVAL` | `10s` | path 探活周期 |
|
||
| `SENSE_ONVIF_MODE` | `disabled` | `disabled` 或 `standard`；默认不访问真实摄像头 |
|
||
| `SENSE_ONVIF_RTSP_REWRITE_HOST` | 空 | NAT 或故障代理场景下重写 ONVIF 返回的 RTSP 主机 |
|
||
| `SENSE_ONVIF_RTSP_REWRITE_PORT` | `0` | 非零时重写 ONVIF 返回的 RTSP 端口 |
|
||
| `SENSE_ONVIF_RTSP_STRIP_QUERY` | `false` | 仅在已验证设备返回不可用查询串时显式移除；默认保留标准 URI 语义 |
|
||
|
||
设备台账只保存 `env://<key>` 凭据引用。真实适配器从进程环境读取以下变量，不把秘密写入 SQLite、日志或 MediaMTX 错误：
|
||
|
||
```text
|
||
SENSE_CREDENTIAL_<KEY>_ONVIF_USERNAME
|
||
SENSE_CREDENTIAL_<KEY>_ONVIF_PASSWORD
|
||
SENSE_CREDENTIAL_<KEY>_RTSP_USERNAME
|
||
SENSE_CREDENTIAL_<KEY>_RTSP_PASSWORD
|
||
```
|
||
|
||
`cmd/sense-lab` 是回环实验室播种与脱敏收敛查询工具，不是已冻结的公共设备管理 API。`cmd/rtsp-fault-proxy` 只用于 T-006 控制真实上游网络路径故障。
|
||
|
||
MediaMTX `v1.19.3` 应作为独立二进制启动并只在可信网络开放 API。获取与 SHA-256 校验值见 `docs/03-tech-stack.md`。生成客户端使用固定版本工具和 vendored 官方 OpenAPI；`internal/mtx/generated/client.gen.go` 不可手改。
|
||
|
||
## T-009 PostgreSQL 17.10
|
||
|
||
初始化 SQL 位于 `deploy/postgres/`，由高权限部署步骤按文件名前缀执行；Sense 进程不会自动创建角色、schema 或 Bell 对象。`bell_app` 拥有 Site/配额和 `bell.site_quota_v1`，`sense_app` 只能读取该视图，不能读取或写入 Bell 源表。应用登录角色和密码由部署环境创建，不进入仓库。
|
||
|
||
Windows 本机集成测试从仓库根目录执行：
|
||
|
||
```powershell
|
||
./scripts/test_postgres.ps1 -PgRoot D:\pgsql17
|
||
```
|
||
|
||
脚本要求冻结的 PostgreSQL `17.10`，使用 `initdb` 创建临时 trust 集群并只监听随机回环端口，重放 migration、执行权限断言和 PostgreSQL repository 测试后停止并清理。它会核对现有 `5432` listener 前后未变化，不读取或修改 `D:\pgsql17\data`。生产安装和恢复边界见 `deploy/postgres/README.md`。
|
||
|
||
选择 PostgreSQL 运行前，管理员必须已经安装 migration，并私下设置无密码回显的连接环境：
|
||
|
||
```powershell
|
||
$env:SENSE_DB_DRIVER = 'postgres'
|
||
$env:SENSE_DB_DSN = '由部署环境私下设置'
|
||
go run ./cmd/sense-api
|
||
```
|
||
|
||
PostgreSQL 启动会检查 Sense migration 版本及当前角色的跨 schema 权限；权限过宽、配额视图不可读或 schema 未安装时 readiness 初始化失败。默认 SQLite 路径和 `cmd/sense-lab` 保持不变，T-009 不搬迁现有 SQLite 数据。
|
||
|
||
Windows 本地准备 MediaMTX（从仓库根目录执行）：
|
||
|
||
```powershell
|
||
$asset = "mediamtx_v1.19.3_windows_amd64.zip"
|
||
Invoke-WebRequest "https://github.com/bluenviron/mediamtx/releases/download/v1.19.3/$asset" -OutFile "$env:TEMP\$asset"
|
||
if ((Get-FileHash "$env:TEMP\$asset" -Algorithm SHA256).Hash.ToLowerInvariant() -ne "5d82148d1032a6a190d9909a2997d9989457aaadf49af87dd02cd4512d31bebe") { throw "MediaMTX checksum mismatch" }
|
||
Expand-Archive "$env:TEMP\$asset" -DestinationPath "$env:TEMP\yovision-mediamtx-v1.19.3" -Force
|
||
& "$env:TEMP\yovision-mediamtx-v1.19.3\mediamtx.exe" "Sense\deploy\mediamtx.yml"
|
||
```
|
||
|
||
Linux amd64 使用同版 `mediamtx_v1.19.3_linux_amd64.tar.gz`，SHA-256 为 `a7ba21268fccda3ebc43fdad76b87fddb85ce77e725b5cb637bca724b5394fbe`。不要把下载的二进制或摄像头凭据提交到仓库。
|
||
|
||
## T-006 Windows 集成验证
|
||
|
||
脚本会启动两套独立 MediaMTX、4 个独立 FFmpeg publisher、真实摄像头网络故障代理和 Sense，在临时目录播种 5 条期望态，执行四类恢复后再连续观察 30 分钟。脚本只输出脱敏计数与时间，不保存视频：
|
||
|
||
```powershell
|
||
./Sense/scripts/t006-integration.ps1 -CameraEnv D:\path\to\ip_camera.env
|
||
```
|
||
|
||
`ip_camera.env` 必须保持在 Git 忽略范围内。调试时可把 `-ObservationMinutes` 降为 1；正式 T-006 证据必须使用默认 30 分钟，且最终 `maximum_unconverged`、`final_unconverged` 都为 0。
|