# ImageUpload 模块安装指南

## 快速开始

### 1. 安装依赖

在项目根目录运行：

```bash
composer dump-autoload
```

由于使用了本地路径仓库（packages/*/*），composer会自动识别新模块。

### 2. 配置 AWS S3

在 `.env` 文件中添加或修改以下配置：

```env
# 设置默认上传磁盘为s3
IMAGE_UPLOAD_DISK=s3

# AWS S3 配置
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name
AWS_URL=https://your-bucket.s3.us-east-1.amazonaws.com
AWS_USE_PATH_STYLE_ENDPOINT=false

# 可选：设置最大上传大小（KB），默认5120KB (5MB)
IMAGE_UPLOAD_MAX_SIZE=5120
```

### 3. 安装AWS S3依赖

如果尚未安装AWS S3 SDK，运行：

```bash
composer require league/flysystem-aws-s3-v3 "^3.0"
```

### 4. 清除缓存

```bash
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
```

### 5. 访问管理后台

登录管理后台后，访问：
```
/admin/image-upload
```

或者在菜单中添加链接到图片上传页面。

### 6. 前端使用

前端用户可以通过 API 上传图片：

- **单张上传**: `POST /api/image-upload/upload`
- **批量上传**: `POST /api/image-upload/upload-multiple`
- **删除图片**: `DELETE /api/image-upload/delete`
- **获取URL**: `GET /api/image-upload/url`

详细的前端使用示例请查看 [FRONTEND_EXAMPLES.md](FRONTEND_EXAMPLES.md)

## 验证安装

### 检查路由是否注册

运行以下命令查看路由：

```bash
php artisan route:list | grep image-upload
```

应该看到以下路由：
- POST   /admin/image-upload/upload
- POST   /admin/image-upload/upload-multiple
- DELETE /admin/image-upload/delete
- GET    /admin/image-upload/url

### 测试上传

1. 访问 `/admin/image-upload`
2. 选择一张图片
3. 点击上传按钮
4. 检查是否成功上传并显示图片URL

## 故障排除

### 问题1: 找不到类错误

如果看到类似 `Class "Longyi\ImageUpload\Services\ImageUploadService" not found` 的错误：

```bash
composer dump-autoload
php artisan clear-compiled
```

### 问题2: S3连接错误

如果遇到S3连接问题：

1. 检查 `.env` 中的AWS配置是否正确
2. 确认IAM用户有S3写入权限
3. 检查Bucket策略是否允许访问
4. 测试AWS凭证：

```bash
php artisan tinker
>>> Storage::disk('s3')->put('test.txt', 'test')
```

### 问题3: 权限错误

确保存储目录有正确的权限：

```bash
chmod -R 775 storage
chmod -R 775 bootstrap/cache
```

### 问题4: 图片上传失败

检查以下内容：

1. PHP上传限制 (`php.ini`)：
   ```ini
   upload_max_filesize = 10M
   post_max_size = 10M
   ```

2. Laravel验证规则中的文件大小限制

3. 查看日志文件：
   ```bash
   tail -f storage/logs/laravel.log
   ```

## 切换到本地存储

如果想使用本地存储而不是S3，修改 `.env`：

```env
IMAGE_UPLOAD_DISK=public
```

然后运行：

```bash
php artisan storage:link
```

## API测试示例

使用curl测试上传API：

### 单张图片上传

```bash
curl -X POST http://your-domain.com/admin/image-upload/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "image=@/path/to/image.jpg" \
  -F "directory=test/uploads"
```

### 多张图片上传

```bash
curl -X POST http://your-domain.com/admin/image-upload/upload-multiple \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "images[]=@/path/to/image1.jpg" \
  -F "images[]=@/path/to/image2.jpg" \
  -F "directory=test/uploads"
```

## 下一步

- 阅读 [README.md](README.md) 了解完整功能
- 查看控制器代码了解API使用方法
- 根据需要自定义配置

## 支持

如有问题，请联系：dev@longyi.com