# base_system

**Repository Path**: 57sy/base_system

## Basic Information

- **Project Name**: base_system
- **Description**: 【  基本系统  】    通用系统开发    
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# General System

基于 **ThinkPHP 8** + **多应用模式** 的电商/内容管理系统，包含前台商城（`home`）与后台管理（`admin`）。

---

## 一、环境要求

### 1.1 服务器建议配置

| 项目 | 最低 | 建议 |
|------|------|------|
| CPU | 1 核 | 2 核及以上 |
| 内存 | 1 GB | 4 GB 及以上 |
| 带宽 | 2 Mbps | 3 Mbps 及以上 |

### 1.2 软件版本

| 软件 | 版本要求 |
|------|----------|
| PHP | **>= 8.0**（推荐 8.1 / 8.2） |
| MySQL | **>= 8.0**（需 **InnoDB** 引擎；`database/data.sql` 按 MySQL 8 导出） |
| Redis | **>= 5.0**（**必装**；异步队列**仅支持 Redis 驱动**，不可关闭） |
| Web 服务器 | **Nginx**（本项目**不支持 Apache**） |
| Composer | 2.x |

### 1.3 PHP 扩展（必装）

安装依赖前请确认已启用：

- `pdo_mysql`
- `mbstring`
- `curl`
- `openssl`
- `json`
- `fileinfo`（`composer.json` 中 `ext-fileinfo` 为必需）
- `gd` 或 `imagick`（图片处理，建议安装）
- `redis`（**必装**；队列为 Redis 驱动，缓存也建议使用 Redis）

查看已安装扩展：

```bash
php -m
```

---

## 二、项目结构（部署相关）

```
general.system.com/
├── app/                 # 应用代码（home 前台、admin 后台、common 公共）
├── config/              # 配置文件（读取 .env）
├── database/
│   └── data.sql         # 全量数据库结构与初始数据
├── public/              # Web 根目录（站点必须指向此目录）
│   ├── index.php        # 入口文件
│   └── static/          # 静态资源
├── runtime/             # 运行时缓存、日志（需可写）
├── vendor/              # Composer 依赖（composer install 生成）
├── .env                 # 环境配置（需自行创建，勿提交 Git）
└── composer.json
```

**重要：** 域名必须绑定到 `public` 目录，不能指向项目根目录，否则源码与 `.env` 可能暴露。

---

## 三、安装步骤

### 3.1 获取代码

```bash
git clone <你的仓库地址> general.system.com
cd general.system.com
```

或直接解压代码包到网站目录。

### 3.2 安装 PHP 依赖

在项目根目录执行：

```bash
composer install
```

国内服务器可使用镜像：

```bash
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
composer install
```

若提示缺少 `vendor`，访问站点时也会看到：`您还未安装PHP依赖包，请输入命令安装：composer install`。

### 3.3 配置环境变量 `.env`

项目根目录**没有**默认 `.env` 文件（已在 `.gitignore` 中忽略）。请复制调试模板并改名：

**Linux / macOS：**

```bash
cp .env.debug .env
```

**Windows（PowerShell）：**

```powershell
Copy-Item .env.debug .env
```

按需编辑 `.env`，常用项说明：

```ini
# 调试：本地 true，生产 false
APP_DEBUG = true

[APP]
DEFAULT_TIMEZONE = Asia/Shanghai

[DATABASE]
HOSTNAME = 127.0.0.1
DATABASE = general_system
USERNAME = root
PASSWORD = 你的密码
HOSTPORT = 3306
PREFIX = gs_
CHARSET = utf8mb4
DEBUG = true

[LANG]
default_lang = en-us

# 缓存（生产建议 redis；见下方说明）
[CACHE]
DRIVER = redis

[REDIS]
HOST = 127.0.0.1
PORT = 6379
PASSWORD =
SELECT = 0
prefix = gs:
```

说明：

- 表前缀默认为 `gs_`，须与 `database/data.sql` 一致。
- **Redis 服务必须安装并启动**（`config/queue.php` 固定为 `redis` 连接，无 file/sync 等备选）。
- `[CACHE] DRIVER` 仅影响 Web 缓存；即使改为 `file`，队列仍走 Redis，**不能**因缓存用文件而省略 Redis。
- 修改 `.env` 后建议清空 `runtime/*` 缓存或重启 PHP-FPM。

