cloudflare/hello-world

cloudflare-example-app 镜像文档

1. 镜像概述和主要用途

1.1 概述

cloudflare-example-app 是一款轻量级示例应用镜像，专为 Cloudflare 容器运行时环境设计，用于演示容器化应用在 Cloudflare 平台的部署与运行流程。镜像封装了基础应用逻辑，确保与 Cloudflare 容器服务的兼容性。

1.2 主要用途

• 作为开发者学习 Cloudflare 容器运行时部署的实践案例；
• 提供基础模板，快速构建适用于 Cloudflare 平台的容器化应用；
• 验证 Cloudflare 容器运行时环境的基础功能及兼容性。

2. 核心功能和特性

• 轻量级设计：镜像体积小（<10MB），启动速度快，资源占用低；
• Cloudflare 兼容：针对 Cloudflare 容器运行时环境优化，支持平台网络与资源调度；
• 简化部署：支持标准 Docker 命令部署，流程直观，无需复杂配置；
• 基础功能演示：内置 HTTP 服务示例，可直接运行并验证服务可用性。

3. 使用场景和适用范围

3.1 使用场景

• Cloudflare 平台用户学习容器化应用部署流程；
• 开发者基于模板快速开发 Cloudflare 兼容应用；
• 测试 Cloudflare 容器运行时的网络策略、资源限制等功能。

3.2 适用范围

• Cloudflare 账号用户（需启用容器运行时环境）；
• 容器化应用开发者（熟悉 Docker 基础操作）；
• 学习边缘计算或 Cloudflare 平台的技术人员。

4. 使用方法和配置说明

4.1 前提条件

• 安装 Docker 引擎（推荐 20.10+ 版本）；
• 拥有 Cloudflare 账号并启用容器运行时环境；
• （可选）配置 Cloudflare API 令牌（用于镜像推送）。

4.2 获取镜像

4.2.1 从 Docker 镜像源拉取

bash
docker pull cloudflare/example-app:latest

4.2.2 本地构建（如需自定义）

1. 克隆源码仓库（假设存在）：

   bash
   git clone https://github.com/cloudflare/example-app.git && cd example-app
   

2. 构建镜像：

   bash
   docker build -t cloudflare-example-app:local .
   

4.3 运行与部署流程

4.3.1 本地测试运行

通过 Docker 命令直接启动容器，验证基础功能：

bash
docker run -d -p 8080:8080 --name example-app-demo cloudflare/example-app:latest

• -d：后台运行容器；
• -p 8080:8080：映射容器内 8080 端口至主机 8080 端口；
• --name：指定容器名称（可选）。

4.3.2 部署至 Cloudflare 容器运行时

1. 登录 Cloudflare 容器注册表：

   bash
   docker login registry.cloudflare.com -u <CLOUDFLARE_ACCOUNT_ID> -p <CLOUDFLARE_API_TOKEN>
   

   （需提前创建 API 令牌，权限包含 edit:images）

2. 为镜像添加 Cloudflare 注册表标签：

   bash
   docker tag cloudflare/example-app:latest registry.cloudflare.com/<CLOUDFLARE_ACCOUNT_ID>/example-app:latest
   

3. 推送镜像至 Cloudflare 注册表：

   bash
   docker push registry.cloudflare.com/<CLOUDFLARE_ACCOUNT_ID>/example-app:latest
   

4. 在 Cloudflare 控制台「容器」页面创建部署，选择推送的镜像并启动服务。

5. 部署方案示例

5.1 docker run 命令示例（带配置）

bash
docker run -d \
  -p 8080:8080 \
  -e APP_PORT=8080 \
  -e LOG_LEVEL=info \
  --name example-app-configured \
  cloudflare/example-app:latest

• -e APP_PORT=8080：指定应用监听端口（默认 8080）；
• -e LOG_LEVEL=info：设置日志级别（默认 info）。

5.2 docker-compose 配置示例

创建 docker-compose.yml 文件：

yaml
version: '3.8'
services:
  example-app:
    image: cloudflare/example-app:latest
    container_name: example-app
    ports:
      - "8080:8080"
    environment:
      - APP_PORT=8080
      - LOG_LEVEL=info
    restart: unless-stopped  # 容器退出时自动重启（除非手动停止）

启动服务：

bash
docker-compose up -d

6. 配置参数说明

6.1 环境变量

6.2 端口映射

容器内默认暴露端口为 8080，需通过 -p <主机端口>:8080 映射至主机，以对外提供服务。

6.3 数据持久化（可选）

若需持久化数据，可通过 -v 参数挂载主机目录至容器内路径（如 /app/data）：

bash
docker run -d -p 8080:8080 -v /host/data:/app/data cloudflare/example-app:latest

7. 注意事项

• 确保 Cloudflare 容器运行时环境网络策略允许应用端口（如 8080）的入站流量；
• 本地测试可通过 docker logs <容器名称> 查看应用日志；
• 推送镜像至 Cloudflare 注册表时，API 令牌需包含 edit:images 权限。