localstripe 镜像文档

镜像概述

localstripe 是一个本地运行的模拟 Stripe 服务器工具，旨在为开发和测试提供无需依赖真实 Stripe 服务的 API 模拟环境。该工具通过模拟 Stripe API 端点并维护状态数据（如客户、支付意向、订阅等），支持本地测试支付流程，避免使用真实支付信息或产生实际交易费用。

核心功能与特性

• Stripe API 模拟：支持 Stripe API 核心端点，包括客户管理、支付意向、订阅、产品等常见操作
• 状态持久化：本地存储所有创建的资源数据（客户、支付记录等），支持容器重启后状态恢复
• 离线运行：无需网络连接，完全在本地环境运行，适合无网络或受限网络环境开发
• 轻量级部署：基于 Docker 容器化，资源占用低，启动快速
• 客户端兼容性：兼容官方 Stripe SDK，可直接通过修改 API 基础地址接入现有应用

使用场景与适用范围

• 开发环境支付流程测试：验证电商平台、订阅服务等应用与 Stripe API 的交互逻辑
• 自动化测试集成：在 CI/CD 流水线中模拟支付流程，确保功能稳定性
• 安全测试：避免使用真实支付卡信息，防止测试环境误触发真实交易
• 离线开发：无网络环境下仍可进行支付功能开发与调试
• 教学演示：展示支付流程实现逻辑，无需配置真实 Stripe 账户

使用方法

Docker 快速启动

通过以下命令直接启动 localstripe 容器：

docker run -d \
  -p 8080:8080 \
  -v ./localstripe-data:/data \
  --name localstripe \
  adrienverge/localstripe

• -p 8080:8080：将容器 8080 端口映射到本地 8080 端口
• -v ./localstripe-data:/data：挂载本地目录持久化状态数据
• --name localstripe：指定容器名称便于管理

Docker Compose 配置

创建 docker-compose.yml 文件实现更灵活的部署：

version: '3.8'
services:
  localstripe:
    image: adrienverge/localstripe
    ports:
      - "8080:8080"  # API 端口映射
    volumes:
      - localstripe_data:/data  # 持久化数据卷
    environment:
      - PORT=8080  # 服务监听端口
      - API_KEY=sk_test_custom_key  # 自定义模拟 API 密钥
      - LOG_LEVEL=debug  # 调试日志级别
    restart: unless-stopped  # 异常退出后自动重启

volumes:
  localstripe_data:  # 命名卷用于数据持久化

启动服务：

docker-compose up -d

应用接入配置

修改应用中的 Stripe 客户端配置，将 API 端点指向本地服务器。以常见开发语言为例：

Python 示例

import stripe
stripe.api_key = "sk_test_custom_key"  # 与容器环境变量 API_KEY 一致
stripe.api_base = "http://localhost:8080"  # 本地服务器地址

# 测试创建客户
customer = stripe.Customer.create(name="测试用户")
print(f"创建客户成功，ID: {customer.id}")

Node.js 示例

const stripe = require('stripe')('sk_test_custom_key');
stripe.setApiVersion('2023-10-16');
stripe.defaults.baseURL = 'http://localhost:8080';

// 测试创建支付意向
stripe.paymentIntents.create({
  amount: 2000,
  currency: 'usd',
  customer: 'cus_test_123'
}).then(paymentIntent => {
  console.log(`支付意向创建成功，ID: ${paymentIntent.id}`);
});

配置参数

环境变量

数据持久化

通过挂载本地目录或 Docker 卷（如示例中的 localstripe_data）持久化状态数据，避免容器重启后客户、支付意向等资源信息丢失。

支持的 API 端点

覆盖 Stripe API 核心业务场景，主要包括：

• 客户管理：/v1/customers（创建、查询、更新、删除客户）
• 支付处理：/v1/payment_intents（支付意向全生命周期）、/v1/charges（收费记录）
• 订阅服务：/v1/subscriptions（订阅创建与管理）、/v1/plans（定价计划）
• 产品管理：/v1/products（产品定义）、/v1/prices（价格设置）

完整支持的端点列表可参考 项目 GitHub 文档。