|
|
@@ -0,0 +1,1010 @@
|
|
|
+# 插件前端自动化部署方案
|
|
|
+
|
|
|
+## 📋 文档信息
|
|
|
+
|
|
|
+- **文档版本**: v1.0
|
|
|
+- **创建日期**: 2024-11-04
|
|
|
+- **作者**: AI Assistant
|
|
|
+- **项目**: SixShop 电商系统
|
|
|
+- **适用范围**: 所有带前端代码的插件
|
|
|
+
|
|
|
+## 🎯 方案目标
|
|
|
+
|
|
|
+### 当前问题
|
|
|
+
|
|
|
+1. **手动操作繁琐**
|
|
|
+ - 安装插件后需要手动复制前端代码
|
|
|
+ - 需要手动运行 `npm run build` 编译
|
|
|
+ - 卸载插件后需要手动删除前端代码
|
|
|
+
|
|
|
+2. **容易出错**
|
|
|
+ - 忘记复制前端代码导致功能不可用
|
|
|
+ - 忘记删除前端代码导致冗余文件
|
|
|
+ - 手动操作可能导致文件遗漏或错误
|
|
|
+
|
|
|
+3. **开发效率低**
|
|
|
+ - 每次测试都要重复手动操作
|
|
|
+ - 影响开发和测试效率
|
|
|
+
|
|
|
+### 期望目标
|
|
|
+
|
|
|
+1. **完全自动化**
|
|
|
+ - 安装插件时自动部署前端代码
|
|
|
+ - 自动触发编译（可选）
|
|
|
+ - 卸载插件时自动清理前端代码
|
|
|
+
|
|
|
+2. **安全可靠**
|
|
|
+ - 完善的错误处理
|
|
|
+ - 操作日志记录
|
|
|
+ - 支持回滚机制
|
|
|
+
|
|
|
+3. **用户友好**
|
|
|
+ - 实时进度反馈
|
|
|
+ - 清晰的状态提示
|
|
|
+ - 友好的错误信息
|
|
|
+
|
|
|
+## 🏗️ 架构设计
|
|
|
+
|
|
|
+### 用户操作流程
|
|
|
+
|
|
|
+#### 安装插件
|
|
|
+
|
|
|
+```
|
|
|
+用户访问插件管理页面
|
|
|
+http://localhost:3000/plugins/index
|
|
|
+ ↓
|
|
|
+点击插件的"安装"按钮
|
|
|
+ ↓
|
|
|
+前端发送 POST 请求
|
|
|
+POST https://sixshop.ddev.site/admin/system/extension/{plugin-id}/install
|
|
|
+ ↓
|
|
|
+后端处理安装
|
|
|
+ ├─ 1. 检查扩展状态
|
|
|
+ ├─ 2. 运行数据库迁移（创建表）
|
|
|
+ ├─ 3. 调用 Extension::install()
|
|
|
+ ├─ 4. 保存默认配置
|
|
|
+ └─ 5. 更新扩展状态为"已安装"
|
|
|
+ ↓
|
|
|
+触发 after_install_extension 事件
|
|
|
+ ↓
|
|
|
+✨ 自动部署前端代码
|
|
|
+FrontendDeployService::deploy()
|
|
|
+ ├─ 1. 检查插件是否有前端代码
|
|
|
+ ├─ 2. 复制前端代码到 frontend/admin/src/views/
|
|
|
+ ├─ 3. 记录部署日志
|
|
|
+ ├─ 4. 推送部署状态（可选）
|
|
|
+ └─ 5. 触发 npm 编译（可选）
|
|
|
+ ↓
|
|
|
+返回 200 OK
|
|
|
+ ↓
|
|
|
+前端显示"安装成功"
|
|
|
+用户可以立即使用插件功能
|
|
|
+```
|
|
|
+
|
|
|
+#### 卸载插件
|
|
|
+
|
|
|
+```
|
|
|
+用户访问插件管理页面
|
|
|
+http://localhost:3000/plugins/index
|
|
|
+ ↓
|
|
|
+点击插件的"卸载"按钮
|
|
|
+ ↓
|
|
|
+前端发送 POST 请求
|
|
|
+POST https://sixshop.ddev.site/admin/system/extension/{plugin-id}/uninstall
|
|
|
+ ↓
|
|
|
+触发 before_uninstall_extension 事件
|
|
|
+ ↓
|
|
|
+✨ 自动清理前端代码
|
|
|
+FrontendDeployService::remove()
|
|
|
+ ├─ 1. 检查前端代码是否存在
|
|
|
+ ├─ 2. 删除 frontend/admin/src/views/{plugin-id}/
|
|
|
+ ├─ 3. 记录删除日志
|
|
|
+ ├─ 4. 推送删除状态（可选）
|
|
|
+ └─ 5. 触发 npm 编译（可选）
|
|
|
+ ↓
|
|
|
+后端处理卸载
|
|
|
+ ├─ 1. 运行数据库回滚（删除表）
|
|
|
+ ├─ 2. 调用 Extension::uninstall()
|
|
|
+ ├─ 3. 删除配置数据
|
|
|
+ └─ 4. 更新扩展状态为"未安装"
|
|
|
+ ↓
|
|
|
+返回 200 OK
|
|
|
+ ↓
|
|
|
+前端显示"卸载成功"
|
|
|
+插件完全清理，不留痕迹
|
|
|
+```
|
|
|
+
|
|
|
+### 技术流程
|
|
|
+
|
|
|
+```
|
|
|
+ExtensionController::install()
|
|
|
+ ↓
|
|
|
+ExtensionManager::install()
|
|
|
+ ├─ 检查扩展状态
|
|
|
+ ├─ 运行数据库迁移
|
|
|
+ ├─ 调用 Extension::install()
|
|
|
+ └─ 更新扩展状态
|
|
|
+ ↓
|
|
|
+触发 after_install_extension 事件
|
|
|
+ ↓
|
|
|
+FrontendDeployService::deploy()
|
|
|
+ ├─ 检查是否有前端代码
|
|
|
+ ├─ 复制前端代码到 views 目录
|
|
|
+ ├─ 记录部署日志
|
|
|
+ ├─ 推送部署状态（可选）
|
|
|
+ └─ 触发 npm 编译（可选）
|
|
|
+ ↓
|
|
|
+返回安装成功
|
|
|
+```
|
|
|
+
|
|
|
+### 关键特性
|
|
|
+
|
|
|
+#### 1. 一键完成
|
|
|
+
|
|
|
+**安装**：
|
|
|
+- ✅ 用户只需点击一次"安装"按钮
|
|
|
+- ✅ 后端自动完成前端+后端安装
|
|
|
+- ✅ 前端代码自动部署到正确位置
|
|
|
+- ✅ 数据库表自动创建
|
|
|
+- ✅ 默认配置自动保存
|
|
|
+- ✅ 用户无需任何额外操作
|
|
|
+
|
|
|
+**卸载**：
|
|
|
+- ✅ 用户只需点击一次"卸载"按钮
|
|
|
+- ✅ 前端代码自动删除
|
|
|
+- ✅ 数据库表自动清理
|
|
|
+- ✅ 配置数据自动删除
|
|
|
+- ✅ 完全卸载，不留痕迹
|
|
|
+
|
|
|
+#### 2. 完全自动化
|
|
|
+
|
|
|
+**对用户**：
|
|
|
+- 无需手动复制文件
|
|
|
+- 无需手动运行命令
|
|
|
+- 无需手动删除文件
|
|
|
+- 安装即可用，卸载即清理
|
|
|
+
|
|
|
+**对开发者**：
|
|
|
+- 无需修改现有代码
|
|
|
+- 只需添加 frontend 目录
|
|
|
+- 系统自动处理一切
|
|
|
+
|
|
|
+**对系统**：
|
|
|
+- 不侵入现有流程
|
|
|
+- 通过事件监听实现
|
|
|
+- 解耦合，易维护
|
|
|
+
|
|
|
+#### 3. 智能检测
|
|
|
+
|
|
|
+**路径检测**：
|
|
|
+- 自动检测插件位置（runtime/extension 或 vendor）
|
|
|
+- 自动检测前端代码是否存在
|
|
|
+- 无前端代码自动跳过
|
|
|
+
|
|
|
+**状态管理**：
|
|
|
+- 实时记录部署状态
|
|
|
+- 完整的操作日志
|
|
|
+- 可追溯的部署历史
|
|
|
+
|
|
|
+#### 4. 安全可靠
|
|
|
+
|
|
|
+**安全性**：
|
|
|
+- 命令执行安全检查
|
|
|
+- 路径安全验证
|
|
|
+- 权限检查机制
|
|
|
+
|
|
|
+**可靠性**：
|
|
|
+- 完善的错误处理
|
|
|
+- 失败自动回滚
|
|
|
+- 不影响插件安装
|
|
|
+
|
|
|
+### 核心组件
|
|
|
+
|
|
|
+#### 1. FrontendDeployService（前端部署服务）
|
|
|
+
|
|
|
+**职责**：
|
|
|
+- 检查插件是否有前端代码
|
|
|
+- 复制/删除前端代码
|
|
|
+- 触发编译任务
|
|
|
+- 状态管理和日志记录
|
|
|
+
|
|
|
+**位置**：
|
|
|
+```
|
|
|
+backend/runtime/extension/system/src/Service/FrontendDeployService.php
|
|
|
+```
|
|
|
+
|
|
|
+#### 2. BuildFrontendJob（编译队列任务）
|
|
|
+
|
|
|
+**职责**：
|
|
|
+- 异步执行 npm 编译
|
|
|
+- 实时推送编译进度
|
|
|
+- 错误处理和日志记录
|
|
|
+
|
|
|
+**位置**：
|
|
|
+```
|
|
|
+backend/runtime/extension/system/src/Job/BuildFrontendJob.php
|
|
|
+```
|
|
|
+
|
|
|
+#### 3. 事件监听器
|
|
|
+
|
|
|
+**监听事件**：
|
|
|
+- `after_install_extension` - 安装后部署前端
|
|
|
+- `before_uninstall_extension` - 卸载前清理前端
|
|
|
+
|
|
|
+**位置**：
|
|
|
+```
|
|
|
+backend/runtime/extension/system/src/Extension.php
|
|
|
+```
|
|
|
+
|
|
|
+## 📁 文件结构
|
|
|
+
|
|
|
+### 插件安装位置
|
|
|
+
|
|
|
+插件可能安装在两个位置：
|
|
|
+
|
|
|
+#### 1. 本地开发插件（runtime/extension）
|
|
|
+```
|
|
|
+backend/runtime/extension/business-card/
|
|
|
+├── frontend/ ✨ 新增：前端代码目录
|
|
|
+│ └── business-card/ # 使用插件名称作为子目录
|
|
|
+│ ├── api/ # API 接口
|
|
|
+│ │ └── index.js
|
|
|
+│ ├── components/ # 组件
|
|
|
+│ │ ├── CardPanel.vue
|
|
|
+│ │ ├── CardForm.vue
|
|
|
+│ │ └── ...
|
|
|
+│ ├── index.vue # 主页面
|
|
|
+│ └── router.js # 路由配置
|
|
|
+├── src/ # 后端代码
|
|
|
+├── database/ # 数据库迁移
|
|
|
+└── ...
|
|
|
+```
|
|
|
+
|
|
|
+#### 2. Composer 安装插件（vendor）
|
|
|
+```
|
|
|
+backend/vendor/sixdec/business-card/
|
|
|
+├── frontend/ ✨ 新增：前端代码目录
|
|
|
+│ └── business-card/ # 使用插件名称作为子目录
|
|
|
+│ ├── api/
|
|
|
+│ ├── components/
|
|
|
+│ ├── index.vue
|
|
|
+│ └── router.js
|
|
|
+├── src/
|
|
|
+├── database/
|
|
|
+└── ...
|
|
|
+```
|
|
|
+
|
|
|
+**说明**：
|
|
|
+- `runtime/extension/` - 本地开发的插件
|
|
|
+- `vendor/six-shop/` - Six-Shop 官方插件
|
|
|
+- `vendor/sixdec/` - SixDec 第三方插件
|
|
|
+- 系统会自动检测插件的实际位置
|
|
|
+- **前端代码目录结构**：`frontend/{plugin-name}/` - 使用插件名称作为子目录，方便直接复制
|
|
|
+
|
|
|
+### 部署后的位置
|
|
|
+
|
|
|
+```
|
|
|
+frontend/admin/src/views/
|
|
|
+├── {plugin-name}/ ✨ 自动复制到这里
|
|
|
+│ ├── api/
|
|
|
+│ ├── components/
|
|
|
+│ ├── index.vue
|
|
|
+│ └── router.js
|
|
|
+├── other-plugin/
|
|
|
+└── ...
|
|
|
+```
|
|
|
+
|
|
|
+### 部署记录
|
|
|
+
|
|
|
+```
|
|
|
+backend/runtime/
|
|
|
+├── frontend_deploy/ ✨ 新增：部署记录目录
|
|
|
+│ ├── deployed.json # 已部署的插件列表
|
|
|
+│ └── logs/ # 部署日志
|
|
|
+│ ├── business-card.log
|
|
|
+│ └── ...
|
|
|
+└── ...
|
|
|
+```
|
|
|
+
|
|
|
+## 🔧 核心功能实现
|
|
|
+
|
|
|
+### 1. 插件路径检测
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 获取插件的实际路径
|
|
|
+ *
|
|
|
+ * 插件可能在两个位置：
|
|
|
+ * 1. runtime/extension/{plugin-name} - 本地开发
|
|
|
+ * 2. vendor/{vendor}/{plugin-name} - Composer 安装
|
|
|
+ */
|
|
|
+private function getPluginPath(string $extensionId): string
|
|
|
+{
|
|
|
+ // 方法 1: 使用 Helper::extension_path()
|
|
|
+ // 这个方法已经处理了路径检测
|
|
|
+ $path = Helper::extension_path($extensionId);
|
|
|
+ if (is_dir($path)) {
|
|
|
+ return $path;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 方法 2: 从 CoreService 获取 Composer 映射
|
|
|
+ if (isset(CoreService::$extensionComposerMap[$extensionId])) {
|
|
|
+ $composerInfo = CoreService::$extensionComposerMap[$extensionId];
|
|
|
+ $vendorPath = base_path('vendor/' . $composerInfo['name']);
|
|
|
+ if (is_dir($vendorPath)) {
|
|
|
+ return $vendorPath;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ // 方法 3: 手动检测常见路径
|
|
|
+ $possiblePaths = [
|
|
|
+ base_path('runtime/extension/' . $extensionId),
|
|
|
+ base_path('vendor/six-shop/' . $extensionId),
|
|
|
+ base_path('vendor/sixdec/' . $extensionId),
|
|
|
+ ];
|
|
|
+
|
|
|
+ foreach ($possiblePaths as $path) {
|
|
|
+ if (is_dir($path)) {
|
|
|
+ return $path;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ throw new RuntimeException("找不到插件路径：{$extensionId}");
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * 获取插件前端代码路径
|
|
|
+ */
|
|
|
+private function getPluginFrontendPath(string $extensionId): string
|
|
|
+{
|
|
|
+ $pluginPath = $this->getPluginPath($extensionId);
|
|
|
+ return $pluginPath . '/frontend';
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 2. 前端代码检测
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 检查插件是否有前端代码
|
|
|
+ */
|
|
|
+private function hasFrontendCode(string $extensionId): bool
|
|
|
+{
|
|
|
+ try {
|
|
|
+ $frontendPath = $this->getPluginFrontendPath($extensionId);
|
|
|
+ } catch (\Exception $e) {
|
|
|
+ Log::warning("获取插件路径失败：{$extensionId}，错误：" . $e->getMessage());
|
|
|
+ return false;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 检查目录是否存在
|
|
|
+ if (!is_dir($frontendPath)) {
|
|
|
+ return false;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 检查必需文件是否存在
|
|
|
+ $requiredFiles = ['index.vue', 'router.js'];
|
|
|
+ foreach ($requiredFiles as $file) {
|
|
|
+ if (!file_exists($frontendPath . '/' . $file)) {
|
|
|
+ Log::warning("插件 {$extensionId} 缺少必需文件：{$file}");
|
|
|
+ return false;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ return true;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 3. 文件复制
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 复制前端代码
|
|
|
+ *
|
|
|
+ * 源目录结构：{plugin-path}/frontend/business-card/
|
|
|
+ * 目标目录：frontend/admin/src/views/business-card/
|
|
|
+ *
|
|
|
+ * 直接复制 frontend/ 目录下的内容到 views/ 目录
|
|
|
+ */
|
|
|
+private function copyFrontendCode(string $extensionId): void
|
|
|
+{
|
|
|
+ // 1. 获取源目录：{plugin-path}/frontend/
|
|
|
+ $sourcePath = $this->getPluginPath($extensionId) . '/frontend';
|
|
|
+
|
|
|
+ if (!is_dir($sourcePath)) {
|
|
|
+ throw new RuntimeException("前端代码目录不存在：{$sourcePath}");
|
|
|
+ }
|
|
|
+
|
|
|
+ // 2. 获取目标目录：frontend/admin/src/views/
|
|
|
+ $targetPath = base_path('frontend/admin/src/views');
|
|
|
+
|
|
|
+ if (!is_dir($targetPath)) {
|
|
|
+ throw new RuntimeException("目标目录不存在：{$targetPath}");
|
|
|
+ }
|
|
|
+
|
|
|
+ // 3. 直接复制 frontend/ 目录下的所有内容
|
|
|
+ // 例如：frontend/business-card/ -> views/business-card/
|
|
|
+ $this->copyDirectory($sourcePath, $targetPath);
|
|
|
+
|
|
|
+ Log::info("前端代码复制成功：{$extensionId}");
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * 递归复制目录
|
|
|
+ */
|
|
|
+private function copyDirectory(string $source, string $target): void
|
|
|
+{
|
|
|
+ // 递归复制文件
|
|
|
+ $iterator = new \RecursiveIteratorIterator(
|
|
|
+ new \RecursiveDirectoryIterator($source, \RecursiveDirectoryIterator::SKIP_DOTS),
|
|
|
+ \RecursiveIteratorIterator::SELF_FIRST
|
|
|
+ );
|
|
|
+
|
|
|
+ foreach ($iterator as $item) {
|
|
|
+ // 计算目标路径
|
|
|
+ $subPath = $iterator->getSubPathName();
|
|
|
+ $targetPath = $target . DIRECTORY_SEPARATOR . $subPath;
|
|
|
+
|
|
|
+ if ($item->isDir()) {
|
|
|
+ // 创建目录
|
|
|
+ if (!is_dir($targetPath)) {
|
|
|
+ mkdir($targetPath, 0755, true);
|
|
|
+ }
|
|
|
+ } else {
|
|
|
+ // 复制文件
|
|
|
+ $targetDir = dirname($targetPath);
|
|
|
+ if (!is_dir($targetDir)) {
|
|
|
+ mkdir($targetDir, 0755, true);
|
|
|
+ }
|
|
|
+ copy($item, $targetPath);
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+**优势**：
|
|
|
+- ✅ 无需重命名，直接复制
|
|
|
+- ✅ 保持目录结构完整
|
|
|
+- ✅ 支持多层嵌套目录
|
|
|
+- ✅ 代码简单，易于维护
|
|
|
+
|
|
|
+**示例**：
|
|
|
+```
|
|
|
+源：backend/runtime/extension/business-card/frontend/business-card/
|
|
|
+目标：frontend/admin/src/views/business-card/
|
|
|
+
|
|
|
+复制结果：
|
|
|
+frontend/admin/src/views/
|
|
|
+└── business-card/
|
|
|
+ ├── api/
|
|
|
+ ├── components/
|
|
|
+ ├── index.vue
|
|
|
+ └── router.js
|
|
|
+```
|
|
|
+
|
|
|
+### 4. 文件删除
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 删除前端代码
|
|
|
+ */
|
|
|
+private function removeDirectory(string $path): void
|
|
|
+{
|
|
|
+ if (!is_dir($path)) {
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ $iterator = new \RecursiveIteratorIterator(
|
|
|
+ new \RecursiveDirectoryIterator($path, \RecursiveDirectoryIterator::SKIP_DOTS),
|
|
|
+ \RecursiveIteratorIterator::CHILD_FIRST
|
|
|
+ );
|
|
|
+
|
|
|
+ foreach ($iterator as $item) {
|
|
|
+ if ($item->isDir()) {
|
|
|
+ rmdir($item);
|
|
|
+ } else {
|
|
|
+ unlink($item);
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ rmdir($path);
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 5. 编译触发
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 触发前端编译
|
|
|
+ */
|
|
|
+private function triggerBuild(string $extensionId): void
|
|
|
+{
|
|
|
+ // 开发环境不编译
|
|
|
+ if (app()->isDebug()) {
|
|
|
+ Log::info("开发环境，跳过编译");
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 检查 exec 是否可用
|
|
|
+ if (!$this->isExecAvailable()) {
|
|
|
+ Log::warning("exec 函数被禁用，无法自动编译");
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 使用队列异步编译
|
|
|
+ Queue::push(new BuildFrontendJob($extensionId));
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 🔒 安全性设计
|
|
|
+
|
|
|
+### 1. 命令执行安全
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 检查 exec 是否可用
|
|
|
+ */
|
|
|
+private function isExecAvailable(): bool
|
|
|
+{
|
|
|
+ $disabled = explode(',', ini_get('disable_functions'));
|
|
|
+ return !in_array('exec', $disabled);
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * 安全执行命令
|
|
|
+ */
|
|
|
+private function safeExec(string $command): array
|
|
|
+{
|
|
|
+ // 1. 检查函数可用性
|
|
|
+ if (!$this->isExecAvailable()) {
|
|
|
+ throw new RuntimeException('exec 函数被禁用');
|
|
|
+ }
|
|
|
+
|
|
|
+ // 2. 转义命令
|
|
|
+ $command = escapeshellcmd($command);
|
|
|
+
|
|
|
+ // 3. 执行并获取输出
|
|
|
+ exec($command, $output, $returnCode);
|
|
|
+
|
|
|
+ return [
|
|
|
+ 'output' => $output,
|
|
|
+ 'code' => $returnCode
|
|
|
+ ];
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 2. 路径安全
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 验证路径安全性
|
|
|
+ */
|
|
|
+private function validatePath(string $path): bool
|
|
|
+{
|
|
|
+ // 1. 检查路径是否包含危险字符
|
|
|
+ if (preg_match('/\.\./', $path)) {
|
|
|
+ return false;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 2. 检查路径是否在允许的范围内
|
|
|
+ $allowedPaths = [
|
|
|
+ base_path('frontend/admin/src/views'),
|
|
|
+ Helper::extension_path()
|
|
|
+ ];
|
|
|
+
|
|
|
+ $realPath = realpath($path);
|
|
|
+ foreach ($allowedPaths as $allowedPath) {
|
|
|
+ if (strpos($realPath, realpath($allowedPath)) === 0) {
|
|
|
+ return true;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ return false;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 3. 权限检查
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 检查文件系统权限
|
|
|
+ */
|
|
|
+private function checkPermissions(): array
|
|
|
+{
|
|
|
+ $errors = [];
|
|
|
+
|
|
|
+ // 检查源目录可读
|
|
|
+ $sourcePath = Helper::extension_path();
|
|
|
+ if (!is_readable($sourcePath)) {
|
|
|
+ $errors[] = "源目录不可读：{$sourcePath}";
|
|
|
+ }
|
|
|
+
|
|
|
+ // 检查目标目录可写
|
|
|
+ $targetPath = base_path('frontend/admin/src/views');
|
|
|
+ if (!is_writable($targetPath)) {
|
|
|
+ $errors[] = "目标目录不可写：{$targetPath}";
|
|
|
+ }
|
|
|
+
|
|
|
+ return $errors;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 📊 进度反馈方案
|
|
|
+
|
|
|
+### 方案对比
|
|
|
+
|
|
|
+| 方案 | 实时性 | 实现难度 | 服务器要求 | 推荐度 |
|
|
|
+|------|--------|----------|-----------|--------|
|
|
|
+| WebSocket | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 需要 WebSocket | ⭐⭐⭐⭐ |
|
|
|
+| 轮询 | ⭐⭐⭐ | ⭐⭐ | 无特殊要求 | ⭐⭐⭐⭐⭐ |
|
|
|
+| 日志文件 | ⭐⭐ | ⭐ | 无特殊要求 | ⭐⭐⭐ |
|
|
|
+
|
|
|
+### 推荐方案：轮询 + 缓存
|
|
|
+
|
|
|
+#### 后端实现
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 设置部署状态
|
|
|
+ */
|
|
|
+private function setDeployStatus(string $extensionId, string $status, string $message, int $progress = 0): void
|
|
|
+{
|
|
|
+ cache('frontend_deploy_' . $extensionId, [
|
|
|
+ 'status' => $status, // idle, copying, building, success, error
|
|
|
+ 'message' => $message,
|
|
|
+ 'progress' => $progress, // 0-100
|
|
|
+ 'updated_at' => time()
|
|
|
+ ], 3600); // 缓存1小时
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * 获取部署状态
|
|
|
+ */
|
|
|
+public function getDeployStatus(string $extensionId): array
|
|
|
+{
|
|
|
+ return cache('frontend_deploy_' . $extensionId) ?: [
|
|
|
+ 'status' => 'idle',
|
|
|
+ 'message' => '',
|
|
|
+ 'progress' => 0,
|
|
|
+ 'updated_at' => 0
|
|
|
+ ];
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 前端实现
|
|
|
+
|
|
|
+```javascript
|
|
|
+// 安装插件后开始轮询
|
|
|
+async function installExtension(extensionId) {
|
|
|
+ // 1. 调用安装接口
|
|
|
+ await api.post(`/extension/${extensionId}/install`)
|
|
|
+
|
|
|
+ // 2. 开始轮询部署状态
|
|
|
+ startPolling(extensionId)
|
|
|
+}
|
|
|
+
|
|
|
+// 轮询部署状态
|
|
|
+function startPolling(extensionId) {
|
|
|
+ const timer = setInterval(async () => {
|
|
|
+ const status = await api.get(`/extension/${extensionId}/deploy-status`)
|
|
|
+
|
|
|
+ // 更新进度条
|
|
|
+ updateProgress(status.progress, status.message)
|
|
|
+
|
|
|
+ // 检查是否完成
|
|
|
+ if (status.status === 'success') {
|
|
|
+ ElMessage.success('安装完成！')
|
|
|
+ clearInterval(timer)
|
|
|
+ } else if (status.status === 'error') {
|
|
|
+ ElMessage.error('安装失败：' + status.message)
|
|
|
+ clearInterval(timer)
|
|
|
+ }
|
|
|
+ }, 2000) // 每2秒查询一次
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 🔄 兼容性处理
|
|
|
+
|
|
|
+### 1. 无前端代码的插件
|
|
|
+
|
|
|
+```php
|
|
|
+public function deploy(string $extensionId): bool
|
|
|
+{
|
|
|
+ // 检查是否有前端代码
|
|
|
+ if (!$this->hasFrontendCode($extensionId)) {
|
|
|
+ Log::info("插件 {$extensionId} 没有前端代码，跳过部署");
|
|
|
+ return true; // 返回 true 表示成功（跳过）
|
|
|
+ }
|
|
|
+
|
|
|
+ // 继续部署流程...
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 2. exec 函数被禁用
|
|
|
+
|
|
|
+```php
|
|
|
+private function triggerBuild(string $extensionId): void
|
|
|
+{
|
|
|
+ if (!$this->isExecAvailable()) {
|
|
|
+ // 记录警告
|
|
|
+ Log::warning("exec 函数被禁用，无法自动编译");
|
|
|
+
|
|
|
+ // 写入标记文件，提示用户手动编译
|
|
|
+ file_put_contents(
|
|
|
+ runtime_path('need_build.txt'),
|
|
|
+ "请手动执行：cd frontend/admin && npm run build\n",
|
|
|
+ FILE_APPEND
|
|
|
+ );
|
|
|
+
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ // 正常编译流程...
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 3. 编译失败处理
|
|
|
+
|
|
|
+```php
|
|
|
+class BuildFrontendJob
|
|
|
+{
|
|
|
+ public function handle(): void
|
|
|
+ {
|
|
|
+ try {
|
|
|
+ // 执行编译
|
|
|
+ $result = $this->safeExec('cd frontend/admin && npm run build');
|
|
|
+
|
|
|
+ if ($result['code'] !== 0) {
|
|
|
+ throw new RuntimeException('编译失败：' . implode("\n", $result['output']));
|
|
|
+ }
|
|
|
+
|
|
|
+ // 更新状态为成功
|
|
|
+ $this->setStatus('success', '编译完成', 100);
|
|
|
+
|
|
|
+ } catch (\Exception $e) {
|
|
|
+ // 记录错误
|
|
|
+ Log::error('前端编译失败：' . $e->getMessage());
|
|
|
+
|
|
|
+ // 更新状态为失败
|
|
|
+ $this->setStatus('error', $e->getMessage(), 0);
|
|
|
+
|
|
|
+ // 不抛出异常，避免影响其他任务
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 📝 部署记录
|
|
|
+
|
|
|
+### 记录格式
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "deployed": [
|
|
|
+ {
|
|
|
+ "extension_id": "business-card",
|
|
|
+ "deployed_at": "2024-11-04 10:30:00",
|
|
|
+ "source_path": "/path/to/extension/business-card/frontend",
|
|
|
+ "target_path": "/path/to/admin/views/business-card",
|
|
|
+ "files_count": 15,
|
|
|
+ "status": "success"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 记录管理
|
|
|
+
|
|
|
+```php
|
|
|
+/**
|
|
|
+ * 记录部署信息
|
|
|
+ */
|
|
|
+private function logDeploy(string $extensionId, array $info): void
|
|
|
+{
|
|
|
+ $logFile = runtime_path('frontend_deploy/deployed.json');
|
|
|
+
|
|
|
+ // 读取现有记录
|
|
|
+ $deployed = [];
|
|
|
+ if (file_exists($logFile)) {
|
|
|
+ $deployed = json_decode(file_get_contents($logFile), true);
|
|
|
+ }
|
|
|
+
|
|
|
+ // 添加新记录
|
|
|
+ $deployed['deployed'][] = array_merge([
|
|
|
+ 'extension_id' => $extensionId,
|
|
|
+ 'deployed_at' => date('Y-m-d H:i:s'),
|
|
|
+ ], $info);
|
|
|
+
|
|
|
+ // 写入文件
|
|
|
+ file_put_contents($logFile, json_encode($deployed, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE));
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 🧪 测试方案
|
|
|
+
|
|
|
+### 测试场景
|
|
|
+
|
|
|
+1. **正常安装**
|
|
|
+ - 有前端代码的插件
|
|
|
+ - 自动复制和编译
|
|
|
+
|
|
|
+2. **无前端代码**
|
|
|
+ - 没有 frontend 目录的插件
|
|
|
+ - 跳过前端部署
|
|
|
+
|
|
|
+3. **重复安装**
|
|
|
+ - 已安装的插件
|
|
|
+ - 覆盖现有文件
|
|
|
+
|
|
|
+4. **卸载清理**
|
|
|
+ - 删除前端代码
|
|
|
+ - 清理部署记录
|
|
|
+
|
|
|
+5. **异常处理**
|
|
|
+ - 权限不足
|
|
|
+ - exec 被禁用
|
|
|
+ - 编译失败
|
|
|
+
|
|
|
+### 测试步骤
|
|
|
+
|
|
|
+```bash
|
|
|
+# 1. 测试安装
|
|
|
+POST /admin/system/extension/business_card/install
|
|
|
+
|
|
|
+# 2. 检查文件是否复制
|
|
|
+ls frontend/admin/src/views/business-card
|
|
|
+
|
|
|
+# 3. 检查部署状态
|
|
|
+GET /admin/system/extension/business_card/deploy-status
|
|
|
+
|
|
|
+# 4. 测试卸载
|
|
|
+POST /admin/system/extension/business_card/uninstall
|
|
|
+
|
|
|
+# 5. 检查文件是否删除
|
|
|
+ls frontend/admin/src/views/business-card # 应该不存在
|
|
|
+```
|
|
|
+
|
|
|
+## 📈 性能优化
|
|
|
+
|
|
|
+### 1. 异步处理
|
|
|
+
|
|
|
+- 文件复制：同步执行（快速）
|
|
|
+- npm 编译：异步队列（慢速）
|
|
|
+- 状态推送：异步（不阻塞）
|
|
|
+
|
|
|
+### 2. 缓存策略
|
|
|
+
|
|
|
+- 部署状态：缓存 1 小时
|
|
|
+- 部署记录：持久化存储
|
|
|
+- 编译日志：定期清理
|
|
|
+
|
|
|
+### 3. 队列优化
|
|
|
+
|
|
|
+```php
|
|
|
+// 使用延迟队列，避免并发编译
|
|
|
+Queue::later(5, new BuildFrontendJob($extensionId));
|
|
|
+
|
|
|
+// 使用队列优先级
|
|
|
+Queue::push(new BuildFrontendJob($extensionId), '', 'high');
|
|
|
+```
|
|
|
+
|
|
|
+## 🚀 实施计划
|
|
|
+
|
|
|
+### 阶段 1: 核心功能（1-2天）
|
|
|
+
|
|
|
+- [ ] 创建 FrontendDeployService
|
|
|
+- [ ] 实现文件复制/删除
|
|
|
+- [ ] 注册事件监听
|
|
|
+- [ ] 基础测试
|
|
|
+
|
|
|
+### 阶段 2: 编译功能（1天）
|
|
|
+
|
|
|
+- [ ] 创建 BuildFrontendJob
|
|
|
+- [ ] 实现安全的命令执行
|
|
|
+- [ ] 错误处理和日志
|
|
|
+
|
|
|
+### 阶段 3: 进度反馈（1天）
|
|
|
+
|
|
|
+- [ ] 实现状态管理
|
|
|
+- [ ] 添加 API 接口
|
|
|
+- [ ] 前端轮询实现
|
|
|
+
|
|
|
+### 阶段 4: 完善和测试（1天）
|
|
|
+
|
|
|
+- [ ] 完整测试所有场景
|
|
|
+- [ ] 优化性能
|
|
|
+- [ ] 编写文档
|
|
|
+
|
|
|
+## 📚 使用文档
|
|
|
+
|
|
|
+### 插件开发者
|
|
|
+
|
|
|
+#### 1. 创建前端代码目录
|
|
|
+
|
|
|
+```bash
|
|
|
+cd backend/runtime/extension/your-plugin
|
|
|
+mkdir frontend
|
|
|
+```
|
|
|
+
|
|
|
+#### 2. 组织前端代码
|
|
|
+
|
|
|
+```
|
|
|
+frontend/
|
|
|
+├── api/
|
|
|
+│ └── index.js
|
|
|
+├── components/
|
|
|
+│ └── YourComponent.vue
|
|
|
+├── index.vue
|
|
|
+└── router.js
|
|
|
+```
|
|
|
+
|
|
|
+#### 3. 测试安装
|
|
|
+
|
|
|
+```bash
|
|
|
+# 安装插件
|
|
|
+POST /admin/system/extension/your-plugin/install
|
|
|
+
|
|
|
+# 检查前端代码
|
|
|
+ls frontend/admin/src/views/your-plugin
|
|
|
+```
|
|
|
+
|
|
|
+### 系统管理员
|
|
|
+
|
|
|
+#### 1. 检查权限
|
|
|
+
|
|
|
+```bash
|
|
|
+# 检查目录权限
|
|
|
+ls -la frontend/admin/src/views
|
|
|
+ls -la backend/runtime/extension
|
|
|
+```
|
|
|
+
|
|
|
+#### 2. 查看部署日志
|
|
|
+
|
|
|
+```bash
|
|
|
+# 查看部署记录
|
|
|
+cat backend/runtime/frontend_deploy/deployed.json
|
|
|
+
|
|
|
+# 查看编译日志
|
|
|
+cat backend/runtime/frontend_deploy/logs/your-plugin.log
|
|
|
+```
|
|
|
+
|
|
|
+#### 3. 手动编译
|
|
|
+
|
|
|
+```bash
|
|
|
+# 如果自动编译失败，可以手动编译
|
|
|
+cd frontend/admin
|
|
|
+npm run build
|
|
|
+```
|
|
|
+
|
|
|
+## ❓ 常见问题
|
|
|
+
|
|
|
+### Q1: exec 函数被禁用怎么办？
|
|
|
+
|
|
|
+**A**: 系统会自动检测并跳过编译，生成提示文件 `runtime/need_build.txt`，管理员可以手动执行编译。
|
|
|
+
|
|
|
+### Q2: 编译很慢怎么办？
|
|
|
+
|
|
|
+**A**: 编译是异步执行的，不会阻塞安装流程。可以通过轮询查看编译进度。
|
|
|
+
|
|
|
+### Q3: 安装失败如何回滚？
|
|
|
+
|
|
|
+**A**: 系统会自动删除已复制的文件，不会留下垃圾文件。
|
|
|
+
|
|
|
+### Q4: 开发时需要每次编译吗？
|
|
|
+
|
|
|
+**A**: 不需要。开发环境会跳过编译，直接使用 Vite 热更新。
|
|
|
+
|
|
|
+### Q5: 如何查看部署状态？
|
|
|
+
|
|
|
+**A**: 调用 API：`GET /admin/system/extension/{id}/deploy-status`
|
|
|
+
|
|
|
+## 📞 技术支持
|
|
|
+
|
|
|
+如有问题，请联系：
|
|
|
+- 邮箱：support@sixdec.com
|
|
|
+- 文档：查看本文档
|
|
|
+- 日志：`backend/runtime/frontend_deploy/logs/`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+**文档结束**
|
