5.6.1 安装指南

# 安装指南

本文档详细说明如何安装和配置一码付 C SDK。

---

## 系统要求

### 操作系统

- Linux（Ubuntu 18.04+、CentOS 7+、Debian 9+）
- macOS（10.14+）
- Windows（通过 MinGW 或 MSVC）

### 编译器

- GCC 4.8+ 或 Clang 3.5+（支持 C99 标准）
- 或 MSVC 2015+（Windows）

### 构建工具

- Make 或 CMake 3.10+
- pkg-config（用于查找依赖库）

---

## 依赖库安装

SDK 依赖以下第三方库：

1. **OpenSSL** (>= 1.1.0) - RSA 签名验签、SHA1 哈希
2. **libcurl** (>= 7.50.0) - HTTP 请求
3. **cJSON** (>= 1.7.0) - JSON 解析

### Ubuntu/Debian

```bash
# 更新包列表
sudo apt-get update

# 安装依赖库
sudo apt-get install -y \
    libssl-dev \
    libcurl4-openssl-dev \
    libcjson-dev \
    build-essential \
    pkg-config
```

### CentOS/RHEL

```bash
# 安装 EPEL 仓库（如果尚未安装）
sudo yum install -y epel-release

# 安装依赖库
sudo yum install -y \
    openssl-devel \
    libcurl-devel \
    gcc \
    make \
    pkg-config

# cJSON 需要从源码编译安装
git clone https://github.com/DaveGamble/cJSON.git
cd cJSON
mkdir build && cd build
cmake ..
make
sudo make install
sudo ldconfig
```

### macOS

使用 Homebrew 安装：

```bash
# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖库
brew install openssl curl cjson pkg-config
```

### Windows (MinGW)

