# 阿里云OSS图片上传方法说明

**文档日期**：2025年1月  
**文件位置**：`netcore/src/Modularity/System/NCC.System/Service/Common/FileService.cs`

---

## 一、核心上传方法

### 1.1 标准文件上传方法

**方法名**：`Uploader`  
**位置**：`FileService.cs` 第60-95行  
**接口路径**：`POST /api/File/Uploader/{type}`

**功能**：
- 上传文件/图片到服务器或OSS
- 支持多种存储类型（本地、MinIO、阿里云OSS、腾讯云COS）
- `annexpic` 类型强制使用阿里云OSS存储

**参数**：
- `type`：文件类型（如：`annexpic`、`avatar`、`temporary` 等）
- `file`：上传的文件（`IFormFile`）

**返回值**：
```json
{
  "name": "原始文件名.jpg",
  "fileId": "20250123_123456789.jpg",
  "url": "https://oss.example.com/2025/01/23/20250123_123456789.jpg?签名参数"
}
```

**关键代码**：
```csharp
[HttpPost("Uploader/{type}")]
[AllowAnonymous]
public async Task<dynamic> Uploader(string type, IFormFile file)
{
    // 1. 验证文件类型
    var fileType = Path.GetExtension(file.FileName).Replace(".", "");
    if (!this.AllowFileType(fileType, type))
        throw NCCException.Oh(ErrorCode.D1800);
    
    // 2. 生成文件路径和文件名
    var _filePath = GetPathByType(type);
    var now = DateTime.Now;
    var _fileName = now.ToString("yyyyMMdd") + "_" + YitIdHelper.NextId().ToString() + Path.GetExtension(file.FileName);
    
    // 3. annexpic 类型强制使用阿里云OSS存储
    string forceStoreType = type == "annexpic" ? "aliyun-oss" : null;
    string uploadFilePath = _filePath;
    if (type == "annexpic")
    {
        // 按天生成文件夹：yyyy/MM/dd
        var dateFolder = now.ToString("yyyy/MM/dd");
        uploadFilePath = dateFolder;
    }
    
    // 4. 上传文件
    await UploadFileByType(file, uploadFilePath, _fileName, forceStoreType);
    
    // 5. 获取访问URL
    string fileUrl;
    if (type == "annexpic")
    {
        fileUrl = await GetOSSAccessUrl(uploadFilePath, _fileName);
    }
    else
    {
        fileUrl = string.Format("/api/File/Image/{0}/{1}", type, _fileName);
    }
    
    return new { name = file.FileName, fileId = _fileName, url = fileUrl };
}
```

---

### 1.2 Base64图片上传方法

**方法名**：`UploadBase64Image`  
**位置**：`FileService.cs` 第696-775行  
**接口路径**：`POST /api/File/UploadBase64Image`

**功能**：
- 上传Base64格式的图片到阿里云OSS
- 自动解析Base64数据并提取图片格式
- 所有类型都上传到阿里云OSS存储

**参数**（`Base64ImageUploadInput`）：
```json
{
  "base64Data": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
  "fileName": "图片名称（可选）",
  "imageType": "annexpic（可选，默认为temporary）"
}
```

**返回值**：
```json
{
  "name": "图片名称.jpg",
  "fileId": "20250123_123456789.jpg",
  "url": "https://oss.example.com/2025/01/23/20250123_123456789.jpg?签名参数",
  "fileSize": 12345,
  "imageFormat": "JPEG",
  "imageType": "annexpic"
}
```

**关键代码**：
```csharp
[HttpPost("UploadBase64Image")]
[AllowAnonymous]
public async Task<dynamic> UploadBase64Image([FromBody] Base64ImageUploadInput input)
{
    // 1. 解析Base64数据
    var imageData = ParseBase64Data(input.Base64Data, out string imageFormat);
    
    // 2. 验证图片格式
    if (!IsValidImageFormat(imageFormat))
        throw NCCException.Oh($"不支持的图片格式: {imageFormat}");
    
    // 3. 生成文件路径和文件名
    var imageType = string.IsNullOrEmpty(input.ImageType) ? "temporary" : input.ImageType;
    var now = DateTime.Now;
    
    string uploadFilePath;
    string fileName;
    
    if (imageType == "annexpic")
    {
        fileName = now.ToString("yyyyMMdd") + "_" + YitIdHelper.NextId().ToString() + "." + imageFormat;
        var dateFolder = now.ToString("yyyy/MM/dd");
        uploadFilePath = dateFolder;
    }
    else
    {
        fileName = GenerateImageFileName(input.FileName, imageFormat);
        var originalPath = GetPathByType(imageType).TrimEnd('/').TrimEnd('\\');
        var dateFolder = now.ToString("yyyy/MM/dd");
        uploadFilePath = $"{originalPath}/{dateFolder}";
    }
    
    // 4. 上传到OSS
    var bucketName = KeyVariable.BucketName;
    var ossPath = $"{uploadFilePath.TrimEnd('/').TrimEnd('\\')}/{fileName}";
    using (var stream = new MemoryStream(imageData))
    {
        await _oSSServiceFactory.Create("aliyun").PutObjectAsync(bucketName, ossPath, stream);
    }
    
    // 5. 获取OSS访问URL
    string accessUrl = await GetOSSAccessUrl(uploadFilePath, fileName);
    
    return new
    {
        name = originalFileName,
        fileId = fileName,
        url = accessUrl,
        fileSize = imageData.Length,
        imageFormat = imageFormat.ToUpper(),
        imageType = imageType,
    };
}
```

