# N7Cockpit 跨服务器迁移与联调手册

## 1. 部署拓扑

本工程采用统一服务端事件链路，不做网页自动点击：

```text
Android / N7Cockpit
  |  HTTPS/HTTP + Bearer token
  |  mode_id / execution_id / event sequence
  v
服务器 A：Cognitive_Agent :8000
  |  展开服务器预设模式、安全校验、执行与状态回读
  +--> Web 控制台（同一事件流）
  +--> CAN 盒与车端设备（仅 hardware + 本地批准时）

服务器 B：保存 N7Cockpit 源码、构建 APK、通过 ADB 安装到 Android
```

`127.0.0.1:8000` 只表示“当前机器”。Android 设备访问服务器 A 时必须使用
服务器 A 的可路由 IP 或 DNS 名。只有 Android Emulator 与服务器 A 同机时，APK
中的服务器 A 地址才使用 `http://10.0.2.2:8000`。

## 2. 服务器 A：启动 Cognitive_Agent

服务器 A 必须已经包含本项目配套修改后的 Cognitive_Agent。进入其工程目录，生成
至少 32 字符的随机设备令牌；令牌只在服务器 A 和服务器 B 的私密文件中保存：

```powershell
cd D:\path\to\Cognitive_Agent
$tokenBytes = New-Object byte[] 48
$rng = [Security.Cryptography.RandomNumberGenerator]::Create()
try { $rng.GetBytes($tokenBytes) } finally { $rng.Dispose() }
$deviceToken = [Convert]::ToBase64String($tokenBytes)
$deviceToken | Set-Content -NoNewline .\n7-device-token.txt
```

启动服务。当前 PowerShell 会话关闭后进程也会终止，生产环境应再配置 Windows
Service、NSSM 或反向代理进程守护：

```powershell
$env:PYTHONPATH = 'src'
$env:COGNITIVE_AGENT_DEVICE_API_TOKEN = (
    Get-Content .\n7-device-token.txt -Raw
).Trim()
python -m cognitive_agent.server --host 0.0.0.0 --port 8000
```

服务器 A 防火墙只允许服务器 B、Android 车机和 Web 管理端访问 TCP 8000。生产
环境必须在服务器前配置 HTTPS；HTTP 仅适用于受信任的隔离局域网。

从服务器 B 检查网络。这里不能使用服务器 B 的 `127.0.0.1`：

```powershell
Test-NetConnection 192.168.1.10 -Port 8000
```

Web 控制台地址也应改为服务器 A 地址：`http://192.168.1.10:8000/`。服务器 A
本机访问时才使用 `http://127.0.0.1:8000/`。

## 3. 服务器 B：解压和初始化

安装以下依赖：

- Windows PowerShell 5.1 或 PowerShell 7；
- JDK 17 或更高版本；
- Android SDK Platform 35 和 Platform Tools；
- 首次构建可访问 Gradle/Google/Aliyun Maven 仓库。

解压 ZIP 后：

```powershell
cd D:\Deploy\N7Cockpit
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\initialize-migration.ps1
```

编辑 `config\migration.psd1`：

```powershell
@{
    ServerAUrl = 'http://192.168.1.10:8000'
    AndroidServerAUrl = 'http://192.168.1.10:8000'
    VehicleId = 'denza_n7'
    HardwareClientId = 'hwc-n7cockpit-server-b-001'
    ExecutionTarget = 'dry_run'
    TokenFile = 'secrets/device-token.txt'
    JavaHome = 'C:\Program Files\Android\Android Studio\jbr'
    AndroidSdk = 'C:\Users\Administrator\AppData\Local\Android\Sdk'
    GradleExecutable = ''
}
```

把服务器 A 的 `n7-device-token.txt` 安全复制到服务器 B 的
`secrets\device-token.txt`。不要通过聊天、代码仓库或普通邮件传输。配置和 secrets
目录均被打包规则排除。

先验证环境及服务器 A：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\verify-migration-environment.ps1
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\check-server-a.ps1
```

两条命令都应返回 `Passed=True`，且 `PresetModes` 大于 0。

## 4. 构建和安装 Android APK

安全联调构建：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\build-migrated-apk.ps1 -Variant debug
```

