7.3 KiB
Sense Windows 安装与运行
本说明适用于 sense-windows-amd64 交付包。Sense 后端和管理网页来自冻结的 GoAdmin/go-admin-ui 基线；启动仍使用 GoAdmin Cobra 的 migrate 与 server 命令。Brain、Bell 不需要启动。
1. 准备环境
- Windows 10/11 或 Windows Server 2019 及以上，amd64。
- PostgreSQL 17；先由数据库管理员创建独立的 Sense 数据库和最小权限账号。
- 已审核版本与许可证的 Windows amd64
mediamtx.exe，放到bin\mediamtx.exe。 - 备份、恢复时还需要 PostgreSQL 客户端的
pg_dump.exe、pg_restore.exe；可把目录加入 PATH，或配置SENSE_POSTGRES_BIN。
交付包不包含 PostgreSQL、数据库数据、管理员默认密码、摄像头密码或客户配置。不要把包解压到所有用户都可写的共享目录。
2. 配置 production
编辑 config\sense.env。脚本只按 NAME=value 读取白名单字段，不会执行文件内容。值中可以包含 #、&、;、空格或 =；如首尾使用成对单/双引号，外层引号会被移除。
至少填写：
SENSE_DATABASE_URL=host=127.0.0.1 port=5432 user=sense password=请替换 dbname=sense sslmode=disable
SENSE_JWT_SECRET=请替换为至少32字符的随机值
SENSE_MEDIAMTX_MODE=managed
SENSE_MEDIAMTX_BINARY=bin\mediamtx.exe
SENSE_MEDIAMTX_CONFIG=config\mediamtx.yml
用 PowerShell 生成随机值，不要把输出写入工单、Wiki 或 Git：
$bytes = New-Object byte[] 48
[Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
[Convert]::ToBase64String($bytes)
同名的非空进程环境变量优先于 sense.env。这便于由服务管理器或秘密管理工具注入值；空进程变量不会覆盖文件值。脚本不会打印数据库连接串、JWT secret、Bootstrap token 或摄像头密钥。
运行启动前检查：
check-sense.bat
它会检查配置格式、HTTP 端口、PostgreSQL TCP 连接、数据库名、JWT 长度、网页文件和 MediaMTX 模式。managed 模式要求二进制与配置文件存在；external 模式要求本机 Control API 已可连接。production 不允许 disabled。
3. 启动、迁移与停止
首次及日常启动：
start-sense.bat
脚本先执行 sense.exe migrate -c data\runtime\settings.yml，成功后再执行 sense.exe server -c ...。迁移失败时不会启动 HTTP 服务。迁移会检查 PostgreSQL 数据库是否存在；脚本不会自动创建生产数据库。
config\db.sql 与 config\pg.sql 是冻结 GoAdmin 首次初始化所需的无秘密基线数据，必须和 sense.exe 同版本保留；删除它们会导致空库首次迁移失败。
浏览器访问 http://127.0.0.1:18080/。当前窗口按 Ctrl+C 可让 Sense 优雅停止，并请求停止由它启动的 MediaMTX。也可在另一管理员终端运行：
stop-sense.bat
停止脚本只会强制停止监听配置端口、且可执行文件确实位于当前交付包的 Sense 进程树；端口属于其他程序时会拒绝操作。日常维护优先在启动窗口按 Ctrl+C 完成优雅停止，窗口丢失或进程失去响应时再使用停止脚本。
只执行迁移或禁用启动时自动迁移：
migrate-sense.bat
start-sense.bat -SkipMigration
只有已完成备份并明确掌握版本状态时才使用 -SkipMigration。也可把 SENSE_AUTO_MIGRATE=false 放到外部进程环境中。
4. 创建首个管理员与修改密码
Sense 不提供生产默认管理员。首次初始化：
- 生成至少 32 字符的一次性随机值，临时填入
SENSE_BOOTSTRAP_TOKEN。 - 启动 Sense。
- 在另一个终端运行
initialize-admin.bat -Username admin，按隐藏提示输入至少 6 位密码。 - 成功后立即清空
SENSE_BOOTSTRAP_TOKEN并重启 Sense。
Bootstrap 只允许在用户表为空时执行一次，token 通过请求头传递，不放在 JSON 或命令行中。不要把密码作为 bat 参数。
管理员登录后，在右上角头像进入“个人中心 → 修改密码”。密码至少 6 个字符；修改成功后重新登录。其他管理员的密码重置只能由授权管理员通过 GoAdmin 用户管理入口完成并形成审计记录。
5. 备份与恢复
创建 PostgreSQL custom-format 备份：
backup-sense.bat
backup-sense.bat -OutputDirectory D:\SenseBackups
默认写入包外可单独保护的 backups 目录。脚本从连接串移除密码后再构造 pg_dump 命令，密码只通过子进程环境传递。
恢复会清理并替换目标库中的对象，必须先停止 Sense、备份当前库，并两次确认数据库名：
restore-sense.bat -BackupFile D:\SenseBackups\sense-sense-20260815-120000.dump -ConfirmDatabaseName sense
migrate-sense.bat
恢复脚本还会交互要求输入 RESTORE-数据库名；名称不完全一致时拒绝执行。不要对来源不明或版本不匹配的备份执行恢复。
6. Demo 隔离
Demo 使用独立的 config\sense.demo.env 和 SENSE_DEMO_DATABASE_URL：
start-sense.bat demo
数据库名必须包含 demo 或 test，且不会回退到 production 的 SENSE_DATABASE_URL。默认 HTTP 端口为 18081、MediaMTX 为 disabled。Demo 数据不属于生产数据，不得迁入生产库或用于客户交付。
Demo 启动窗口按 Ctrl+C 停止；窗口不可用时执行 stop-sense.bat -Mode demo。
7. 日志与排错
- Sense 文件日志：
logs\ - 运行时生成的 GoAdmin YAML：
data\runtime\settings.yml（包含秘密，不得复制到工单或发送给无权限人员） - MediaMTX 日志：由 Sense 启动窗口和 MediaMTX 自身输出提供
- 包完整性：
MANIFEST.sha256
常见错误：
SENSE_DATABASE_URL is required：编辑当前包的config\sense.env，或设置非空进程变量。PostgreSQL is unreachable：确认服务、地址、端口和防火墙；数据库不存在会在迁移阶段明确失败。port ... already in use：先运行stop-sense.bat，或确认占用者后修改SENSE_PORT。Managed MediaMTX binary not found：把已审核的mediamtx.exe放入bin，不要只复制配置文件。External MediaMTX Control API is unreachable：启动外部实例并确认 API 只监听回环地址。migration failed：不要跳过；先备份，保留错误输出，核对数据库账号权限和版本。- 网页返回 404：检查
web\index.html与SENSE_WEB_ROOT=web，不要把源码目录或node_modules放进包。 - 网页返回 200 但白屏：在浏览器开发者工具检查 JS/CSS 是否 404；正式包的构建审计会逐项核对
web\index.html引用的本地资源，缺失时拒绝生成交付包。
8. 构建交付包
开发机在仓库根目录执行：
Sense\scripts\build\build-windows.bat
若要把已审核的 MediaMTX 一并放入包：
Sense\scripts\build\build-windows.ps1 -MediaMTXPath D:\approved\mediamtx.exe
构建严格检查 Go 1.26.5、Node 22.22.1 和 pnpm 9.15.1，生成：
Sense\dist\sense-windows-amd64\Sense\dist\sense-windows-amd64.zip
构建末尾会审计包内容：逐项核对 web\index.html 引用的本地 JS/CSS，并拒绝 node_modules、嵌套 dist、Git/缓存目录、数据库/备份文件、非空秘密字段、常见默认密码和私钥标记。dist 为可重建产物，不提交 Git。