### 3.4 创建数据库并导入

1. 确认 MySQL 版本为 **8.0 及以上**（`SELECT VERSION();`）。

2. 创建数据库（字符集 **utf8mb4**）：

```sql
CREATE DATABASE general_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

3. 导入项目 SQL（文件较大，请耐心等待）：

```bash
mysql -u root -p general_system < database/data.sql
```

或在 Navicat / phpMyAdmin 中选择 `general_system` 后运行 `database/data.sql`。

4. 确认 `.env` 中 `[DATABASE]` 与库名、账号、前缀一致。

> MySQL 5.7 及以下版本不保证兼容（排序规则、JSON 等可能与 `data.sql` 不一致）。

### 3.5 目录权限

以下目录/Web 服务器用户（如 `www`、`www-data`、`nginx`）需具备**写权限**：

| 目录 | 用途 |
|------|------|
| `runtime/` | 缓存、编译模板、日志 |
| `runtime_cli/` | 命令行运行时（若使用） |
| `public/storage/` | 上传附件、商品图等 |
| `public/` | 生成 `sitemap.xml` 等文件时需可写 |

**Linux 示例：**

```bash
chown -R www:www runtime runtime_cli public/storage
chmod -R 755 runtime runtime_cli public/storage
```

Windows 本地开发（phpStudy、小皮等）一般使用当前用户即可；若上传失败，检查目录是否只读。

### 3.6 配置 Web 服务器

#### 站点根目录

- 文档根目录（DocumentRoot）：`<项目路径>/public`
- 示例本地域名：`http://general.system.com`（hosts 自行绑定）

#### Nginx 虚拟主机示例

```nginx
server {
    listen 80;
    server_name general.system.com;
    root /www/wwwroot/general.system.com/public;
    index index.php index.html;

    location / {
        if (!-e $request_filename) {
            rewrite ^(.*)$ /index.php?s=$1 last;
            break;
        }
    }

    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;   # 或 unix:/tmp/php-cgi.sock
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
        include        fastcgi_params;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 7d;
        access_log off;
    }
}
```

ThinkPHP 8 也支持 **pathinfo** 风格，若使用 `try_files` 方案：

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

需保证 `fastcgi_param PATH_INFO` 等配置与当前 PHP 版本匹配（宝塔、LNMP 面板一般已配好）。

> **说明：** 请勿使用 Apache / `.htaccess` 部署；伪静态、PATH_INFO 等按 **Nginx + PHP-FPM** 方案编写与测试。

### 3.7 启动 Redis

安装后请先启动 Redis，并确认可连接：

```bash
redis-cli ping
# 期望返回 PONG
```

### 3.8 验证安装

1. 浏览器访问前台：`http://你的域名/`
2. 访问后台登录：`http://你的域名/admin/login/index`

若出现 404，优先检查：**伪静态**、**站点是否指向 public**。

数据库 `data.sql` 中带有演示管理员账号（如 `admin`），密码为加密存储。**请勿在公网使用默认密码**；登录后请在后台修改密码。若忘记密码，需在数据库 `gs_admin` 表中按项目加密规则重置。

---

## 四、安装后必做配置（后台）

登录后台后，建议依次完成：

