搭建教程

本教程用于在宝塔或 aaPanel 面板中部署系统。两种面板的操作入口基本一致，截图以 aaPanel 为例；使用宝塔时，可按照相同模块名称查找对应入口。

重要要求：运行环境必须使用 PHP 8.3。PHP 版本不一致会导致扩展无法加载或后台无法正常运行。

1. 准备事项

当前交付扩展适用于 Linux x86_64、PHP 8.3 NTS（ABI 20230831）。不能直接用于 ARM、Windows 或其他 PHP 主版本；安装前先核对服务器架构与 PHP 构建。

开始搭建前，请准备以下内容：

• 一台已安装宝塔或 aaPanel 的服务器。
• 一个可用域名，并已解析到服务器 IP。
• 系统程序包。
• PHP 8.3 对应的 jft3amengine.so 扩展文件。
• 授权开通所需的信息或后续提供的授权码。

建议使用全新的站点目录部署，避免旧文件、旧配置或旧缓存影响安装结果。

2. 进入应用商店

进入宝塔或 aaPanel 后，先打开左侧菜单中的「应用商店」或「软件商店」。

部署本系统时，必须安装：

• Web 服务：Nginx。
• PHP：必须选择 PHP 8.3。

后续在共用同一套 PHP 8.3 环境的站点上搭建多个站点时，PHP 8.3 和扩展只需配置一次。新增站点时，从「创建站点」开始重复站点相关步骤即可。

3. 安装 Web 服务

在应用商店搜索 nginx，选择 Nginx 并安装。

推荐选择：

• 选择 Nginx 的「极速安装」，等待任务完成。

同一台服务器通常只需要安装一种 Web 服务。安装时选择「极速安装」，等待任务完成。

4. 安装 PHP 8.3

在应用商店搜索框输入 php，列表中会显示多个 PHP 版本。找到 PHP-8.3 后点击「安装」。

安装弹窗中选择「极速安装」。

提交后，安装任务会进入消息盒子。看到任务已经加入队列后，可以关闭消息盒子，不需要一直停留在日志页面。等待 PHP 8.3 安装完成后再继续创建站点。

5. 创建站点

运行环境安装完成后，进入「网站」页面，点击「添加站点」。

填写站点信息：

• 域名：填写实际访问域名，例如 example.com。
• 根目录：建议使用默认目录，也可以指定为空目录。
• PHP 版本：选择 PHP-83 或 PHP 8.3。
• 数据库：本系统不需要数据库，可不创建。
• FTP：按需要选择是否创建。

点击「确定」后，面板会创建站点目录和 Web 服务配置。创建完成后，站点列表中可以看到新站点，PHP 版本应显示为 8.3。

6. 放置程序文件

使用交付的整套 PHP 程序，不把其他环境的插件、全局配置或站点数据混入。网站运行目录只指向 public/，不要对外暴露 global/、sites/ 或 plugins/。

进入「文件」页面，打开刚创建站点的根目录。

上传系统程序包并解压。解压后，请确认站点根目录中可以看到程序入口文件和相关目录。

常见目录结构示例：

app.php
public/
plugins/
global/
sites/

如果程序包解压后多了一层目录，请把内部文件移动到站点根目录，避免访问时找不到入口文件。

7. 设置网站运行目录

PHP-FPM 需要读取项目根目录下的程序、插件和配置，并写入站点数据及 runtime/。检查运行账号权限和面板的 open_basedir：允许程序访问必要的项目路径，不能只允许 public/。网站对外运行目录仍保持 public/。

系统前台入口位于 public 目录。回到「网站」列表，点击站点右侧「Conf」或「设置」，进入站点设置。

进入「Directory」或「网站目录」页签，将运行目录设置为：

/public

保存后，网站访问会从 public/index.php 进入系统。保存成功后，面板会提示设置成功。

8. 配置 URL 重写

进入站点设置中的「URL 重写」或「伪静态」，写入下面规则并保存：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

说明：

• 这条规则会把不存在的路径交给 index.php 处理。
• 如果不设置 URL 重写，部分前台页面、伪静态路径或后台路径可能无法正常访问。

9. 注释 JS/CSS 静态规则

进入站点设置中的「配置」，找到默认的 JS/CSS 静态资源规则：

location ~ .*\.(js|css)?$
{
    expires      12h;
    error_log /dev/null;
    access_log /dev/null;
}

将这段规则注释掉：

# JFT3amEngine needs to receive CSS and JS requests.
# Keep this static JS/CSS rule commented.
# location ~ .*\.(js|css)?$
# {
#     expires      12h;
#     error_log /dev/null;
#     access_log /dev/null;
# }

保存配置后，重载或重启 Nginx。

这一步很重要。系统需要接管部分 CSS 和 JS 访问，如果保留面板默认静态规则，相关请求会被 Nginx 提前处理，程序无法接收到这些访问。

10. 放置 PHP 扩展文件

以下路径是宝塔 / aaPanel 常见 PHP 8.3 安装路径。扩展还需匹配服务器架构和 PHP 构建方式；自定义安装以该 PHP-FPM 环境的实际扩展目录为准。

