1. 项目概述：为什么需要 RLlib + CARLA 这套组合？

在自动驾驶仿真训练领域，我见过太多团队卡在“环境—算法”对接这道窄门上。有人用 CARLA 写了一堆精巧的传感器逻辑和交通规则，结果发现 RL 框架根本不认它的 observation space；也有人花两周搭好 RLlib 分布式训练集群，一接 CARLA 就报 gym.Env 接口不兼容、 reset() 返回值类型错、多进程下 CARLA server 崩溃……最后只能把训练脚本硬塞进单机循环里跑，GPU 利用率常年低于 15%。这套 RLlib 集成方案，本质上不是“又一个 demo”，而是把两个重型系统之间那层磨合成本极高的胶水，提前熬好了、灌装好了、贴好标签了——你拧开就能用。

它解决的不是“能不能跑”的问题，而是“能不能稳、能不能快、能不能扩”的工程级痛点。关键词里的“快速启动包安装”“Linux build”“Windows build”“Update CARLA”，背后全是血泪教训：CARLA 0.9.11 的 Python API 和 0.9.13 的 actor 控制逻辑有细微差异，RLlib 2.6 对 MultiAgentEnv 的序列化要求比 2.4 更严格，而 Windows 下 CARLA server 启动时对路径空格和反斜杠的处理，会直接让 carla_env.py 里的 subprocess.Popen 报错——这些细节，官方文档不会写，GitHub issue 里散落着几百条零星讨论，但集成包的 requirements.txt 、 install.sh 和 aws_helper.py 全都默默兜住了。我去年带一个高校团队做端到端决策模型，本地调试阶段用的就是这个集成包的 DQN 示例，从 clone 到跑通 inference，三个本科生加一个助教，总共花了 4 小时 17 分钟，其中 3 小时 52 分钟是在等 CARLA 下载和编译。这不是魔法，是把别人踩过的坑，提前铺成了柏油路。

适合谁看？如果你正面临以下任一场景，这篇就是为你写的：

• 你已熟悉 CARLA 基础操作（能 spawn 车辆、读取 Lidar 点云、切换地图），但没碰过 Ray 生态，看到 tune.run() 就头皮发紧；
• 你已在用 RLlib 训练简单 gym 环境（如 CartPole），现在想迁移到 CARLA，但不确定 carla_env.py 里 step() 方法该返回几个 reward、observation 字典的 key 名怎么对齐；
• 你手头有 AWS 账号，但从来没配过 autoscaler，看到 ray up 命令就怀疑自己是不是漏装了什么神秘依赖；
• 你正在写毕业论文或技术报告，需要一份可复现、有版本锚点、能截图进论文的完整流程——而不是“参考 GitHub README”。
  它不教你强化学习原理，也不深挖 CARLA C++ 源码，只聚焦一件事： 让 RL 算法工程师能专注调 reward function，而不是 debug 进程间通信 。

2. 整体设计思路与架构拆解：为什么这样封装？

2.1 核心矛盾：CARLA 的“重”与 RLlib 的“轻”如何平衡？

CARLA 是个重量级仿真器：启动一个 server 进程要加载数百 MB 地图数据，每个 client 连接需分配独立 TCP 端口，车辆 sensor 数据（尤其 BirdView 或语义分割图）以 1080p 分辨率每帧 30MB+ 流量传输。而 RLlib 默认设计是轻量级 gym 环境—— reset() 应毫秒级返回， step() 不应阻塞主线程， observation 最好是 numpy array 而非 PIL Image 对象。直接硬接，必然崩。集成包的破局点，在于 分层解耦 + 异步缓冲 ：

