# HTTP API 參考

本頁列出 node-image-server 的所有 HTTP 端點，以及所有請求共用的行為。

## 端點

| 方法 | 路徑 | 說明 | 處理器 | 詳細 |
|---|---|---|---|---|
| `GET` | `/c/img/{path}` | 讀取圖片，依參數即時轉檔並寫入快取 | `GetFromPath`（`app/src/router/get`） | [圖片參數](/zh/api-reference-image) |
| `POST` | `/upload/{path}` | 上傳檔案至 `storage/image/upload/{path}/` | `PostToPath`（`app/src/router/post`） | [上傳 API](/zh/api-reference-upload) |
| `DELETE` | `/del/{path}` | 將檔案或資料夾移至當日垃圾桶 | `DeleteFromPath`（`app/src/router/delete`） | [刪除 API](/zh/api-reference-delete) |
| `GET` | `/check/state` | 健康檢查，回傳 `200` `ok` | — | — |
| `GET` | `/storage/image/...` | `express.static` 直接提供 `storage/image/` 下的檔案（含 `upload/` 與 `cache/`） | — | — |
| 任意 | 其他路徑 | `404` `404 Not Found` | — | — |

`{path}` 可包含 `/`，對應 `storage/image/upload/` 之下的相對路徑。

## 共用行為

| 項目 | 行為 | 實作 |
|---|---|---|
| `User-Agent` | 請求沒有 `User-Agent` 標頭時直接關閉 socket，不回應 | `middlewares/dataInit.ts` |
| CORS | `Access-Control-Allow-Origin: *`，允許 `GET,PUT,PATCH,POST,DELETE` | `middlewares/cors.ts` |
| 請求日誌 | 寫入 `storage/logs/req.log`（每 3 天輪替），欄位為台北時間、狀態碼、國別、IP、方法、URL、耗時、referrer | `middlewares/logger.ts` |
| 錯誤格式 | 成功回應為 JSON；錯誤回應為純文字訊息 | 各處理器 |

## 經由 Nginx 的路由

| 路徑 | 上游 | 快取 |
|---|---|---|
| `/c/img/` | `nodejs:8080` | `proxy_cache` |
| `/upload/`、`/del/`、其他 | `nodejs:3000` | 不快取 |
| 以 `.` 開頭的路徑片段（如 `/.trash`） | 拒絕 | — |

上游埠號須與 `NODE_PORT` 一致，見 [設定](/zh/configuration)。