企业官网建设流程全解析

• 自动驾驶
• 数据集
• 计算机视觉

docs/docker.md是 Waymo Open Dataset（WOD）仓库中专讲 Docker 使用方式的文档：它给出了从源码构建官方镜像、启动带waymo_open_dataset依赖的 Jupyter Notebook 服务，并打开本地教程tutorial_local.ipynb的完整三步流程。本文以该文档为核心，结合仓库中的 tutorial/cpu-jupyter.Dockerfile、tutorial/jupyter_kernel.py 与 tutorial/BUILD 等源码，逐条剖析每条命令背后的构建链路与服务配置，并给出与当前代码树布局匹配的可执行版本及常见问题的处理建议。

一、文档给出的完整流程

docs/docker.md 的原始内容只有三条命令，但完整覆盖了一条“构建镜像 → 启动服务 → 打开教程”的闭环路径：

# 1. 构建 docker 容器 docker build --tag=open_dataset . # 2. 启动一个以 waymo_open_dataset 为依赖的 Jupyter notebook docker run -p 8888:8888 open_dataset # 3. 浏览器打开 http://0.0.0.0:8888，点击 tutorial_local.ipynb 打开教程

流程上的三个关键点：

1. 构建阶段把 TensorFlow、Jupyter、Bazel 和 WOD 源码的编译全部打进一个名为open_dataset的镜像，用户机器上无需预装任何依赖；
2. 运行阶段只映射一个端口8888（Jupyter 服务端口），容器内实际执行的是 Bazel 目标//waymo_open_dataset/tutorial:jupyter_kernel；
3. 使用阶段不需要任何认证 token，直接在浏览器里打开tutorial_local.ipynb，该 notebook 使用容器内自带的两帧示例数据演示数据集的读取与可视化。

下面逐段展开。

二、构建命令剖析：docker build --tag=open_dataset .

2.1 构建上下文与 Dockerfile 的对应关系

docker build --tag=open_dataset .中的.表示构建上下文（build context），open_dataset是本地的镜像 tag。文档编写时期，仓库约定在构建上下文的根目录放置Dockerfile；而在当前代码树中，与教程容器对应的 Dockerfile 位于 tutorial/cpu-jupyter.Dockerfile。因此在当前仓库下更稳妥的等价写法是显式指定文件：

docker build -f tutorial/cpu-jupyter.Dockerfile --tag=open_dataset .

从源码结构看，构建上下文本身的作用很小——该 Dockerfile 在镜像内部会自行拉取 WOD 仓库源码（见下文），本地图像层主要提供构建工具链。仓库中的 src/waymo_open_dataset/.dockerignore 定义了构建时应忽略的产物（bazel-*符号链接、IDE 缓存、虚拟环境等），用于避免把本地产物误打进上下文。

2.2 Dockerfile 逐步拆解

tutorial/cpu-jupyter.Dockerfile 共 22 行，逻辑可以分成五段（代码块中已对上游仓库地址做了脱敏注释）：

# 基础镜像：官方 TensorFlow Python3 镜像 FROM tensorflow/tensorflow:latest-py3 # (1) 系统工具链 RUN apt-get update && apt-get install -y \ git build-essential wget vim findutils curl \ pkg-config zip g++ zlib1g-dev unzip python3 python3-pip RUN apt-get install -y wget golang RUN go install github.com/bazelbuild/bazelisk@latest # (2) Jupyter 服务与可视化依赖 RUN pip3 install jupyter matplotlib jupyter_http_over_ws &&\ jupyter serverextension enable --py jupyter_http_over_ws # (3) 拉取 WOD 仓库并进入 bazel 工作区（官方上游仓库地址，原文为 git clone ...） RUN git clone <official waymo-open-dataset repo> waymo-od WORKDIR /waymo-od/src # (4) 预构建（运行测试并构建包，耗时最长的一步） RUN pip_pkg_scripts/build.sh # (5) 暴露端口并安装默认 Python kernel EXPOSE 8888 RUN python3 -m ipykernel.kernelspec # 容器入口：用 bazel 以优化模式编译并运行 Jupyter kernel 目标 CMD ["bash", "-c", "source /etc/bash.bashrc && bazel run -c opt //waymo_open_dataset/tutorial:jupyter_kernel"]

各步骤的工程含义：

• 基础镜像tensorflow/tensorflow:latest-py3：预装了 TensorFlow 运行时，WOD 的指标库与数据工具大量依赖 TensorFlow（如 src/waymo_open_dataset/metrics/ops/ 下的自定义 op 包装）。使用latest标签意味着镜像中的 TF 版本会随上游发布变化，复现问题时应固定基础镜像 tag。