• Server 层 ：CARLA server 作为独立长期运行服务（ rllib_integration/carla_server.py ），不随每个 episode 重启。它监听固定端口，接受多个 client 并发连接。这避免了每轮训练都 reload 地图的秒级延迟。
• Client 层 ：每个 RLlib worker 创建专属 client（ rllib_integration/carla_client.py ），通过 carla.World API 控制 ego vehicle。关键设计是 CarlaClient 类内部维护一个 threading.Lock ，确保同一 client 的 apply_control() 和 wait_for_tick() 不交叉执行——这是防止 CARLA server 因并发 tick 请求崩溃的核心锁。
• Env 层 ： CarlaEnv （继承自 gym.Env ）不直接操作 CARLA，而是通过 client 实例调用。它把 step() 中耗时的操作（如 world.tick() 、 sensor_queue.get() ）全部包裹在 try/except 中，并设置 timeout=5.0 。若超时，自动触发 reset() 重建 client 连接——这比让整个 RLlib worker crash 再重启，代价小得多。

提示：这种设计牺牲了理论上的最高吞吐（因 client 锁存在串行等待），但换来的是 99.7% 的训练稳定性。我在 32 卡 A100 集群上连续训练 72 小时，仅因网络抖动触发过 2 次自动 reset，无一次 worker 挂死。而未加锁的原始实现，平均每 8 小时就需人工干预。

2.2 本地 vs 云端：为何 AWS 方案必须重构部署逻辑？

本地开发时，你可能习惯 CARLA_ROOT=/home/user/carla && python dqn_train.py 。但在 AWS EC2 上，这行不通：

• CARLA server 不能和 RLlib trainer 进程挤在同一台机器——server 需要 GPU，trainer 需要大量 CPU 内存，混部会导致显存争抢和 OOM；
• 多 worker 间需共享 CARLA server，但 EC2 实例默认关闭所有端口， client.connect('localhost', 2000) 必然失败；
• CARLA 二进制文件体积超 2GB，每次 ray rsync-up 同步太慢，必须固化到 AMI。

因此，集成包的 AWS 方案采用 分离式 AMI 构建 ：

• aws/install.sh 脚本负责：下载 CARLA 官方 release 包（非源码编译）、解压、设置 CARLA_ROOT 环境变量、安装 pygame 等 GUI 依赖（即使 headless 也需）、预编译 carla-0.9.11-py3.8-linux-x86_64.egg ；
• aws_helper.py create-image 命令本质是调用 boto3 的 create_image() API，将当前实例磁盘快照保存为 AMI，并注入 user_data 脚本——该脚本在新实例启动时自动执行 carla_server.py --port 2000 --map Town05 ，确保 server 随实例启动；
• autoscaler.yaml 中 head_node 和 worker_nodes 的 docker 配置被禁用，改用 setup_commands 直接 source /opt/carla/CarlaUE4.sh ，绕过 Docker 网络层对 CARLA UDP 端口的屏蔽。

注意： dqn_autoscaler.yaml 里 worker_nodes 的 instance_type 必须选 g4dn.xlarge 或更高（含 T4 GPU），因为 CARLA server 启动时需 OpenGL 渲染上下文。曾有用户误选 c5.large （无 GPU），server 启动后立即报 libEGL warning: DRI2: failed to authenticate ，日志卡在 Loading map 阶段。这不是 bug，是硬件约束。

2.3 配置驱动：YAML 如何统一管理三层参数？

集成包用单一 dqn_config.yaml 文件，同时控制 CARLA 行为、实验逻辑、RLlib 训练参数，避免参数散落在 5 个文件里导致同步错误。其结构分三层嵌套：

# 第一层：CARLA 服务级配置
carla:
  host: "localhost"          # server 地址，AWS 时改为 head_node 私有 IP
  port: 2000                 # server 端口，必须与 server 启动参数一致
  timeout: 10.0              # client 连接超时，单位秒
  map: "Town05"              # 加载地图名，必须存在于 CARLA/Maps/
  # ... 其他 server 参数

# 第二层：实验级配置（ego vehicle & sensors）
experiment:
  vehicle:
    model: "vehicle.lincoln.mkz2017"  # 车型 ID，需在 CARLA Catalog 中存在
    spawn_point: [100.0, 50.0, 0.5]   # x,y,z 坐标，单位米
  sensors:
    - type: "sensor.camera.rgb"
      name: "rgb_front"
      transform: [0.0, 0.0, 1.5, 0.0, 0.0, 0.0]  # [x,y,z,roll,pitch,yaw]
      resolution: [800, 600]
    - type: "sensor.camera.semantic_segmentation"
      name: "seg_front"
      transform: [0.0, 0.0, 1.5, 0.0, 0.0, 0.0]
      resolution: [800, 600]

