jyshd_mWtK2/DEPLOYMENT.md

部署说明（FastAdmin / ThinkPHP5）

本文档用于指导你将本项目部署到生产环境（Linux + Nginx/Apache + PHP-FPM + MySQL + Redis）。项目为 FastAdmin（ThinkPHP 5.0.x） 多模块应用，Web 根目录为 public/。

1. 技术栈与关键组件

• 后端框架：ThinkPHP 5.0.x（topthink/framework ~5.0.24）
• 后台框架：FastAdmin（含插件机制 addons）
• 数据库：MySQL（配置文件 application/database.php，默认表前缀 fa_）
• 缓存/队列：Redis
  • Redis 业务配置：application/config.php 的 redis
  • 队列配置：application/extra/queue.php（connector=redis，默认 select=5）
• 队列：topthink/think-queue 1.1.6（命令：php think queue:listen / php think queue:work --daemon）
• 定时任务：项目内存在 API 形式的定时任务入口（见 application/api/controller/Cron.php），以及 K 线生成脚本（见根目录 NewTradeKline*.php、TradeKline.php）

2. 服务器与运行环境要求

• PHP：>= 7.0（建议 7.2/7.4，更高版本需要你自行验证兼容性）
• PHP 扩展（至少）：
  • pdo_mysql
  • curl
  • json
  • 以及常用扩展：mbstring、openssl、gd/imagick（如涉及图片处理）
• MySQL：5.7/8.0（推荐 5.7 起）
• Redis：5.x/6.x
• Web Server：Nginx 或 Apache

3. 代码发布目录建议

假设你发布到：

• 项目目录：/www/wwwroot/exchange-admin（示例）
• Web 根目录：/www/wwwroot/exchange-admin/public

注意：ThinkPHP/FastAdmin 必须 将站点根指向 public/，不要直接指向项目根目录。

4. 目录结构说明（部署相关）

部署与运维时，重点关注下面这些目录/文件的用途：

• public/
  • Web 根目录（Nginx/Apache 的 root 必须指向这里）
  • 包含 index.php 应用入口
  • 上传目录通常在 public/uploads/（按实际生成）