---

## 二、核心上传逻辑

### 2.1 UploadFileByType 方法

**位置**：`FileService.cs` 第301-344行  
**功能**：根据存储类型上传文件

**关键代码**：
```csharp
[NonAction]
public async Task UploadFileByType(IFormFile file, string filePath, string fileName, string forceStoreType = null)
{
    var bucketName = KeyVariable.BucketName;
    var fileStoreType = !string.IsNullOrEmpty(forceStoreType) ? forceStoreType : KeyVariable.FileStoreType;
    
    // OSS路径使用正斜杠，不使用Path.Combine
    var uploadPath = fileStoreType == "aliyun-oss" || fileStoreType == "tencent-cos" || fileStoreType == "minio"
        ? $"{filePath.TrimEnd('/').TrimEnd('\\')}/{fileName}"
        : Path.Combine(filePath, fileName);
    
    var stream = file.OpenReadStream();
    switch (fileStoreType)
    {
        case "minio":
            await _oSSServiceFactory.Create().PutObjectAsync(bucketName, uploadPath, stream);
            break;
        case "aliyun-oss":
            // ✅ 阿里云OSS上传
            await _oSSServiceFactory.Create("aliyun").PutObjectAsync(bucketName, uploadPath, stream);
            break;
        case "tencent-cos":
            await _oSSServiceFactory.Create("qcloud").PutObjectAsync(bucketName, uploadPath, stream);
            break;
        default:
            // 本地存储
            if (!Directory.Exists(filePath))
                Directory.CreateDirectory(filePath);
            using (var stream4 = File.Create(uploadPath))
            {
                await file.CopyToAsync(stream4);
            }
            break;
    }
}
```

**关键点**：
- ✅ 使用 `_oSSServiceFactory.Create("aliyun")` 创建阿里云OSS服务
- ✅ 使用 `PutObjectAsync(bucketName, uploadPath, stream)` 上传文件
- ✅ OSS路径使用正斜杠 `/`，不使用 `Path.Combine`

---

### 2.2 GetOSSAccessUrl 方法

**位置**：`FileService.cs` 第391-476行  
**功能**：获取阿里云OSS文件的访问URL（带签名的临时访问URL）

**关键代码**：
```csharp
[NonAction]
private async Task<string> GetOSSAccessUrl(string filePath, string fileName)
{
    var bucketName = KeyVariable.BucketName;
    var uploadPath = $"{filePath.TrimEnd('/').TrimEnd('\\')}/{fileName}";
    
    // 使用OSS服务生成带签名的临时访问URL（有效期24小时）
    var ossService = _oSSServiceFactory.Create("aliyun");
    var presignedUrl = await ossService.PresignedGetObjectAsync(bucketName, uploadPath, 86400);
    
    // 获取带签名的URL字符串
    string urlString = string.Empty;
    if (presignedUrl != null)
    {
        var urlType = presignedUrl.GetType();
        var absoluteUriProp = urlType.GetProperty("AbsoluteUri");
        if (absoluteUriProp != null)
        {
            urlString = absoluteUriProp.GetValue(presignedUrl)?.ToString() ?? string.Empty;
        }
        else
        {
            urlString = presignedUrl.ToString() ?? string.Empty;
        }
    }
    
    // 如果配置了自定义域名，替换为自定义域名
    var customDomain = _configuration["NCC_App:AliyunOSS:CustomDomain"]
        ?? _configuration["NCC_APP:AliyunOSS:CustomDomain"];
    
    if (!string.IsNullOrEmpty(customDomain))
    {
        // 替换域名逻辑...
    }
    
    return urlString;
}
```

**关键点**：
- ✅ 使用 `PresignedGetObjectAsync` 生成带签名的临时访问URL
- ✅ 有效期：86400秒（24小时）
- ✅ 支持自定义域名配置

---

## 三、OSS服务配置

### 3.1 服务注册

**位置**：`Startup.cs` 第109-137行

