# 架構

本頁以一張概覽圖說明 node-image-server 各層的關係與職責。

## 系統概覽

```mermaid
graph TB
    Client[用戶端] --> Worker[Cloudflare Worker<br>worker/index.js]
    Client --> Nginx[Nginx<br>config/nginx/nodejs.conf]
    Worker --> Nginx
    Nginx -->|/c/img/| App[Express cluster<br>app/app.ts]
    Nginx -->|/upload/ · /del/ · /| App
    App --> MW[Middlewares<br>app/src/middlewares]
    MW --> Router[Router<br>app/src/router]
    Router --> GET[GetFromPath<br>sharp]
    Router --> POST[PostToPath<br>multer]
    Router --> DEL[DeleteFromPath]
    GET --> Upload[(storage/image/upload)]
    GET --> Cache[(storage/image/cache)]
    POST --> Upload
    DEL --> Trash[(upload/.trash/YYYY-MM-DD)]
```

## 分層

| 層 | 位置 | 職責 |
|---|---|---|
| CDN | `worker/index.js` | 以 URL＋query string 為快取鍵快取 7 天，未命中時轉發至來源 |
| 反向代理 | `config/nginx/nodejs.conf` | `/c/img/` 的 `proxy_cache`、安全標頭、拒絕 dotfile、限制 HTTP 方法與上傳大小 |
| 程序管理 | `app/app.json`、`app/app.ts` | PM2 以 ts-node 載入；主程序 fork worker 並在退出時補位 |
| 中介層 | `app/src/middlewares/` | 解析、CORS、請求日誌、HTML 壓縮、拒絕無 `User-Agent` 的請求 |
| 路由 | `app/src/router/` | 依 HTTP 方法分派至 GET／POST／DELETE 子路由 |
| 處理器 | `GetFromPath`、`PostToPath`、`DeleteFromPath` | 轉檔與快取、上傳、搬入垃圾桶 |
| 儲存 | `app/storage/image/` | `upload/` 原檔、`cache/` 轉檔結果、`upload/.trash/` 刪除項目 |

## 跨切原則

| 原則 | 實作 |
|---|---|
| 只處理一次 | 轉檔結果寫成快取檔，邊緣層再各自快取 |
| 不實體刪除 | 刪除一律 `renameSync` 搬入當日垃圾桶 |
| 不放大圖片 | 所有尺寸參數以原圖尺寸為上限 |

## 延伸閱讀

- 各模組內部流程與時序圖：[doc/architecture.zh.md](https://github.com/pardnio/node-image-server/blob/master/doc/architecture.zh.md)
- 快取鍵與失效：[快取層](/zh/caching)
- 讀取流程：[圖片處理流程](/zh/image-pipeline)