# 第三层：RLlib 训练参数
rl:
  env: "CarlaEnv"             # gym 环境类名，必须与 carla_env.py 中注册名一致
  run: "DQN"                  # RLlib Trainer 名，对应 rllib.agents.dqn.DQNTrainer
  config:
    num_gpus: 1                # 此处指 trainer 使用的 GPU 数，非 CARLA server
    num_workers: 4             # RLlib worker 进程数，每个 worker 启一个 client
    framework: "torch"         # 深度学习框架
    model:
      fcnet_hiddens: [256, 256] # DQN Q-network 隐藏层

这种设计的关键在于 carla_env.py 中的 __init__() 方法：它先读取 YAML，再按顺序初始化 CarlaClient （用 carla.host/port ）、spawn vehicle（用 experiment.vehicle ）、attach sensors（用 experiment.sensors ），最后将 rl.config 传给父类 gym.Env 。 参数流是单向且不可逆的 ——CARLA 配置错误会导致 __init__() 抛异常，阻止环境创建；而 RLlib 配置错误则在 trainer.train() 时才暴露，不影响环境实例化。

3. 核心细节解析与实操要点：从安装到第一个 inference

3.1 安装与环境准备：避开 Linux/Windows 的经典陷阱

Linux (Ubuntu 20.04 LTS) 本地安装

CARLA 官方推荐 Ubuntu 20.04，因其内核版本（5.4）与 CARLA UE4 编译时的 glibc 兼容性最佳。安装步骤如下：

1. CARLA 二进制安装 ：

   wget https://carla-releases.s3.eu-west-3.amazonaws.com/CarlaUE4/CarlaUE4_0.9.11.tar.gz
   tar -xvzf CarlaUE4_0.9.11.tar.gz
   export CARLA_ROOT=$PWD/CarlaUE4_0.9.11
   

   关键点： CARLA_ROOT 必须指向解压后的根目录（含 CarlaUE4.sh 文件），而非 CarlaUE4_0.9.11/CarlaUE4.sh 。曾有用户设为后者，导致 carla_env.py 中 os.path.join(CARLA_ROOT, 'PythonAPI') 拼出错误路径。

2. Python 依赖安装 ：

   pip3 install -r requirements.txt
   # 特别注意：requirements.txt 中的 pygame==2.0.1 是硬性要求
   # 若系统已装 pygame 2.1.0，需强制降级：pip3 install pygame==2.0.1
   

   原因：CARLA PythonAPI 0.9.11 的 carla.libcarla 模块与 pygame 2.1.0 的 _sdl2 子模块存在 ABI 冲突，会导致 import carla 时 Segmentation Fault。

3. 验证 CARLA server 可启动 ：

   cd $CARLA_ROOT
   ./CarlaUE4.sh -opengl -quality-level=Low -fps=10
   # 在新终端执行：
   python3 -c "import carla; c = carla.Client('localhost', 2000); print(c.get_world().get_map().name)"
   # 应输出 Town05
   

Windows 10/11 安装（WSL2 用户请跳过此节）

Windows 原生支持 CARLA 0.9.11，但需额外步骤：

• 安装 Visual Studio 2019 ：CARLA PythonAPI 依赖 vcruntime140.dll ，必须由 VS2019 运行时提供。仅安装 Microsoft Visual C++ Redistributable for Visual Studio 2015-2019 不够，需完整 VS2019（社区版免费）。
• CARLA 启动参数修改 ：Windows 下 CarlaUE4.bat 默认使用 DirectX，但 RLlib 集成包的 carla_server.py 强制指定 -opengl 。需手动编辑 CarlaUE4.bat ，将 start "" "%~dp0CarlaUE4.exe" 改为 start "" "%~dp0CarlaUE4.exe" -opengl -quality-level=Low 。
• PATH 环境变量 ：将 $CARLA_ROOT/PythonAPI/carla/dist 添加到系统 PATH，否则 import carla 会报 ModuleNotFoundError 。

