# 快速開始

本頁說明如何以 Docker Compose 啟動 node-image-server，並完成第一次上傳與讀取。

## 前置需求

| 項目 | 版本 |
|---|---|
| Docker 與 Docker Compose v2 | 建議部署方式 |
| Node.js | 22 以上（僅本機直接執行時需要；容器使用 `node:22-alpine`） |

## 以 Docker Compose 啟動

```bash
git clone https://github.com/pardnio/node-image-server.git
cd node-image-server
docker compose up -d
```

| 服務 | 映像 | 說明 |
|---|---|---|
| `nginx` | `nginx:stable-alpine` | 對外監聽 `8080`，載入 `config/nginx/nodejs.conf` |
| `nodejs` | `node:22-alpine` | 啟動時執行 `npm install`，再以 `npx pm2-runtime start app.json` 載入 `app.ts` |

## 本機直接執行

```bash
cd node-image-server/app
npm install
mkdir -p storage/logs storage/image
npx pm2-runtime start app.json
```

此時直接連線 Express（`http://localhost:8080`），不經 Nginx。

## 第一次上傳

```bash
curl -fsS -X POST \
  -F "filepath=@./photo.jpg" \
  http://localhost:8080/upload/blog/2025 \
  || echo "上傳失敗"
```

成功時回傳 `201`：

```json
{
  "success": 1,
  "filename": "ERftP1gTS7WCTeJ8_1744080848530.jpg",
  "type": "image/jpeg",
  "size": 2501808,
  "src": "http://localhost:8080/c/img/blog/2025/ERftP1gTS7WCTeJ8_1744080848530.jpg"
}
```

## 第一次讀取

```bash
# 預設：WebP、品質 75、短邊超過 1024px 時長邊縮至 1024px
curl -fsS -o photo.webp \
  http://localhost:8080/c/img/blog/2025/ERftP1gTS7WCTeJ8_1744080848530.jpg

# 寬 800px 的 AVIF
curl -fsS -o w800.avif \
  "http://localhost:8080/c/img/blog/2025/ERftP1gTS7WCTeJ8_1744080848530.jpg?w=800&t=avif"
```

第一次請求會以 sharp 轉檔並寫入 `storage/image/cache/`，之後相同參數直接讀快取檔。

## 下一步

- 參數完整清單：[圖片參數](/zh/api-reference-image)
- 快取如何分層：[快取層](/zh/caching)
- 正式環境設定：[設定](/zh/configuration)