Stripe CLI Docker镜像文档

镜像概述和主要用途

本镜像为容器化的Stripe CLI工具，基于Alpine Linux构建，旨在提供轻量级、易部署的Stripe命令行环境。Stripe CLI是Stripe官方提供的命令行工具，用于与Stripe API交互、管理Stripe资源（如支付链接、事件、账户配置等），支持本地开发调试、自动化脚本执行及CI/CD流程集成。

核心功能和特性

• Stripe API交互：直接通过命令行调用Stripe API，支持创建/查询支付意向、客户、产品等资源。
• 事件监听：实时监听Stripe Webhook事件，便于本地开发调试Webhook处理逻辑。
• 支付链接管理：快速创建、查询和管理Stripe Payment Link。
• 账户配置：支持登录Stripe账户、切换团队/项目、管理API密钥等。
• 轻量级基础：基于Alpine Linux，镜像体积小（通常<20MB），启动速度快，资源占用低。

使用场景和适用范围

• 本地开发调试：开发者在本地环境中调试Stripe集成逻辑，无需直接在宿主机安装Stripe CLI。
• CI/CD流程集成：在自动化部署流程中嵌入Stripe操作（如创建测试支付意向、验证Webhook配置）。
• 自动化脚本：通过Docker容器执行批量Stripe资源管理脚本（如批量更新产品价格、导出交易记录）。
• 多环境隔离：通过容器化实现不同项目/环境的Stripe CLI配置隔离（如开发/测试/生产环境的API密钥分离）。

使用方法和配置说明

环境变量

持久化配置

Stripe CLI的配置文件（包含登录状态、API密钥等）默认存储在~/.config/stripe目录。为避免容器重启后配置丢失，可通过挂载宿主机目录持久化配置：

-v /本地路径/.config/stripe:/root/.config/stripe

基本命令示例

容器内可直接执行Stripe CLI原生命令，语法与非容器化环境一致。常用命令包括：

• stripe login：登录Stripe账户（需手动在浏览器完成验证）
• stripe listen：监听Stripe事件并转发至本地Webhook端点
• stripe payment-links create：创建支付链接
• stripe api <resource> <action>：直接调用Stripe API（如stripe api customers list）

Docker部署方案示例

docker run 命令示例

1. 登录Stripe账户（首次使用）

docker run --rm -it \
  -v $HOME/.config/stripe:/root/.config/stripe \
  stripe/stripe-cli:latest login

说明：

• --rm：容器退出后自动删除
• -it：交互式终端，用于输入登录验证信息
• -v：挂载宿主机配置目录，持久化登录状态

2. 监听Stripe事件并转发至本地Webhook

docker run --rm -it \
  -e STRIPE_API_KEY=sk_test_xxx \  # 可选：直接传入API密钥（优先级高于配置文件）
  -v $HOME/.config/stripe:/root/.config/stripe \
  stripe/stripe-cli:latest listen --forward-to [***]

说明：

• --forward-to：指定本地Webhook端点（host.docker.internal为Docker Desktop的宿主机地址，Linux需替换为宿主机IP）
• 若未传入STRIPE_API_KEY，则使用配置文件中的密钥

3. 执行基本Stripe命令（如创建支付链接）

docker run --rm \
  -e STRIPE_API_KEY=sk_test_xxx \
  stripe/stripe-cli:latest payment-links create \
    --amount 2000 \          # 金额（单位：分，此处为20美元）
    --currency usd \         # 货币类型
    --description "Test Product"  # 描述

docker-compose 配置示例

适用于需要长期运行或集成到多容器环境的场景（如本地开发环境）：

version: '3.8'
services:
  stripe-cli:
    image: stripe/stripe-cli:latest
    environment:
      - STRIPE_API_KEY=sk_test_xxx  # 可选：API密钥（优先级低于配置文件）
    volumes:
      - $HOME/.config/stripe:/root/.config/stripe  # 持久化配置
    tty: true  # 保持终端交互能力（用于登录、监听等命令）

使用方式：

# 启动服务并登录
docker-compose run --rm stripe-cli login

# 监听事件
docker-compose run --rm stripe-cli listen --forward-to [***]

注意事项

1. API密钥安全：避免在镜像或配置文件中硬编码生产环境API密钥，优先通过环境变量或宿主机配置文件传入。
2. 配置持久化：首次登录后需挂载配置目录，否则容器重启后需重新登录。
3. 宿主机网络访问：容器内访问宿主机服务时，需使用宿主机IP（如172.17.0.1，Linux）或host.docker.internal（Docker Desktop）。
4. 更多命令及参数详见 Stripe CLI官方文档。