日期：2025年 12月 27日
標籤： Linux Ubuntu Docker Docker-Compose Container BookStack MariaDB LinuxServer.io Portaniner Webhook.site
摘要：資訊筆記
應用所需：1. Linux 主機(本篇 Linux Ubuntu 22.04 作業系統)
2. 已安裝 Docker-Compose (Docker ≥ 20.x（rootful）、docker‑compose ≥ v2)
解決問題：1. 如何結合 Google Mail Server 從 NAS 上的 BookStack 發送郵件到合法的外部 Mail 信箱
2. 啟用 BookStack WebHook 測試+驗證 & 便於未來自動化應用
相關參考：0023. 【NAS 進階】Synology 打造免費私人知識庫：Docker 安裝 + Tailscale Funnel 對外開放完整教學
基本介紹：本篇分為 3 大部分。
第一部分：設定 Gmail SMTP 發送郵件
第二部分：啟用 Webhook 自動化功能
第三部分：補充遭遇問題
第一部分：設定 Gmail SMTP 發送郵件
Step 1：發送郵件相關操作頁面 - 新增使用者
登入 BookStack 後 -> 設定 -> 使用者 -> 新增使用者
Step 2：啟用 Mail 的好處 - 放止密碼外洩
註冊使用者時，可以選擇將密碼直接發送到註冊用戶的個人 Email
這時如果有啟用 BookStack 發送 Mail 功能，就可以避免透過其他方式傳遞的時候被第三方竊取(EX: Line、Whatsapp 等)
補充：如果沒有在 docker-compose.yml 配置啟用，那麼就必定會出現圖中的錯誤，無法使用 Email 發信
Step 3：啟用 Email 送信 - Google 啟用應用程式密碼
要先啟用 Google mail 的啟用應用程式密碼配置，才能將 Google 的 SMTP 當作發送方
也可參考此篇：0026. log4net 發送Email的方法，使用Gmail為範例
Step 4：啟用應用程式密碼 - 建立
輸入一個名稱，自己知道用途，後續不使用可以進行刪除
Step 5：啟用應用程式密碼 - 產生密碼
系統會為您的 Google 帳戶產生一組密碼，此密碼可以用於程式碼的發送 Email 郵件
Step 6：設定 BookStack docker-compose
透過 SSH 登入 NAS Server ，並且先停止 BookStack 的 Container
docker-compose down -v
然後將 docker-compose.yml 添加以下資訊，其中 {} 都是要替換的地方
- MAIL_DRIVER=smtp
- MAIL_HOST=smtp.gmail.com
- MAIL_PORT=587
- MAIL_FROM_ADDRESS={您的 Google Email帳號}@gmail.com
- MAIL_ENCRYPTION=tls
- MAIL_USERNAME={您的 Google Email帳號}@gmail.com
- MAIL_PASSWORD={應用程式密碼16碼}
如圖，應會如下：
Step 7：啟動 BookStack - 發送測試信 - 設定完成
然後再輸入以下指令啟動 BookStack
docker-compose up -d
登入 BookStack -> 設定 -> 維護 -> 點擊 執行測試電子郵件 的按鈕
我們可以從信箱收到 BookStack 發送的信件
備註：這邊會記送到登入者的信箱，做為測試信
EX: 我是用 Cap8825@gmail.com 登入 BookStack 執行測試信，就會從此 Gmail 收到測試信
第二部分：啟用 Webhook 自動化功能
Step 1：啟用 Webhook 用途 - 主動通知
常見 BookStack 的觸發 Webhook 的時機點如下：
| 分類 | 可觸發事件 |
|---|---|
| 書本 (Books) | 建立、更新、刪除 |
| 頁面 (Pages) | 建立、更新、刪除、回覆評論 |
| 章節 (Chapters) | 建立、更新、刪除 |
| 標籤 (Tags) | 新增或移除標籤 |
| 使用者 (Users) | 建立、更新、刪除、登入 |
| 權限 (Roles/Permissions) | 權限變更 |
| 其他 | 上傳附件、新建書架、複製文件等 |
Step 2：Webhook 在 BookStack 應用
當觸發 BookStack 時，可以針對以下應用場景進行 WebHook 的自動化工作：
| 類別 | 應用場景 | 說明 |
|---|---|---|
| 文件更新通知 | 文件被建立、修改、刪除時通知審核人或團隊 | 用於審核流程或重要文件變更提醒 |
| 文件同步整合 | 文件更新後同步到 Git、Confluence 或其他知識庫 | 維持多平台內容一致 |
| 即時公告 | 新文件或留言推播至 Slack / Teams / Discord | 讓團隊即時掌握文件動態 |
| AI 摘要與推播 | 文件更新觸發 AI 生成重點摘要 | 自動產生每日/每週文件更新摘要 |
| 權限與安全監控 | 偵測角色或權限變更、異常刪除 | 通知安全系統或紀錄為稽核事件 |
| 自動備份 | 重要文件變更或刪除即自動匯出備份 | 使用 WebHook + BookStack API 匯出 HTML/PDF |
| 知識貢獻統計 | 收集 WebHook 事件生成活躍度報表 | 顯示「誰最常新增或維護文件」 |
舉個簡單的例子：當新書上架時，可以透過 WebHook 呼叫 NAS MailPlus 然後發信給 BookStack 上已訂閱的用戶
Step 3：啟用 Webhook - 先開啟 webhook.site
為了確定 BookStack 的 Webhook 是否正確啟用，可以使用測試網站webhook site進行驗證
當確保 BookStack 的發送 Webhook 功能是正常的，後續其他應用只需要改成對應的 Webhook 的端口即可
進入 webhook.site
關鍵在 Your unique URL 獲得測試用的 Key : 1388def0-2e71-4858-9836-3b37b7f846b
https://webhook.site/1388def0-2e71-4858-9836-3b37b7f846b
接著保持 此頁面不關閉
Step 4：：啟用 Webhook - 回到 BookStack 配置
登入 BookStack 後 -> 設定 -> Webhooks -> 建立 Webhook
Step 5：啟用 Webhook - 設定 Webhook
將從 webhook.site 得到的 unique URL 貼上 -> 保存
https://webhook.site/1388def0-2e71-4858-9836-3b37b7f846b
Step 6：啟用 Webhook - 驗證結果
回到未關閉的 Webhook.site 可以看到發送的結果，裡面的發送來源為 Tailscale Funnel 獲取的域名 (NAS 上架設的 BookStack 對外訪問域名)
第三部分：補充遭遇問題
Step 1：BookStack 無法正常發送郵件 - Image 差異
在調整的過程中，設定 BookStack 郵件會一值出現以下錯誤：
Connection could not be established with host "localhost:587": stream_socket_client(): Unable to connect to localhost:587 (Address not available)
關鍵在 Image 來自於 LinuxServer.io 容器的環境變數命名，有以下差異：
| 標準 BookStack | 標準 BookStack |
|---|---|
| MAIL_FROM | MAIL_FROM_ADDRESS |
這是因為容器內部會將環境變數轉換成 Laravel 的 .env 格式,而 Laravel 使用的是 MAIL_FROM_ADDRESS
因此若 使用本篇範例 (LinuxServer.io)，必須使用 MAIL_FROM_ADDRESS
若是使用了 MAIL_FROM 在 docker-compose.yml 必定會出現相同無法發信的錯誤