From e0a0ed3760720a7efc3def925c6d1e2313e1433a Mon Sep 17 00:00:00 2001 From: ila <2+ila@noreply.git.ilapage.cn> Date: Sat, 15 Aug 2026 15:56:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20#70=20=E5=9B=9E?= =?UTF-8?q?=E5=BD=92=E5=BD=92=E6=A1=A3=E6=8E=92=E7=89=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...E%E6%89%93%E5%8C%85%E4%BA%A4%E4%BB%98.-.md | 137 +++++++++--------- 1 file changed, 69 insertions(+), 68 deletions(-) diff --git a/Task-70-Sense-Windows%E9%85%8D%E7%BD%AE%E5%90%AF%E5%8A%A8%E4%B8%8E%E6%89%93%E5%8C%85%E4%BA%A4%E4%BB%98.-.md b/Task-70-Sense-Windows%E9%85%8D%E7%BD%AE%E5%90%AF%E5%8A%A8%E4%B8%8E%E6%89%93%E5%8C%85%E4%BA%A4%E4%BB%98.-.md index 7a88a77..3b1ca88 100644 --- a/Task-70-Sense-Windows%E9%85%8D%E7%BD%AE%E5%90%AF%E5%8A%A8%E4%B8%8E%E6%89%93%E5%8C%85%E4%BA%A4%E4%BB%98.-.md +++ b/Task-70-Sense-Windows%E9%85%8D%E7%BD%AE%E5%90%AF%E5%8A%A8%E4%B8%8E%E6%89%93%E5%8C%85%E4%BA%A4%E4%BB%98.-.md @@ -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 交付流程。