# imgproxy-processor

**Repository Path**: panshangqi/imgproxy-processor

## Basic Information

- **Project Name**: imgproxy-processor
- **Description**: imgproxy 图像处理服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

以下是完整的 `README.md` 文档：

```markdown
# ImgProxy OSS 风格图片代理服务

一个基于 Node.js 的图片代理服务，支持阿里云 OSS 风格的 `x-oss-process` 参数，自动转换为 imgproxy 处理指令。

## 功能特性

- ✅ 支持 OSS 风格 `x-oss-process` 参数语法
- ✅ 自动转换裁剪、缩放、旋转、格式转换等操作
- ✅ 无参数时直接代理到 S3 存储
- ✅ 流式传输，内存占用低
- ✅ 支持多操作链式组合

## 系统要求

- Node.js >= 18.0.0
- npm >= 9.0.0
- imgproxy 服务（端口 8020）
- S3 兼容存储服务（端口 11010）

## 快速开始

### 1. 安装依赖

```bash
# 克隆或创建项目目录
mkdir imgproxy-oss-proxy && cd imgproxy-oss-proxy

# 安装依赖
npm install express axios http-proxy-middleware
```

### 2. 创建服务文件

创建 `server.js` 文件（完整代码见下文）

### 3. 启动服务

```bash
# 开发模式
npm run dev

# 生产模式
npm start

# 使用 PM2（推荐）
pm2 start server.js --name imgproxy-proxy
```

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PORT` | 服务监听端口 | `8021` |
| `IMGPROXY_HOST` | imgproxy 服务地址 | `http://127.0.0.1:8020` |
| `S3_STORAGE_HOST` | S3 存储服务地址 | `http://127.0.0.1:11010` |
| `S3_BUCKET` | S3 存储桶名称 | `beijing` |

### 端口说明

| 端口 | 服务 | 说明 |
|------|------|------|
| 8020 | imgproxy | 图片处理服务 |
| 8021 | 本代理服务 | OSS 风格代理 |
| 11010 | S3 存储 | 原始图片存储 |

## 支持的 OSS 操作

### 1. 裁剪 (crop)

| OSS 语法 | imgproxy 转换 | 说明 |
|----------|--------------|------|
| `crop,w_500,h_500` | `crop:500:500:ce` | 中心裁剪 500x500 |
| `crop,w_800,h_600` | `crop:800:600:ce` | 中心裁剪 800x600 |

### 2. 缩放 (resize)

| OSS 语法 | imgproxy 转换 | 说明 |
|----------|--------------|------|
| `resize,w_300` | `resize:fill:300:0` | 宽度缩放到 300px |
| `resize,w_800,h_600` | `resize:fill:800:600` | 缩放到 800x600 |

### 3. 旋转 (rotate)

| OSS 语法 | imgproxy 转换 | 说明 |
|----------|--------------|------|
| `rotate,90` | `rot:90` | 顺时针旋转 90 度 |
| `rotate,180` | `rot:180` | 旋转 180 度 |
| `rotate,270` | `rot:270` | 顺时针旋转 270 度 |

### 4. 格式转换 (format)

| OSS 语法 | imgproxy 转换 | 说明 |
|----------|--------------|------|
| `format,webp` | `format:webp` | 转换为 WebP 格式 |
| `format,png` | `format:png` | 转换为 PNG 格式 |
| `format,jpg` | `format:jpg` | 转换为 JPEG 格式 |

### 5. 质量设置 (quality)

| OSS 语法 | imgproxy 转换 | 说明 |
|----------|--------------|------|
| `quality,q_80` | `q:80` | 设置图片质量为 80% |
| `quality,q_90` | `q:90` | 设置图片质量为 90% |

## 使用示例

### 基础示例

```bash
# 1. 无参数 - 直接返回原图（代理到 S3 存储）
curl "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png"

# 2. 裁剪 - 中心裁剪 300x300
curl "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_300,h_300"

# 3. 缩放 - 宽度缩放到 300px
curl "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/resize,w_300"

# 4. 旋转 - 顺时针旋转 90 度
curl "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/rotate,90"
```

