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 路由）

示例：

```nginx
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`）。