Nginx 镜像 BYOI 源码级讲解

源码路径：CubeSandbox/examples/cubesandbox-base-nginx/

概述

本例演示"Bring Your Own Image"（BYOI）流程：基于 cubesandbox-base 基础镜像叠加 Nginx，构建一个可注册为 Cube 模板的自定义镜像。

核心问题：为什么不能直接用任意 Docker 镜像？因为 CubeSandbox 的 VM 需要一个特殊的 envd 服务来对接平台控制面。

镜像分层架构

源码解析：Dockerfile

FROM cubesandbox-base

# 安装 nginx
RUN apt-get update && apt-get install -y nginx

# 拷贝静态页面
COPY index.html /var/www/html/

# 暴露端口：envd(49983) + nginx(80)
EXPOSE 49983 80

# 启动脚本：同时运行 envd 和 nginx
CMD ["sh", "-c", "envd & nginx -g 'daemon off;'"]

关键设计点

源码解析：test_files.py — SDK 验证

with Sandbox.create(template=template_id) as sandbox:
    # ① 通过 SDK 读取沙箱内文件
    nginx_conf = sandbox.files.read("/etc/nginx/nginx.conf")

    # ② 通过端口访问 nginx 服务
    resp = requests.get(f"https://{sandbox.get_host(80)}/")
    print(resp.text)

两条数据通路

路径	协议	端口	用途
文件操作	gRPC via envd	49983	读写沙箱文件
HTTP 服务	HTTPS via CubeProxy	80	访问 nginx 服务

模板注册流程

cubemastercli tpl create-from-image \
    --image <registry>/cubesandbox-demo-nginx:latest \
    --expose-port 49983 \    # envd（必须）
    --expose-port 80 \       # nginx（业务）
    --probe 49983 \          # 探针目标
    --probe-path /health     # 探针路径

注册后的路由表

BYOI 必须满足的契约

契约	说明	不满足的后果
运行 envd	平台 SDK 依赖 envd 通信	文件/命令操作全部失败
响应 /health	CubeProbe 判定就绪	沙箱永远处于 Starting 状态
端口声明	--expose-port 必须声明	外部无法访问

推荐阅读

1. Dockerfile — 镜像构建逻辑
2. test_files.py — SDK 验证流程
3. README.md — 完整步骤说明

源码参考：cubesandbox-base-nginx/