将 jft3amengine.so 上传到 PHP 8.3 的扩展目录：

/www/server/php/83/lib/php/extensions/no-debug-non-zts-20230831/

上传后扩展文件完整路径应为：

/www/server/php/83/lib/php/extensions/no-debug-non-zts-20230831/jft3amengine.so

注意事项：

• 必须使用 PHP 8.3 对应的扩展文件。
• 扩展文件名保持为 jft3amengine.so。
• 如果扩展目录不存在，请先确认 PHP 8.3 是否安装完成。
• 共用同一套 PHP 8.3 环境的站点只需要放置一次 jft3amengine.so 。后续新增站点时，不需要重复上传扩展文件。

11. 配置 PHP 扩展

进入「应用商店 / 软件商店」中的 PHP 8.3 设置，打开「配置文件」或 php.ini 编辑页面。

切换到「配置文件」后，在配置文件末尾追加扩展配置。

在配置文件末尾添加：

[jft3amengine.so]
extension = /www/server/php/83/lib/php/extensions/no-debug-non-zts-20230831/jft3amengine.so

保存配置后，重启 PHP 8.3。

共用同一套 PHP 8.3 环境的站点只需要配置一次 PHP 扩展。后续新增站点时，不需要重复修改 PHP 8.3 配置文件。

12. 检查扩展是否生效

在面板中确认 PHP 8.3 已成功重启，再通过站点请求检查。站点由 PHP-FPM 运行；终端 PHP 的结果不能替代站点验证。

1. 访问站点，确认不再出现 JFT3amEngine\App 找不到的错误。
2. 未授权时继续下一步；已有授权时应能打开后台登录页。
3. 如出现 500，在面板查看 PHP 8.3 错误日志，核对扩展路径、文件权限与运行版本。

13. 首次访问并获取授权信息

扩展加载成功后，先访问你的站点地址。首次未授权时，页面会显示「授权异常」和当前服务器机器码。

这是正常的授权开通流程，说明程序文件、站点入口和 PHP 扩展已经运行到授权检查阶段。请完整复制页面中显示的机器码，并按交付说明提交，用于开通当前服务器授权。

14. 填写授权码

拿到授权码后，再回到 PHP 8.3 的「配置文件」页面，在刚才的扩展配置下方追加授权码配置：

jft3amengine.license=请填写交付时提供的授权码

完整配置示例：

[jft3amengine.so]
extension = /www/server/php/83/lib/php/extensions/no-debug-non-zts-20230831/jft3amengine.so
jft3amengine.license=请填写交付时提供的授权码

保存配置后，回到 PHP 8.3 管理弹窗，在面板中点击「Restart」或「重启」按钮，等待 PHP 8.3 重启完成。

请以宝塔或 aaPanel 面板里的 PHP 8.3 重启为准。只保存配置、不重启 PHP 8.3，授权码不会生效。

授权码请使用交付时提供的完整内容。不要把正式授权码放到公开文档、截图或聊天记录中。

15. 验证后台是否可访问

首次部署要选择模板组：进入默认站点的「站点配置」，把模板目录选择为 default 并保存。交付包文件位于 sites/default/templates/default/，初始配置的模板名为空；留空并不会自动选择这个子目录。

授权生效后，在浏览器访问后台路径：

/__jft3am_cp/#/login

如果能进入后台登录页，表示授权已经生效，系统部署成功。

使用随程序交付的后台账号登录，登录后立即修改初始密码。

登录后建议先完成以下检查：

• 进入「系统设置」修改默认密码。
• 确认后台路径符合你的安全要求。
• 进入「站点管理」确认默认站点存在。
• 进入「模板管理」确认模板文件可读取。
• 访问前台域名，确认页面可以正常渲染。

如果仍然显示「授权异常」，说明程序已经运行到引擎，但当前授权码没有生效或不适用于这台服务器。请检查授权码是否完整、是否保存到 PHP 8.3 配置文件，并确认已经在宝塔或 aaPanel 面板中重启 PHP 8.3。

16. 常见问题

页面显示 500 错误

优先检查 PHP 8.3 是否正常运行、扩展是否加载成功、授权码是否正确。

后台能打开，前台页面打不开

检查站点运行目录是否设置为 /public，并确认伪静态规则已保存。

CSS 或 JS 路径没有进入程序

检查站点「配置」中默认的 JS/CSS 静态规则是否已经注释。如果没有注释，Nginx 会提前处理 .css 和 .js 请求，程序无法接管这些访问。

提示扩展不存在

检查 jft3amengine.so 是否上传到 PHP 8.3 扩展目录，并确认 php.ini 中的路径完全一致。

修改配置后仍不生效

保存 PHP 配置后，必须在宝塔或 aaPanel 的 PHP 8.3 管理弹窗中点击「Restart」或「重启」。修改 Web 服务配置后，需要重载或重启 Nginx。

上传后目录不对

如果访问时出现 404 或入口文件不存在，请检查程序文件是否被解压到多余的子目录中。站点根目录应直接包含 public、plugins、global、sites 等内容。