302 lines
12 KiB
Markdown
302 lines
12 KiB
Markdown
# YwxApp 企业级应用框架
|
||
|
||
> 基于 ThinkPHP 6 的多应用 + 插件化企业建站/应用市场框架。框架免费，通过插件与模板商业化变现（Discuz! 式闭环：提交 → 审核 → 上架 → 购买 → 支付 → 授权 → 域名绑定 → 运行期巡检 → 分润提现）。
|
||
|
||
- **版本**：`1.0.16`
|
||
- **官网**：https://www.ywxapp.cn
|
||
- **运行环境**：PHP >= 7.4（推荐 8.0+）、MySQL >= 5.7、Redis（可选，用于缓存/队列）
|
||
|
||
---
|
||
|
||
## 一、特性
|
||
|
||
| 特性 | 说明 |
|
||
| --- | --- |
|
||
| 多应用架构 | `frontend`（企业站/官网，默认首页）、`backend`（后台，入口 `/admin`）、`member`（会员中心，入口 `/user`）、`api`（接口，入口 `/api`） |
|
||
| 插件化体系 | 业务功能以插件形式存在（`addon/<name>/`），支持在线安装、离线包安装、热重载、一键修复 |
|
||
| 应用市场 | 内置 `appmall` 插件（中心站），对接自托管市场，支持购买、授权、域名绑定、升级巡检 |
|
||
| 数据库自愈 | 模型壳内置 `ensureSchema()`，缺表建表、缺列补列，部署无需手跑 SQL |
|
||
| 可视化设计器 | 开发模式下后台「设计插件」可可视化生成插件骨架、配置项、菜单、路由、页面 |
|
||
| 前后台皮肤 | 支持模板/皮肤叠加（`SkinOverlay`），核心后台布局与业务视图分离 |
|
||
| 命令行工具 | 插件管理、脚手架生成、健康检测、授权校验、框架升级等全套 CLI |
|
||
|
||
---
|
||
|
||
## 二、环境要求与准备
|
||
|
||
- PHP 7.4+（推荐 8.0+），需开启扩展：`pdo_mysql`、`mbstring`、`curl`、`openssl`、`fileinfo`、`redis`（可选）
|
||
- MySQL 5.7+ / MariaDB 10.2+
|
||
- Composer 2.x
|
||
- Web 服务器：Nginx / Apache（推荐 Nginx，已内置伪静态规则）
|
||
|
||
### 目录权限
|
||
|
||
部署后请确保以下目录可写（Linux 下建议 `755`，运行时目录 `777`）：
|
||
|
||
```
|
||
runtime/ 运行时缓存、日志
|
||
public/static/ 插件静态资源发布目录（安装/重载时写入）
|
||
addon/ 插件源码目录
|
||
```
|
||
|
||
---
|
||
|
||
## 三、安装部署
|
||
|
||
### 方式一：Web 安装器（推荐）
|
||
|
||
项目内置 Web 安装向导，访问站点根目录即可进入：
|
||
|
||
```
|
||
http://your-domain.com/install/
|
||
```
|
||
|
||
安装器位于 `public/install/`，流程：
|
||
|
||
1. 环境检测（PHP 版本、扩展、目录权限）
|
||
2. 配置数据库连接（读取/生成 `.env`）
|
||
3. 导入 `public/install/install.sql` 初始化数据表与管理员账号
|
||
4. 安装完成，**务必删除 `public/install/` 目录**以防被重复触发
|
||
|
||
> 注意：`.env` 含数据库敏感配置，请勿将其整体覆盖或提交到公开仓库；修改配置请用局部 `replace_in_file`。
|
||
|
||
### 方式二：手动部署（已有数据库）
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
composer install --no-dev -o
|
||
|
||
# 2. 复制环境变量模板并填写
|
||
cp .env.example .env # 如无模板则手动创建 .env
|
||
|
||
# 3. 导入数据库（自行执行 install.sql 或已有库）
|
||
|
||
# 4. 生成应用密钥并设置运行时权限
|
||
php think key:generate # 如支持
|
||
chmod -R 755 runtime addon public/static
|
||
```
|
||
|
||
### 伪静态（Nginx 示例）
|
||
|
||
```nginx
|
||
location / {
|
||
if (!-e $request_filename) {
|
||
rewrite ^(.*)$ /index.php?s=/$1 last;
|
||
break;
|
||
}
|
||
}
|
||
```
|
||
|
||
Apache 已内置 `.htaccess`。
|
||
|
||
---
|
||
|
||
## 四、目录结构
|
||
|
||
```
|
||
ywxapp_dev/
|
||
├── addon/ # 插件目录（核心业务以插件交付）
|
||
│ ├── blog/ # 博客插件
|
||
│ ├── forum/ # 论坛插件
|
||
│ ├── articles/ # 内容管理(CMS)插件
|
||
│ ├── haonav/ # 网址导航插件
|
||
│ ├── appmall/ # 应用市场（中心站）
|
||
│ └── wxchat/ # 微信客服插件
|
||
├── app/ # 多应用（系统级）
|
||
│ ├── frontend/ # 企业站/官网（默认首页）
|
||
│ ├── backend/ # 后台管理（入口 /admin）
|
||
│ ├── member/ # 会员中心（入口 /user）
|
||
│ └── api/ # 接口应用（入口 /api）
|
||
├── ywxapp/ # 框架核心库
|
||
│ ├── AddonBase.php # 插件基类（插件控制器须 use ywxapp\AddonBase）
|
||
│ ├── service/ # AppService(启动/命令注册/路由加载)、AddonService、MarketService…
|
||
│ ├── model/ # BaseModel（数据库自愈引擎）
|
||
│ ├── command/ # 命令行（addon:manage / repair / make / health / license-check / ywxapp:upgrade）
|
||
│ └── controller/ # BackendBase / FrontendBase / MemberBase 基类
|
||
├── config/ # 全局配置
|
||
│ ├── ywxapp.php # 框架主配置（验证码/多语言/API地址/插件开关…）
|
||
│ ├── app.php # 多应用配置（default_app / app_map）
|
||
│ ├── route.php # 路由
|
||
│ └── database.php # 数据库
|
||
├── public/ # Web 根目录
|
||
│ ├── install/ # Web 安装器（安装后删除）
|
||
│ ├── static/ # 静态资源（插件资源发布到此）
|
||
│ └── index.php # 入口
|
||
├── runtime/ # 运行时（缓存/日志，可写）
|
||
├── extend/ # 扩展目录
|
||
├── composer.json
|
||
└── README.md
|
||
```
|
||
|
||
> 旧版 `addons/`（复数）已重命名为 `addon/`（单数），核心基类 `ywxapp/Addons.php` 已重命名为 `AddonBase.php`，请勿再使用旧的 `use ywxapp\Addons`。
|
||
|
||
---
|
||
|
||
## 五、多应用与访问入口
|
||
|
||
`config/app.php` 配置多应用映射（`app_map`）：
|
||
|
||
| 访问入口 | 应用目录 | 说明 |
|
||
| --- | --- | --- |
|
||
| `/`（默认） | `app/frontend` | 企业站/官网，`default_app=frontend` |
|
||
| `/admin/*` | `app/backend` | 后台管理（登录页 `/admin/login/index`） |
|
||
| `/user/*` | `app/member` | 会员中心（登录页 `/user/login/index`） |
|
||
| `/api/*` | `app/api` | 接口应用 |
|
||
|
||
后台升级相关控制器使用 `framework` 前缀路由（如 `framework/check`、`framework/upgrade`），请勿改回 `upgrade`。
|
||
|
||
---
|
||
|
||
## 六、插件开发
|
||
|
||
### 6.1 插件目录约定
|
||
|
||
```
|
||
addon/<name>/
|
||
├── info.php # 插件元信息（name/title/version/state/config…）
|
||
├── menu.json # 后台/会员/前台菜单（backend/member/frontend 三段）
|
||
├── route/
|
||
│ └── app.php # 路由（写相对组名，由 AppService 自动补全插件前缀）
|
||
├── controller/
|
||
│ ├── Index.php # 前台控制器
|
||
│ ├── backend/Article.php # 后台控制器
|
||
│ └── member/Article.php # 会员控制器
|
||
├── model/ # 模型（含 ensureSchema() 自愈）
|
||
├── service/ # 业务服务
|
||
├── view/ # 模板
|
||
├── install.sql # 安装 SQL（CREATE TABLE + 种子；禁 -- 注释、禁 \' 转义）
|
||
├── upgrade.sql # 升级 SQL
|
||
└── config.php # 插件配置（支持 .env 覆盖）
|
||
```
|
||
|
||
### 6.2 插件元信息 `info.php`
|
||
|
||
```php
|
||
return [
|
||
'name' => 'blog',
|
||
'title' => '博客应用',
|
||
'version' => '1.0.2',
|
||
'state' => 1, // 1=启用
|
||
'url' => '/blog',
|
||
'config' => [], // 插件配置项
|
||
];
|
||
```
|
||
|
||
### 6.3 控制器基类
|
||
|
||
插件控制器继承框架基类，后台控制器绑定 `AdminAuth` 须用 `static::class`：
|
||
|
||
```php
|
||
<?php
|
||
namespace addons\blog\controller\backend;
|
||
|
||
use ywxapp\AddonBase; // 注意：是 AddonBase，不是 Addons
|
||
use ywxapp\controller\BackendBase;
|
||
|
||
class Article extends BackendBase
|
||
{
|
||
// 禁止无参 fetch()，须 fetch('backend/article/index')
|
||
}
|
||
```
|
||
|
||
### 6.4 路由与菜单
|
||
|
||
- 插件 `route/app.php` 写相对组名，由 `AppService::loadAddonRoutes()` 的 `Route::group('<插件名>')` 补全，**不要**加前缀或 `->prefix('api/')`。
|
||
- **后台 URL 必须用「带点」形式**（`blog/backend.article/index`），因为 `Route::group` 下出现 `backend` 层级 TP 会拼成点分隔；斜杠形式恒 404。
|
||
- 修改 `menu.json` 后执行 `php think addon:repair <name> --menu` 重载菜单。
|
||
- **改完路由务必清路由缓存**：`Remove-Item runtime/route_list.php`，否则旧规则导致 404/500。
|
||
|
||
### 6.5 模型与数据库自愈
|
||
|
||
每个模型壳内置静态 `ensureSchema()` 自建表，`BaseModel` 提供 `ensureTable/ensureColumn/tableExists/ensureAutoIncrementPk/currentPrefix/ensureTableFromInstall`。部署时缺表缺列会自动补齐，无需手跑 SQL。
|
||
|
||
> 时间字段统一：`create_at` / `update_at` / `delete_at`（软删除 int 时间戳，0=未删）。
|
||
> 后台表 `admin_*` → `backend_*`；用户中心 `user_*` → `member_*`。
|
||
|
||
---
|
||
|
||
## 七、命令行工具
|
||
|
||
命令在 `ywxapp/service/AppService.php` 的 `boot()` 中显式注册（`config/console.php` 的 commands 不生效）。
|
||
|
||
| 命令 | 说明 |
|
||
| --- | --- |
|
||
| `php think addon:manage <name> -a develop` | 开发者模式安装（源码已在 `addon/<name>`，原地建表/注入菜单/启用，免打包） |
|
||
| `php think addon:manage <name> -a install [--local=<zip>] [--force]` | 在线/离线安装插件 |
|
||
| `php think addon:manage [<name>] -a reload [--force] [--status]` | 热重载插件（重导菜单/资源） |
|
||
| `php think addon:repair <name> [--menu\|--db\|--config]` | 一键修复：菜单重载 + 数据库自愈 + 配置补全；`<name>` 可为 `all` |
|
||
| `php think addon:make <name> -a <action> [--name=<类>]` | 脚手架：生成 controller/model/middleware/validate/event/listener/service/subscribe |
|
||
| `php think addon:health` | 插件健康检测（依赖/表/菜单完整性） |
|
||
| `php think addon:license-check` | 运行期授权校验 |
|
||
| `php think ywxapp:upgrade` | 框架在线升级（`framework` 路由配套） |
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 安装 blog 插件（开发者模式）
|
||
php think addon:manage blog -a develop
|
||
|
||
# 修复所有插件的菜单与数据库
|
||
php think addon:repair all
|
||
|
||
# 用脚手架生成一个后台控制器
|
||
php think addon:make blog -a controller --name=backend/Stat
|
||
```
|
||
|
||
---
|
||
|
||
## 八、后台使用与配置
|
||
|
||
- 后台入口：`/admin`（映射 `app/backend`），登录页 `/admin/login/index`
|
||
- 会员中心：`/user`，登录页 `/user/login/index`
|
||
- 主配置：`config/ywxapp.php`
|
||
- `usercenter`：是否开启前台会员中心
|
||
- `login_captcha` / `user_register_captcha`：登录/注册验证码
|
||
- `api_url`：应用市场 API 地址（中心站留空或 `market_mode=center`，客户机指向中心站域名）
|
||
- `addon_developer`：开发模式开关（开启后后台出现「设计插件」入口）
|
||
- `addon_license_check`：运行期授权校验开关
|
||
- `lang_switch_on`：多语言开关
|
||
|
||
### 中心站 / 客户机模式
|
||
|
||
由 `config/ywxapp.php` 的 `market_mode`（auto/center/client）决定，`auto` 时按 `api_url` 推导（空=中心站，指向他机=客户机）。解耦设计：中心站逻辑全在 `addon/appmall/`，`ywxapp/`、`app/` 禁直读 `appmall_*` 表；插件控制器只做分发（客户机 → 远程服务，中心站 → `MarketService`，缺失 → 503）。
|
||
|
||
---
|
||
|
||
## 九、打包与分发
|
||
|
||
- 插件包：`scripts/package_addon.php`（版本号自动递增）
|
||
- 框架包：`scripts/package_framework.php`（排除 `config/`、`.env`、`addon/`、`public/static/<插件名>/`）
|
||
- 升级：`AddonService::onlineUpgrade($version)`；`importsql` 仅放行 `CREATE TABLE`/`INSERT`，拒绝 `ALTER`/`DROP`（旧库迁移须手动 `RENAME TABLE`）
|
||
|
||
---
|
||
|
||
## 十、常见问题（FAQ）
|
||
|
||
**Q1：后台菜单点了 404？**
|
||
先确认 `menu.json` 的 `jump`/路由用的是「带点」形式（`blog/backend.article/index`），再 `php think addon:repair <name> --menu`，最后清路由缓存 `Remove-Item runtime/route_list.php`。
|
||
|
||
**Q2：插件装完页面破图 / 资源 404？**
|
||
执行 `php think addon:manage <name> -a reload` 重新发布静态资源到 `public/static/<name>/`。
|
||
|
||
**Q3：数据库表不存在报错？**
|
||
模型壳的 `ensureSchema()` 通常会自动建表；若仍报错执行 `php think addon:repair <name> --db`。
|
||
|
||
**Q4：改了插件代码不生效？**
|
||
多半是路由缓存。`Remove-Item runtime/route_list.php` 后重试；生产环境关闭 `APP_DEBUG` 前请先清缓存。
|
||
|
||
**Q5：PHP 文件上传后报「已发送头」/ 乱码？**
|
||
`write_to_file` 可能产生 UTF-8 BOM，上线前请去 BOM（或 `php -l` 校验）。
|
||
|
||
---
|
||
|
||
## 十一、许可与商业化
|
||
|
||
- 框架核心基于 ThinkPHP 协议，免费使用。
|
||
- 商业化通过 `addon/appmall` 应用市场分发插件与模板，支持购买、授权、域名绑定、分润提现。
|
||
- 详细商业化与运营文档见 `docs/`。
|
||
|
||
---
|
||
|
||
© 2026-2036 YwxApp. All rights reserved. https://www.ywxapp.cn
|