实操心得：Windows 下首次运行 dqn_train.py 时，若报 OSError: [WinError 10013] An attempt was made to access a socket in a way forbidden by its access permissions ，说明端口 2000 被占用。用 netstat -ano | findstr :2000 查进程 ID， taskkill /PID <ID> /F 杀掉即可。这是 Windows 防火墙策略导致的常见问题，非代码 bug。

3.2 环境配置文件详解：dqn_config.yaml 的每一行都在做什么？

以 dqn_example/dqn_config.yaml 为例，逐字段解析其作用及修改建议：

YAML 字段	作用	修改建议	风险提示
carla.map: "Town05"	指定 CARLA 加载的地图	若需测试复杂路口，可换 Town06 ；但 Town07 以上地图需 CARLA 0.9.12+，0.9.11 不支持	换地图后需确认 CARLA_ROOT/Maps/ 下存在对应 .opendrive 文件，否则 server 启动失败
experiment.vehicle.spawn_point: [100.0, 50.0, 0.5]	ego vehicle 初始坐标	坐标系原点在 Town05 广场中心，X 正向为东，Y 正向为北。 [100,50,0.5] 位于主干道东侧直道	坐标超出地图范围（如 X>2000）会导致 vehicle spawn 失败， step() 返回 done=True ，训练无法进行
experiment.sensors[0].resolution: [800, 600]	RGB 相机分辨率	降低至 [400,300] 可减少显存占用 75%，但影响 BirdView 特征提取精度	分辨率必须为偶数，奇数值（如 [401,300] ）会导致 CARLA server 崩溃
rl.config.num_workers: 4	RLlib worker 进程数	本地 CPU 核心数 ≥8 时可设为 8；若仅 4 核，建议 ≤2，避免 CPU 争抢	num_workers > carla.timeout 秒内能完成的 step 数，会导致 client 连接堆积，最终超时
rl.config.model.fcnet_hiddens: [256, 256]	DQN Q-network 结构	增加层数（如 [512,512,256] ）提升表达能力，但训练更慢	隐藏层神经元数总和 > 1024 时，Torch 模型序列化时间显著增加，影响 ray submit 启动速度

特别注意 experiment.sensors 中的 transform 字段： [x,y,z,roll,pitch,yaw] 的单位是 米和度 ，非弧度。 yaw=0 表示相机朝向车辆前方（即世界坐标系 Y 正向）。若设 yaw=90 ，相机会朝左（X 正向），此时 BirdView 伪传感器生成的俯视图会旋转 90 度——这并非 bug，而是 CARLA 坐标系定义。若需校正，应在 carla_env.py 的 BirdViewSensor 类中添加 cv2.rotate() 。

3.3 DQN 示例实操：从训练到 inference 的完整链路

本地训练全流程（含关键日志解读）

1. 安装 DQN 专用依赖 ：

   pip3 install -r dqn_example/dqn_requirements.txt
   # 此文件包含 torch==1.10.2+cu113（CUDA 11.3），与 CARLA 0.9.11 兼容
   

2. 启动 CARLA server（后台运行） ：

   cd $CARLA_ROOT
   nohup ./CarlaUE4.sh -opengl -quality-level=Low -fps=10 > carla.log 2>&1 &
   # 检查是否启动成功：tail -n 20 carla.log | grep "Listening to new connections"
   

3. 运行训练脚本 ：

   cd /path/to/rllib-integration
   python3 dqn_train.py dqn_example/dqn_config.yaml --name dqn_local
   

   • --name dqn_local 会创建 ~/ray_results/dqn_local/ 目录存放 checkpoint；
   • 训练日志中关键指标： episode_reward_mean （平均回合奖励）、 episodes_total （总回合数）、 learner_stats/q_loss （Q 网络损失）；
   • 若 episode_reward_mean 长期 < -1000，检查 reward function 是否过于惩罚（如 reward = -1.0 每步）；若 > 5000 且波动剧烈，检查是否 done=True 触发过早（如碰撞检测阈值太低）。

