# 执行计划：修复全部启动功能失败 — token_api_host 错误回退

> **执行日期**: 2026-08-20
> **关联问题**: [问题分析_token_api_host错误回退导致全部启动失败.md](../问题处理/问题分析_token_api_host错误回退导致全部启动失败.md)
> **预计工时**: 10 分钟
> **风险等级**: 低（单行代码修改，逻辑清晰）

---

## 一、问题摘要

`device_sim_service.py` 第 843 行在获取 `token_api_host` 时，使用了不安全回退逻辑：

```python
token_api_host = config.default_topic_params.get("token_api_host") or config.broker_host
```

当环境配置未设置 `token_api_host` 时，回退到 MQTT Broker 地址，导致门口屏和无纸化模拟器启动时错误地调用 Token API。批量启动 500+ 台设备时，每台串行失败，全部启动功能挂起无法完成。

---

## 二、修复步骤

### 阶段 1：代码修复

**文件：** `backend/app/services/device_sim_service.py` 第 843 行

| 修改前 | 修改后 |
|--------|--------|
| `token_api_host = config.default_topic_params.get("token_api_host") or config.broker_host` | `token_api_host = config.default_topic_params.get("token_api_host")` |

**原理：** 如果环境配置未设置 `token_api_host`，则保持 `None`，模拟器 `start()` 方法判断 `if not token_host:` 为 True，跳过 Token 获取，直接走 MQTT 启动流程，与之前版本行为一致。

### 阶段 2：部署到 5.60 服务器

1. 更新 `deploy_door_http_final.py`，添加 `device_sim_service.py` 到上传列表
2. 执行部署脚本
3. 重启 Docker 容器
4. 验证部署

### 阶段 3：部署后验证

| 验证项 | 方法 | 预期结果 |
|--------|------|----------|
| 健康检查 | `curl http://192.168.5.60/health` | `{"status":"healthy"}` |
| 门口屏全部启动 | 前端页面操作 | 540 台设备全部启动成功 |
| 无纸化全部启动 | 前端页面操作 | 500 台设备全部启动成功 |
| 门口屏单台启动 | 前端页面操作 | 单台设备启动成功 |
| 设备统计 | `GET /api/device-sim/devices/stats` | running 计数正确 |

---

## 三、回滚方案

若部署后出现新问题，可通过 SSH 登录 5.60 服务器执行：

```bash
cd /data/third_party/plat-auto-test/backend/app/services/
# 从备份恢复旧版本
git checkout -- device_sim_service.py
# 或手动将第 843 行改回: token_api_host = config.default_topic_params.get("token_api_host") or config.broker_host
```

---

## 四、完成标准

- [ ] 门口屏"全部启动"可正常启动所有设备
- [ ] 无纸化"全部启动"可正常启动所有设备
- [ ] 环境配置未设置 `token_api_host` 时，设备启动不报错
- [ ] 环境配置设置了 `token_api_host` 时，设备正常获取 Token 并启动
- [ ] 更新 HANDOFF 文档记录本次修复

---

*本文档由 Claude Code 生成，2026-08-20*