1. 安装 [MSYS2](https://www.msys2.org/)

2. 在 MSYS2 终端中安装依赖：

```bash
# 更新包数据库
pacman -Syu

# 安装依赖库
pacman -S mingw-w64-x86_64-gcc \
          mingw-w64-x86_64-openssl \
          mingw-w64-x86_64-curl \
          mingw-w64-x86_64-cjson \
          mingw-w64-x86_64-pkg-config \
          make
```

---

## SDK 编译

### 方式 1：使用 Makefile

```bash
# 克隆或下载 SDK 源码
cd allinpay-shopoint-sdk-c

# 编译 SDK
make

# 编译成功后会生成以下文件：
# - libocpay.so (动态库)
# - libocpay.a (静态库)
# - examples/basic_usage (示例程序)
# - examples/query_transaction (示例程序)
```

### 方式 2：使用 CMake

```bash
# 克隆或下载 SDK 源码
cd allinpay-shopoint-sdk-c

# 创建构建目录
mkdir build && cd build

# 配置项目
cmake ..

# 编译
make

# 编译成功后会在 build 目录生成库文件和示例程序
```

### 编译选项

**Makefile 编译选项：**

```bash
# 调试模式编译
make DEBUG=1

# 指定编译器
make CC=clang

# 清理编译产物
make clean
```

**CMake 编译选项：**

```bash
# 调试模式编译
cmake -DCMAKE_BUILD_TYPE=Debug ..

# 指定安装路径
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..

# 指定编译器
cmake -DCMAKE_C_COMPILER=clang ..
```

---

## SDK 安装

### 系统级安装

将 SDK 安装到系统目录（需要 root 权限）：

```bash
# 使用 Makefile
sudo make install

# 或使用 CMake
cd build
sudo make install
```

默认安装路径：
- 库文件：`/usr/local/lib/libocpay.so` 和 `/usr/local/lib/libocpay.a`
- 头文件：`/usr/local/include/ocpay/*.h`

### 自定义安装路径

```bash
# 使用 Makefile
sudo make install DESTDIR=/opt/ocpay

# 使用 CMake
cmake -DCMAKE_INSTALL_PREFIX=/opt/ocpay ..
sudo make install
```

### 更新动态库缓存

安装后需要更新动态库缓存：

```bash
# Linux
sudo ldconfig

# macOS
sudo update_dyld_shared_cache
```

### 用户级安装（无需 root 权限）

如果没有 root 权限，可以安装到用户目录：

```bash
# 安装到用户目录
make install DESTDIR=$HOME/.local

# 添加到环境变量
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
export C_INCLUDE_PATH=$HOME/.local/include:$C_INCLUDE_PATH
```

---

## 配置 SDK

### 方式 1：使用配置文件

创建配置文件 `config.json`：

```json
{
  "app_id": "your_app_id",
  "sign_type": "RSA",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----",
  "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----",
  "debug_enabled": 1
}
```

**字段说明：**

- `app_id`：应用 ID（必填）
- `sign_type`：签名类型，支持 "RSA"、"SM2"、"MD5"（必填）
- `private_key`：RSA 私钥，PEM 格式（必填）
- `public_key`：RSA 公钥，PEM 格式（必填）
- `debug_enabled`：调试模式，1=开启，0=关闭（可选，默认 0）

**注意事项：**

1. 私钥和公钥必须是 PEM 格式
2. JSON 中的换行符需要使用 `\n` 转义
3. 不要将配置文件提交到版本控制系统
4. 建议将配置文件权限设置为 600：`chmod 600 config.json`

### 方式 2：使用环境变量

```bash
# 设置环境变量
export OCPAY_APP_ID="your_app_id"
export OCPAY_SIGN_TYPE="RSA"
export OCPAY_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"
export OCPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----"
export OCPAY_DEBUG=1
```

**或者从文件读取：**

```bash
# 将密钥保存到文件
cat > private_key.pem << 'EOF'
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----
EOF

cat > public_key.pem << 'EOF'
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----
EOF

# 设置文件权限
chmod 600 private_key.pem public_key.pem

# 设置环境变量指向文件
export OCPAY_APP_ID="your_app_id"
export OCPAY_SIGN_TYPE="RSA"
export OCPAY_PRIVATE_KEY="$(cat private_key.pem)"
export OCPAY_PUBLIC_KEY="$(cat public_key.pem)"
export OCPAY_DEBUG=1
```

---

## 验证安装

### 编译测试程序

创建测试文件 `test.c`：

```c
#include <stdio.h>
#include "ocpay_sdk.h"

int main() {
    printf("一码付 SDK 版本测试\n");
    
    // 创建配置对象
    ocpay_config_t *config = ocpay_config_create();
    if (!config) {
        fprintf(stderr, "创建配置对象失败\n");
        return -1;
    }
    
    printf("✓ SDK 安装成功\n");
    
    ocpay_config_free(config);
    return 0;
}
```

编译并运行：

```bash
# 编译
gcc -o test test.c -locpay -lssl -lcrypto -lcurl -lcjson

# 运行
./test
```

如果输出 "✓ SDK 安装成功"，说明安装成功。

### 运行示例程序

```bash
# 进入示例目录
cd examples

# 创建配置文件（使用模板）
cp config.template.json config.json
# 编辑 config.json，填入真实的配置信息
vim config.json

# 运行基本使用示例
./basic_usage

# 运行交易查询示例
./query_transaction PN20240101120000abcdef
```

---

## 故障排除

### 问题 1：找不到头文件

**错误信息：**
```
fatal error: ocpay_sdk.h: No such file or directory
```

**解决方法：**

```bash
# 方法 1：指定头文件路径
gcc -I/usr/local/include/ocpay -o test test.c -locpay

# 方法 2：添加到环境变量
export C_INCLUDE_PATH=/usr/local/include/ocpay:$C_INCLUDE_PATH
```

### 问题 2：找不到库文件

**错误信息：**
```
/usr/bin/ld: cannot find -locpay
```

**解决方法：**

```bash
# 方法 1：指定库文件路径
gcc -o test test.c -L/usr/local/lib -locpay

# 方法 2：添加到环境变量
export LIBRARY_PATH=/usr/local/lib:$LIBRARY_PATH
```

### 问题 3：运行时找不到动态库

**错误信息：**
```
error while loading shared libraries: libocpay.so: cannot open shared object file
```

**解决方法：**

```bash
# 方法 1：更新动态库缓存
sudo ldconfig

# 方法 2：添加到 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

# 方法 3：使用静态库
gcc -o test test.c /usr/local/lib/libocpay.a -lssl -lcrypto -lcurl -lcjson
```

### 问题 4：OpenSSL 版本不兼容

**错误信息：**
```
undefined reference to `EVP_MD_CTX_new'
```

**解决方法：**

这通常是因为 OpenSSL 版本过低（< 1.1.0）。请升级 OpenSSL：

```bash
# Ubuntu/Debian
sudo apt-get install libssl-dev

# CentOS/RHEL
sudo yum install openssl11-devel

# macOS
brew upgrade openssl
```

### 问题 5：cJSON 库未找到

**错误信息：**
```
Package libcjson was not found in the pkg-config search path
```

**解决方法：**

从源码编译安装 cJSON：

```bash
git clone https://github.com/DaveGamble/cJSON.git
cd cJSON
mkdir build && cd build
cmake ..
make
sudo make install
sudo ldconfig
```

### 问题 6：编译警告

**警告信息：**
```
warning: implicit declaration of function 'xxx'
```

**解决方法：**

确保包含了正确的头文件：

```c
#include "ocpay_sdk.h"
#include "ocpay_config.h"
#include "ocpay_response.h"
#include "ocpay_errors.h"
```

---

## 卸载 SDK

### 卸载系统级安装

```bash
# 删除库文件
sudo rm -f /usr/local/lib/libocpay.so
sudo rm -f /usr/local/lib/libocpay.a

# 删除头文件
sudo rm -rf /usr/local/include/ocpay

# 更新动态库缓存
sudo ldconfig
```

### 卸载用户级安装

```bash
# 删除用户目录中的文件
rm -rf $HOME/.local/lib/libocpay.*
rm -rf $HOME/.local/include/ocpay
```

---

## 下一步

- 阅读 [API 文档](API.md) 了解详细的接口说明
- 查看 [使用示例](EXAMPLES.md) 学习常见使用场景
- 查看 `examples/` 目录中的示例代码

---

## 获取帮助

如果遇到安装问题，请：

1. 检查系统是否满足要求
2. 确认所有依赖库已正确安装
3. 查看本文档的故障排除部分
4. 联系技术支持或提交 Issue