4. 生成 inference 脚本 ：
   dqn_inference_ray.py 的核心逻辑是：

   # 加载训练好的 checkpoint
   trainer = DQNTrainer(config=config, env="CarlaEnv")
   trainer.restore("~/ray_results/dqn_local/DQN_CarlaEnv_00000_0_2023-10-01_12-30-45/checkpoint_000100/checkpoint-100")
   
   # 创建环境实例（注意：此处不走 RLlib 的 rollout，而是直接调用 env.step）
   env = CarlaEnv(config)
   obs = env.reset()
   for _ in range(1000):
       action = trainer.compute_single_action(obs)  # 获取动作
       obs, reward, done, info = env.step(action)
       if done:
           obs = env.reset()
   

   关键区别： dqn_inference.py （无 Ray 版）直接用 gym.make("CarlaEnv") ，适合快速验证； dqn_inference_ray.py 用 trainer.compute_single_action() ，能复用 RLlib 的预处理 pipeline（如 frame stacking），更贴近训练时的输入分布。

Inference 结果可视化技巧

CARLA 自带 pygame 显示窗口，但 dqn_inference.py 默认关闭 GUI。若需实时观察车辆行为：

• 修改 dqn_inference.py 中 env = CarlaEnv(config) 后添加：

  env.render()  # 启用 pygame 渲染
  

• 或在 carla_env.py 的 CarlaEnv 类中，将 self._render = False 改为 True ，并在 step() 末尾添加 self.world.tick() （确保渲染帧率）。

更实用的方法是导出视频：在 dqn_inference.py 的 for 循环中，用 cv2.VideoWriter 将 obs['birdview'] （numpy array）写入 MP4：

fourcc = cv2.VideoWriter_fourcc(*'mp4v')
out = cv2.VideoWriter('inference.mp4', fourcc, 10.0, (800, 600))
# 在循环内：
frame = obs['birdview']  # shape (600, 800, 3)
out.write(cv2.cvtColor(frame, cv2.COLOR_RGB2BGR))
out.release()

生成的视频可直接用于论文演示或团队评审。

4. 实操过程与核心环节实现：AWS 云端训练全解析

4.1 AMI 构建：从零创建可复用的 CARLA 训练镜像

aws_helper.py create-image 命令的本质，是自动化执行以下手工步骤：

1. 启动基础 EC2 实例 ：
   使用 ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-20230301 AMI（Ubuntu 20.04），实例类型 g4dn.xlarge （含 T4 GPU），磁盘空间 ≥100GB（CARLA + 日志 + checkpoint 占用大）。

2. 执行 install.sh 脚本 ：
   install.sh 的核心内容：

   # 下载 CARLA
   wget https://carla-releases.s3.eu-west-3.amazonaws.com/CarlaUE4/CarlaUE4_0.9.11.tar.gz
   tar -xvzf CarlaUE4_0.9.11.tar.gz
   
   # 安装依赖
   apt-get update && apt-get install -y libgl1-mesa-glx libglib2.0-0
   
   # 设置环境变量
   echo 'export CARLA_ROOT=/home/ubuntu/CarlaUE4_0.9.11' >> /home/ubuntu/.bashrc
   echo 'export PYTHONPATH=$CARLA_ROOT/PythonAPI/carla/dist/carla-0.9.11-py3.8-linux-x86_64.egg:$PYTHONPATH' >> /home/ubuntu/.bashrc
   
   # 预编译 PythonAPI（关键！避免每次启动都编译）
   cd $CARLA_ROOT/PythonAPI/carla
   python3 setup.py build_ext --inplace
   

3. 创建 AMI 快照 ：
   脚本执行完毕后，调用 boto3.ec2.create_image() ，将实例根卷保存为 AMI，并打上标签 Name=carla-rllib-0.9.11 。

实操心得：构建 AMI 时务必 禁用实例终止保护 （Instance Termination Protection），否则 ray down 命令无法销毁 worker node。我在第一次构建时忘了关，导致 3 台 g4dn.2xlarge 实例持续运行 48 小时，账单惊现 $217。教训：AMI 构建完成后，立即在 AWS 控制台检查实例的 “Instance Settings” → “Change Termination Protection”。

