191 lines
9.0 KiB
Markdown
191 lines
9.0 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: f68bbd8c7a99689e65453ae00c7bbd2c3ee00357
|
||
synchronized_at: 2026-08-14T07:02:43Z
|
||
<!-- 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 | `cd Sense/server; go build ./...`、`cd Sense/ui; corepack pnpm@9.15.1 build:prod` | `go test ./...`、`go vet ./...`、前端 lint/单测 | `sense server -c <仓库外配置>` | GoAdmin 源码骨架已建立；业务模块待后续工单 |
|
||
| Brain | 待骨架工单冻结 | 待冻结 | 待冻结 | 未初始化业务代码 |
|
||
| Bell | 待 GoAdmin 派生工单建立 | 待建立 | 待建立 | 旧实现仅在 `explore`；新基线未初始化 |
|
||
|
||
不得复制旧仓库命令来填空。每个骨架工单必须同时建立 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 本地构建与验证
|
||
|
||
Sense 后端与前端已从冻结源码建立。先确认 Go 1.26.5、Node 22.22.1 和 pnpm 9.15.1，再执行：
|
||
|
||
```powershell
|
||
cd Sense/server
|
||
go test ./...
|
||
go vet ./...
|
||
go build ./...
|
||
|
||
cd ../ui
|
||
corepack pnpm@9.15.1 install --frozen-lockfile
|
||
corepack pnpm@9.15.1 lint
|
||
corepack pnpm@9.15.1 test:unit
|
||
corepack pnpm@9.15.1 build:prod
|
||
```
|
||
|
||
数据库固定为 PostgreSQL。复制 `Sense/server/config/settings.yml` 到仓库外，填写连接串和至少 32 个字符的随机 JWT 密钥；仓库模板本身不可直接启动生产服务。首次运行先执行 `sense migrate -c <配置路径>`，再通过只存在于当前进程的高熵令牌启动服务并创建首位管理员：
|
||
|
||
```powershell
|
||
$env:SENSE_BOOTSTRAP_TOKEN = Read-Host "输入至少 32 个字符的一次性初始化令牌"
|
||
sense server -c <配置路径>
|
||
|
||
# 在另一个 PowerShell 中输入相同令牌；不要把真实值写入脚本或命令历史
|
||
$bootstrapToken = Read-Host "输入一次性初始化令牌"
|
||
$bootstrapBody = @{
|
||
username = "admin"
|
||
password = Read-Host "输入至少 6 个字符的管理员密码"
|
||
nickname = "系统管理员"
|
||
} | ConvertTo-Json
|
||
Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:<端口>/api/v1/bootstrap" -Headers @{ "X-Sense-Bootstrap-Token" = $bootstrapToken } -ContentType "application/json" -Body $bootstrapBody
|
||
Remove-Variable bootstrapToken, bootstrapBody
|
||
```
|
||
|
||
初始化成功后停止服务，从启动环境中执行 `Remove-Item Env:SENSE_BOOTSTRAP_TOKEN`，再按正常生产方式启动。已有任一用户时初始化接口会拒绝请求。生产登录需要先调用验证码接口并提交验证码；自动化集成验证不得通过关闭生产安全约束来冒充生产结果。
|
||
|
||
身份回归至少覆盖：admin 可管理账户及查看审计；implementation_operator 只能查看实施所需日志和字典支撑数据；site_admin 可维护账户并读取角色、部门、岗位、字典，但不能修改角色或菜单；viewer 不能访问管理接口。还要验证配置/接口管理路由返回 404、短密码被拒绝、6 位全小写密码可用，以及登录/登出/改密/拒绝审计中不含密码、令牌、Cookie 或验证码。身份审计直接写入 PostgreSQL，不依赖通用操作日志数据库开关。
|
||
|
||
详细来源与安全约束见 `Sense/LICENSES/SOURCES.md` 和 `Sense/README.md`。
|
||
|
||
设备台账启用凭据写入前，还必须在服务进程环境提供独立随机密钥；示例文件 `Sense/server/config/credential.env.example` 只保留空值：
|
||
|
||
```powershell
|
||
# 生成一次随机 32 字节密钥并以 Base64 形式注入当前进程；不要打印或写入仓库
|
||
$keyBytes = New-Object byte[] 32
|
||
[System.Security.Cryptography.RandomNumberGenerator]::Fill($keyBytes)
|
||
$env:SENSE_CREDENTIAL_KEY = [Convert]::ToBase64String($keyBytes)
|
||
[Array]::Clear($keyBytes, 0, $keyBytes.Length)
|
||
```
|
||
|
||
缺少或格式错误的密钥时，普通设备台账仍可读写，但凭据更新返回服务不可用且不得产生部分写入。设备回归至少覆盖：中文名称与位置、未知 JSON 字段拒绝、版本冲突返回 409、非视频设备显示适配器未就绪、viewer 只读、凭据响应/操作日志不含明文，以及 PostgreSQL 迁移重复执行不增加菜单或权限记录。
|
||
<!-- sense-runtime:end -->
|
||
|
||
|
||
<!-- bell-runtime:start -->
|
||
## Bell 本地构建与验证
|
||
|
||
新 Bell 尚未初始化。骨架工单必须从冻结 GoAdmin 源码建立并验证独立构建、数据库、认证和前端流程；旧 Bell 命令只在 `explore` 对应提交中适用。
|
||
<!-- bell-runtime:end -->
|
||
|
||
<!-- sense-windows-package:start -->
|
||
## Sense Windows 打包状态
|
||
|
||
旧 Sense Windows 包脚本只属于 `explore` 快照。新的打包命令必须在 GoAdmin 派生骨架和业务迁移完成后由独立工单重新建立、验证和记录。
|
||
<!-- sense-windows-package:end -->
|
||
|
||
|
||
## GoAdmin 派生前置检查
|
||
|
||
每个 Sense/Bell 骨架或基础能力工单在修改前必须：
|
||
|
||
1. 核对 `goadmin-baseline.json` 中三个完整 commit。
|
||
2. 核对本机只读副本或重新检出的上游仓库 HEAD。
|
||
3. 阅读任务相关的 go-admin-doc 主题/文件，并把参考项记录到工单。
|
||
4. 记录计划继承的 go-admin/go-admin-ui 路径、计划隐藏/禁用的模块和许可证处理。
|
||
5. 验证最终产品树确实包含上游派生结构；只使用 Go、Vue、Element Plus 或相似视觉不算通过。
|