Cognitive_Agent/N7Cockpit/MIGRATION_GUIDE.md

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

1. 部署拓扑

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

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 的私密文件中保存：

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 或反向代理进程守护：

$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：

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 后：

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

编辑 config\migration.psd1：

@{
    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 -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 -NoProfile -ExecutionPolicy Bypass `
  -File .\scripts\build-migrated-apk.ps1 -Variant debug

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

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

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

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

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 -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 -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 缓存。