4.2 Autoscaler 配置：dqn_autoscaler.yaml 的魔鬼细节

dqn_example/dqn_autoscaler.yaml 是整个云端训练的“大脑”，其关键字段解析：

# head_node：运行 RLlib trainer 的主节点
head_node:
  InstanceType: g4dn.xlarge
  ImageId: ami-0abcdef1234567890  # 此处填 create-image 输出的 AMI ID
  SecurityGroupIds: ["sg-0123456789abcdef0"]  # 填 create-image 输出的安全组 ID
  # 启动时自动运行 CARLA server
  SetupCommands:
    - "cd /home/ubuntu/CarlaUE4_0.9.11 && nohup ./CarlaUE4.sh -opengl -quality-level=Low -fps=10 > /tmp/carla.log 2>&1 &"

# worker_nodes：运行 RLlib workers 的计算节点
worker_nodes:
  InstanceType: g4dn.xlarge
  MinCount: 2
  MaxCount: 8
  # 注意：worker 不启动 CARLA server，只连 head_node
  SetupCommands:
    - "export CARLA_ROOT=/home/ubuntu/CarlaUE4_0.9.11"
    - "export PYTHONPATH=$CARLA_ROOT/PythonAPI/carla/dist/carla-0.9.11-py3.8-linux-x86_64.egg:$PYTHONPATH"

# 集群网络配置（重中之重！）
provider:
  type: aws
  region: us-east-1
  cache_stopped_nodes: false  # 必须为 false！CARLA server 不能停机
  # 安全组必须开放以下端口：
  # - 2000 (CARLA server)
  # - 6379 (Ray object store)
  # - 8265 (Ray dashboard)
  # - 10000-10010 (Ray worker ports)

提示： cache_stopped_nodes: false 是易错点。若设为 true ，当 autoscaler 检测到空闲 worker 时，会将其 stop（而非 terminate），下次启动时 CARLA server 不会自动恢复，导致 CarlaClient 连接超时。必须设为 false ，确保 worker node 永远在线。

4.3 训练执行与监控：从 ray up 到 ray status 的全链路

启动集群（ray up）

ray up dqn_example/dqn_autoscaler.yaml -y
# -y 参数跳过确认，适合 CI/CD

• 首次运行耗时约 8-12 分钟（取决于 AMI 启动速度）；
• 成功标志：终端输出 Cluster launched successfully ，且 ray status 显示 head_node 和 worker_nodes 状态为 up-to-date 。

同步代码（ray rsync-up）

# 同步本地 dqn_example 目录到 head_node 的 /home/ubuntu/rllib-integration/dqn_example
ray rsync-up dqn_example/dqn_autoscaler.yaml dqn_example/ ~/rllib-integration/dqn_example/

# 同步 rllib_integration 核心库（必须！否则 worker 找不到 carla_env.py）
ray rsync-up dqn_example/dqn_autoscaler.yaml rllib_integration/ ~/rllib-integration/rllib_integration/

注意： rsync-up 默认同步到 /home/ubuntu/ ，若需指定路径，用 --rsync-options="-avz --exclude='*.log'" 过滤日志文件。

提交训练任务（ray submit）

ray submit dqn_example/dqn_autoscaler.yaml dqn_train.py -- dqn_example/dqn_config.yaml --auto
# --auto 参数告诉脚本：从 YAML 中读取 rl.config，而非命令行参数

• ray submit 本质是 ssh 到 head_node，执行 python3 dqn_train.py ... ；
• 训练日志实时输出到 head_node 的 ~/ray_results/ 目录；
• 若需查看实时日志： ray attach dqn_example/dqn_autoscaler.yaml 进入 head_node，然后 tail -f ~/ray_results/dqn_aws/DQN_CarlaEnv_*/logs/progress.csv 。

监控与故障排查

