# 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` 读取白名单字段，不会执行文件内容。值中可以包含 `#`、`&`、`;`、空格或 `=`；如首尾使用成对单/双引号，外层引号会被移除。

至少填写：

```dotenv
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：

```powershell
$bytes = New-Object byte[] 48
[Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
[Convert]::ToBase64String($bytes)
```

同名的非空进程环境变量优先于 `sense.env`。这便于由服务管理器或秘密管理工具注入值；空进程变量不会覆盖文件值。脚本不会打印数据库连接串、JWT secret、Bootstrap token 或摄像头密钥。

运行启动前检查：

```bat
check-sense.bat
```

它会检查配置格式、HTTP 端口、PostgreSQL TCP 连接、数据库名、JWT 长度、网页文件和 MediaMTX 模式。`managed` 模式要求二进制与配置文件存在；`external` 模式要求本机 Control API 已可连接。production 不允许 `disabled`。

## 3. 启动、迁移与停止

首次及日常启动：

```bat
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。也可在另一管理员终端运行：

```bat
stop-sense.bat
```

停止脚本只会强制停止监听配置端口、且可执行文件确实位于当前交付包的 Sense 进程树；端口属于其他程序时会拒绝操作。日常维护优先在启动窗口按 `Ctrl+C` 完成优雅停止，窗口丢失或进程失去响应时再使用停止脚本。

只执行迁移或禁用启动时自动迁移：

```bat
migrate-sense.bat
start-sense.bat -SkipMigration
```

只有已完成备份并明确掌握版本状态时才使用 `-SkipMigration`。也可把 `SENSE_AUTO_MIGRATE=false` 放到外部进程环境中。

## 4. 创建首个管理员与修改密码

Sense 不提供生产默认管理员。首次初始化：

1. 生成至少 32 字符的一次性随机值，临时填入 `SENSE_BOOTSTRAP_TOKEN`。
2. 启动 Sense。
3. 在另一个终端运行 `initialize-admin.bat -Username admin`，按隐藏提示输入至少 6 位密码。
4. 成功后立即清空 `SENSE_BOOTSTRAP_TOKEN` 并重启 Sense。

Bootstrap 只允许在用户表为空时执行一次，token 通过请求头传递，不放在 JSON 或命令行中。不要把密码作为 bat 参数。

管理员登录后，在右上角头像进入“个人中心 → 修改密码”。密码至少 6 个字符；修改成功后重新登录。其他管理员的密码重置只能由授权管理员通过 GoAdmin 用户管理入口完成并形成审计记录。

## 5. 备份与恢复

创建 PostgreSQL custom-format 备份：

```bat
backup-sense.bat
backup-sense.bat -OutputDirectory D:\SenseBackups
```

默认写入包外可单独保护的 `backups` 目录。脚本从连接串移除密码后再构造 `pg_dump` 命令，密码只通过子进程环境传递。

恢复会清理并替换目标库中的对象，必须先停止 Sense、备份当前库，并两次确认数据库名：

```bat
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`：

```bat
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. 构建交付包

开发机在仓库根目录执行：

```bat
Sense\scripts\build\build-windows.bat
```

若要把已审核的 MediaMTX 一并放入包：

```powershell
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。