• application/

  • ThinkPHP 应用代码（多模块）

  • 常见模块：

    • application/admin/：后台模块
    • application/api/：API 模块
    • application/index/：前台模块

  • 核心配置：

    • application/config.php：应用配置（含 redis 等）
    • application/database.php：数据库配置（通过 Env::get('database.xxx', ...)）

  • 扩展配置：application/extra/（如 queue.php、site.php、upload.php）

  • 目录用途细分（重点：控制器在哪、对应哪个模块）：

    • application/admin/
      • controller/：后台控制器（典型：app\admin\controller\Index、Dashboard）
      • model/：后台模块模型
      • view/：后台页面模板
      • command/：后台相关 CLI 命令（安装/资源压缩/插件等）
      • config.php：后台模块的补充配置（会覆盖/补充全局配置）
    • application/api/
      • controller/：API 控制器（典型：app\api\controller\Index、Cron、Job）
      • job/：队列任务类（如 app\api\job\Dismiss，由 think-queue 消费执行）
      • common.php / config.php：API 模块内的补充逻辑与配置
    • application/index/
      • controller/：前台控制器（典型：app\index\controller\Index）
      • view/：前台模板
    • application/kefu/
      • controller/：客服/网关相关启动类（Workerman/GatewayWorker，典型：app\kefu\controller\Sgateway）
    • application/common/
      • controller/：控制器基类与公共逻辑
        • Backend.php：后台控制器基类（app\common\controller\Backend）
        • Api.php：API 控制器基类（app\common\controller\Api）
        • Frontend.php：前台控制器基类（app\common\controller\Frontend）
      • model/：公共模型
      • view/：公共视图/模板
    • application/extra/
      • queue.php：队列配置
      • site.php：站点配置（后台“系统配置”常会生成/覆盖此文件）
      • upload.php：上传配置
      • addons.php：插件 Hook/路由相关配置

  • 模块/控制器与 URL 的关系（常见规则）：

    • ThinkPHP5 默认格式：/{module}/{controller}/{action}
    • 例如：
      • application/api/controller/Index.php -> /api/index/*
      • application/admin/controller/Index.php -> 后台入口文件 + /index/*
    • public/index.php 为统一入口；后台入口通常是 public/admin.php（安装后可能被重命名为随机文件名）。
• addons/
  • FastAdmin 插件目录（启用/禁用插件会影响系统行为与路由）
• runtime/
  • 运行时目录（日志、缓存等）
  • 生产环境通常需要可写权限（由 PHP-FPM 运行用户写入）
• vendor/
  • Composer 依赖（生产环境需要完整存在；一般不建议放到 Web 根可访问路径下）
• think
  • ThinkPHP 控制台入口（命令行）
  • 常用：安装 php think install、队列 php think queue:work --daemon 等

部署建议：

• 只暴露 public/ 为 Web 根，其余目录不要通过 Web Server 直接访问。
• 确保 runtime/、public/uploads/ 对 PHP-FPM 用户可写。

5. 环境配置（.env）

根目录存在示例文件：.env.sample，你可以复制为 .env：

• Linux：cp .env.sample .env
• Windows：复制并重命名

示例内容（节选）：

• app.debug / app.trace
• database.hostname / database.database / database.username / database.password / database.hostport / database.prefix

说明：

• application/config.php 与 application/database.php 会通过 think\Env::get() 读取环境变量（即 .env 或系统环境变量）。
• 生产环境请确保：[app] debug=false。

6. 初始化安装（推荐：命令行安装）

本项目内置 FastAdmin 安装命令：php think install（见 application/admin/command/Install.php）。

6.1 方式 A：命令行安装（推荐）

在项目根目录执行：

• php think install --hostname=127.0.0.1 --hostport=3306 --database=YOUR_DB --username=YOUR_USER --password=YOUR_PASS --prefix=fa_

安装过程会自动：

• 创建数据库（若权限允许）
• 导入初始化 SQL：application/admin/command/Install/fastadmin.sql
• 写入/更新 application/database.php 中的 Env::get('database.xxx', '...') 默认值
• 将 public/admin.php 重命名为随机文件名（提升安全性）
• 写入安装锁：application/admin/command/Install/install.lock

安装完成后终端会输出：

• 后台入口（随机文件名）
• 后台账号与密码

6.2 方式 B：手工导入 SQL（不推荐，除非你很清楚自己在做什么）

你也可以手工导入：

• application/admin/command/Install/fastadmin.sql

然后自行配置数据库连接、后台入口等。但因为安装命令还会改写 application/database.php 和重命名后台入口文件，手工方式更容易遗漏步骤。

7. Nginx 配置示例

请按你的域名与证书路径调整，重点是：

• root 指向 public/
• index 包含 index.php
• try_files 将请求转发到 index.php（ThinkPHP 路由）

示例：

server {
    listen 80;
    server_name example.com;

    root /www/wwwroot/exchange-admin/public;
    index index.php index.html;

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

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_pass 127.0.0.1:9000;  # 按实际 php-fpm 调整
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location ~ /\. {
        deny all;
    }
}

8. 目录权限与运行权限

生产环境常见需要可写的目录（以实际情况为准）：

• runtime/
• public/uploads/（上传文件）

建议：

• 让 PHP-FPM 运行用户（如 www/nginx）对上述目录具备写权限。

8. 队列（Redis）部署

本项目已配置 application/extra/queue.php 使用 Redis 队列。

8.1 启动队列消费者

在项目根目录：

• 监听模式：php think queue:listen
• Work 模式：php think queue:work --daemon

建议生产环境使用 Supervisor 守护进程常驻（或 systemd），保证进程异常退出可自动拉起。

8.2 关键注意点

• Redis 连接参数来源：application/extra/queue.php（读取 Env::get('redis.host')、Env::get('redis.port')）
• 本项目队列 Redis DB 索引默认：select => 5

9. 定时任务 / Cron 部署

项目中存在两类定时/循环任务：

9.1 API 形式定时任务（application/api/controller/Cron.php）

Cron.php 内部通过宝塔面板 API（addons/btpanel）去创建 crontab，并大量使用 curl 调用 https://cs.400110.cn/api/... 这类接口。

建议你按实际业务：

• 确认定时任务目标域名（Cron.php 里的 $url）是否为你的生产域
• 明确定时任务应当在 业务服务器内部 调用还是由外部定时器触发

9.2 K 线生成脚本（根目录 NewTradeKline*.php / TradeKline.php）

这些脚本通过 define('BIND_MODULE', 'api/xxx/index') 绑定到 API 模块执行。

常见用法（参考 Cron.php 中的示例）：

• php NewTradeKlines.php start -d
• php NewTradeKlines.php stop

说明：这些命令风格类似 Workerman 的启动方式，建议用守护进程/面板托管，避免意外退出。

10. HTTPS 证书与私钥

根目录存在：

• server.key
• server.pem

生产环境请确保：

• 私钥文件权限严格控制
• 不要将真实生产私钥提交到公开仓库

11. 安全与敏感信息检查（强烈建议）

我在配置里看到了疑似明文敏感信息（例如 application/extra/site.php 中的 mail_smtp_pass 等）。生产部署前请务必：

• 替换为你自己的邮箱/短信/第三方平台配置
• 避免明文写死，优先改为 .env 或服务器环境变量注入
• 检查 application/extra/site.php、application/database.php、各插件配置是否包含生产密钥

12. 常见问题排查

• 访问首页跳转安装：检查 application/admin/command/Install/install.lock 是否存在；未安装时 public/index.php 会跳转到 install.php。
• 500 / 空白页：先确认 PHP 版本与扩展；再看 runtime/log/ 下日志（或 ThinkPHP 日志目录）。
• 上传失败：检查 public/uploads 权限，以及 application/extra/upload.php 的限制（大小、后缀）。
• 队列不执行：确认 Redis 可用、queue.php 的 select 是否一致，且 php think queue:work --daemon 常驻。

---

如你希望我把 Supervisor/systemd 的完整配置也写进来，请告诉我：你的生产环境是 CentOS/Ubuntu/Debian 哪一种，以及 PHP-FPM 的服务名与运行用户（www-data/nginx/www）。