diff --git a/docker/Dockerfile b/docker/Dockerfile
index 8efa506..cfca35f 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -242,7 +242,6 @@ RUN set -ex && \
     fi && \
     mkdir -p /opt/vllm_build && \
     export HIP_PLATFORM=amd HIP_PATH=/opt/rocm ROCM_PATH=/opt/rocm && \
-    CMAKE_EC=0; \
     cmake -S /opt/vllm -B /opt/vllm_build -G Ninja \
         -DCMAKE_BUILD_TYPE=RelWithDebInfo \
         -DVLLM_TARGET_DEVICE=rocm \
@@ -254,16 +253,7 @@ RUN set -ex && \
         -DHIP_COMPILER=/opt/rocm/llvm/bin/clang++ \
         -DHIP_PATH=/opt/rocm \
         -DHIP_INCLUDE_DIR=/opt/rocm/include \
-        -DCMAKE_PREFIX_PATH="/opt/rocm;${VENV}/lib/python${PYTHON_VER}/site-packages/torch/share/cmake" \
-        >/tmp/cmake.log 2>&1 || CMAKE_EC=$?; \
-    cat /tmp/cmake.log; \
-    if [ $CMAKE_EC -ne 0 ]; then \
-        echo ""; \
-        echo "========== CMake FAILED (exit=$CMAKE_EC) =========="; \
-        echo "=== grep CMake Error / fatal ==="; \
-        grep -i 'cmake error\|CMake Error\|fatal' /tmp/cmake.log || true; \
-        exit $CMAKE_EC; \
-    fi && \
+        -DCMAKE_PREFIX_PATH="/opt/rocm;${VENV}/lib/python${PYTHON_VER}/site-packages/torch/share/cmake" && \
     cd /opt/vllm_build && ninja -j8 && \
     cp /opt/vllm_build/*.abi3.so /opt/vllm/vllm/ && \
     echo "vllm C++ build complete (layer cached)."
diff --git a/docker/ISSUES.md b/docker/ISSUES.md
index 1ea1fb2..6448f18 100644
--- a/docker/ISSUES.md
+++ b/docker/ISSUES.md
@@ -62,6 +62,27 @@ git config --global http.version HTTP/1.1
 git config --global http.postBuffer 524288000
 ```
 
+### 1.5 PyTorch ROCm wheels 下载中断
+
+**现象**：`IncompleteRead` (pip 下载 .whl 到一半断开)
+
+**原因**：PyTorch 官方 CDN (`download.pytorch.org`) 在国内直连不稳定
+
+**解决**：下载 PyTorch 时设环境变量走代理
+
+```bash
+export http_proxy=http://127.0.0.1:8118 https_proxy=http://127.0.0.1:8118
+pip install ... --pre torch==2.11.0+rocm7.2 ...
+```
+
+### 1.6 flash-attention 子模块代理递归断连
+
+**现象**：`--recursive` 克隆 flash-attention 时子模块 `cutlass` (~200MB) 下载失败：`RPC failed; curl 56 GnuTLS recv error`
+
+**原因**：3 个子模块（composable_kernel + cutlass + aiter）挤在一条代理链路上，大文件容易丢包
+
+**解决**（可选）：宿主机预克隆后 COPY 入镜像。或用 `--depth 1` + 逐个 `git submodule update --init --depth 1`（断了一个可单独重试）
+
 ---
 
 ## 2. Dockerfile 语法类
@@ -148,6 +169,22 @@ if [ -f csrc/mamba/mamba_ssm/selective_scan.h ]; then sed ...; else echo "skippi
 2. 补丁 6：`platforms/__init__.py` 加 `torch.version.hip` 兜底
 3. 补丁 7：`platforms/rocm.py` 中 `logger.warning_once()` → `sys.stderr.write()`
 
+### 3.6 缺 hip_version.h 头文件
+
+**现象**：`Could not find hip/hip_version.h or rocm-core/rocm_version.h`
+
+**原因**：ROCm 7.2.1 的 apt 安装已将 `hip_version.h` 从默认路径移除，且 `rocm-core` 包未安装
+
+**解决**：
+1. 安装 `rocm-core` 包（提供 `rocm_version.h`）
+2. 手动创建 `/opt/rocm/include/hip/hip_version.h` 兼容头文件
+
+```bash
+apt-get install -y rocm-core
+# 兜底：手动生成 hip_version.h
+printf '#define HIP_VERSION_MAJOR 7\n#define HIP_VERSION_MINOR 2\n...'
+```
+
 ### 3.7 cmake 需显式设 HIP 编译器路径
 
 **现象**：仅设 `PATH` + `HIP_ROOT_DIR` + `ROCM_PATH` 不足以让 cmake 发现 HIP
@@ -161,6 +198,58 @@ if [ -f csrc/mamba/mamba_ssm/selective_scan.h ]; then sed ...; else echo "skippi
 -DCMAKE_PREFIX_PATH="/opt/rocm;..."
 ```
 
+### 3.8 PyTorch Caffe2Targets 缺失 cmake target（Docker 容器特有）
+
+**现象**：cmake 反复报 `hip::amdhip64` / `hiprtc::hiprtc` / `roc::hipblas` / `roc::hipblaslt` 等 target 未找到
+
+**原因**：裸机部署时 ROCm 的 cmake 配置通过 `/opt/rocm` 完整安装，cmake 能自动发现所有 target。但 Docker 容器内 apt 安装的 dev 包缺少部分 cmake config 文件，PyTorch 的 `Caffe2Targets.cmake` 硬编码引用了这些 target
+
+**涉及 target 及修复**：
+
+| 报错 target | 命名空间问题 | 最终 alias |
+|:--|:--|:--|
+| `hip::amdhip64` | 普通 target | SHARED IMPORTED → `libamdhip64.so` |
+| `hiprtc::hiprtc` | 需双冒号命名空间 | `hiprtc::hiprtc` ALIAS `hip::hiprtc` |
+| `roc::hipblas` | roc:: 而非 hip:: | `roc::hipblas` ALIAS `roc::rocblas` |
+| `roc::hipblaslt` | 同上 | `roc::hipblaslt` ALIAS `hip::hipblaslt` |
+| `roc::hiprand` / `roc::hipsolver` 等 | 同上 | 各指向对应 `roc::roc*` target |
+
+**注意**：`roc::hip*` → 应直接指向底层 `roc::roc*`（不能通过 `hip::hip*` 中转，因为后者本身是 ALIAS，CMake 不允许链式 ALIAS）
+
+### 3.9 rocm-core-dev → rocm-core 包名错误
+
+**现象**：`E: Unable to locate package rocm-core-dev`
+
+**原因**：ROCm 7.2.1 仓库中的包名为 `rocm-core`（无 -dev 后缀）
+
+**解决**：`s/rocm-core-dev/rocm-core/`
+
+### 3.10 -lMIOpen 链接失败
+
+**现象**：`/usr/bin/ld: cannot find -lMIOpen`
+
+**原因**：miopen cmake config 使用了 `INTERFACE IMPORTED`（无实际 .so 路径），链接器找不到 `libMIOpen.so`
+
+**解决**：改为 `SHARED IMPORTED` + 指定 `IMPORTED_LOCATION`，并检查版本化目录的符号链接
+
+```cmake
+# 错误
+add_library(miopen INTERFACE IMPORTED)
+# 正确
+add_library(miopen SHARED IMPORTED)
+set_target_properties(miopen PROPERTIES
+    IMPORTED_LOCATION "/opt/rocm/lib/libMIOpen.so"
+    INTERFACE_INCLUDE_DIRECTORIES "/opt/rocm/include")
+```
+
+### 3.11 printf 参数计数错误
+
+**现象**：cmake 报 `add_library` 在第 11 行语法错误（`hiprtc-config.cmake:11`）
+
+**原因**：生成 cmake config 的 shell printf 格式串含 13 个 `%s`，但只传了 12 个参数，最后一行 `hip::%s` 未替换
+
+**解决**：减少单行 printf 参数，复杂结构拆成独立循环
+
 ---
 
 ## 4. Docker 缓存策略
@@ -180,8 +269,15 @@ if [ -f csrc/mamba/mamba_ssm/selective_scan.h ]; then sed ...; else echo "skippi
 
 任一 RUN 层的指令或上下文变化都会导致该层及之后所有层重建。修改 `ARG`、`ENV`、`COPY` 文件内容均会触发。
 
----
+### 4.3 COPY 脚本在 RUN 引用之后
 
+**现象**：阶段 8b 执行 `python /opt/patch_vllm_platform.py` → 文件不存在
+
+**原因**：`COPY scripts/patch_vllm_platform.py` 在阶段 8.5（原序号），但阶段 8b 已引用该脚本——Dockerfile 中 COPY 位于引用它的 RUN 之后
+
+**解决**：将 COPY 指令移到所有需要脚本的 RUN 之前（阶段 7.5）。规则：**COPY 必须在引用它的 RUN 之前**
+
+---
 ## 5. 网络策略总览
 
 | 资源 | 访问方式 |
@@ -195,4 +291,4 @@ if [ -f csrc/mamba/mamba_ssm/selective_scan.h ]; then sed ...; else echo "skippi
 
 ---
 
-*最后更新: 2026-06-04*
+*最后更新: 2026-06-05*