准备工作清单
先确认本机环境，提前安装以下2个工具，所有步骤通用Windows/MacOS/Linux。
- Docker Desktop：下载地址 https://www.docker.com/products/docker-desktop/，安装后全程保持运行
- Stripe账号：注册地址 https://dashboard.stripe.com/register，无需企业资质，个人可快速注册测试环境
第一步：搭建本地轻量档案管理Strapi系统
Strapi是开源Headless CMS，可直接生成档案管理的后端接口和后台。
1.1 创建Strapi项目目录
打开终端（Windows用PowerShell/CMD，Mac/Linux用Terminal），执行以下2条命令：
```bash
mkdir strapi-archive-pay && cd strapi-archive-pay
```
1.2 快速启动Strapi容器
直接使用官方Docker镜像，无需手动配置Node.js，终端执行完整命令：
```bash
docker run -d \
-p 1337:1337 \
-e STRAPI_ADMIN_JWT_SECRET=your-random-admin-secret-key-here-change-later \
-e STRAPI_API_TOKEN_SALT=your-random-api-token-salt-here-change-later \
-v $(pwd):/srv/app \
strapi/strapi:4.25.3
```
注意：
- 命令里的2个随机密钥，后续生产环境必须替换为强密码（可用 https://www.random.org/strings/ 生成32位字符）
- Windows PowerShell需把`$(pwd)`换成`${PWD}`
1.3 配置Strapi基础档案管理
等待30-60秒，浏览器访问 http://localhost:1337/admin 首次注册后台管理员账号（随便填，仅本地测试）。
1.3.1 创建档案内容类型
登录后：
1. 点击左侧菜单
Content-Type Builder
2. 点击右上角
Create new collection type
3. 显示名称输入
Archive，点击继续
4. 添加以下字段（按顺序）：
- 文本字段：显示名 title，勾选 Required field，点击完成
- 富文本字段：显示名 content，勾选 Required field，点击完成
- 媒体字段：显示名 attachments，类型选 Multiple media，点击完成
- 布尔字段：显示名 is_paid，默认值设为 True，勾选 Required field，点击完成
- 数字字段：显示名 price_cents，格式选 Integer，默认值设为 100（即1美元），勾选 Required field，点击完成
5. 点击右上角
Save，等待系统重启（20秒左右）
1.3.2 插入测试档案数据
1. 左侧菜单点击
Content Manager →
Archive
2. 点击
Create new entry
3. 填写title：《2024技术面试核心档案》，content：随便写一段付费内容，attachments上传1个测试文件，is_paid默认True，price_cents默认100
4. 点击
Save，再点击
Publish
5. 再创建1条免费测试数据：is_paid设为False，其他随便填
1.3.3 配置公开API权限
1. 左侧菜单点击
Settings →
Users & Permissions Plugin →
Roles
2. 点击
Public 角色
3. 找到
Archive，勾选
find 和
findOne 权限
4. 点击右上角
Save
第二步：对接Stripe按需付费接口
2.1 获取Stripe测试密钥
1. 登录Stripe Dashboard，右上角切换到
Test mode（开关必须打开，紫色状态）
2. 左侧菜单点击
Developers →
API keys
3. 复制
Publishable key（格式pk_test_xxx）和
Secret key（格式sk_test_xxx）备用
2.2 配置Stripe Webhook接收
Webhook用于Stripe告知Strapi支付成功：
1. 左侧菜单点击
Developers →
Webhooks
2. 点击
Add endpoint
3. 先安装本地Webhook测试工具Stripe CLI：
- Windows：打开PowerShell执行 `winget install Stripe.StripeCLI`
- MacOS：执行 `brew install stripe/stripe-cli/stripe`
- Linux：参考 https://stripe.com/docs/stripe-cliinstall
4. 终端执行Stripe CLI登录（输入后跳转到浏览器授权）：
```bash
stripe login
```
5. 终端执行监听本地1337端口的Webhook：
```bash
stripe listen --forward-to localhost:1337/api/webhooks/stripe
```
6. 回到Stripe Dashboard的Add endpoint页面，Endpoint URL暂时留空，Events to send选择
Select all events（测试用），点击
Add endpoint，复制生成的
Signing secret（格式whsec_xxx）备用
2.3 Strapi添加Stripe插件和Webhook接口
2.3.1 进入Strapi容器终端
新打开一个终端窗口，执行：
```bash
docker exec -it strapi-archive-pay_strapi_1 /bin/bash
```
注意：如果容器名称不对，执行`docker ps`找到正确的NAME列替换
2.3.2 安装Stripe SDK
容器终端执行：
```bash
npm install stripe --save
```
2.3.3 创建Webhook接口和支付服务
容器终端执行以下命令创建目录和文件：
```bash
mkdir -p src/api/webhook/controllers src/api/webhook/services
```
1. 创建Webhook控制器：`src/api/webhook/controllers/webhook.js`
```javascript
'use strict';
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const crypto = require('crypto');
module.exports = {
async stripe(ctx) {
const sig = ctx.request.headers['stripe-signature'];
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;
let event;
try {
event = stripe.webhooks.constructEvent(
ctx.request.body,
sig,
endpointSecret
);
} catch (err) {
ctx.badRequest(`Webhook Error: ${err.message}`);
return;
}
// 处理支付成功事件
if (event.type === 'checkout.session.completed') {
const session = event.data.object;
const archiveId = session.metadata.archive_id;
// 这里后续可以记录用户购买记录，因为是演示本地公开权限，暂时跳过
strapi.log.info(`支付成功！档案ID：${archiveId}`);
}
ctx.send({ received: true });
},
};
```
2. 创建支付服务：`src/api/webhook/services/webhook.js`
```javascript
'use strict';
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
module.exports = {
async createCheckoutSession(archiveId, priceCents) {
const archive = await strapi.entityService.findOne('api::archive.archive', archiveId);
if (!archive) throw new Error('档案不存在');
const session = await stripe.checkout.sessions.create({
payment_method_types: ['card'],
line_items: [{
price_data: {
currency: 'usd',
product_data: {
name: archive.title,
},
unit_amount: priceCents,
},
quantity: 1,
}],
mode: 'payment',
success_url: 'http://localhost:3000/success?session_id={CHECKOUT_SESSION_ID}',
cancel_url: 'http://localhost:3000/cancel',
metadata: {
archive_id: archiveId,
},
});
return session.url;
},
};
```
3. 创建Webhook路由：`src/api/webhook/routes/webhook.js`
```javascript
'use strict';
module.exports = {
routes: [
{
method: 'POST',
path: '/webhooks/stripe',
handler: 'webhook.stripe',
config: {
policies: [],
middlewares: [
// 禁用bodyParser的json解析，Stripe需要原始body
{
name: 'body-parser',
config: {
json: false,
},
},
],
},
},
],
};
```
2.3.4 配置Strapi环境变量和支付API权限
1. 退出容器终端：`exit`
2. 编辑本地项目目录的`.env`文件（如果没有就新建）：
```env
HOST=0.0.0.0
PORT=1337
APP_KEYS=your-app-keys-from-original-env-file-if-any
API_TOKEN_SALT=your-random-api-token-salt-here-change-later
ADMIN_JWT_SECRET=your-random-admin-secret-key-here-change-later
JWT_SECRET=your-random-jwt-secret-key-here-change-later
新增Stripe配置
STRIPE_PUBLISHABLE_KEY=pk_test_你的测试公钥
STRIPE_SECRET_KEY=sk_test_你的测试私钥
STRIPE_WEBHOOK_SECRET=whsec_你的测试签名密钥
```
注意：把`STRIPE_PUBLISHABLE_KEY`等3个替换成第二步获取的真实值；APP_KEYS如果原来的`.env`有就保留，没有可以随便填4个用逗号分隔的32位字符
3. 重启Strapi容器：
```bash
docker restart strapi-archive-pay_strapi_1
```
4. 登录Strapi后台，
Settings →
Users & Permissions Plugin →
Roles →
Public
5. 找到
Webhook，如果没有就刷新页面，然后勾选
createCheckoutSession（需要先手动在Content-Type Builder里给webhook添加自定义API？不对刚才的服务是自定义的，要手动创建路由和控制器对应的权限？哦刚才漏了，重新登录Strapi后台，在Content-Type Builder里点击右侧
Customize the API？不对刚才的webhook是纯后端API，直接去Roles页面手动添加权限配置？或者换个方式，直接允许Public访问自定义路由：在路由文件`src/api/webhook/routes/webhook.js`里添加一个支付创建的路由，然后权限设为Public
新增支付创建路由：
```javascript
{
method: 'POST',
path: '/webhooks/stripe/checkout',
handler: 'webhook.createCheckoutSession',
config: {
policies: [],
auth: false,
},
},
```
6. 然后修改Webhook控制器，添加createCheckoutSession方法：
```javascript
module.exports = {
async createCheckoutSession(ctx) {
const { archiveId, priceCents } = ctx.request.body;
try {
const checkoutUrl = await strapi.service('api::webhook.webhook').createCheckoutSession(archiveId, priceCents);
ctx.send({ checkoutUrl });
} catch (err) {
ctx.badRequest(err.message);
}
},
// 原来的stripe方法保留
};
```
7. 再次重启Strapi容器
第三步：编写极简前端测试页面
本地创建一个`index.html`文件，放在任意目录，完整代码：
```html
轻量档案管理系统测试
轻量档案管理系统
```
3.1 启动前端测试
用浏览器直接打开刚才创建的`index.html`，或者用VS Code的Live Server插件启动（推荐，避免跨域问题）。
3.2 测试免费档案和付费流程
1. 免费档案直接显示内容
2. 付费档案点击“立即购买”跳转到Stripe测试页面，使用以下测试信用卡信息：
- 卡号：4242 4242 4242 4242
- 有效期：12/34
- CVC：123
- 其他随便填
3. 支付成功后跳转到success页面（演示用，可自行修改），Strapi容器终端会打印支付成功日志
