docs: 修正 #70 回归归档排版
@@ -1,62 +1,62 @@
|
||||
# 70 Sense Windows配置启动与打包交付
|
||||
|
||||
- 类型：需求
|
||||
- 所属 Epic：#7
|
||||
- 所属 MVP / 版本：#8
|
||||
- 状态：待验收
|
||||
- 日期：2026-08-15
|
||||
- Gitea 工单：https://git.ilapage.cn/ila/yovision/issues/70
|
||||
- Wiki 页面：Task-70-Sense-Windows配置启动与打包交付
|
||||
- Wiki revision：见本地镜像头
|
||||
|
||||
## 背景与目标
|
||||
|
||||
在 #61–#69 完成冻结 GoAdmin 基线及 Sense 独立业务纵切后，重建 Windows amd64 前后端单包交付能力。交付必须继续使用 GoAdmin Cobra 的迁移与服务入口，并覆盖包内配置、PostgreSQL、MediaMTX、管理员初始化、停止、备份和恢复；不得回用 explore 中的自研运行框架，也不得包含默认密码或客户秘密。
|
||||
|
||||
## 最终方案
|
||||
|
||||
- `Sense/scripts/build/build-windows.ps1` 严格检查 Go 1.26.5、Node 22.22.1、pnpm 9.15.1，执行前后端生产构建、许可证和迁移基线复制、内容审计并生成目录与 ZIP。
|
||||
- `Sense/scripts/runtime` 提供白名单 env 解析、check/start/stop/migrate/bootstrap/backup/restore。配置文件只作为数据读取，同名非空进程环境优先，日志不打印秘密。
|
||||
- production 只接受 PostgreSQL，要求至少 32 字符 JWT secret，MediaMTX 使用 managed 或 external；启动前完成迁移与媒体服务就绪检查，失败不开放 HTTP。Demo 使用独立配置和名称含 demo/test 的数据库。
|
||||
- 继续调用现有 `sense.exe migrate -c ...` 与 `sense.exe server -c ...`。在现有 Gin Engine 上增加可选同源 SPA fallback；未配置 `SENSE_WEB_ROOT` 时保持上游行为。MediaMTX 显式模式增加启动前就绪门禁，未配置模式保留既有惰性行为。
|
||||
- 管理员初始化无默认账户密码；密码经隐藏提示输入。停止脚本验证端口与可执行文件归属；备份密码只通过子进程环境；恢复要求目标库名称和二次短语确认。
|
||||
- 空白 PostgreSQL 17 已成功执行完整迁移，未复现 #67 曾记录的旧 `sys_config` 字段长度问题，因此未修改上游迁移。
|
||||
|
||||
## 修改文件
|
||||
|
||||
- `Sense/scripts/build/**`、`Sense/tests/package/**`：固定工具链构建、包审计与配置/失败路径自动化。
|
||||
- `Sense/scripts/runtime/**`：Windows 配置、检查、迁移、启动停止、初始化、备份恢复入口。
|
||||
- `Sense/config/**`、`Sense/package/**`、`Sense/README-WINDOWS.md`：空值示例、MediaMTX 基线和现场说明。
|
||||
- `Sense/server/cmd/api/server.go`、`web.go`、`web_test.go`：现有 GoAdmin Gin 服务的可选 SPA 托管。
|
||||
- `Sense/server/app/sense/media/runtime.go`、`runtime_test.go`：显式 MediaMTX 模式的启动前就绪门禁。
|
||||
- `Sense/.gitignore`：忽略可重建交付产物并允许版本化构建脚本。
|
||||
- Wiki `Architecture-and-Code-Map`、`Local-Development-and-Verification`、`Delivery-Documentation-Guide` 及对应 `docs/` 镜像：运行链、构建验证和现场交付说明。
|
||||
|
||||
## 验收结果
|
||||
|
||||
| 验收标准 | 结果 |
|
||||
|---|---|
|
||||
| 干净环境按单一命令生成 Windows amd64 交付包 | 通过；固定工具链构建目录和 ZIP |
|
||||
| 包不包含 node_modules、构建缓存、真实秘密或客户数据 | 通过；包审计及源码残留检查通过 |
|
||||
| start 读取 config/sense.env，进程环境优先且不执行内容 | 通过；自动化覆盖优先级、特殊字符和注入非执行 |
|
||||
| production 检查 PostgreSQL、迁移、端口和 MediaMTX | 通过；隔离 PostgreSQL 17 与 MediaMTX 包 smoke 通过 |
|
||||
| demo 与 production 明确隔离 | 通过；独立配置且数据库名必须含 demo/test |
|
||||
| 提供安全初始化、密码修改、停止、备份和恢复步骤 | 通过；脚本、包内说明与长期 Wiki 已更新 |
|
||||
|
||||
最终 ZIP：`Sense/dist/sense-windows-amd64.zip`，大小 56,595,209 字节，SHA-256 `7E35394F6377F9F4AB0046E8413F29B140D6F301383C54C87CE871B435EF253D`。包内 `VERSION.txt` 记录集成提交 `c088caf816422cb684c402bb8c85e18db1832186`，包含已验收 #92 与待验收 #95 的旧库兼容修复。
|
||||
|
||||
## 测试
|
||||
|
||||
- `go test ./...`、`go vet ./...`、`go build ./...`：通过。
|
||||
- `go test -race ./app/sense/media ./cmd/api`：通过。
|
||||
- PowerShell 包测试：18 项断言通过，覆盖配置注入不执行、特殊字符、环境优先级、demo 数据库隔离、不支持字段拒绝及全部脚本语法。
|
||||
- `Sense/scripts/build/build-windows.ps1 -MediaMTXPath <已审核本机路径>`：通过；前端仅有冻结上游 6 条构建 warning。
|
||||
- `Sense/scripts/build/test-package.ps1 -PackageRoot Sense/dist/sense-windows-amd64`：通过。
|
||||
- 隔离 PostgreSQL 17：空库 8 个迁移通过；首页、SPA fallback、`/healthz`、MediaMTX Control API、包外目录启动停止通过；119,630 字节 custom-format 备份及恢复到另一数据库通过。
|
||||
- `git diff --check`：通过。
|
||||
- `python dev_scripts/check_harness.py --strict`：未通过，原因仅为既存 `docs/task/66`、`docs/task/67` 缺少当前模板要求的“修改文件/未验证”章节；#70 未修改这两个既有归档，也未发现 #70 新增问题。
|
||||
- **未验证部分**：尚未在全新客户 Windows 机器、客户生产 PostgreSQL 账号、目标浏览器和真实获准摄像机上验收；Windows 服务化不在本工单范围。
|
||||
|
||||
# 70 Sense Windows配置启动与打包交付
|
||||
|
||||
- 类型：需求
|
||||
- 所属 Epic：#7
|
||||
- 所属 MVP / 版本：#8
|
||||
- 状态：待验收
|
||||
- 日期：2026-08-15
|
||||
- Gitea 工单：https://git.ilapage.cn/ila/yovision/issues/70
|
||||
- Wiki 页面：Task-70-Sense-Windows配置启动与打包交付
|
||||
- Wiki revision：见本地镜像头
|
||||
|
||||
## 背景与目标
|
||||
|
||||
在 #61–#69 完成冻结 GoAdmin 基线及 Sense 独立业务纵切后，重建 Windows amd64 前后端单包交付能力。交付必须继续使用 GoAdmin Cobra 的迁移与服务入口，并覆盖包内配置、PostgreSQL、MediaMTX、管理员初始化、停止、备份和恢复；不得回用 explore 中的自研运行框架，也不得包含默认密码或客户秘密。
|
||||
|
||||
## 最终方案
|
||||
|
||||
- `Sense/scripts/build/build-windows.ps1` 严格检查 Go 1.26.5、Node 22.22.1、pnpm 9.15.1，执行前后端生产构建、许可证和迁移基线复制、内容审计并生成目录与 ZIP。
|
||||
- `Sense/scripts/runtime` 提供白名单 env 解析、check/start/stop/migrate/bootstrap/backup/restore。配置文件只作为数据读取，同名非空进程环境优先，日志不打印秘密。
|
||||
- production 只接受 PostgreSQL，要求至少 32 字符 JWT secret，MediaMTX 使用 managed 或 external；启动前完成迁移与媒体服务就绪检查，失败不开放 HTTP。Demo 使用独立配置和名称含 demo/test 的数据库。
|
||||
- 继续调用现有 `sense.exe migrate -c ...` 与 `sense.exe server -c ...`。在现有 Gin Engine 上增加可选同源 SPA fallback；未配置 `SENSE_WEB_ROOT` 时保持上游行为。MediaMTX 显式模式增加启动前就绪门禁，未配置模式保留既有惰性行为。
|
||||
- 管理员初始化无默认账户密码；密码经隐藏提示输入。停止脚本验证端口与可执行文件归属；备份密码只通过子进程环境；恢复要求目标库名称和二次短语确认。
|
||||
- 空白 PostgreSQL 17 已成功执行完整迁移，未复现 #67 曾记录的旧 `sys_config` 字段长度问题，因此未修改上游迁移。
|
||||
|
||||
## 修改文件
|
||||
|
||||
- `Sense/scripts/build/**`、`Sense/tests/package/**`：固定工具链构建、包审计与配置/失败路径自动化。
|
||||
- `Sense/scripts/runtime/**`：Windows 配置、检查、迁移、启动停止、初始化、备份恢复入口。
|
||||
- `Sense/config/**`、`Sense/package/**`、`Sense/README-WINDOWS.md`：空值示例、MediaMTX 基线和现场说明。
|
||||
- `Sense/server/cmd/api/server.go`、`web.go`、`web_test.go`：现有 GoAdmin Gin 服务的可选 SPA 托管。
|
||||
- `Sense/server/app/sense/media/runtime.go`、`runtime_test.go`：显式 MediaMTX 模式的启动前就绪门禁。
|
||||
- `Sense/.gitignore`：忽略可重建交付产物并允许版本化构建脚本。
|
||||
- Wiki `Architecture-and-Code-Map`、`Local-Development-and-Verification`、`Delivery-Documentation-Guide` 及对应 `docs/` 镜像：运行链、构建验证和现场交付说明。
|
||||
|
||||
## 验收结果
|
||||
|
||||
| 验收标准 | 结果 |
|
||||
|---|---|
|
||||
| 干净环境按单一命令生成 Windows amd64 交付包 | 通过；固定工具链构建目录和 ZIP |
|
||||
| 包不包含 node_modules、构建缓存、真实秘密或客户数据 | 通过；包审计及源码残留检查通过 |
|
||||
| start 读取 config/sense.env，进程环境优先且不执行内容 | 通过；自动化覆盖优先级、特殊字符和注入非执行 |
|
||||
| production 检查 PostgreSQL、迁移、端口和 MediaMTX | 通过；隔离 PostgreSQL 17 与 MediaMTX 包 smoke 通过 |
|
||||
| demo 与 production 明确隔离 | 通过；独立配置且数据库名必须含 demo/test |
|
||||
| 提供安全初始化、密码修改、停止、备份和恢复步骤 | 通过；脚本、包内说明与长期 Wiki 已更新 |
|
||||
|
||||
最终 ZIP：`Sense/dist/sense-windows-amd64.zip`，大小 56,595,209 字节，SHA-256 `7E35394F6377F9F4AB0046E8413F29B140D6F301383C54C87CE871B435EF253D`。包内 `VERSION.txt` 记录集成提交 `c088caf816422cb684c402bb8c85e18db1832186`，包含已验收 #92 与待验收 #95 的旧库兼容修复。
|
||||
|
||||
## 测试
|
||||
|
||||
- `go test ./...`、`go vet ./...`、`go build ./...`：通过。
|
||||
- `go test -race ./app/sense/media ./cmd/api`：通过。
|
||||
- PowerShell 包测试：18 项断言通过，覆盖配置注入不执行、特殊字符、环境优先级、demo 数据库隔离、不支持字段拒绝及全部脚本语法。
|
||||
- `Sense/scripts/build/build-windows.ps1 -MediaMTXPath <已审核本机路径>`：通过；前端仅有冻结上游 6 条构建 warning。
|
||||
- `Sense/scripts/build/test-package.ps1 -PackageRoot Sense/dist/sense-windows-amd64`：通过。
|
||||
- 隔离 PostgreSQL 17：空库 8 个迁移通过；首页、SPA fallback、`/healthz`、MediaMTX Control API、包外目录启动停止通过；119,630 字节 custom-format 备份及恢复到另一数据库通过。
|
||||
- `git diff --check`：通过。
|
||||
- `python dev_scripts/check_harness.py --strict`：未通过，原因仅为既存 `docs/task/66`、`docs/task/67` 缺少当前模板要求的“修改文件/未验证”章节；#70 未修改这两个既有归档，也未发现 #70 新增问题。
|
||||
- **未验证部分**：尚未在全新客户 Windows 机器、客户生产 PostgreSQL 账号、目标浏览器和真实获准摄像机上验收；Windows 服务化不在本工单范围。
|
||||
|
||||
## 旧库交付回归
|
||||
|
||||
- 真实迁移前已生成仓库外 PostgreSQL custom-format 备份与配置副本，备份通过 `pg_restore --list` 校验。
|
||||
@@ -64,12 +64,13 @@
|
||||
- 真实库 2 条媒体路由完整保留，运行态列无空值，`idx_sense_media_routes_path` 与设备/Profile 组合唯一索引均有效，媒体迁移版本已登记。
|
||||
- Web 首页、SPA、`/healthz`、MediaMTX Control API 均返回 200；停止脚本成功且 Sense/MediaMTX 监听端口全部清空。
|
||||
- PowerShell `Invoke-WebRequest` 在本机受代理环境影响而无法访问 loopback；使用明确绕过代理的本机 HTTP 客户端确认服务正常，该现象不属于 Sense 服务失败。
|
||||
## 遗留问题
|
||||
|
||||
- Harness 严格检查的 #66/#67 既有归档格式问题需独立处理，不阻塞 #70 产品代码和交付包验证。
|
||||
- 客户环境验收需由实施人员使用脱敏测试账户和获准设备完成。
|
||||
|
||||
## 相关提交
|
||||
|
||||
- `6b79478` 建立 Sense Windows 交付包。
|
||||
- `e4544a0` 记录 Sense Windows 交付流程。
|
||||
|
||||
## 遗留问题
|
||||
|
||||
- Harness 严格检查的 #66/#67 既有归档格式问题需独立处理，不阻塞 #70 产品代码和交付包验证。
|
||||
- 客户环境验收需由实施人员使用脱敏测试账户和获准设备完成。
|
||||
|
||||
## 相关提交
|
||||
|
||||
- `6b79478` 建立 Sense Windows 交付包。
|
||||
- `e4544a0` 记录 Sense Windows 交付流程。
|
||||
|
||||
Reference in New Issue
Block a user