# ImgJoiner

**Repository Path**: nodejs-master/img-joiner

## Basic Information

- **Project Name**: ImgJoiner
- **Description**: 图片拼接、裁剪处理
- **Primary Language**: NodeJS
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-12
- **Last Updated**: 2025-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图标拼接与裁剪服务

这是一个基于Node.js和Sharp库开发的图像处理Web应用，支持将单个图标拼接成2x2网格并从中心裁剪，还能对处理结果再次2x2拼接，适合生成无缝平铺纹理。

## 功能描述

- 通过Web界面或API上传单个图标文件
- 将该图标复制四份，排列成2x2的网格
- 从拼接后的大图中心裁剪出与原图同样大小的区域，保证无缝平铺
- 对裁剪结果再次进行2x2拼接，展示最终平铺效果
- 前端页面可同时预览和下载两张处理结果图片
- 支持历史处理结果的浏览与删除

## 技术栈

- **后端**：Node.js, Express
- **图像处理**：Sharp
- **文件上传**：Multer
- **前端**：HTML, CSS, JavaScript, Bootstrap
- **配置管理**：dotenv

## 安装与运行

确保您已安装Node.js，然后执行以下命令：

```bash
# 克隆仓库
# git clone https://github.com/yourusername/img-joiner-server.git
cd img-joiner-server

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 根据需要编辑.env文件

# 启动服务
npm start

# 开发模式（自动重启）
npm run dev
```

服务启动后，在浏览器访问 `http://localhost:3000` 即可使用Web界面。

## 环境变量配置

详见`.env.example`，常用配置如下：

```
PORT=3000                # 应用监听端口
NODE_ENV=development     # 环境模式
MAX_FILE_SIZE=5242880    # 最大上传文件大小(5MB)
```

## 项目结构

```
img-joiner-server/
├── index.js              # 应用入口
├── package.json          # 依赖和配置
├── .env                  # 环境变量
├── public/               # 前端静态资源
│   └── index.html        # Web界面
├── uploads/              # 上传文件目录
├── results/              # 处理结果目录
└── src/
    ├── server.js         # 服务器启动
    ├── app.js            # Express配置
    ├── controllers/      # 控制器
    │   └── imageController.js # 图像处理核心
    ├── routes/           # 路由
    └── ...
```

## 前端交互说明

- 上传图标后，页面会显示：
  - 原始图标
  - 处理结果（无缝中心裁剪）
  - 拼接效果（处理结果的2x2平铺）
- 可分别下载两张处理结果图片
- 历史处理结果可浏览和删除

## API接口文档

### 1. 处理图像

**请求**:
- 方法: `POST`
- 路径: `/api/images/process`
- 内容类型: `multipart/form-data`
- 参数:
  - `icon`: 图标文件（必需）

**响应**:
```json
{
  "success": true,
  "message": "图像处理成功",
  "data": {
    "original": "/uploads/1234567890.png",
    "processed": "/results/processed-1234567890.png",
    "tiled": "/results/tiled-processed-1234567890.png",
    "processedFilename": "processed-1234567890.png",
    "tiledFilename": "tiled-processed-1234567890.png"
  }
}
```
- `processed`：中心裁剪后的无缝图像
- `tiled`：对处理结果再次2x2拼接的平铺效果图

### 2. 获取处理结果列表

**请求**:
- 方法: `GET`
- 路径: `/api/images/results`

**响应**:
```json
{
  "success": true,
  "count": 2,
  "data": [
    {
      "filename": "processed-1234567890.png",
      "url": "/results/processed-1234567890.png",
      "createdAt": "2023-05-20T10:30:45.000Z"
    },
    {
      "filename": "tiled-processed-1234567890.png",
      "url": "/results/tiled-processed-1234567890.png",
      "createdAt": "2023-05-20T10:30:45.000Z"
    }
  ]
}
```

### 3. 删除处理结果

**请求**:
- 方法: `DELETE`
- 路径: `/api/images/results/:filename`

**响应**:
```json
{
  "success": true,
  "message": "文件已成功删除"
}
```

## 图像处理流程说明

1. **2x2拼接**：将上传的图标复制四份，排列成2x2网格，生成大图。
2. **中心裁剪**：从大图中心裁剪出与原图同样大小的区域，保证四边无缝衔接。
3. **再次拼接**：对裁剪结果再次进行2x2拼接，生成最终平铺效果图。
4. **结果展示与下载**：前端页面和API均返回两张图片，便于预览和下载。

## 依赖

- [Express](https://expressjs.com/)
- [Sharp](https://sharp.pixelplumbing.com/)
- [Multer](https://github.com/expressjs/multer)
- [Cors](https://github.com/expressjs/cors)
- [Morgan](https://github.com/expressjs/morgan)
- [Dotenv](https://github.com/motdotla/dotenv)

## 许可

MIT

## 常见问题

### 图像处理中的白线问题

- 已采用高质量参数和精确像素定位，彻底解决拼接白线问题。
- 若遇特殊图片仍有问题，请反馈issue。

### 环境变量配置

详见`.env.example`，可自定义端口、最大上传大小、调试模式等。

## 云服务器部署指南

本项目可方便地部署到任意Linux云服务器（如阿里云、腾讯云、AWS、华为云等），推荐使用PM2进行进程守护和管理。

### 1. 服务器准备

- 推荐系统：Ubuntu 20.04+/CentOS 7+/Debian 10+
- 已安装Node.js（建议v16及以上）和npm
- 已开放Web端口（如3000）

### 2. 上传与安装

```bash
# 1. 上传代码到服务器（可用git clone或SCP等方式）
# git clone https://github.com/yourusername/img-joiner-server.git
cd img-joiner-server

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.example .env
# 编辑.env，按需修改端口、最大上传大小等
vi .env
```

### 3. 安装PM2

```bash
npm install -g pm2
```

### 4. 使用PM2启动服务

```bash
# 启动服务（推荐用 index.js 作为入口）
npm start         # 本地测试服务是否正常

# 用PM2守护进程
pm2 start index.js --name img-joiner
# 或
pm2 start src/server.js --name img-joiner

# 设置开机自启
pm2 startup
pm2 save
```

- 推荐用 `index.js` 作为 PM2 启动入口（会自动加载 src/server.js）。
- 本项目无需构建步骤，直接 `npm start` 即可。

### 5. 配置Nginx反向代理（可选，推荐）

如需绑定域名或用80/443端口对外服务，建议用Nginx反代：

```
server {
    listen 80;
    server_name your-domain.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

- 配置好后重载Nginx：`sudo systemctl reload nginx`

### 6. 常用PM2命令

- 查看进程：`pm2 ls`
- 查看日志：`pm2 logs img-joiner`
- 重启服务：`pm2 restart img-joiner`
- 停止服务：`pm2 stop img-joiner`
- 删除服务：`pm2 delete img-joiner`

### 7. 生产环境建议

- 配置防火墙，仅开放必要端口
- 定期备份`results/`目录
- 可用HTTPS（Nginx+Let's Encrypt）提升安全性
- 监控服务器资源，合理设置上传大小

---

如有云部署相关问题，欢迎提issue或联系维护者。