175 lines
7.8 KiB
Markdown
175 lines
7.8 KiB
Markdown
<!-- gitea-wiki-mirror:start -->
|
||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||
wiki_page: Local-Development-and-Verification
|
||
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.-
|
||
wiki_revision: 426001a8c28bde9c336ecc8b7166924f14aa55ae
|
||
synchronized_at: 2026-08-13T03:39:26Z
|
||
<!-- gitea-wiki-mirror:end -->
|
||
|
||
# 本地开发与验证
|
||
|
||
## 环境要求
|
||
|
||
| 工具 | 当前用途 | 检查命令 |
|
||
|---|---|---|
|
||
| Git | 版本和工作区保护 | `git --version` |
|
||
| Python 3 | Harness 脚本和测试 | `python --version` |
|
||
| Gitea | 工单与 Wiki | 浏览仓库或调用 MCP |
|
||
| Gitea PAT | Wiki 写入 | 仅由 MCP 或 `GITEA_TOKEN` 提供，不打印 |
|
||
|
||
Sense/Bell 的 Go、Node 与 pnpm 基线已冻结并记录于下文；Brain 的 Python/CUDA 以及 PostgreSQL、MediaMTX 精确版本仍将在对应骨架工单冻结。旧仓库环境不自动成为新项目事实。
|
||
|
||
## 第一次运行
|
||
|
||
1. 检查工作区：
|
||
|
||
```powershell
|
||
git status --short --branch
|
||
```
|
||
|
||
预期：显示 `main` 和本任务创建的引导文件，没有来源不明改动。
|
||
|
||
2. 检查 Harness：
|
||
|
||
```powershell
|
||
python dev_scripts/check_harness.py --strict
|
||
```
|
||
|
||
预期：输出“DevHarness 检查通过”。
|
||
|
||
3. 运行 Harness 测试：
|
||
|
||
```powershell
|
||
python -m unittest discover -s tests -v
|
||
```
|
||
|
||
预期：全部测试为 `ok`。
|
||
|
||
4. 对照 Wiki：
|
||
|
||
```powershell
|
||
python dev_scripts/sync_wiki_docs.py --check
|
||
```
|
||
|
||
预期：全部映射一致。
|
||
|
||
## 子项目命令状态
|
||
|
||
| 项目 | 构建 | 测试 | 运行 | 当前状态 |
|
||
|---|---|---|---|---|
|
||
| Sense | 待骨架工单冻结 | 待冻结 | 待冻结 | 未初始化业务代码 |
|
||
| Brain | 待骨架工单冻结 | 待冻结 | 待冻结 | 未初始化业务代码 |
|
||
| Bell | `go build ./...`；`pnpm build:prod` | `go test ./...`；`pnpm lint` | `go run . migrate`；`go run . serve`；`pnpm dev` | 首个独立纵切已实现，待验收 |
|
||
|
||
不得复制旧仓库命令来填空。每个骨架工单必须同时建立 README、可复制命令和最小测试。
|
||
|
||
## 常用调试方式
|
||
|
||
- Harness 语法：`python -m compileall -q dev_scripts tests`。
|
||
- 单测：`python -m unittest tests.test_harness_docs -v`。
|
||
- 查看差异：`git diff --check`、`git diff`。
|
||
- 查看 Wiki 配置：只查看 `wiki-docs.json`，不得打印 token。
|
||
- 跨项目问题先验证契约，再分别验证生产者和消费者，不直接修改两端猜测修复。
|
||
|
||
## 测试数据与日志
|
||
|
||
- 只使用合成或脱敏事件、合成 RTSP 和明确授权的实验室设备。ONVIF 自动化测试需覆盖 Basic、Digest challenge、Media 服务发现、跨主机地址归一化、拒绝地址凭据和禁止重定向。
|
||
- 不提交真实视频、客户名称、地址、手机号、摄像头密码或通知凭据；真实设备验证只记录状态与 Profile 数量，不记录设备地址、Authorization 或 Stream URI。
|
||
- 日志必须可按 request/event/alert ID 追踪，但不得记录 Authorization、Cookie 或连接密钥。
|
||
|
||
## 完成修改前
|
||
|
||
```powershell
|
||
python -m unittest discover -s tests -v
|
||
python dev_scripts/check_harness.py --strict
|
||
python dev_scripts/sync_wiki_docs.py --check
|
||
git diff --check
|
||
git status --short
|
||
```
|
||
|
||
业务工单还必须运行其声明的子项目测试；跨契约工单必须运行所有受影响项目的契约测试。未执行部分写入工单。
|
||
|
||
## Sense/Bell 固定工具链与只读参考源
|
||
|
||
根 `goadmin-baseline.json` 是机器可读基线。开始 Sense/Bell 骨架或升级工作前，先核对：
|
||
|
||
```powershell
|
||
Get-Content .\goadmin-baseline.json
|
||
|
||
git -C D:\github\goadmin\go-admin rev-parse HEAD
|
||
git -C D:\github\goadmin\go-admin-ui rev-parse HEAD
|
||
git -C D:\github\goadmin\go-admin-doc rev-parse HEAD
|
||
|
||
go version
|
||
node --version
|
||
pnpm --version
|
||
```
|
||
|
||
`D:\github\goadmin` 下三个仓库只允许读取和核对，不允许在其中开发或提交 yovision 产品代码。本机路径不是跨机器事实；缺少该路径时，应从清单中的上游 URL 检出相同 commit 到仓库外目录。
|
||
|
||
截至 2026-08-12，系统 Go 1.23.0 仍不满足基线；开发机已在仓库外安装并校验隔离 Go 1.26.5，并通过 Corepack 使用 pnpm 9.15.1。Sense、Bell 的后端测试/构建与前端 lint/build 已在该隔离工具链完成。隔离目录是开发机临时事实，不得写入部署配置；其他机器应从官方来源安装相同精确版本。
|
||
|
||
`go-admin-doc` 只用于理解上游框架；项目自己的架构、开发规则和版本事实仍以 yovision Wiki、Agent 规则与 `goadmin-baseline.json` 为准。
|
||
|
||
<!-- sense-runtime:start -->
|
||
## Sense 本地构建与验证
|
||
|
||
使用根 `goadmin-baseline.json` 的精确版本。当前机器可用的隔离 Go 路径为开发机临时工具目录，不应写入部署配置。
|
||
|
||
```powershell
|
||
$env:PATH = 'C:\Users\ila20\AppData\Local\Temp\yovision-tools\go1.26.5\go\bin;' + $env:PATH
|
||
powershell -ExecutionPolicy Bypass -File .\Sense\scripts\bootstrap\check-toolchain.ps1
|
||
cd Sense\server
|
||
go test ./...
|
||
go build ./...
|
||
cd ..\ui
|
||
corepack pnpm@9.15.1 install --frozen-lockfile
|
||
corepack pnpm@9.15.1 lint
|
||
corepack pnpm@9.15.1 build
|
||
cd ..\..
|
||
powershell -ExecutionPolicy Bypass -File .\Sense\scripts\bootstrap\smoke.ps1
|
||
```
|
||
|
||
正式后端启动必须设置 `SENSE_DATABASE_MODE=postgres` 和仓库外提供的 `SENSE_DATABASE_URL`。健康检查为 `GET /healthz`，就绪检查为 `GET /readyz`。本地 smoke 明确设置 `SENSE_DATABASE_MODE=memory`，不能代替 PostgreSQL 部署验证。
|
||
<!-- sense-runtime:end -->
|
||
|
||
|
||
<!-- bell-runtime:start -->
|
||
## Bell 本地构建与验证
|
||
|
||
先从根 `goadmin-baseline.json` 核对精确版本，再从仓库外环境设置 Bell 专用数据库与会话密钥。命令中的值只能使用本地测试凭据，不得提交：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .\Bell\scripts\bootstrap\check-toolchain.ps1
|
||
Set-Location Bell\server
|
||
go test ./...
|
||
go build ./...
|
||
go run . migrate
|
||
go run . serve
|
||
Set-Location ..\web
|
||
corepack pnpm@9.15.1 install --frozen-lockfile
|
||
corepack pnpm@9.15.1 lint
|
||
corepack pnpm@9.15.1 build:prod
|
||
```
|
||
|
||
后端启动前必须提供独立 `BELL_DATABASE_URL` 与至少 32 字符的 `BELL_SESSION_SECRET`；`BELL_ENV` 可取 development、test、production。健康检查为 `GET /healthz`，就绪检查为 `GET /readyz`。首次管理员用 `go run . create-admin` 创建，密码通过 `BELL_BOOTSTRAP_PASSWORD` 进程环境一次性提供。
|
||
|
||
在 Sense、Brain 停止时，development/test 可使用“合成事件测试”完成 Event 入站、规则匹配、Alert 关联、ack 和结果必填 close。production 必须验证 `/api/v1/synthetic/*` 返回 404。PostgreSQL 集成测试使用空的 Bell 专用测试数据库，禁止复用 Sense 或生产数据库。
|
||
<!-- bell-runtime:end -->
|
||
|
||
<!-- sense-windows-package:start -->
|
||
## Sense Windows 打包与产物验证
|
||
|
||
将冻结的 Go 1.26.5 放在 `PATH` 首位后，从仓库根目录运行：
|
||
|
||
```powershell
|
||
cmd /c .\Sense\scripts\package-windows.bat
|
||
Get-FileHash .\Sense\dist\sense-windows-amd64.zip -Algorithm SHA256
|
||
```
|
||
|
||
脚本精确校验 Node 22.22.1 和 pnpm 9.15.1，冻结安装并构建前端，以 Windows amd64/CGO 关闭方式编译后端，然后生成被 Git 忽略的 `Sense\dist\sense-windows-amd64\` 和 ZIP。同一运行目录重新打包时会保留已有 `config\sense.env`，但该文件不会进入 ZIP。
|
||
|
||
解压后运行 `start-sense.bat demo` 可做内存模式临时预览。生产配置可写入运行目录的 `config\sense.env`，也可通过 Windows 进程环境注入；非空进程环境变量优先，启动器只读取 `SENSE_*` 键且不打印配置值。运行 `start-sense.bat check` 可在不连接数据库、不启动服务的情况下检查必填配置，然后用 `start-sense.bat` 启动生产模式。包内不含 PostgreSQL、MediaMTX、系统服务、客户数据或秘密，真实 `sense.env` 不得提交或重新打入交付 ZIP。
|
||
<!-- sense-windows-package:end -->
|
||
|