Cloudflare CLI 镜像文档

镜像概述

本镜像提供了与Cloudflare服务交互的命令行工具(CLI)，封装了访问Cloudflare API的核心能力，允许用户在容器环境中便捷地管理Cloudflare资源。无需在主机系统直接安装CLI工具，通过容器化方式即可完成Cloudflare相关配置与操作，适用于开发、测试及生产环境的自动化管理场景。

核心功能与特性

• 资源管理：支持管理DNS记录（创建、查询、更新、删除）、CDN配置、SSL/TLS证书、防火墙规则等核心Cloudflare资源。
• API集成：完整对接Cloudflare API，支持通过命令行参数或配置文件调用所有API端点。
• 认证支持：兼容API令牌（推荐）、API密钥+邮箱等多种认证方式，通过环境变量或配置文件注入凭证。
• 跨平台兼容：基于轻量级基础镜像构建，可在Linux、Windows、macOS等支持Docker的系统中运行。
• 自动化友好：支持非交互式命令执行，可集成至CI/CD流水线、定时任务等自动化流程。

使用场景与适用范围

• CI/CD流水线：在自动化部署流程中动态更新DNS记录、切换CDN配置或更新SSL证书。
• 服务器管理：通过容器运行CLI工具，避免主机环境依赖冲突，简化多版本工具并存管理。
• 批量操作：通过脚本批量处理Cloudflare资源（如批量添加DNS记录、批量更新缓存策略）。
• 开发测试：快速验证Cloudflare API调用逻辑，调试资源配置方案。

使用方法与配置说明

前提条件

• 已安装Docker引擎（20.10+推荐）。
• 拥有Cloudflare账号及对应权限的认证凭证（API令牌或API密钥+邮箱）。API令牌可在Cloudflare控制台-我的个人资料-API令牌创建，需包含目标操作的权限（如Zone.DNS、Zone.Settings等）。

基础使用

获取工具帮助信息

docker run --rm cloudflare-cli --help

验证认证与版本信息

# 使用API令牌认证（推荐）
docker run --rm -e CLOUDFLARE_API_TOKEN="your_api_token" cloudflare-cli version

# 使用API密钥+邮箱认证（旧版方式）
docker run --rm -e CLOUDFLARE_EMAIL="your_email" -e CLOUDFLARE_API_KEY="your_api_key" cloudflare-cli version

常用操作示例

管理DNS记录

# 列出指定域名的DNS记录（需替换Zone ID，可通过`list-zones`命令获取）
docker run --rm -e CLOUDFLARE_API_TOKEN="your_api_token" cloudflare-cli dns list --zone-id "your_zone_id"

# 添加DNS A记录
docker run --rm -e CLOUDFLARE_API_TOKEN="your_api_token" cloudflare-cli dns create \
  --zone-id "your_zone_id" \
  --name "subdomain.example.com" \
  --type "A" \
  --content "192.168.1.1" \
  --ttl 300

管理CDN缓存

# 清除指定域名的全部缓存
docker run --rm -e CLOUDFLARE_API_TOKEN="your_api_token" cloudflare-cli cache purge --zone-id "your_zone_id" --purge-everything

高级配置

通过环境变量注入认证凭证

推荐使用API令牌认证，通过CLOUDFLARE_API_TOKEN环境变量传入：

docker run --rm \
  -e CLOUDFLARE_API_TOKEN="your_api_token" \
  cloudflare-cli zone list  # 列出账号下所有域名（Zone）

挂载配置文件

如需持久化配置或使用复杂策略，可将本地配置文件挂载至容器内默认配置路径（通常为/root/.cloudflare/config.yaml）：

docker run --rm \
  -v /path/to/local/config.yaml:/root/.cloudflare/config.yaml \
  cloudflare-cli dns list --zone-id "your_zone_id"

配置文件示例（config.yaml）：

api_token: "your_api_token"
default_zone_id: "your_default_zone_id"  # 可选，设置默认Zone ID简化命令
timeout: 30  # API请求超时时间（秒）

Docker Compose示例

创建docker-compose.yml文件，集成CLI工具至服务栈：

version: "3.8"
services:
  cloudflare-cli:
    image: cloudflare-cli
    environment:
      - CLOUDFLARE_API_TOKEN=your_api_token
      - CLOUDFLARE_DEFAULT_ZONE_ID=your_zone_id  # 可选，设置默认Zone ID
    volumes:
      - ./scripts:/scripts  # 挂载本地脚本目录
    command: /scripts/batch-update-dns.sh  # 执行批量DNS更新脚本

启动服务：

docker-compose up

配置参数说明

环境变量

命令行参数

工具支持通过命令行参数覆盖默认配置，常用参数示例：

注意事项

• API令牌权限需与操作匹配，例如管理DNS需包含Zone.DNS权限，管理SSL需包含Zone.SSL权限。
• 敏感凭证（如API令牌）避免硬编码至命令或配置文件，建议通过环境变量注入或使用Docker Secrets管理。
• 大规模操作（如批量删除资源）建议先通过--dry-run参数（若工具支持）验证操作范围，避免误操作。