### 链式组合示例

```bash
# 5. 裁剪 + 缩放
curl "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_500,h_500/resize,w_300"

# 6. 裁剪 + 缩放 + 旋转
curl "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_500,h_500/resize,w_300/rotate,90"

# 7. 裁剪 + 缩放 + 格式转换
curl "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_500,h_500/resize,w_300/format,webp"

# 8. 完整链式处理
curl "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_500,h_500/resize,w_300/rotate,90/format,webp/quality,q_80"
```

### 保存处理后的图片

```bash
# 下载并保存
curl -o processed.jpg "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_500,h_500/resize,w_300"

# 保存为 WebP 格式
curl -o processed.webp "http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_500,h_500/resize,w_300/format,webp"
```

### 浏览器访问

直接在浏览器中打开以下 URL：

```
http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png
http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_300,h_300
http://localhost:8021/beijing/ScreenShot_2026-03-16_020646_998.png?x-oss-process=image/crop,w_500,h_500/resize,w_300/rotate,90
```

## 测试对照表

| 原始图片 | OSS 处理参数 | 代理 URL |
|----------|-------------|----------|
| `image.png` | 无 | `/beijing/image.png` |
| `image.png` | `crop,w_300,h_300` | `/beijing/image.png?x-oss-process=image/crop,w_300,h_300` |
| `image.png` | `resize,w_500` | `/beijing/image.png?x-oss-process=image/resize,w_500` |
| `image.png` | `rotate,90` | `/beijing/image.png?x-oss-process=image/rotate,90` |
| `image.png` | `format,webp` | `/beijing/image.png?x-oss-process=image/format,webp` |
| `image.png` | `crop,w_500,h_500/resize,w_300` | `/beijing/image.png?x-oss-process=image/crop,w_500,h_500/resize,w_300` |

## 架构说明

```
客户端请求
    │
    ▼
┌─────────────────────────────────────┐
│  代理服务 (端口 8021)                │
│                                     │
│  判断是否有 ?x-oss-process 参数      │
└─────────────────────────────────────┘
    │                    │
    │ 有参数              │ 无参数
    ▼                    ▼
┌──────────────┐  ┌──────────────┐
│  imgproxy    │  │  S3 存储     │
│  (端口 8020) │  │  (端口 11010)│
└──────────────┘  └──────────────┘
    │                    │
    └────────┬───────────┘
             ▼
        返回处理后的图片
```

## 故障排查

### 1. 检查服务状态

```bash
# 健康检查
curl http://localhost:8021/health

# 返回示例
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "config": {
    "imgproxy": "http://127.0.0.1:8020",
    "s3Storage": "http://127.0.0.1:11010",
    "bucket": "beijing"
  }
}
```

### 2. 查看日志

```bash
# 直接运行模式
npm start

# PM2 模式
pm2 logs imgproxy-proxy

# 查看错误日志
pm2 logs imgproxy-proxy --err
```

### 3. 常见错误

| 错误 | 可能原因 | 解决方法 |
|------|---------|---------|
| `ECONNREFUSED` | imgproxy 或 S3 服务未启动 | 检查端口 8020 和 11010 是否正常 |
| `404 Not Found` | 图片不存在 | 确认图片路径和桶名称是否正确 |
| `Invalid x-oss-process` | 参数格式错误 | 检查 OSS 参数语法是否正确 |
| `Timeout` | 处理超时 | 检查网络连接或增加超时时间 |

## 性能优化建议

1. **使用 PM2 集群模式**
```bash
pm2 start server.js -i max --name imgproxy-proxy
```

2. **启用缓存**（在 imgproxy 配置中）
```bash
IMGPROXY_CACHE_SIZE=1073741824  # 1GB 缓存
```

3. **调整超时时间**（根据图片大小）
```javascript
timeout: 60000  // 增加到 60 秒
```

## 相关链接

- [imgproxy 官方文档](https://docs.imgproxy.net/)
- [阿里云 OSS 图片处理](https://help.aliyun.com/document_detail/44686.html)

## License

MIT
```

这个 `README.md` 包含了完整的使用方法、测试样例和故障排查指南。