• 工具链部分（第 3–8 行）：安装golang后用go install安装bazelisk——WOD 是 Bazel 工程，src/WORKSPACE 中通过http_archive声明了全部外部依赖，bazelisk负责按仓库声明拉取并执行对应版本的 Bazel。

• jupyter_http_over_ws（第 11–12 行）：这是一个把 Jupyter 的 HTTP 请求改走 WebSocket 通道的扩展。它使得浏览器可以通过一个 WebSocket 端点访问容器内服务，适合在只有端口转发的环境（如远程服务器隧道、Colab 类环境）中使用，与后文jupyter_kernel.py中放行 Colab 域名同源（见第四节）。

• RUN pip_pkg_scripts/build.sh：这一步调用构建脚本 src/waymo_open_dataset/pip_pkg_scripts/build.sh，其实际动作（第 21–23 行）是：

  bazelisk test -c opt ... --test_output=all bazelisk build -c opt //waymo_open_dataset/pip_pkg_scripts:wheel_manylinux cp bazel-out/k8-opt/bin/waymo_open_dataset/pip_pkg_scripts/auditwheel_manylinux/* /tmp/wod

  即先跑全量测试，再以-c opt优化模式构建 manylinux wheel 并拷出。由于 build.Dockerfile 与 pip_pkg_scripts/README.md 中的 pip 包构建链路复用同一套脚本，这一步本质上是把 WOD 的 C++ 算子（metrics/ops、wdl_limited下的 camera model ops 等）在镜像内完成一次预热编译。

• bazel run -c opt //waymo_open_dataset/tutorial:jupyter_kernel（第 22 行）：容器启动时才真正执行的目标，它把 tutorial/jupyter_kernel.py 编译为可运行的py_binary（依赖关系见第五节），并启动 Notebook 服务。

布局差异提示：文档中的命令与该 Dockerfile 均基于早期仓库布局编写（当时pip_pkg_scripts位于src/直接子目录下）。当前代码树中该脚本位于 src/waymo_open_dataset/pip_pkg_scripts/build.sh，Bazel 包路径也已前缀为//waymo_open_dataset/...。从源码结构看，若直接用当前快照作为构建源，第 17 行的RUN pip_pkg_scripts/build.sh路径需要按新布局调整；这也是官方文档推荐“在容器内自行 clone 上游仓库”方式的原因——镜像内拉取的是上游 master，与其当时的布局保持一致。

三、运行命令剖析：docker run -p 8888:8888 open_dataset

docker run -p 8888:8888 open_dataset

参数含义：

文档建议打开http://0.0.0.0:8888（本地等价于http://localhost:8888），在文件列表里点击tutorial_local.ipynb即可进入教程。该 notebook 由 Bazel 目标作为data打进运行环境（见第五节），使用容器内自带的两帧本地数据演示 WOD 的读取流程，无需先下载完整数据集。

首次运行的等待：容器首次启动时bazel run需要完成依赖编译（C++ proto 库、自定义 op、TF 相关依赖），耗时显著长于后续冷启动；这是由 Bazel 的增量构建机制决定的，属于预期行为。

四、Jupyter 服务配置：jupyter_kernel.py源码级解析

容器里真正定义“服务怎么跑”的是 tutorial/jupyter_kernel.py。其main函数对NotebookApp单例做了如下配置，逐条对应到文档中的操作体验：

def main(_): instance = notebookapp.NotebookApp.instance() instance.open_browser = False instance.ip = "0.0.0.0" instance.port = 8888 instance.port_retries = 0 instance.allow_origin_pat = "https://colab\\.[^.]+\\.google.com" instance.allow_root = True instance.token = "" instance.disable_check_xsrf = True instance.initialize() instance.start()

安全提示：token = ""加disable_check_xsrf = True意味着该 Jupyter 服务没有认证。这套配置面向“本机自测教程”的场景；不要把 8888 端口直接暴露到公网，远程使用时应走 SSH/VPN 隧道，且注意端口映射只绑到本机（如需限制可加--net或使用-p 127.0.0.1:8888:8888形式）。

五、容器内容物：Bazel 目标tutorial:jupyter_kernel

Dockerfile 的CMD运行的是 tutorial/BUILD 中定义的py_binary目标，它决定了容器内 Jupyter 环境里“能 import 到什么”。

