v2.tiantianxinye.365care/支付宝面对面支付密钥配置说明.md

# 支付宝面对面支付密钥配置说明

## 📋 需要的密钥参数

根据代码 `AlipayF2F.class.php`，支付宝面对面支付需要以下 **3个核心参数**：

| 代码中的变量名 | 数据库字段 | 说明 | 是否必需 |
|--------------|-----------|------|---------|
| `merchantPrivateKey` | `private_key` | **应用私钥（商户私钥）** | ✅ 必需 |
| `appId` | `appid` | **应用ID（APPID）** | ✅ 必需 |
| `alipayPublicKey` | `alipay_key` | **支付宝公钥** | ✅ 必需 |
| - | `public_key` | **应用公钥** | ⚠️ 需要上传到支付宝，但代码中不使用 |

## 🔑 各密钥的作用

### 1. **应用ID (APPID)**
- **作用**：标识您的应用，支付宝用来识别是哪个应用发起的请求
- **获取位置**：支付宝开放平台 → 开发者中心 → 应用详情页
- **格式**：通常是数字字符串，如 `2021001234567890`

### 2. **应用私钥 (merchantPrivateKey / private_key)**
- **作用**：用于对请求参数进行签名，确保请求的真实性和完整性
- **生成方式**：使用支付宝密钥生成工具生成
- **格式**：RSA2 私钥，通常以 `-----BEGIN RSA PRIVATE KEY-----` 开头
- **⚠️ 重要**：**绝对不能泄露**，泄露后可能导致资金损失

### 3. **支付宝公钥 (alipayPublicKey / alipay_key)**
- **作用**：用于验证支付宝返回数据的签名，确保数据来源的真实性
- **获取位置**：上传应用公钥后，在支付宝开放平台自动生成
- **格式**：RSA2 公钥，通常以 `-----BEGIN PUBLIC KEY-----` 开头

### 4. **应用公钥 (public_key)**
- **作用**：需要上传到支付宝开放平台，支付宝用此公钥验证您的签名
- **生成方式**：与应用私钥成对生成
- **⚠️ 注意**：代码中不使用此字段，但必须上传到支付宝平台

## 📍 获取步骤

### 第一步：注册并登录支付宝开放平台

1. 访问：**https://open.alipay.com/**
2. 使用支付宝账号登录
3. 完成开发者认证（企业或个人）

### 第二步：申请开通当面付功能

1. 登录后，进入 **"产品中心"**
2. 搜索 **"当面付"** 产品
3. 点击 **"立即接入"** 进行申请
4. 填写相关信息并提交审核
5. 等待审核通过（通常1-3个工作日）

### 第三步：创建应用并获取 APPID

1. 进入 **"开发者中心"** → **"我的应用"**
2. 点击 **"创建应用"**
3. 选择应用类型：**"网页&移动应用"**
4. 填写应用信息：
   - 应用名称
   - 应用图标
   - 应用描述
   - 应用类型等
5. 提交审核
6. 审核通过后，在应用详情页可以看到 **APPID**

### 第四步：生成密钥对

#### 4.1 下载密钥生成工具

- 工具下载地址：**https://opendocs.alipay.com/common/02khjo**
- 或者访问：支付宝开放平台 → 文档中心 → 开发工具 → 密钥生成工具

#### 4.2 生成密钥对

1. 运行密钥生成工具
2. 选择密钥类型：**RSA2（推荐）**
3. 点击 **"生成密钥"**
4. 工具会生成：
   - **应用私钥**（`private_key`）- 保存好，不要泄露
   - **应用公钥**（`public_key`）- 需要上传到支付宝

#### 4.3 保存密钥

- **应用私钥**：复制保存到数据库的 `private_key` 字段
- **应用公钥**：复制保存到数据库的 `public_key` 字段（用于上传）

### 第五步：上传应用公钥并获取支付宝公钥

1. 进入应用详情页 → **"开发设置"** 或 **"接口加签方式"**
2. 找到 **"应用公钥"** 配置项
3. 将生成的 **应用公钥** 粘贴进去
4. 点击 **"保存"**
5. 保存后，支付宝会自动生成 **支付宝公钥**
6. 复制 **支付宝公钥**，保存到数据库的 `alipay_key` 字段