脚本会先验证服务器 A、运行 Android 单元测试，再生成：

```text
dist\N7Cockpit-remote-debug.apk
dist\build-info.json
```

`GradleExecutable` 留空时使用包内 Gradle Wrapper；首次构建会下载 Gradle 8.9。
服务器若已安装 Gradle 8.9，可填写 `gradle.bat` 的绝对路径以避免重复下载。

设备开启开发者选项和 USB 调试，执行：

```powershell
adb devices
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\install-migrated-apk.ps1 -Variant debug
```

如有多个设备，增加 `-Serial <adb序列号>`。远程调试包名为
`com.seeker.n7cockpit.remote`，可与正式包共存。

## 5. dry_run 联调验收

先进行不会访问 CAN 的服务器 A 冒烟测试：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\test-server-a-dry-run.ps1
```

必须看到：

- `Passed=True`；
- `CanExecuted=False`；
- `ExecutionTarget=dry_run`；
- `Status=succeeded`。

然后打开 Android 的“模式”页：

1. 顶部应显示服务器 A URL 和“编排服务已连接”；
2. 应加载宝宝午睡、零重力、小憩、轻松进出等服务器预设模式；
3. 点击“宝宝午睡模式”；
4. Android 显示 `queued/executing/succeeded`、execution_id 和车端模拟状态；
5. 打开服务器 A 的 Web 控制台，显示同一模式、`source:N7Cockpit`、同一
   execution_id 和同步后的数字孪生状态。

此阶段不要点击“申请真实硬件控制”。

## 6. 实体 Android 与模拟器的地址选择

| 场景 | AndroidServerAUrl |
|---|---|
| 模拟器与服务器 A 同机 | `http://10.0.2.2:8000` |
| 模拟器在服务器 B，服务器 A 独立 | 服务器 A 的 LAN IP/DNS |
| 实体 Android/车机 | 服务器 A 的 LAN IP/DNS |
| 生产环境 | 服务器 A 的 HTTPS 域名 |

服务器 B 的 `ServerAUrl` 始终填写服务器 B 能访问的服务器 A 地址。

## 7. 切换真实 CAN（完成 dry_run 后单独进行）

真实硬件不属于默认迁移验收范围。确认急停、机械限位、CAN 通道和车端供电安全后：

1. 将配置改为 `ExecutionTarget='hardware'`；
2. 显式构建：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\build-migrated-apk.ps1 -Variant release -AllowHardware
```

3. Android 点击“申请真实硬件控制”；
4. 只能在服务器 A 本机打开 `/hardware-control` 批准对应 HardwareClientId；
5. 批准后才允许 hardware 任务进入 CAN 执行。

`-AllowHardware` 和服务器 A 本地批准是两层独立安全门，远程设备令牌不能自批准。

## 8. 常见故障

- `401`：服务器 A 与 APK 使用的设备令牌不一致，或服务重启时没有加载令牌。
- `Connection refused/timed out`：服务未监听 `0.0.0.0`、防火墙未放行，或 URL
  错填为 Android/服务器 B 自己的 `127.0.0.1`。
- 模式为空：车型 ID 不匹配，或服务器 A 不是包含预设模式 API 的配套版本。
- Android 可访问但 Web 不更新：Web 未登录，或浏览器标签长期后台导致轮询暂停；
  激活页面后会继续读取新事件。
- Gradle 下载失败：检查代理/DNS；工程已同时配置 Aliyun 与官方仓库。
- SDK XML 警告：Android Studio 与 command-line tools 版本差异警告，若构建最终
  `BUILD SUCCESSFUL` 通常不影响 APK。

## 9. 安全说明

设备令牌会进入 APK BuildConfig。只应把 APK 安装到受控车机；如果 APK 可能公开
分发，应改为设备注册和短期凭据。令牌泄露后必须在服务器 A 生成新令牌、重启服务
并重新构建 APK。ZIP 源码包不会包含设备令牌、构建目录、历史 APK、测试截图或
本机 Gradle 缓存。