异次元店铺系统
异次元
异次元店铺系统（ACG-Faka）完整文档
文档版本：V1.0 适用系统：异次元店铺系统 / 荔枝发卡 V3.0 / ACG-Faka 官方文档站：https://faka.wiki 官方体验站：https://demo.faka.wiki 项目仓库：https://github.com/lizhipay/acg-faka
1. 系统介绍
1.1 什么是异次元店铺系统
异次元店铺系统（英文名 ACG-Faka，又称异次元发卡系统）是一款基于 PHP 8 开发的开源虚拟商品自动发卡平台。它由早期的“荔枝发卡系统 3.0”完全从零代码重构而来，采用二次元（ACG）风格界面设计，主要用于销售游戏点卡、软件激活码、会员账号、数字内容兑换券等虚拟商品。
系统的核心设计目标是全链路交易自动化：用户下单支付成功后，系统自动从预设卡池中分配对应商品，通过站内信或邮件即时投递卡密或兑换码，全程无需人工干预。
法律声明：本系统基于 MIT 协议开源，完全免费。项目初衷是为开发者提供学习和研究机会。未取得合法资质时，严禁将其用于任何商业用途或搭建外网平台进行商品销售。使用本程序即表示您已充分理解并同意本法律声明的所有内容。
1.2 核心功能
支付系统 拥有强悍的插件扩展能力，目前已支持全网任意平台、任意支付渠道。
云更新 系统升级新版本时，无需进行繁琐操作，只需在店铺后台即可无缝完成升级。
商品销售 支持商品配图、会员价、游客价、邮件通知、卡密预选（用户可以预选自己想购买的账号或者卡号）、API 对接、强制登录购买、强悍的自定义控件功能、限时秒杀、批发优惠、优惠券等众多功能。
分站系统 前台用户可以开通分站，分站可以独立运行，也可以销售主站商品，类似于商业店铺的运作模式。
会员系统 会员/商户融为一体，支持会员等级以及商户等级完全自定义，商品可自定义会员等级对应价格。
推广/代理系统 拥有三级分销返佣功能，注册账号即实现自动发展下级。
共享店铺系统 可以在后台直接对接别人的店铺，通过扣除余额来进行无感知进货。
应用商店 拥有众多插件以及模板，让店铺功能更加强大。
界面适配 完美支持 PC 和手机端，真正的内外二次元文化。
扩展能力 可以通过本程序在几分钟之内快速实现任意在线购物功能：
- 游戏方面：物品购买即时到玩家背包
- 商业软件余额充值
- 商业软件自动授权
- 论坛/社区 VIP 自动开通
- 更多场景等待发掘
1.3 技术架构
| 组件 | 技术选型 | 说明 |
|---|---|---|
| 开发语言 | PHP >= 8.0 | 使用大量 PHP 8 注解及新特性 |
| 数据库 | MySQL >= 5.6 | 不推荐 5.6，推荐 5.7 或 8.0 |
| 数据库底层 | Eloquent ORM (illuminate/database ^7.30) | 来自 Laravel 生态 |
| 模板引擎 | Smarty 3.1 + PHP 原生渲染 | — |
| 会话管理 | PHP 原生 Session | 全程使用 Session |
| 邮件组件 | PHPMailer ^6.5 | 订单通知、发货通知 |
| HTTP 客户端 | Guzzle ^7.4 | 外部 API 调用 |
| 鉴权令牌 | Firebase PHP-JWT ^6.11 | API 接口鉴权 |
| HTML 过滤 | ezyang/htmlpurifier ^4.18 | 内容安全过滤 |
必需 PHP 扩展：ext-json、ext-openssl、ext-gd、ext-zip、ext-curl、ext-pdo_mysql。其中 pdo_mysql 是数据库连接必需，zip 用于安装流程，缺少将无法完成安装。
2. 环境要求
| 组件 | 最低要求 | 推荐配置 |
|---|---|---|
| Web 服务器 | Nginx / Apache / IIS | Nginx 1.20+ |
| PHP | >= 8.0 | PHP 8.1 / 8.2 |
| MySQL | >= 5.6 | MySQL 5.7 / 8.0 |
官方 Docker 镜像默认采用 PHP 8.2（bookworm 底座） 构建，因为 PHP 8.0 已于 2023 年 11 月停止安全维护。
3. 部署教程
3.1 快速体验
在部署前，可通过官方演示环境了解系统功能：
| 入口 | 地址 | 账号 | 密码 |
|---|---|---|---|
| 后台演示 | https://demo.faka.wiki/admin |
demo@demo.com |
123456 |
| 前台演示 | https://demo.faka.wiki |
为了明天美好而战斗 |
123456 |
体验账号为公共测试入口，数据可能会被定期重置，仅供功能了解使用。
3.2 宝塔面板部署（推荐）
第一步：环境准备
在宝塔面板中安装以下组件：
- Nginx 1.20+
- PHP 8.0 及以上（需安装
opcache、gd、pdo_mysql扩展） - MySQL 5.6 及以上（推荐 5.7 或 8.0）
第二步：创建站点
在宝塔面板“网站”菜单添加站点，填写已解析的域名，创建数据库并记录数据库名、用户名、密码。选择 PHP 版本为 8.0 及以上。
第三步：申请 SSL 证书
在站点设置中申请并部署 SSL 证书，这会使网站更快更安全。后续支付回调必须使用 HTTPS 协议。
第四步：上传源码
从 GitHub 下载最新版：
git clone https://github.com/lizhipay/acg-faka.git
或使用 Composer 下载：
composer create-project lizhipay/acg-faka
将源码上传至网站根目录并解压。
第五步：设置目录权限
chown -R www:www /www/wwwroot/你的站点目录
chmod -R 755 /www/wwwroot/你的站点目录
第六步：配置伪静态
在宝塔站点设置中，将 Nginx 伪静态规则粘贴到“伪静态”输入框中保存：
location ~* ^/(runtime|kernel|config|vendor)/ { return 404; }
location ~ /\.(?!well-known) { return 404; }
location ~* \.(log|sql|sqlite|db|db-wal|db-shm|bak|old|save|orig|swp|swo|tmp|ini|lock)$ { return 404; }
location ~* (~|composer\.(json|lock)|package(-lock)?\.json)$ { return 404; }
location / {
try_files $uri $uri/ /index.php?s=$uri&$args;
}
说明：前四条是安全拦截规则，分别拦截程序核心目录、点文件、敏感后缀文件、版本控制文件，统一返回 404。最后一条
try_files是单入口转发规则。Apache 无需配置，根目录已包含.htaccess文件。
第七步：设置 PHP 版本
在站点设置中将 PHP 版本切换为 8.0 及以上，并关闭“防跨站攻击（open_basedir）”，否则可能因权限限制导致程序无法正常运行。
第八步：访问安装向导
浏览器访问域名，系统将自动检测 PHP 版本、扩展和目录权限。确认通过后，填写数据库信息和管理员账号（邮箱+密码）。
数据库主机端口非 3306 时，按照
127.0.0.1:端口格式填写。
第九步：登录后台
安装完成后，后台地址为：
https://你的域名/admin
首次登录后，建议先在后台检查系统是否为最新版本，如果不是请更新。
3.3 Docker 部署
单容器模式（最简单）
一条命令即可完成部署，镜像自带 MariaDB 和 Redis，数据库密码首次启动随机生成：
docker run -d --name acg-faka -p 80:80 -v acg_data:/data --restart unless-stopped ghcr.io/lizhipay/acg-faka:latest
打开 http://服务器IP 直接进入安装向导，数据库信息已自动填好，只需设置管理员账号即可。
注意事项：
- 容器内部端口是 80，不是 8080，映射错了浏览器打不开
/data必须挂载出来，站点的数据库、配置、上传文件、插件、模板全在里面，不挂载的话容器删除后数据会丢失
Docker Compose 模式
version: '3'
services:
acgfaka:
image: ghcr.io/lizhipay/acg-faka:latest
ports:
- "8080:80"
environment:
- DB_HOST=mysql
- DB_NAME=acgfaka
- DB_USER=root
- DB_PASS=yourpassword
volumes:
- ./data:/data
mysql:
image: mysql:8.0
environment:
- MYSQL_ROOT_PASSWORD=yourpassword
- MYSQL_DATABASE=acgfaka
volumes:
- ./mysql:/var/lib/mysql
在宝塔 / 1Panel 的“创建容器”界面中，只需填写三件事：
- 镜像：
ghcr.io/lizhipay/acg-faka:latest - 端口映射：主机端口 → 容器 80
- 目录映射：挂载一个卷到
/data
4. 支付插件配置
4.1 Epusdt（USDT/TRX 加密货币）对接
官方 Epusdt 插件存在验签问题和回调数据格式限制（仅支持 form-data，不支持 JSON）。推荐使用社区修复版，该版本修复了验签逻辑并增加了对 TRX 的支持。
安装步骤：
- 如果已安装原版 Epusdt 插件，请先卸载删除
- 将修复兼容版解压上传到网站根目录的
app/Pay目录 - 确保插件目录结构如下：
app/Pay/Epusdt/ ├── Config/ │ ├── Config.php │ ├── Info.php │ └── Submit.php └── Impl/ ├── Pay.php └── Signature.php - 设置权限：
chown -R www:www app/Pay/Epusdt（如果不是 www:www 请自行修改，否则无法正常使用）
插件配置：
- 支付网关：必须以
http(s)://开头、以/结尾 - 密钥：搭建 BEpusdt 时的参数
AUTH_TOKEN
在后台找到插件，点击右侧“配置”按钮，填写参数后保存。
添加支付方式：后台 → 支付接口 → 添加支付 → 选择 Epusdt，根据需求选择支付类型（USDT-TRC20 或 TRON-TRX）。
4.2 支付FM / 易支付对接
支付FM 插件兼容易支付 API 规范。安装时需将插件上传至 app/Pay/，并手动执行插件包内的 SQL 脚本以注册支付方式。插件安装后需要根据对接步骤进行配置。
5. 常见问题排查
5.1 支付回调失败
表现：用户已付款，但系统仍显示未支付，卡密未发放。
排查清单：
-
检查网站设置中的域名：后台“其他设置”中的网站地址必须是当前使用的域名，且使用
https://协议。如果域名变更过，务必同步更新此设置。 -
检查支付平台白名单：登录支付宝/微信开发者后台，确认回调域名已加入白名单，同样需要使用
https://协议。 -
检查伪静态规则：确认 Nginx/Apache 伪静态配置正确，回调路径可正常访问。
-
CDN 干扰排查：如果使用了 CDN，可以尝试绑定服务器 IP + 端口的访问方式（如
123.123.123.123:1823）来绕过 CDN 防火墙，同时加快回调速度。
核心总结：回调问题关键就两个点 —— 发卡网站后台地址写
https://域名，支付宝后台添加https://域名白名单。
5.2 插件安装后不显示
- 确认插件目录权限为
www:www - 确认插件目录结构符合规范（包含
Config/和Impl/子目录） - 清除系统缓存后重新进入后台查看
5.3 登录状态频繁过期
已知原因：中间层 CDN 可能导致 Session 丢失。部分用户反馈移除 CDN 或调整 CDN 的 Cookie 透传规则后问题解决。
5.4 Docker 环境下的订单查询 Bug
在 Docker 部署环境中，若遇到付款后无法正确查看卡密的情况，需修改 app/Controller/User/Index.php 中订单查询返回的 tradeNo 参数处理方式：
// 修改前
return $this->theme("订单查询", "QUERY", "Index/Query.html", [
'user' => $this->getUser(),
'tradeNo' => (string)$_GET['tradeNo']
]);
// 修改后
return $this->theme("订单查询", "QUERY", "Index/Query.html", [
'user' => $this->getUser(),
'tradeNo' => explode("?", (string)$_GET['tradeNo'])[0]
]);
6. 安全加固指南
6.1 部署安全
| 措施 | 说明 |
|---|---|
| 重命名后台路径 | 将 /admin 改为自定义路径，降低自动化扫描风险 |
| 修改默认表前缀 | 从 acg_ 改为自定义字符串，降低 SQL 注入探测成功率 |
| 删除 install 目录 | 安装完成后立即删除 install/ 目录 |
| 限制后台 IP | 在宝塔“安全”页面或 Web 服务器层面限制 admin 目录的访问来源 IP |
6.2 PHP 安全配置
在 php.ini 中禁用危险函数：
disable_functions = exec, passthru, shell_exec, system, proc_open, popen
同时启用：
expose_php = Off
display_errors = Off
log_errors = On
6.3 支付安全
- 所有回调地址使用
https://协议 - 支付密钥/私钥不在日志中记录，不在前端回显
- 定期轮换支付密钥
- 启用支付插件的验签功能（不可跳过）
7. 适用场景
| 场景 | 说明 |
|---|---|
| 游戏道具/点卡 | 购买后即时发放 CDK 或直接充值到游戏账号 |
| 软件激活码 | 自动分发软件授权序列号 |
| 数字内容销售 | 漫画、插画、教程等数字作品的自动交付 |
| 论坛/社区 VIP | 支付成功后自动开通会员权限 |
| 在线教育课程 | 多级分销体系支持课程推广 |
| SaaS 订阅管理 | 支持按日/月/年等多维度计费 |
| 商业软件余额充值 | 自动充值到用户账户 |
| 游戏物品到背包 | 通过游戏 API 实现购买后即时到账 |
8. 生态资源
官方资源
| 资源 | 地址 |
|---|---|
| 源码仓库 | https://github.com/lizhipay/acg-faka |
| 文档地址 | https://faka.wiki |
| 官方体验站 | https://demo.faka.wiki |
社区插件
| 插件 | 说明 | 来源 |
|---|---|---|
| Epusdt 修复兼容版 | 修复验签问题，增加 TRX 支持 | 社区维护 |
| HashPay | RSA-SHA256 签名 + RSA-OAEP-256+A256GCM 加密回调 | 社区维护 |
| 支付FM 插件 | 兼容易支付规范，支持多种签约与免签支付方式 | 支付FM 官方 |
使用注意事项
- 部分应用商店的插件和模板需要付费购买（19.9 元起），包括基础的支付插件。
- 系统功能丰富但部分用户反馈“小毛病可能比较多”，需要一定的排查和维护能力。
- 建议在生产环境部署前，在测试环境中充分验证支付流程和回调机制。