py_binary( name = "jupyter_kernel", srcs = ["jupyter_kernel.py"], data = [ "tutorial_local.ipynb", ":cameradata", ":framedata", "//waymo_open_dataset/metrics/tools:compute_detection_metrics_main", "//waymo_open_dataset/metrics/tools:fakedata", "//waymo_open_dataset/utils/testdata:motion_dataset_test_data", ], main = "jupyter_kernel.py", deps = [ requirement('matplotlib'), requirement('numpy'), requirement('tensorflow'), requirement('tensorflow_graphics'), "//third_party/py/cv2", ... # dataset/label proto、metrics ops、utils 等 ], )

其中值得关注的三点：

1. data即教程的“离线数据”：tutorial_local.ipynb本体、点云/语义分割样例图与帧列表（framedatafilegroup，含 tutorial/3d_point_cloud.png、frames_with_maps.tfrecord等）、相机码本womd_camera_codebook.npy（cameradata）、以及 metrics/tools 下的compute_detection_metrics_main与假数据生成目标fakedata、motion 测试集。这正是文档最后一步“点击 tutorial_local.ipynb 即可运行”的数据来源——教程全程不需要访问外部数据集。
2. deps即 Python 依赖闭包：除tensorflow、tensorflow_graphics、numpy、matplotlib、cv2外，还包含 metrics/ops/py_metrics_ops（TF 自定义 op 的 Python 封装）、wdl_limited/camera/ops的相机模型 ops 及sim_agents_metrics指标模块等，说明容器内可直接复现检测/关键点/运动等任务的评测脚本。
3. 同一 BUILD 文件还定义了jupyter_kernel_v2（tutorial/BUILD），其deps换成//waymo_open_dataset/v2与plotly、visu3d，对应仓库中 tutorial/tutorial_v2.ipynb 使用的 V2 数据接口（parquet 列式格式，参见 src/waymo_open_dataset/v2/testdata/ 中的 parquet 样例）。

依赖版本以 src/waymo_open_dataset/requirements.in 中的固定版本为准（如tensorflow==2.13、numpy==1.23.5、pandas==1.5.3、pyarrow==16.0.0），wheel 打包声明同样列于 src/waymo_open_dataset/pip_pkg_scripts/BUILD 的py_wheel(requires = [...])中。注意 Docker 基础镜像用的是latest-py3标签，镜像内 TF 版本与上述 pin 版本可能存在漂移，复现实验时建议以requirements.in的 pin 为基准核对。

六、仓库中其他 Docker 文件（边界说明）

为避免混淆，列出当前仓库中与 Docker 相关的全部文件及其定位——它们与本文主题（教程容器）是并列而非替代关系：

pip wheel 构建镜像的关键设计（供延伸阅读）：使用非 root 用户（rules_python新版本下 root 构建会失败）、通过CPYTHON_PATH指向 cp311、用auditwheel修复为manylinux_2_28_x86_64平台 wheel，详见 pip_pkg_scripts/README.md。

七、常见问题与实操建议

结合上述源码，常见情况与对应处理方式：

1. 宿主 8888 端口被占用：port_retries = 0决定了容器内服务不会自动换端口。保留容器端口 8888 不变，把宿主端口改掉即可：

   docker run -p 8889:8888 open_dataset # 浏览器改开 http://localhost:8889

2. 镜像构建很慢/失败：Dockerfile 中pip_pkg_scripts/build.sh会先执行全量bazelisk test -c opt ...，这是最耗时的一步；构建环境需要能拉取 Bazel 外部依赖（网络受限环境应先配置代理）。若只是要跑教程，可按第二节末的提示核对脚本路径与当前仓库布局的一致性。

3. 找不到tutorial_local.ipynb：确认访问的是 Bazelpy_binary的运行时目录（bazel 输出目录中的运行目录），该文件由data依赖随bazel run自动放置到位，不要期望它出现在宿主机的tutorial/目录下。

4. 远程服务器上使用：该服务未启用 token 认证，不要-p 8888:8888后直接映射到公网；使用ssh -L 8888:localhost:8888 <server>之类隧道后再打开http://localhost:8888。

5. 想固定环境版本：构建时把基础镜像替换为具体 tag 的 TensorFlow 官方镜像，并对照 requirements.in 的 pin 版本核对 Python 依赖。

八、命令速查

小结：docs/docker.md的三条命令背后是一条完整链路——Bazel 工程（src/WORKSPACE）提供依赖解析，tutorial/cpu-jupyter.Dockerfile 提供工具链与预编译，tutorial/jupyter_kernel.py 定义服务行为，tutorial/BUILD 的py_binary把教程 notebook 与离线样例数据一并封装进运行环境。理解这四者后，你既能按文档原样复现官方流程，也能针对当前仓库布局、端口冲突与远程访问场景做出正确的调整。

• 自动驾驶
• 数据集
• 计算机视觉