易支付系统 · 安装文档 - 开发文档

易支付系统 · 安装文档

云枢支付聚合支付系统 · 安装文档

当前版本：V1.0.1　|　基于 ThinkPHP 8.1（PHP 8.0+ / MySQL 5.7+ / MariaDB 10.3+）

一、环境要求

1. 运行环境

项目	要求	说明
PHP	≥ 8.0（推荐 8.1）	8.0 及以上均可，建议 8.1/8.2
数据库	MySQL 5.7+ / MariaDB 10.3+	安装向导内置建库脚本，自动创建数据表
Web 服务器	Nginx / Apache / IIS	站点根目录指向 `public/` 即可
PHP 扩展	pdo_mysql、curl、openssl、mbstring、gd、fileinfo	缺一不可，安装向导会逐项检测
目录权限	`runtime/`、`.env` 可写	日志、缓存、会话写入需要

2. PHP 扩展开启方式（宝塔面板示例）

软件商店 → PHP-8.1 → 设置 → 安装扩展
勾选：pdo_mysql、curl、openssl、mbstring、gd、fileinfo（一般默认已开启）
同时确认「禁用函数」中没有禁用：proc_open、putenv、pcntl_*

3. 推荐生产配置

PHP memory_limit ≥ 128M，max_execution_time ≥ 120
Nginx 站点伪静态规则（ThinkPHP）：

location / {
    if (!-e $request_filename) {
        rewrite ^(.*)$ /index.php?s=$1 last;
        break;
    }
}

二、安装步骤

方式一：安装向导（推荐）

将程序包完整上传到服务器网站目录（如 /www/wwwroot/epay），并解压；
访问 http://你的域名/install 进入安装向导；
环境检测：向导自动检测 PHP 版本、扩展、目录权限，全部通过后进入下一步；
填写数据库信息（主机、端口、用户名、密码、数据库名），点击「测试连接」→「开始安装」；
设置管理员账号密码，点击「完成安装」；
安装完成后 务必删除或重命名 install 目录，防止被重复安装。

方式二：命令行安装（开发者）

cd /www/wwwroot/epay
php think upgrade        # 幂等升级：自动建表/补列/初始化配置

三、安装后必做事项

1. 配置站点地址

后台 → 系统管理 → 系统设置 → 基础设置：

配置项	说明
站点名称	平台显示名称
站点地址（site_url）	必填，用于生成回调地址、支付链接、收款码；正式环境填 `https://` 正式域名

2. 配置计划任务（定时任务）

系统依赖定时任务完成：订单关闭、退款查询、自动结算、账单同步、投诉同步、码支付监控等。将以下命令加入服务器 crontab（或宝塔计划任务），每 1 分钟执行一次：

php /www/wwwroot/epay/think cron

Windows 服务器可运行程序包内的 run_epay_tasks.bat（任务计划程序里每分钟触发）。

内置任务清单（由 cron 守护进程按计划自动调度）：

任务	说明	建议频率
order:close	超时订单自动关闭	10 分钟
refund:query	异步退款结果轮询	5 分钟
poll:query	通道主动查单补单/关单	后台可配
settle:run	自动结算（T+N）	每日 01:30
report:daily	日报统计	每日 01:30
wxpay:cert	微信证书自动同步	每日 02:30
complain:sync	微信/支付宝投诉同步	5 分钟
codepay:monitor	码支付支付宝账单监控	1-2 分钟（挂机端）
codepay:settle	码支付微信账单对账	每日 10 点后

3. 配置支付通道

后台 → 支付接口 → 支付通道 → 新增通道：选择支付插件（支付宝/微信/QQ…）、填写通道参数、设置费率与单笔限额。

4. 安全加固

修改后台入口路径（后台 → 系统设置 → 安全设置）；
删除 install 目录；
public/ 目录建议只开放运行所需文件；
数据库账号避免使用 root，使用最小权限账号。

四、升级方法

备份：备份数据库与 public/uploads/、.env、extend/plugins/ 目录；
覆盖上传新版程序文件（不要覆盖 .env 与 extend/plugins/ 下自定义插件）；
执行升级命令（幂等，可重复执行）：

php think upgrade

刷新后台，系统管理 → 系统更新页可检查云端最新版本。

五、常见问题

问题	排查方法
500 错误	查看 `runtime/log/` 下当天日志；确认 `.env` 的 `APP_DEBUG` 是否可临时打开定位
安装向导环境检测不通过	按提示安装缺失扩展；宝塔需在对应 PHP 版本的「安装扩展」里操作
支付回调收不到	检查 `site_url` 是否为公网可达域名；检查通道回调地址是否配置正确（回调路径 `pay/notify/{通道类型}/{订单号}`）
页面 404	Nginx 伪静态未配置；或站点根目录未指向 `public/`
无法连接数据库	检查数据库地址/端口/账号权限；宝塔注意「本地服务器」地址为 `127.0.0.1`
验证码不显示	检查 GD 扩展；PHP `session` 目录可写

六、目录结构速览

epay/
├── app/                    # 应用代码（api/后台接口、index/前台、admin/merchant 旧版页面）
├── config/                 # 框架配置（console.php 注册定时命令）
├── extend/plugins/         # 通道插件（热插拔，上传即用）
├── public/                 # Web 根目录
│   ├── index.php           # 入口文件
│   ├── submit.php          # 易支付协议下单端点（PC）
│   ├── mapi.php            # 易支付协议下单端点（移动端/JSON）
│   ├── api.php             # 易支付协议查询/退款端点
│   └── static/             # 静态资源（admin-spa 后台 / merchant-spa 商户中心 / cashier-spa 收银台）
├── install/                # 安装向导（epay.sql 建库脚本）
├── runtime/                # 日志/缓存/会话（需可写）
├── docs/                   # 本文档目录
└── .env                    # 环境配置（APP_SECRET 等）

← 返回文档列表