# 快速開始

本頁說明啟動 go-image-server 所需的環境、兩種安裝方式，以及第一次上傳與讀取圖片。

## 前置需求

| 項目 | 需求 | 來源 |
|---|---|---|
| Docker Compose 部署 | Docker 與 Docker Compose | `docker-compose.yaml` |
| 自行編譯 | Go 1.21 以上（容器使用 `golang:1.22-alpine`） | `app/go.mod` |
| 影像處理 | libvips（含 `pkg-config`）；輸出 AVIF 需 libheif／libavif | `docker-compose.yaml` 的 `apk add` |
| 404 佔位圖 | `app/internal/assets/image/404-light.svg` 與 `404-dark.svg` | `configs.Get404SVG()` |

404 佔位圖不在 repo 內：`.gitignore` 的 `**/image/` 規則會排除 `app/internal/assets/image/`，部署前需自行放置這兩個檔案，否則讀圖失敗時無法回傳佔位圖。

## 以 Docker Compose 啟動

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

| 服務 | 映像 | 對外埠 | 說明 |
|---|---|---|---|
| `nginx` | `nginx:stable-alpine` | `8080 → 80` | 掛載 `./config/nginx`，日誌寫入 `./logs/nginx` |
| `golang` | `golang:1.22-alpine` | 不對外 | 啟動時安裝 libvips 後執行 `go build -o main ./cmd/server && ./main` |

圖片資料掛載於專案根目錄的 `./image`，對應容器內的 `storage/image`。

## 從原始碼編譯

```bash
git clone https://github.com/pardnio/go-image-server.git
cd go-image-server/app
go build -o main ./cmd/server
./main
```

所有儲存路徑皆以 `os.Getwd()` 為根，必須在 `app/` 目錄下執行，否則 `storage/image` 與佔位圖會落在錯誤位置。服務預設監聽 `8080`，可用 `PORT` 覆寫（見 [設定](/zh/configuration)）。

## 第一次上傳與讀取

```bash
# 上傳到 storage/image/upload/blog
curl -X POST -F "filepath=@./photo.jpg" http://localhost:8080/upload/blog

# 用回應中的 src 讀取，預設輸出 WebP
curl -o photo.webp "http://localhost:8080/c/img/blog/<filename>"

# 健康檢查
curl http://localhost:8080/check/state
```

上傳回應格式見 [上傳 API](/zh/api-reference-upload)，讀取參數見 [圖片讀取參數](/zh/api-reference-image)。