彩虹易支付（epay）使用教程

它是什么、适合谁

这个仓库是彩虹易支付的 Docker 部署套件：一条 docker compose 命令就能把 nginx、PHP、MySQL、定时任务四个容器拉起来，构成一个完整的聚合支付站点（收银台 + 商户后台 + 多渠道支付插件）。它不是又一个易支付源码拷贝——易支付本体来自上游镜像 ghcr.io/aliveranme/epay:latest，本仓库负责编排、配置和一组持续维护的补丁（后台界面全屏化、侧栏优化、测试支付页修复、缓存版本控制等）。

适合两类人：想自己架一套聚合支付站的运维，以及需要长期维护生产站点（本仓库的生产实例是 pay.88531.cn）的开发者。补丁采用挂载机制，镜像升级、容器重建都不会把改动冲掉，这是它与「改完镜像就丢」的部署方式最大的区别。

快速开始

前置：机器上装好 Docker 与 compose 插件，先在同目录准备 .env 文件，至少填上数据库与管理员密码（参考下方配置表）。

启动整套服务：

docker compose -f docker-compose.prod.yml up -d

启动后按 NGINX_PORT（默认 80）访问站点，用 ADMIN_PASSWORD 对应的管理员账号进后台。查看各容器状态与日志：

docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f

MySQL 已按中文站需求配置：utf8mb4 字符集、空 sql-mode、时区 +08:00，无需再手动改库配置。

常用操作

改配置：编辑 .env（DB_*、ADMIN_PASSWORD、SITE_URL、CRON_KEY、NGINX_PORT、API_TIMESTAMP_CHECK 等），然后 docker compose -f docker-compose.prod.yml up -d 重建生效。SITE_URL 决定回调与 cron 地址，换域名时必须同步改。
改补丁：所有界面/逻辑定制都在 patches/ 目录。改完对应文件后同步进容器：

bash docker cp patches/epay-ui.css epay-php:/var/www/html/assets/dist/epay-ui.css

再打开 patches/head.php 里的 ?v= 版本号，浏览器与前置反代的缓存就会强制回源，全端立即看到新样式。改完记得提交推送。 3. 确认补丁还在：容器每次启动都会把 patches/ 从 staging 同步进工作目录，所以 docker compose -f docker-compose.prod.yml up -d 重建（含镜像升级）后补丁不会丢，不用手工重铺。 4. 加/改支付插件：插件源码在 plugins/ 目录（alipay、wxpay、unionpay、paypal、stripe、jeepay、bepusdt 等 60+ 个），该目录以挂载形式进入容器，改完重启 php 容器生效。 5. 跑定时任务：cron 容器每 5 分钟请求一次 SITE_URL/cron.php?key=CRON_KEY，结算、对账这类任务靠它驱动；站点访问异常时先查这条链路（docker logs epay-cron）。 6. 接第三方服务时：容器里已把 newapi.88531.cn、ai.88531.cn、pay.88531.cn 映射到宿主机（host-gateway），容器出站访问这几个域名会直接走宿主，无需再改 hosts。

常见问题

升级镜像后我改的界面没了？ 不会。只要改动是落在 patches/ 里并通过 compose 挂载的，entrypoint 启动时会从 staging 自动同步，重建即恢复。若某个文件没出现在挂载清单里，说明它是「改在容器内」的——这种改动才会丢，应补一条挂载。
后台样式改了不生效？ 多半是缓存。nginx 已把 /assets/dist/epay-ui.css|js 设为 no-cache，但浏览器和前置反代还可能记着旧版本：把 patches/head.php 里的 ?v= 改成新版本号即可强制更新。
测试支付页空白？ 历史问题是服务端 paytype 输出成 JSON 对象导致前端 .map 抛错，已由 patches/test.php 用 array_values() 修复；若仍白屏，检查该补丁是否在挂载清单中。
后台通道名、商户名显示乱码？ 历史数据是被按 cp1252 二次编码的，README 给了可重复执行的修复 SQL（CONVERT(CAST(CONVERT(name USING latin1) AS BINARY) USING utf8mb4)，只命中不含中文的行）。先在测试库跑一遍再上生产。
后台右侧留白太多 / 菜单找不到当前项？ 这正是补丁解决的问题：全屏化 + 侧栏加宽到 320px 且当前菜单自动滚动到可视区，升级后若样式回退，确认 epay-ui.css、epay-ui.js 两个挂载仍在。
忘了 .env 里的变量有哪些？ 直接看 docker-compose.prod.yml 的 environment 段，每个变量都有注释与默认值；.env 属敏感文件，不会入库，丢了需要自行重建（数据库卷 mysql_data 不受影响）。

目录速查

docker-compose.prod.yml   生产编排（nginx / php / mysql / cron）
docker/                   nginx.conf、php-custom.ini
patches/                  补丁文件（挂载 staging，启动时同步）
plugins/                  支付插件源码
.env                      环境变量（不入库）