部署哨站

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

映象釋出狀態：可用版本以 GitHub Releases 和 GHCR 為準。

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 的備份命令見備份教學。

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 個字元的管理員密碼。設定完成前，重啟哨站會生成新的設定碼。

接下來按第一條通知教學新增信箱和通知通道。

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 的安裝見官方安裝說明。使用 Nginx Proxy Manager 等面板時，填寫相同的域名和代理目標，並在面板申請證書。

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

4. 更新版本

先完成一次備份，再在 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 接入說明設定 HTTPS 和裝置配對。

原始碼構建與本機開發見開發指南。

原始碼構建與程序設定

開發構建見原始碼倉庫說明和貢獻者構建指南。

容器外 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 使用獨立配對身分。確實需要更換環境時，停止哨站，使用原資料目錄和已儲存的舊推播中繼服務地址執行重置：

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

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

Markdown · AGPL-3.0-only · Mailwake 貢獻者