# 部署哨站

在自己的伺服器或 NAS 上執行
哨站，讓選定資料夾的新郵件觸發通知。安裝只需要 Docker；使用 Compose
方式時還需要 Docker Compose v2。

**映象釋出狀態**：可用版本以
[GitHub Releases](https://github.com/mingzaily/mailwake/releases)
和
[GHCR](https://github.com/mingzaily/mailwake/pkgs/container/mailwake)
為準。

## 1. 選擇安裝方式

**推薦 Docker Compose**，後續更新、備份和恢復都使用同一份設定。映象地址為
`ghcr.io/mingzaily/mailwake:latest`，支援 Linux amd64 /
arm64。`latest` 跟隨穩定版本；固定版本時，將它替換為
Releases 中已釋出的版本標籤。

在伺服器終端執行：

```
mkdir -p ~/mailwake
cd ~/mailwake
```

在這個目錄建立 `compose.yaml`，複製以下完整內容：

```
services:
  core:
    image: ghcr.io/mingzaily/mailwake:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      MAILWAKE_LISTEN: "0.0.0.0:8080"
      MAILWAKE_DATA_DIR: "/data"
      MAILWAKE_RELAY_URL: "${MAILWAKE_RELAY_URL:-}"
    volumes:
      - core-data:/data
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    stop_grace_period: 30s
volumes:
  core-data:
```

拉取映象並啟動：

```
docker compose pull core
docker compose up -d
docker compose ps
docker compose logs --tail=50 core
```

**成功標誌**：`core` 顯示 `Up` /
`running`，日誌出現首次設定碼。儲存這個終端，下一步會使用設定碼。以後在
`~/mailwake` 目錄執行 Compose 命令。

資料存放在 Docker 的 `core-data` 命名卷中，容器內路徑為
`/data`；預設專案目錄下的實際卷名是
`mailwake_core-data`。重建容器保留資料，`docker compose down -v`
會刪除資料卷。

### Docker Run

習慣單條命令時，可以選擇下面的等價安裝方式。兩種安裝方式選擇一種即可。

```
docker volume create mailwake-data
docker run -d \
  --name mailwake \
  --restart unless-stopped \
  --stop-timeout 30 \
  --read-only \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  -p 127.0.0.1:8080:8080 \
  -v mailwake-data:/data \
  ghcr.io/mingzaily/mailwake:latest
docker logs --tail=50 mailwake
```

Docker Run 的資料卷名是 `mailwake-data`。後面的管理命令以
Compose 為例，Docker Run 的備份命令見[備份教學](backup.md#docker-run-安裝的備份)。

## 2. 開啟管理頁面

**在執行 Docker 的電腦上存取**：開啟
<http://127.0.0.1:8080>。

**部署在遠端伺服器或 NAS**：在自己的電腦終端執行以下命令，將
`user@server` 替換為伺服器的 SSH 使用者和地址：

```
ssh -L 18080:127.0.0.1:8080 user@server
```

保持終端連線，在自己電腦的瀏覽器開啟
<http://127.0.0.1:18080>。這樣即可完成首次設定；需要長期透過域名存取時，再按下一節設定
HTTPS。

**成功標誌**：看到 Mailwake
的初始化頁面。輸入日誌中的設定碼，建立至少 12
個字元的管理員密碼。設定完成前，重啟哨站會生成新的設定碼。

接下來按[第一條通知教學](first-notification.md)新增信箱和通知通道。

## 3. 設定 HTTPS

已有域名和反向代理時，將域名指向伺服器，把代理目標設為
`http://127.0.0.1:8080`。下面以安裝在同一宿主機的 Caddy
為例，在 `Caddyfile` 中加入自己的域名：

```
mail.example.org {
    reverse_proxy 127.0.0.1:8080
}
```

確保域名解析正確，伺服器允許 80 / 443 入站，再校驗和過載設定：

```
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

開啟
`https://mail.example.org`，確認瀏覽器證書有效、可以登入並開啟信箱頁面。Caddy 的安裝見[官方安裝說明](https://caddyserver.com/docs/install)。使用 Nginx Proxy Manager
等面板時，填寫相同的域名和代理目標，並在面板申請證書。

代理在另一個容器中執行時，讓它與哨站加入同一 Docker 網路，目標使用
`http://core:8080`；容器中的
`127.0.0.1` 指向它自己。代理須保留原始 Host，並設定
`X-Forwarded-For`。哨站
接受來自本機和私有網段的代理資訊，8080
應只向代理及可信本機客戶端開放。

## 4. 更新版本

先完成一次[備份](backup.md)，再在 Compose
目錄執行：

```
docker compose pull core
docker compose up -d
docker compose ps
docker compose logs --tail=50 core
```

使用固定版本時，先修改
`compose.yaml`
中的映象標籤，再執行上述命令。開啟管理頁面，確認信箱正常監聽，再傳送一封新郵件驗證通知。保留升級前的備份；需要回退時，按恢復教學同時恢復舊資料和對應映象。

## 5. 常見問題

### 映象拉取失敗

先檢查 GHCR 是否已有目標版本。`manifest unknown`
通常表示標籤不存在。若出現
`denied`，先核對映象地址和包的公開狀態；網路超時則檢查伺服器到 GHCR
的連線。

### 打不開管理頁面

`127.0.0.1` 表示當前電腦。遠端部署請使用 SSH 轉發或 HTTPS
域名。執行 `docker compose ps` 與
`docker compose logs --tail=50 core`，先確認容器執行。8080 已被佔用時，將埠對映左側改為
`127.0.0.1:18080:8080`，瀏覽器與代理目標也改為 18080。

### 忘記管理員密碼

在 Compose 目錄執行，按終端提示輸入新密碼：

```
docker compose stop core
docker compose run --rm -it core admin reset-password
docker compose start core
```

恢復命令會獲取資料目錄鎖定，執行前先停止
哨站。重置密碼會登出瀏覽器會話，保留 API Token、信箱與佇列。

### 官方 App 與 Pro 怎麼接入

Free 的 Web 管理和 Bark / Pushover / Webhook 可獨立使用。官方 App
尚未上架，正式下載入口、推播中繼服務
地址和簽章公鑰以官方釋出為準。具備正式接入設定後，按
[App 接入說明](connect-app.md)設定 HTTPS 和裝置配對。

原始碼構建與本機開發見[開發指南](https://github.com/mingzaily/mailwake/blob/main/docs/development.md)。

## 原始碼構建與程序設定

開發構建見 [原始碼倉庫說明](https://github.com/mingzaily/mailwake#run-from-source) 和[貢獻者構建指南](https://github.com/mingzaily/mailwake/blob/main/CONTRIBUTING.md)。

容器外 `MAILWAKE_LISTEN` 預設 `127.0.0.1:8080`，容器內為 `0.0.0.0:8080`。`MAILWAKE_DATA_DIR` 預設 `data`，容器內為 `/data`。`MAILWAKE_RELAY_URL` 預設 `https://notify.mailwake.oritx.com`。重啟與升級時保留包含 `secret.key` 的完整資料目錄。

## 更換推播中繼服務環境

生產與 Sandbox 使用獨立配對身分。確實需要更換環境時，停止哨站，使用原資料目錄和已儲存的舊推播中繼服務地址執行重置：

```sh
docker compose stop core
docker compose run --rm -it core admin reset-native-push
```

按提示輸入 `reset-native-push`。命令會在舊推播中繼服務撤銷配對；舊服務無法存取時，保留舊設定並等待服務可存取後重試。確認未解決目標為零後，設定新的 `MAILWAKE_RELAY_URL`，執行 `docker compose up -d` 重建容器並[重新配對](connect-app.md)。命令保留哨站簽章身分和普通管道歷史。