| 配置项 | 路径/说明 |
|--------|-----------|
| 网站域名 | 系统配置 → **域名配置** → `site_domain`（前台链接、sitemap、邮件等，**末尾不要加 /**） |
| 附件/静态域名 | 同组 `attachment_domain`、`static_domain` |
| 邮件、支付等 | 按业务在对应菜单配置 |
| 定时脚本 | **系统脚本** `/admin/command/datalist`：启用 `order:expire` 等，并在服务器配置 **第七章 Crontab** |
| 队列 Worker | **队列管理** `/admin/job_manager/datalist`：按提示配置 **第八章 Supervisor** 守护 `queue:work` |

本地开发时 `site_domain` 可填：`http://general.system.com`（与浏览器访问一致）。

---

## 五、多应用与访问路径

| 应用 | 默认入口 | 说明 |
|------|----------|------|
| `home` | `/` | 前台商城、会员、结算等 |
| `admin` | `/admin/...` | 后台管理 |

`config/app.php` 中 `default_app` 为 `home`，`deny_app_list` 包含 `common`（禁止 URL 直接访问）。

---

## 六、Redis 与队列（必装）

### 6.1 Redis 服务

- 部署前请安装 Redis **>= 5.0**，并设置开机自启。
- `.env` 中 `[REDIS]` 的地址、端口、密码须与实例一致；PHP 已启用 `redis` 扩展。
- `[CACHE] DRIVER=redis` 时，系统配置等走 Redis 缓存（推荐）；与队列共用同一 Redis 实例即可。

### 6.2 异步队列（仅 Redis）

项目使用 `topthink/think-queue`，**仅配置 Redis 驱动**（见 `config/queue.php` 中 `default => redis`，不支持改为 database / sync 等）。

- 队列 Redis 常用 **`select => 1`**，与缓存的 `SELECT = 0` 可分开，避免 key 冲突。
- 未启动 Redis 或 Worker 时，商品访问统计等异步任务会失败或堆积。

生产环境**必须**用进程管理工具守护 `queue:work`（见下文 **第八章**），开发环境可用 `queue:listen` 方便改代码热生效。

异步队列完整清单见下文 **第八章表格**；后台 **队列管理**：`/admin/job_manager/datalist`。

更多失败重试、发版重启等见：`app/job/README.MD`。

---

## 七、定时任务一览（Think 命令 / Crontab）

项目在 `config/console.php` 注册的命令如下。继承 `BaseCommand` 的脚本会读表 **`gs_crontab`**：仅当 **`status = 1`** 时执行业务；可在后台 **系统脚本**（`/admin/command/datalist`）启用/关闭并查看上次执行时间。

### 7.1 全部定时/命令行脚本

| 命令 | PHP 类 | 类型 | 是否配置 Crontab | 建议 Crontab 频率 | 说明 |
|------|--------|------|------------------|---------------------|------|
| `order:expire` | `app\command\OrderExpire` | 定时业务 | **是** | `* * * * *`（每分钟） | 未支付订单超时关闭；参数 `n` 分钟在后台配置；每分钟跑一次，检查略有延迟属正常 |
| `order:confirm` | `app\command\OrderConfirm` | 定时业务 | **是** | `0 * * * *`（每小时）或每天一次 | 发货满 N 天后自动确认收货，N 在后台配置 |
| `currency:update-rate` | `app\command\CurrencyRate` | 定时业务 | **是** | `0 2 * * *`（示例：每天 2:00） | 更新货币汇率 |
| `admin:reset-password` | `app\command\AdminResetPassword` | 运维 CLI | **否** | — | 重置管理员密码，如 `php think admin:reset-password admin -p 新密码` |
| `admin:clear-database` | `app\command\AdminClearDatabase` | 运维 CLI | **否** | — | 交互式清理订单等数据，危险操作 |
| `hello` | `app\command\Hello` | 示例 | **否** | — | 框架示例命令，生产无需配置 |

> **类型说明：**「定时业务」= 建议写入服务器 Crontab；「运维 CLI」= 仅故障/维护时 SSH 手动执行。

### 7.2 Crontab 配置示例

将 `/www/wwwroot/general.system.com` 换成你的**项目根目录**（含 `think` 文件，不是 `public`）。PHP 路径可用 `which php`，或与 `.env` 中 `PHP_EXE_PATH` 一致（宝塔等面板常需写绝对路径）。

```cron
# 订单超时（每分钟）
* * * * * cd /www/wwwroot/general.system.com && /usr/bin/php think order:expire >> /www/wwwroot/general.system.com/runtime/log/cron-order-expire.log 2>&1

# 自动确认收货（每小时整点）
0 * * * * cd /www/wwwroot/general.system.com && /usr/bin/php think order:confirm >> /www/wwwroot/general.system.com/runtime/log/cron-order-confirm.log 2>&1

# 货币汇率（每天凌晨 2 点）
0 2 * * * cd /www/wwwroot/general.system.com && /usr/bin/php think currency:update-rate >> /www/wwwroot/general.system.com/runtime/log/cron-currency-rate.log 2>&1
```

**建议：**

- 确保 `runtime/log/` 可写，便于排查定时任务输出。
- 若担心同一分钟重复触发，可在命令外加 `flock`（示例）：
  `flock -xn /tmp/order-expire.lock -c 'cd ... && php think order:expire'`
- 新增自定义命令需在 `config/console.php` 注册，并同步到 `gs_crontab`（后台脚本列表会自动扫描可见命令）。

---

## 八、异步队列 Job 一览（Redis + Worker）

任务写入 Redis 后，必须由 **常驻** `php think queue:work` 消费；**Crontab 不能代替 Worker**。队列驱动见 `config/queue.php`（`default => redis`，常用 **`select => 1`**）。

### 8.1 全部队列 Job

| 队列名 | Job 类 | 名称 | 说明 | 投递位置 | 生产 Worker 命令（在项目根执行） |
|--------|--------|------|------|----------|----------------------------------|
| `goods_visit_queue` | `app\job\GoodsVisitJob` | 商品访问记录 | 前台商品详情访问异步写入 `gs_goods_visit` | `app/home/controller/Goods.php`（商品详情） | `php think queue:work --queue goods_visit_queue` |
| `mail_task` | `app\job\MailTaskJob` | 邮件批量发送 | 后台营销邮件任务按收件人入队发送 | `app/admin/service/MailTaskService.php` | `php think queue:work --queue mail_task` |

| 后台管理 | 路径 |
|----------|------|
| 队列列表（含按环境生成的 Worker 命令） | `/admin/job_manager/datalist` |
| Job 源码与注解 | `app/job/*.php`，`#[JobMeta(...)]` |

**注意：** 未带 `--queue` 的 `php think queue:work` 只消费 **`default`**，不会处理上表两个队列。

### 8.2 生产环境推荐命令

```bash
# 商品访问（访问量大可 numprocs=2+）
php think queue:work --queue goods_visit_queue

# 邮件批量发送（有营销邮件时必须单独守护）
php think queue:work --queue mail_task
```

也可合并监听（左侧队列优先）：

```bash
php think queue:work --queue mail_task,goods_visit_queue
```

重试、超时等由各 Job 类内逻辑控制（如 `BaseJob::MAX_ATTEMPTS`），**无需**在 `queue:work` 上配置 `--sleep`、`--tries`、`--timeout`。

**注意：** 只跑 `php think queue:work` 且不写 `--queue` 时，默认只消费 **`default`** 队列，**不会**处理 `goods_visit_queue` / `mail_task`。

开发调试可用（勿用于生产长期运行）：

```bash
php think queue:listen --queue goods_visit_queue
```

### 8.3 Supervisor 配置示例（Linux）

安装 Supervisor 后，在 `/etc/supervisor/conf.d/` 增加（路径按实际修改）：

```ini
[program:queue-goods-visit]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /www/wwwroot/general.system.com/think queue:work --queue goods_visit_queue
directory=/www/wwwroot/general.system.com
autostart=true
autorestart=true
user=www
numprocs=2
redirect_stderr=true
stdout_logfile=/www/wwwroot/general.system.com/runtime/log/queue-goods-visit.log
stopwaitsecs=3600

[program:queue-mail-task]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /www/wwwroot/general.system.com/think queue:work --queue mail_task
directory=/www/wwwroot/general.system.com
autostart=true
autorestart=true
user=www
numprocs=1
redirect_stderr=true
stdout_logfile=/www/wwwroot/general.system.com/runtime/log/queue-mail-task.log
stopwaitsecs=3600
```

加载并启动：

```bash
supervisorctl reread
supervisorctl update
supervisorctl start queue-goods-visit:*
supervisorctl start queue-mail-task:*
supervisorctl status
```

### 8.4 发版与重启 Worker

代码或 Job 类更新后需让 Worker 加载新代码：

```bash
cd /www/wwwroot/general.system.com
php think queue:restart
supervisorctl restart queue-goods-visit:*
supervisorctl restart queue-mail-task:*
```

`queue:restart` 会通知**所有**正在运行的 `queue:work` 在**当前任务结束后**退出；须依赖 Supervisor **自动拉起**，否则队列无人消费。

### 8.5 Windows 服务器

无 Supervisor 时，可用 **NSSM** 将上述 `queue:work` 注册为 Windows 服务，或使用计划任务反复拉起（不如 Supervisor 稳定）。**不要**在生产长期使用 `queue:listen`。

---

## 九、常用命令

在项目根目录执行：

```bash
# 查看 ThinkPHP 命令
php think

# 清除缓存（改配置、升级后建议执行）
php think clear

# 队列消费（生产用 work，开发可用 listen）
php think queue:work --queue goods_visit_queue

# 发版后通知 Worker 优雅重启
php think queue:restart
```

---

## 十、生产环境检查清单

1. `.env` 中设置 `APP_DEBUG = false`，关闭数据库 `DEBUG`。
2. 站点启用 **HTTPS**，后台「域名配置」改为 `https://` 开头。
3. 禁止将 `.env`、`runtime` 日志、备份目录置于可下载路径。
4. 定期备份 MySQL 与 `public/storage` 上传目录。
5. **Redis** 已安装、开机自启；`.env` 与 `config/queue.php` 配置正确。
6. **Crontab** 已配置第七章中的 `order:expire` 等脚本，且后台对应脚本为「启用」。
7. **Supervisor**（或等价方案）已守护第八章中的 `queue:work` 进程。
8. `composer install --no-dev -o` 部署，勿在生产环境暴露 `think-trace`。

---

## 十一、常见问题

### 11.1 打开页面空白或 500

- 查看 `runtime/log/` 下日志。
- 确认 PHP 版本 >= 8.0、扩展齐全。
- 确认 `runtime` 可写。

### 11.2 样式/JS 404

- 确认访问域名与 `public` 根目录正确。
- 静态资源在 `public/static/`。

### 11.3 后台能开、前台 404

- 检查 Nginx 伪静态是否生效。
- 本地可暂时访问：`http://域名/index.php` 对比排查。

### 11.4 上传图片失败

- 检查 `public/storage` 权限。
- PHP `upload_max_filesize`、`post_max_size` 是否过小。

### 11.5 链接域名不对（商品链接、sitemap 等）

- 后台 **域名配置** → `site_domain` 是否与浏览器访问一致。
- 修改后清理缓存：后台操作或 `php think clear`。

### 11.6 队列不消费 / 推送失败

- 确认 Redis 已启动：`redis-cli ping` 应返回 `PONG`。
- 核对 `.env` 的 `[REDIS]` 与 `config/queue.php`（队列常用 `select => 1`）。
- 确认 Supervisor 中 `queue:work --queue <队列名>` 在运行，且队列名与 `Queue::push` 第三参数一致（见第八章、 `app/job/README.MD`）。
- 后台 **队列管理** 核对 Worker 命令是否已部署。

### 11.7 定时任务不执行

- 服务器是否已添加第七章 Crontab，路径是否为**项目根目录**。
- 后台 **系统脚本** 对应命令是否为「启用」（`gs_crontab.status = 1`）。
- 查看 `runtime/log/cron-*.log` 或手动执行：`php think order:expire` 看终端输出。

### 11.8 缓存想用文件、能否不装 Redis？

**不可以。** 仅 `[CACHE] DRIVER=file` 时，Web 页面缓存可落盘，但**队列仍强制走 Redis**，必须安装 Redis 服务与 PHP `redis` 扩展。

---

## 十二、技术栈摘要

- [ThinkPHP 8](https://www.thinkphp.cn/)
- think-multi-app（前台 / 后台分离）
- think-view、think-captcha、think-queue
- PHPMailer、PhpSpreadsheet、PayPal SDK、Dompdf 等（见 `composer.json`）

---

## 许可证

Apache-2.0（见 `composer.json`）