Table of Contents

70 Sense Windows配置启动与打包交付

背景与目标
最终方案
修改文件
验收结果
测试
旧库交付回归
白屏验收反馈修复
遗留问题
相关提交
#97 集成与最终重打包（2026-08-16）
人工验收

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

70 Sense Windows配置启动与打包交付

类型：需求
所属 Epic：#7
所属 MVP / 版本：#8
状态：已完成
日期：2026-08-15
Gitea 工单：#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,455,903 字节，SHA-256 B500982BD566005DC8876A418C26A75BCABE41F498D10E3DAD286A71C92F0241。包内 VERSION.txt 记录实现提交 b66c39724c42b9e63891d06a41fb4a87c8c3f6c7，包含 #92、#95 的旧库兼容修复、白屏修复及已验收 #97 的免验证码登录。

测试

go test ./...、go vet ./...、go build ./...：通过。
go test -race ./app/sense/media ./cmd/api：通过。
PowerShell 包测试：21 项断言通过，覆盖配置注入不执行、特殊字符、环境优先级、demo 数据库隔离、不支持字段拒绝、HTML 本地资源正反例及全部脚本语法。
Sense/scripts/build/build-windows.ps1 -MediaMTXPath <已审核本机路径>：通过；前端剩余 4 条非阻塞构建 warning；导致启动失败的 runtime 与 SCSS 导出 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 校验。
#92 成功把旧设备 capabilities 转为 JSONB；#95 继续兼容旧媒体路由 path 唯一约束和缺失运行态列。
真实库 2 条媒体路由完整保留，运行态列无空值，idx_sense_media_routes_path 与设备/Profile 组合唯一索引均有效，媒体迁移版本已登记。
Web 首页、SPA、/healthz、MediaMTX Control API 均返回 200；停止脚本成功且 Sense/MediaMTX 监听端口全部清空。
PowerShell Invoke-WebRequest 在本机受代理环境影响而无法访问 loopback；使用明确绕过代理的本机 HTTP 客户端确认服务正常，该现象不属于 Sense 服务失败。

白屏验收反馈修复

用户运行发布包后访问生产入口出现白屏。只读诊断确认首页 HTML 返回 200，但现代浏览器请求的 runtime.daef9028.js 不在包内并返回 404；修复 runtime 内联配置后，浏览器继续暴露 GoAdmin :export 主题变量在 css-loader 6 下没有 JavaScript 导出的启动错误。
删除不可靠的 runtime 内联插件配置，使现代与 legacy runtime 都作为独立文件进入产物；为 css-loader 启用不改写普通类名的 ICSS mode，保留 GoAdmin 原有 SCSS :export 变量模式。
新增 assert-web-assets.ps1，构建阶段逐项核对 index.html 引用的本地 JS/CSS；缺失 runtime 的反例会直接使包构建失败。
Chromium 最终打开 http://127.0.0.1:18080/ 并进入账号登录页；首屏 7 个 JS/CSS 全部返回 200，白屏和阻止 Vue 挂载的错误消失。测试完成后停止 Sense 与 MediaMTX，18080 无监听。
浏览器仍观察到不阻塞首屏的既有 /api/v1/app-config 404 和上游默认百度统计请求；不属于本次白屏修复范围，未混入当前提交。

遗留问题

Harness 严格检查的 #66/#67 既有归档格式问题需独立处理，不阻塞 #70 产品代码和交付包验证。
客户环境验收需由实施人员使用脱敏测试账户和获准设备完成。

#97 集成与最终重打包（2026-08-16）

将 dev@116318df748ff0d46d3fe5f8a4f41a6507567eec 合入 #70 分支，发布包现已包含 #97 的账号密码直接登录；登录页和登录载荷不再包含验证码字段或请求，兼容 captcha API 保留。
Windows PowerShell 构建在生成清单时暴露 Get-FileHash 模块自动加载依赖；改用 .NET SHA256 流式计算，避免客户构建环境因模块加载差异失败。实现提交：b66c39724c42b9e63891d06a41fb4a87c8c3f6c7。
固定工具链构建通过；21 项包测试、Go 全量 test/vet、65 个 ZIP 清单文件逐项哈希、模板配置/无 node_modules 审计通过。
使用仓库外配置备份完成真实 PostgreSQL 迁移、首页/SPA、MediaMTX、外部目录 start/stop smoke；测试后 18080/9997 无监听。本地解压目录恢复现场 sense.env，ZIP 内仍只含无秘密模板。
首次在 PowerShell 7 下调用 smoke 的 Invoke-WebRequest 出现 loopback 超时；同一服务用 curl 返回 200，按交付目标的 Windows PowerShell 5.1 正式入口复测全部通过，确认不是 Sense 服务阻塞。
新 ZIP：56,455,903 字节；SHA-256 B500982BD566005DC8876A418C26A75BCABE41F498D10E3DAD286A71C92F0241。

人工验收

2026-08-16：用户明确验收通过 #70。
#95 已先合入 dev，随后按依赖顺序合并 PR #89；main 保持不变。