框架部署教程

安装包

框架安装包下载地址：https://1727471.share.123pan.cn/123pan/Ggx9-97HMv

基础环境

• Nginx
• PHP 8.2
• MySQL 5.7 或 MySQL 8.0
• PHP 扩展：fileinfo、redis
• 安装或启用 PHP 扩展后必须重启 PHP。
• 域名需要先到对应域名服务商添加解析。

宝塔自动安装（推荐）

1. 在宝塔安装 Nginx、PHP 8.2、MySQL 5.7 以上版本，并为 PHP 安装 fileinfo 和 redis 扩展。
2. 将框架代码上传到 /www/wwwroot/自定义站点目录 并解压。
3. 进入解压后的 saas-framework 目录。
4. 在终端执行以下命令，把域名替换为实际域名：

./auto.sh --domain example.com

1. 命令执行完成并显示数据库、目录等安装信息后，访问域名。
2. 在网页安装界面填写脚本生成或显示的数据库信息和站点信息，完成安装。
3. Redis 没有设置密码时，密码可以留空。

使用自动安装后，可以忽略后面的手动配置。

宝塔手动安装

解除 PHP 禁用函数

手动配置前必须解除禁用函数。以下三种方式任选一种，不需要全部执行。

宝塔 PHP 8.2 推荐命令；其他 PHP 版本需要将路径中的 82 改成对应版本：

curl -Ss https://www.workerman.net/webman/fix-disable-functions | /www/server/php/82/bin/php

使用当前 CLI PHP 的通用命令：

curl -Ss https://www.workerman.net/webman/fix-disable-functions | php

也可以进入站点的 backend 目录执行：

php webman fix-disable-functions

执行前应确认脚本来源可信。配置站点前，在终端执行 php -v，确保 CLI PHP 为 8.2 或更高版本。如果版本不正确，应先在宝塔中切换命令行 PHP 版本。

上传源码

1. 在 /www/wwwroot 下新建站点目录。
2. 上传并解压框架源码。
3. 将整站所有者设置为 www，权限设置为 755。

启动端口

默认后端启动端口是 8787。单台服务器运行多个项目时，需要为不同项目修改启动端口，并同步修改 Nginx 伪静态配置中的代理端口。

新增宝塔站点

1. 在宝塔中新增站点，项目类型选择“异步项目”。
2. 项目目录选择源码目录下的 backend 目录。
3. 数据库字符集选择 utf8mb4。
4. 启动命令填写：

php start.php start

修改运行目录

站点创建完成后，进入站点设置，将运行目录修改为 public。

配置 Nginx 伪静态

进入“网站 -> 设置 -> 配置文件/伪静态”，使用以下配置。默认端口是 8787；如果项目修改过启动端口，必须同步修改 proxy_pass 的端口。

# 将请求转发到后端接口
location ^~ / {
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    if (!-f $request_filename) {
        proxy_pass http://127.0.0.1:8787;
    }
}

# 拒绝访问所有以 .php 结尾的文件
location ~ \.php$ {
    return 404;
}

# 允许访问 .well-known 目录
location ~ ^/\.well-known/ {
    allow all;
}

# 拒绝访问其他以 . 开头的文件或目录
location ~ /\. {
    return 404;
}

开发环境

• 推荐在 WSL 或 Linux 环境开发，环境要求与服务端类似。
• 使用 Codex、Cursor、Trae、CodeBuddy 等开发工具时，可以先让 AI 阅读项目 skills 和整体代码，再生成或优化适合当前项目的 skill，然后描述需要开发的功能并完成调试。
• 推荐使用应用/插件开发模式。

常见问题

安装应用插件后报错

先重启站点，也可以进入“开发总后台 -> 系统运维 -> 便捷终端”，执行“重载后端”。执行前应确保 CLI PHP 环境正确。

fileinfo 或 redis 扩展验证不通过

1. 确认扩展已安装并启用。
2. 严格按前文解除 PHP 禁用函数。
3. 重启 PHP 和站点。
4. 仍不通过时，可以先关闭站点，进入站点的 backend 目录执行：

php start.php start

使用 AI 开发插件

1. 先部署好本地开发环境，也可以让 AI 参考本知识库协助搭建。
2. 使用开发工具打开完整项目。
3. 让 AI 阅读 skills 和项目整体结构，并生成或优化当前项目的开发 skill。
4. 描述具体插件需求，让 AI 按项目规范拆解、开发并调试。