ila/yovision
1
0
Fork 0
Code Issues 14 Pull Requests 14 Actions Packages Projects Releases Wiki Activity

docs: 记录 Sense Windows 交付流程 (#70)

Browse Source
This commit is contained in:
QiuSW
2026-08-15 11:04:15 +08:00
parent 6b79478414
commit e4544a011f
3 changed files with 56 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02-architecture-and-code-map.md
+12 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.-
wiki_revision: 0ba2909431bd04320a9b31121126b59b1824e3dc
synchronized_at: 2026-08-15T01:13:02Z
wiki_revision: a95b7692bc0c6bf4d05f8c57088a83379e15a08f
synchronized_at: 2026-08-15T03:01:57Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
@@ -130,3 +130,13 @@ ONVIF 支持 Basic 与 MD5/SHA-256 Digest challenge，Profile 与无凭据 Strea
认证 API 为 `/api/v1/area/configurations` 及其版本子资源，接入 GoAdmin JWT、Casbin、动态菜单和操作权限。API 只返回设备/Profile 展示字段、规格、归一化坐标和版本信息，不返回 RTSP URI、摄像头凭据或 MediaMTX 内部路径。
<!-- sense-area:end -->
<!-- sense-windows-delivery:start -->
## Sense Windows 交付运行链
工单 #70 在 GoAdmin 派生入口上建立 Windows amd64 交付链。构建入口为 `Sense/scripts/build/build-windows.ps1`；运行包入口为 `start-sense.bat`，它先调用现有 `sense.exe migrate -c data\runtime\settings.yml`，迁移成功后再调用 `sense.exe server -c ...`。前端生产构建复制到包内 `web/`，后端只在显式配置 `SENSE_WEB_ROOT` 时提供同源静态资源和 SPA fallback，API 与健康检查不会被 fallback 覆盖。
运行脚本将 `config\sense.env` 当作数据解析，只接受白名单 `SENSE_*` 字段，不执行文件内容；同名非空进程环境变量优先。生成的 `data\runtime\settings.yml` 含运行秘密，只能留在部署目录。production 固定使用 PostgreSQL，要求至少 32 字符 JWT secret，且 MediaMTX 只能为 `managed` 或 `external`；`managed` 在 HTTP 启动前拉起包内二进制，`external` 在 HTTP 启动前确认回环 Control API 可达。Demo 使用独立配置和名称含 demo/test 的隔离数据库，默认禁用 MediaMTX，绝不回退 production 数据库。
交付包同时提供检查、迁移、管理员初始化、停止、备份和恢复入口。停止脚本只操作当前包且监听配置端口的 Sense 进程树；备份密码只进入子进程环境；恢复要求数据库名和二次短语确认。包不包含 PostgreSQL、生产数据、默认管理员、默认密码或客户秘密。
<!-- sense-windows-delivery:end -->
docs/04-local-development-and-verification.md
+33 -4
View File
@@ -2,8 +2,8 @@
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: 31cad04ab68ee653f2ec3ca6d7297a6bef768f54
synchronized_at: 2026-08-15T01:13:07Z
wiki_revision: ef1ab78f2915af480de123e168afa8f76351a222
synchronized_at: 2026-08-15T03:02:06Z
<!-- gitea-wiki-mirror:end -->
# 本地开发与验证
@@ -230,9 +230,38 @@ corepack pnpm@9.15.1 build:prod
<!-- bell-runtime:end -->
<!-- sense-windows-package:start -->
## Sense Windows 打包状态
## Sense Windows 打包与验证
旧 Sense Windows 包脚本只属于 `explore` 快照。新的打包命令必须在 GoAdmin 派生骨架和业务迁移完成后由独立工单重新建立、验证和记录。
在仓库根目录使用冻结工具链构建：
```powershell
Sense\scripts\build\build-windows.ps1 -MediaMTXPath D:\approved\mediamtx.exe
```
构建脚本严格检查 Go 1.26.5、Node 22.22.1 和 pnpm 9.15.1，执行前端生产构建与 Windows 后端构建，并生成 `Sense\dist\sense-windows-amd64\` 和同名 ZIP。未传 `-MediaMTXPath` 时只生成占位说明，交付前必须另外提供已审核的 Windows amd64 MediaMTX。构建末尾会执行包审计，并清理源码目录的 `Sense/ui/node_modules` 与 `Sense/ui/dist`。
提交前验证：
```powershell
cd Sense\server
go test ./...
go vet ./...
go build ./...
go test -race ./app/sense/media ./cmd/api
cd ..\..
Sense\scripts\build\test-package.ps1 -PackageRoot Sense\dist\sense-windows-amd64
```
包内验证从解压目录执行：
```bat
check-sense.bat
start-sense.bat
stop-sense.bat
```
检查项至少覆盖配置解析与进程环境优先级、特殊字符不被执行、production/demo 数据库隔离、迁移失败不启动服务、首页 SPA fallback、`/healthz`、MediaMTX Control API、包外工作目录启动与停止、PostgreSQL custom-format 备份及恢复到独立数据库。真实摄像机、目标客户数据库账号、目标浏览器与干净客户机器仍须在授权交付环境验收。
<!-- sense-windows-package:end -->
docs/delivery/README.md
+11 -7
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Delivery-Documentation-Guide
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Delivery-Documentation-Guide.-
wiki_revision: 45c86f2a0e4d3252e8042df5ee725e633dd497c1
synchronized_at: 2026-08-14T09:47:31Z
wiki_revision: 3d95c9d392e81cf59d2af1f6f21d8e67f580b68f
synchronized_at: 2026-08-15T03:02:47Z
<!-- gitea-wiki-mirror:end -->
# 交付文档指南
@@ -97,12 +97,16 @@ Sense 面向网管、实施人员和非技术现场人员，菜单按日常任
<!-- sense-windows-package:start -->
## Sense Windows 运行包交付
交付对象为实施和运维人员。`sense-windows-amd64.zip` 包含后端程序、已构建前端、空值示例配置、上游许可证、启动脚本与包内说明；不包含 PostgreSQL、MediaMTX、Windows 服务、生产数据或秘密。
交付对象为实施和运维人员。以 `sense-windows-amd64.zip` 交付后端程序、已构建前端、空值示例配置、迁移基线、许可证、启动/检查/停止/备份/恢复脚本与包内说明；不包含 PostgreSQL、生产数据、默认管理员、默认密码或客户秘密。可按交付决定是否包含已审核的 `bin\mediamtx.exe`。
- 临时查看必须显式运行 `start-sense.bat demo`，其内存数据在进程结束后丢失，不能当作生产部署。
- 生产配置可由运维写入解压目录的 `config\sense.env`，或通过 Windows 进程环境安全注入；进程环境优先。先运行 `start-sense.bat check` 检查必填项，再运行 `start-sense.bat`。
- 交付时记录 ZIP SHA-256，并至少验证 `/healthz` 与首页；真实 PostgreSQL、MediaMTX、摄像机和目标浏览器仍需在获准环境验收。
- 包内 `README-WINDOWS.md` 是现场操作入口；真实 `config\sense.env` 只留在具体部署目录，不得提交 Git 或重新打入交付 ZIP，交付 ZIP 只保留 `sense.env.example`。
- production 先复制 `config\sense.env.example` 为 `config\sense.env`，填写 PostgreSQL、至少 32 字符 JWT secret、凭据密钥、获准 ONVIF 网络和 MediaMTX 模式。进程环境中的同名非空值优先，脚本不执行 env 文件内容，也不打印秘密。
- 先运行 `check-sense.bat`，再运行 `start-sense.bat`。启动会先迁移，失败时不会开放 HTTP；`managed` MediaMTX 在 Sense HTTP 前启动，`external` 必须已有可达的回环 Control API，production 禁止 `disabled`。
- 首位管理员通过至少 32 字符的一次性 bootstrap token 和 `initialize-admin.bat -Username admin` 创建，密码由隐藏提示输入；成功后立即清空 token 并重启。仓库与交付包均无默认账号密码。
- 临时演示必须显式运行 `start-sense.bat demo`，使用独立 `config\sense.demo.env` 和名称含 demo/test 的数据库；不会回退 production 数据库，也不能作为生产部署。
- 日常停止优先在启动窗口按 Ctrl+C；窗口丢失或进程无响应时使用 `stop-sense.bat`。脚本会验证端口与可执行文件归属，拒绝停止其他程序。
- 备份使用 `backup-sense.bat` 生成 PostgreSQL custom-format 文件。恢复前停止服务并再次备份，执行 `restore-sense.bat` 时需确认目标数据库名及 `RESTORE-数据库名`，随后重新迁移。
- 交付时保存 ZIP 和 `MANIFEST.sha256` 的 SHA-256，至少验证首页、`/healthz`、数据库迁移、MediaMTX API、启动/停止和备份/恢复。真实摄像机、目标浏览器与客户数据库账号仍在授权现场验证。
- 包内 `README-WINDOWS.md` 是现场事实入口；真实 `config\sense.env`、运行生成的 `data\runtime\settings.yml`、日志和备份不得提交 Git 或重新打入 ZIP。
<!-- sense-windows-package:end -->
<!-- sense-device-ledger:start -->