## 📚 官方文档链接

### 主要文档

1. **支付宝开放平台首页**
   - https://open.alipay.com/

2. **当面付产品文档**
   - https://opendocs.alipay.com/open/194/105201

3. **密钥生成工具下载**
   - https://opendocs.alipay.com/common/02khjo

4. **密钥配置指南**
   - https://opendocs.alipay.com/common/02kkv7

5. **EasySDK 使用文档**（您的代码使用的是 EasySDK）
   - https://opendocs.alipay.com/apis/api_1/alipay.trade.pay

6. **API 文档 - 统一收单交易支付接口**
   - https://opendocs.alipay.com/open/194/105201

### 开发指南

- **扫码支付接入指引**：https://developer.alibaba.com/docs/doc.htm?articleId=106078&docType=1&treeId=292
- **密钥管理**：https://opendocs.alipay.com/common/02kkv7

## 💾 数据库配置

在系统中配置时，需要填写以下字段：

```php
// 数据库表：alipay_account
[
    'name' => '支付宝账号名称',           // 便于识别的名称
    'appid' => '2021001234567890',        // 应用ID
    'private_key' => '-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----',           // 应用私钥（完整内容）
    'public_key' => '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----',                // 应用公钥（完整内容，需上传到支付宝）
    'alipay_key' => '-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----',                // 支付宝公钥（完整内容）
]
```

## ⚠️ 重要注意事项

### 安全相关

1. **应用私钥绝对不能泄露**
   - 不要提交到代码仓库
   - 不要通过邮件、聊天工具发送
   - 建议存储在数据库中，并做好数据库安全防护

2. **密钥格式要完整**
   - 必须包含 `-----BEGIN...-----` 和 `-----END...-----` 标记
   - 必须包含所有换行符
   - 不要删除任何空格或换行

3. **密钥长度**
   - RSA2 密钥通常较长（2048位）
   - 确保数据库字段长度足够（代码中设置为 2048 字符）

### 配置相关

1. **签名方式**
   - 代码中使用的是 **RSA2** 签名方式
   - 确保支付宝平台也配置为 RSA2

2. **环境区分**
   - 沙箱环境（测试）：使用沙箱的 APPID 和密钥
   - 正式环境（生产）：使用正式环境的 APPID 和密钥

3. **应用公钥上传**
   - 必须上传应用公钥到支付宝平台
   - 上传后支付宝才会生成对应的支付宝公钥
   - 如果更换了密钥对，需要重新上传

## 🔍 代码中的使用位置

```php
// app/Libs/AlipayF2F.class.php

public function getOptions(AlipayAccount $alipayAccount)
{
    $options = new Config();
    $options->protocol = 'https';
    $options->gatewayHost = 'openapi.alipay.com';
    $options->signType = 'RSA2';  // 使用 RSA2 签名
    
    // 从数据库读取配置
    $options->merchantPrivateKey = $alipayAccount->private_key;  // 应用私钥
    $options->appId = $alipayAccount->appid;                     // 应用ID
    $options->alipayPublicKey = $alipayAccount->alipay_key;      // 支付宝公钥
    
    return $options;
}
```

## 🛠️ 常见问题

### Q1: 密钥生成工具在哪里下载？
A: https://opendocs.alipay.com/common/02khjo

### Q2: 应用公钥和支付宝公钥有什么区别？
A: 
- **应用公钥**：您自己生成的，需要上传到支付宝
- **支付宝公钥**：支付宝根据您的应用公钥生成的，用于验证支付宝返回的数据

### Q3: 私钥泄露了怎么办？
A: 立即重新生成密钥对，并更新支付宝平台配置，同时更换数据库中的私钥

### Q4: 测试环境和正式环境的密钥可以共用吗？
A: 不可以，测试环境（沙箱）和正式环境需要使用不同的 APPID 和密钥

### Q5: 密钥格式要求是什么？
A: 必须包含完整的 PEM 格式，包括 BEGIN 和 END 标记，以及所有换行符

## 📞 技术支持

- **支付宝开放平台客服**：https://open.alipay.com/
- **开发者社区**：https://openclub.alipay.com/
- **工单系统**：在开放平台提交工单