**配置代码**：
```csharp
#region 阿里云OSS

var aliyunOSSEndpoint = App.Configuration["NCC_App:AliyunOSS:Endpoint"];
var aliyunOSSAccessKey = App.Configuration["NCC_App:AliyunOSS:AccessKeyId"];
var aliyunOSSSecretKey = App.Configuration["NCC_App:AliyunOSS:AccessKeySecret"];
var aliyunOSSRegion = App.Configuration["NCC_App:AliyunOSS:Region"];
var bucketName = App.Configuration["NCC_App:BucketName"];

if (!string.IsNullOrEmpty(aliyunOSSEndpoint) && !string.IsNullOrEmpty(aliyunOSSAccessKey) && !string.IsNullOrEmpty(aliyunOSSSecretKey))
{
    services.AddOSSService("aliyun", option =>
    {
        option.Provider = OSSProvider.Aliyun;
        option.Endpoint = aliyunOSSEndpoint;  // 格式：oss-{region}.aliyuncs.com
        option.AccessKey = aliyunOSSAccessKey;
        option.SecretKey = aliyunOSSSecretKey;
        option.IsEnableHttps = true;
        option.IsEnableCache = true;
        if (!string.IsNullOrEmpty(aliyunOSSRegion))
        {
            option.Region = aliyunOSSRegion;  // 如：cn-chengdu
        }
    });
}

#endregion
```

### 3.2 配置文件

**位置**：`appsettings.json`

**配置项**：
```json
{
  "NCC_App": {
    "AliyunOSS": {
      "Endpoint": "oss-cn-chengdu.aliyuncs.com",
      "AccessKeyId": "your-access-key-id",
      "AccessKeySecret": "your-access-key-secret",
      "Region": "cn-chengdu",
      "CustomDomain": "https://cdn.example.com"  // 可选，自定义域名
    },
    "BucketName": "your-bucket-name",
    "FileStoreType": "aliyun-oss"  // 默认存储类型
  }
}
```

---

## 四、使用示例

### 4.1 标准文件上传

**前端调用**：
```javascript
// 使用 FormData
const formData = new FormData();
formData.append('file', file);

const response = await fetch('/api/File/Uploader/annexpic', {
  method: 'POST',
  body: formData
});

const result = await response.json();
// result: { name: "原始文件名.jpg", fileId: "20250123_123456789.jpg", url: "https://..." }
```

**curl 示例**：
```bash
curl -X POST "http://localhost:2011/api/File/Uploader/annexpic" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/image.jpg"
```

---

### 4.2 Base64图片上传

**前端调用**：
```javascript
const base64Data = "data:image/jpeg;base64,/9j/4AAQSkZJRg...";

const response = await fetch('/api/File/UploadBase64Image', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    base64Data: base64Data,
    fileName: "图片名称",
    imageType: "annexpic"
  })
});

const result = await response.json();
// result: { name: "图片名称.jpg", fileId: "20250123_123456789.jpg", url: "https://...", fileSize: 12345, imageFormat: "JPEG", imageType: "annexpic" }
```

**curl 示例**：
```bash
curl -X POST "http://localhost:2011/api/File/UploadBase64Image" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "fileName": "图片名称",
    "imageType": "annexpic"
  }'
```

---

## 五、文件路径规则

### 5.1 annexpic 类型

- **文件夹结构**：`yyyy/MM/dd`（如：`2025/01/23`）
- **文件名格式**：`yyyyMMdd_{ID}.{ext}`（如：`20250123_123456789.jpg`）
- **完整路径**：`2025/01/23/20250123_123456789.jpg`
- **存储类型**：强制使用阿里云OSS

### 5.2 其他类型

- **文件夹结构**：`{原始路径}/yyyy/MM/dd`
- **文件名格式**：根据类型生成
- **存储类型**：根据配置决定（`KeyVariable.FileStoreType`）

---

## 六、依赖服务

### 6.1 IOSSServiceFactory

**接口**：`IOSSServiceFactory`  
**实现**：`OnceMi.AspNetCore.OSS` 库

**使用方式**：
```csharp
// 创建阿里云OSS服务
var ossService = _oSSServiceFactory.Create("aliyun");

// 上传文件
await ossService.PutObjectAsync(bucketName, uploadPath, stream);

// 生成预签名URL
var presignedUrl = await ossService.PresignedGetObjectAsync(bucketName, uploadPath, 86400);
```

---

## 七、注意事项

### 7.1 路径格式

- ✅ OSS路径使用正斜杠 `/`，不使用 `Path.Combine`
- ✅ 路径格式：`{filePath}/{fileName}`

### 7.2 文件命名

- ✅ 文件名格式：`yyyyMMdd_{ID}.{ext}`
- ✅ 使用 `YitIdHelper.NextId()` 生成唯一ID

### 7.3 访问URL

- ✅ 返回带签名的临时访问URL（有效期24小时）
- ✅ 支持自定义域名配置
- ✅ 如果生成失败，返回相对路径作为降级方案

### 7.4 错误处理

- ✅ 上传失败时抛出异常，包含详细错误信息
- ✅ URL生成失败时返回相对路径

---

## 八、相关文件

- **主服务文件**：`netcore/src/Modularity/System/NCC.System/Service/Common/FileService.cs`
- **服务注册**：`netcore/src/Application/NCC.API.Core/Startup.cs`
- **配置文件**：`netcore/src/Application/NCC.API/appsettings.json`
- **依赖库**：`OnceMi.AspNetCore.OSS`

---

**文档完成时间**：2025年1月  
**文档状态**：✅ **已完成**