CRMEB/backend/driver/upload/DEVELOPMENT.md

上传驱动扩展开发指南

概述

上传驱动扩展位于 driver/upload/{Driver}/ 目录，负责对接多种云存储服务（本地存储、阿里云OSS、腾讯云COS、七牛云等）。

系统通过 crmeb\services\driver\DriverRegistry 扫描各驱动包的 plugin.json 完成驱动注册。

已有驱动

驱动目录	驱动标识	说明
Local	local	本地存储（开箱即用）
Oss	oss	阿里云OSS
Cos	cos	腾讯云COS
Qiniu	qiniu	七牛云
Obs	obs	华为云OBS
Jdoss	jdoss	京东云OSS
Tyoss	tyoss	天翼云OSS

开发步骤

1. 创建驱动目录

mkdir -p driver/upload/{DriverName}

2. 创建 plugin.json

{
    "key": "your_driver_key",
    "name": "存储名称",
    "description": "驱动功能简述",
    "version": "1.0.0",
    "author": "CRMEB",
    "type": "driver",
    "path": "driver/upload/YourDriver",
    "require": {
        "crmeb": "^6.0",
        "php": "^8.0"
    },
    "driver": {
        "name": "存储名称",
        "driver_key": "your_driver_key",
        "class_name": "Driver",
        "icon": "icon-xxx",
        "is_builtin": true,
        "sort": 100,
        "domain_template": "https://{bucket}.oss-cn-hangzhou.aliyuncs.com",
        "capabilities": ["upload", "delete", "stream", "thumb", "water"],
        "config_fields": [
            {"field": "access_key", "label": "AccessKey", "type": "text", "required": true, "group": "密钥"},
            {"field": "secret_key", "label": "SecretKey", "type": "password", "required": true, "group": "密钥"},
            {"field": "bucket", "label": "存储空间", "type": "text", "required": true, "group": "存储"}
        ],
        "bucket_fields": [
            {"field": "region", "label": "地域", "type": "text", "group": "存储"}
        ],
        "help_doc": {
            "title": "使用说明",
            "steps": ["步骤1", "步骤2"],
            "link": "https://example.com"
        }
    }
}

plugin.json driver 子对象字段说明

位置	字段	类型	必填	说明
driver	name	string	✅	驱动名称
driver	driver_key	string	✅	驱动唯一标识
driver	class_name	string	❌	驱动类名，默认 Driver
driver	icon	string	❌	图标类名
driver	domain_template	string	❌	域名模板（用于生成访问地址）
driver	is_builtin	bool	❌	是否内置
driver	sort	int	❌	排序
driver	capabilities	array	❌	能力声明（upload 上传 / delete 删除 / stream 流上传 / thumb 缩略图 / water 水印）
driver	config_fields	array	❌	配置字段
driver	bucket_fields	array	❌	存储空间配置字段
driver	help_doc	object	❌	帮助文档

顶层字段（key/name/description/version/author/type/path/require）与通用 driver 插件一致，参见 sms/DEVELOPMENT.md 的字段说明表。

3. 创建 Driver.php

<?php
namespace driver\upload\{DriverName};

use crmeb\services\upload\BaseUpload;

/**
 * {DriverName} 上传
 * Class Driver
 * @package driver\upload\{DriverName}
 */
class Driver extends BaseUpload
{
    protected function initialize(array $config): void
    {
        parent::initialize($config);
        // 初始化客户端
    }

    /**
     * 文件上传
     * @param string $file 表单字段名
     * @param bool $realName 是否保留原始文件名
     * @return array|bool|\StdClass
     */
    public function move(string $file = 'file', $realName = false)
    {
        // 实现文件上传逻辑
    }

    /**
     * 删除文件
     * @param string $filePath
     * @return bool
     */
    public function delete(string $filePath): bool
    {
        // 实现文件删除逻辑
    }

    /**
     * 获取文件路径
     * @param string $key
     * @return string
     */
    public function getFilePath(string $key): string
    {
        // 返回文件完整访问URL
    }
}

4. 验证驱动

use crmeb\services\driver\DriverRegistry;

$drivers = DriverRegistry::scan('upload');                              // 全部上传驱动
$class   = DriverRegistry::getDriverClass('upload', 'your_driver_key'); // 完整类名 driver\upload\YourDriver\Driver

接口规范

必须实现的方法

方法	说明	返回值
move()	文件上传（form表单）	\StdClass
delete()	删除文件	bool
getFilePath()	获取文件访问路径	string

可选实现的方法

方法	说明	适用场景
stream()	文件流上传	远程下载文件
down()	文件流下载保存	保存远程资源
thumb()	生成缩略图	本地存储
water()	添加水印	本地存储
image()	图片水印	本地存储
text()	文字水印	本地存储
upload()	文件路径上传	服务端文件操作
listbuckets()	获取存储空间列表	云存储
createBucket()	创建存储空间	云存储
setBucketCors()	设置跨域规则	云存储
bindDomian()	绑定域名	云存储
getDomian()	获取域名列表	云存储
getRegion()	获取区域列表	云存储
getTempKeys()	获取临时密钥（前端直传）	云存储
to()	设置上传路径	链式调用
validate()	设置验证规则	链式调用

链式调用模式

上传驱动支持链式调用，新增驱动需支持：

$upload = app()->make(\crmeb\services\upload\UploadService::class);
$result = $upload->to('product/2025/01')
    ->validate(['fileExt' => ['jpg','png'], 'filesize' => 2097152])
    ->move('file');

云存储客户端封装

对于云存储，建议在 extend/ 目录中封装 SDK 客户端：

driver/upload/{DriverName}/
├── Driver.php
├── plugin.json
└── extend/
    └── {driver}/
        ├── Client.php       # 客户端封装
        ├── Signature.php    # 签名工具（可选）
        └── ...              # 其他辅助类

参考实现

• 本地存储 Local — 完整上传/缩略图/水印实现
• 腾讯云COS — 云存储实现参考（含客户端封装）