# 架構

本頁以一張概覽圖說明 go-image-server 從邊緣快取到 Go 服務、libvips 與檔案儲存的層級關係。

## 系統概覽

```mermaid
graph TB
    Client[客戶端] --> Browser[瀏覽器快取]
    Browser --> Worker[Cloudflare Worker]
    Browser --> Nginx[Nginx proxy_cache]
    Worker --> Nginx
    Nginx --> Gin[Gin 路由 routes]
    Gin --> Get[GetFromPath]
    Gin --> Post[PostToPath]
    Gin --> Del[DeleteFromPath]
    Get --> Vips[libvips govips]
    Get --> Cache[(storage/image/cache)]
    Get --> Upload[(storage/image/upload)]
    Post --> Upload
    Del --> Trash[(upload/.trash/YYYY-MM-DD)]
```

## 分層

| 層 | 位置 | 職責 |
|---|---|---|
| 邊緣 | `worker/index.js` | 依完整 URL（含 query）快取圖片 7 天 |
| 反向代理 | `config/nginx/nodes.conf` | `/c/img/` 快取、上傳與刪除路由轉發、安全標頭 |
| 路由 | `app/internal/routes/` | `SetGET`／`SetPOST`／`SetDELETE` 註冊端點，`Set404` 處理未知路徑 |
| 處理器 | `app/internal/handlers/` | 讀取轉檔、上傳、移入回收桶 |
| 設定 | `app/internal/configs/config.go` | 環境變數與儲存路徑 |
| 工具 | `app/internal/utils/` | query 別名解析、錯誤回應 |

## 跨切原則

| 原則 | 實作 |
|---|---|
| 每個請求 30 秒上限 | 三個處理器皆以 `context.WithTimeout` 包住 goroutine，逾時回 `408 timed out` |
| 參數即快取 key | 本地快取檔名直接串接尺寸、品質、模糊、亮度與格式參數 |
| 刪除即搬移 | 刪除一律 `os.Rename` 至依日期分桶的 `.trash` |
| 串流輸出 | 圖片以 chunked 傳輸，buffer 依檔案大小調整 |

## 延伸閱讀

- 模組級完整圖（各處理器流程、資料流 sequence）：[doc/architecture.zh.md](https://github.com/pardnio/go-image-server/blob/master/doc/architecture.zh.md)
- 四層快取細節：[快取分層](/zh/caching)
- 轉檔流程：[影像處理流程](/zh/image-pipeline)