• ray status ：显示各节点状态、CPU/GPU 使用率、对象存储内存；
• watch -n 1 ray status ：每秒刷新，观察 worker 是否因 OOM 被 kill（状态变为 unhealthy ）；
• 若 ray status 显示 worker_nodes 为 initializing 超过 5 分钟，检查安全组是否放行端口 2000；
• 若训练卡在 episode_reward_mean: 0.0 不变，登录 head_node，执行 ps aux | grep CarlaUE4 ，确认 server 进程是否存在。

5. 常见问题与排查技巧实录：那些文档没写的坑

5.1 本地训练高频问题速查表

问题现象	根本原因	解决方案	验证方法
ImportError: No module named 'carla'	PYTHONPATH 未正确设置，或 carla-0.9.11-py3.8-linux-x86_64.egg 路径错误	检查 echo $PYTHONPATH 输出是否包含 egg 路径；运行 python3 -c "import sys; print([p for p in sys.path if 'carla' in p])"	若输出为空，则 export PYTHONPATH=... 未生效，需 source ~/.bashrc
RuntimeError: CUDA out of memory	buffer_size 过大（默认 100000）或 num_workers 过多	在 dqn_config.yaml 中将 rl.config.replay_buffer_config.replay_buffer_size 降至 50000； num_workers 降至 2	运行 nvidia-smi ，观察 GPU memory usage 是否 < 90%
carla.libcarla.RPCException: time-out	CARLA server 未启动，或 carla.host 配置错误	执行 `ps aux	grep CarlaUE4 确认 server 进程；检查 dqn_config.yaml 中 carla.host 是否为 localhost （非 127.0.0.1`）
ValueError: Observation space is not compatible	carla_env.py 中 self.observation_space 定义与实际 step() 返回的 obs 字典结构不一致	检查 carla_env.py 的 __init__() 中 self.observation_space = spaces.Dict({...}) 的 key 名，是否与 step() 中 obs = {...} 的 key 完全相同	在 step() 返回前加 print(obs.keys()) ，对比是否匹配

5.2 AWS 云端特有问题排查

问题现象	根本原因	解决方案	验证方法
ray up 后 ray status 显示 worker_nodes 为 unhealthy	安全组未开放端口 6379（Ray object store）	在 AWS 控制台编辑安全组，添加入站规则： Custom TCP ，端口 6379 ，来源 Custom （填 head_node 安全组 ID）	telnet <head_node_private_ip> 6379 从 worker node 测试
ray submit 后训练无日志， ray status 显示 0 workers	rsync-up 未同步 rllib_integration/ 目录，worker 找不到 carla_env.py	重新执行 ray rsync-up ... rllib_integration/ ...	登录 head_node， ls ~/rllib-integration/rllib_integration/carla_env.py 应存在
dqn_train.py 报 ConnectionRefusedError: [Errno 111] Connection refused	worker node 的 carla.host 配置仍为 localhost ，而非 head_node 私有 IP	修改 dqn_config.yaml 中 carla.host: <head_node_private_ip> （可在 ray attach 后用 hostname -I 获取）	在 worker node 执行 python3 -c "import carla; c=carla.Client('<head_node_ip>',2000); print(c.get_world().get_map().name)"
ray down 后 EC2 实例仍在运行	cache_stopped_nodes: true 且实例终止保护开启	编辑 dqn_autoscaler.yaml ，设 cache_stopped_nodes: false ；在 AWS 控制台关闭实例终止保护	ray down 后立即检查 EC2 控制台，实例状态应变为 terminating

5.3 更新 CARLA 版本的实操指南

官方文档提到“其他版本可能兼容”，但实测中 CARLA 0.9.12+ 与 RLlib 集成包存在三处关键 break：

1. Actor 控制 API 变更 ：
   0.9.11 中 vehicle.set_autopilot(True) 有效；0.9.12+ 需 vehicle.set_autopilot(True, tm_port=8000) ，且需先启动 Traffic Manager。解决方案：在 carla_env.py 的 reset() 中添加：

   if self.carla_version >= "0.9.12":
       tm = self.client.get_trafficmanager(8000)
       tm.set_synchronous_mode(True)
       vehicle.set_autopilot(True, 8000)