Health Check Service 部署手冊

經濟部 即時訊息工具建置案 · 正式環境 GCP AP VM CA53101L(Ubuntu 26.04,無 Docker)· 程式版本 0.1.1(healthcheck/mm_healthcheck)· 更新 2026-11-02

文件狀態:正式 VM 已以 HTTP 啟用(2026-11-02 18:44)。安裝目錄 2026-11-02 由 /opt/mm_healthcheck 改為 /opt/mattermost_healthcheck(與 SSO Bridge 的 /opt/mattermost_sso_bridge 一致,版號升為 0.1.1)。DB 連線改連 postgres 資料庫(不是 mmdb),只確認 SELECT 1(2026-11-02 使用者決定)。內網網址為 https://EE531.intra3.moea.gov.tw:19999/health(2026-11-02);監控來源 IP 與 HTTPS 憑證尚未取得。各項以標籤區分: 實測 已在正式 VM、ubuntu:26.04(amd64)容器或 dev PostgreSQL 驗證(各處註明); 推論 未實機驗證; 待確認 需向經濟部/DBA 取得。

1. 服務概要

經濟部「應用系統共同監控機制」定期以 GET 呼叫本服務(經濟部規格稱 Healthcheck Bridge,內部稱 Health Check Service)。本服務每次新建連線到 Mattermost 的 PostgreSQL、執行 SELECT 1、斷線,依結果回應。與 SSO Bridge 分開部署(獨立目錄、venv、系統帳號、systemd unit、版號),不讀 Bridge 任何檔案。

狀況回應 body(經濟部規格 2026-10-30)HTTP
連線、查詢成功且回傳 1{"status":"000","message":"正常運作"}200
連不上、逾時、認證失敗、查詢異常{"status":"500","message":"DB連線異常"}預設 200,可設 5xx 待確認
來源 IP 不在白名單forbidden(純文字)403

2. 版本與環境

項目值依據
作業系統/PythonUbuntu 26.04.1 LTS、系統 python3 3.14.4實測 正式 VM 2026-10-27(同 SSO Bridge)
Python 依賴requirements.txt(== 鎖定):FastAPI 0.143.0、uvicorn 0.54.0、psycopg/psycopg-binary 3.3.6 等 16 個實測 2026-10-30 ubuntu:26.04 容器離線安裝後 pip freeze 與檔案完全一致
libpq不需另裝:psycopg-binary wheel 內含實測 同上,容器未裝 libpq5
Mattermost DBPostgreSQL 18.6,主機 CD53101L、port 50419、MM 的 DB 為 mmdb、sslmode=require;Health Check 連 postgres 資料庫(2026-11-02 決定)實測 2026-10-29 讀 MM config.json
對外網路VM 連不到 PyPI,一律用 WHEELS=1 的 zip實測 2026-10-28(同 SSO Bridge 部署手冊)
Listen port19999,只提供內網呼叫2026-10-30 定案;HTTPS 憑證來源 待確認,取得前為 HTTP

3. 打包與上傳

# 開發機(repo 根目錄;需 Docker 下載 wheel)
make package HC=1 NO_BRIDGE=1 WHEELS=1   # NO_BRIDGE=1:Bridge 版號沒變就不重出它的 zip
#   dist/mm-healthcheck-0.1.1.zip    mm_healthcheck/、requirements.txt、healthcheck.env.example、
#                                    ops/systemd/mm-healthcheck.service、wheels/(16 個)
#   dist/SHA256SUMS-<Bridge 版號>    更新這次產出的 zip 那行,其他行保留
scp dist/mm-healthcheck-0.1.1.zip dist/SHA256SUMS-0.3.0 <帳號>@<VM>:~/

# VM
sha256sum -c --ignore-missing SHA256SUMS-0.3.0      # mm-healthcheck-0.1.1.zip: OK

zip 以 git archive 從 HEAD 取檔,有未 commit 的修改時腳本中止。版號取自 healthcheck/mm_healthcheck/__init__.py,與 Bridge 無關;SHA256SUMS 檔名沿用 Bridge 版號。

同檔名的 zip 已存在時腳本中止(2026-11-05 起):程式有改就先升 __version__;要重出已發行的版本,從 tag healthcheck-v<版號> checkout 再打包;確定要覆蓋才加 FORCE=1。不加 NO_BRIDGE=1 時也會檢查 Bridge zip,Bridge 版號沒變就會被擋下來。

實測 2026-10-30(commit 43f6079):zip 內容如上、雜湊 OK。

4. 安裝步驟

VM 上的目錄配置:

/opt/mattermost_healthcheck/
├── app/    zip 內容(mm_healthcheck/、requirements.txt、wheels/、ops/…)   root 擁有,唯讀
├── venv/   Python 虛擬環境                                               root 擁有
└── etc/    healthcheck.env(含 DB 密碼)                                 root:healthcheck,750/640

沒有 var/:服務不寫檔,log 全進 journald。

複製指令前注意:行尾續行的 \ 後面不能有空白(從文件複製常被補上)。否則指令在該行就結束,install -d … \␠ 會在目前目錄建出名為空白的目錄、unzip … -d \␠ 會以 root 解壓到那裡 推論,依 bash 語法;2026-11-02 在客戶文件草稿中發現。設定檔用 sudoedit,不用 sudo vi(後者可能在 etc/ 留下含密碼的 .swp)。

  1. 系統帳號(已存在就跳過:id healthcheck)
    sudo useradd -r -s /usr/sbin/nologin -d /opt/mattermost_healthcheck healthcheck
  2. 目錄
    sudo install -d -o root -g root -m 755 /opt/mattermost_healthcheck /opt/mattermost_healthcheck/app
    sudo install -d -o root -g healthcheck -m 750 /opt/mattermost_healthcheck/etc
  3. 解壓與安裝相依(離線)
    sudo unzip -o ~/mm-healthcheck-0.1.1.zip -d /opt/mattermost_healthcheck/app
    sudo python3 -m venv /opt/mattermost_healthcheck/venv
    sudo /opt/mattermost_healthcheck/venv/bin/pip install --no-index \
        --find-links /opt/mattermost_healthcheck/app/wheels -r /opt/mattermost_healthcheck/app/requirements.txt
  4. 設定檔(第 5 節填值)
    sudo cp /opt/mattermost_healthcheck/app/healthcheck.env.example /opt/mattermost_healthcheck/etc/healthcheck.env
    sudo chown root:healthcheck /opt/mattermost_healthcheck/etc/healthcheck.env
    sudo chmod 640 /opt/mattermost_healthcheck/etc/healthcheck.env
    sudoedit /opt/mattermost_healthcheck/etc/healthcheck.env
  5. 先手動確認 DB 連得上(VM 已有 psql;密碼互動輸入,不留在 shell 歷史)
    psql "host=CD53101L port=50419 dbname=postgres user=mm_healthcheck sslmode=require connect_timeout=3" -c "SELECT 1"

    只連 postgres 資料庫、只確認 SELECT 1(2026-11-02 決定):能偵測 PostgreSQL 服務停止、網路或帳密問題;mmdb 單獨損毀或無法連線時偵測不到。

    錯誤對照:no pg_hba.conf entry → DBA 尚未放行(網路與 SSL 其實已通);password authentication failed → 帳密錯;逾時 → 網路/防火牆。

  6. systemd(HTTPS 憑證到位後以 drop-in tls.conf 啟用,不直接改 unit,見第 8 節「HTTPS」)
    sudo cp /opt/mattermost_healthcheck/app/ops/systemd/mm-healthcheck.service /etc/systemd/system/
    sudo systemd-analyze verify /etc/systemd/system/mm-healthcheck.service
    sudo systemctl daemon-reload
    sudo systemctl enable --now mm-healthcheck.service
    systemctl status mm-healthcheck.service --no-pager
  7. 防火牆:GCP 防火牆(點對點申請)只開放經濟部監控來源 IP → CA53101L 的 19999/tcp。VM 本身若有 ufw(sudo ufw status)一併開放 待確認。

實測 2026-10-30:在 ubuntu:26.04(amd64,Python 3.14.4)容器照第 1~4、6 步操作(DB 改連 dev PostgreSQL、sslmode=disable):離線安裝成功、systemd-analyze verify 通過、以 healthcheck 帳號啟動後 GET /health 回 {"status":"000","message":"正常運作"}、其他帳號讀 healthcheck.env 被拒。容器內沒有 systemd 在跑,enable --now 未實測。

實測 2026-11-02(0.1.1,commit 28d3b76,新路徑 /opt/mattermost_healthcheck):同樣在 ubuntu:26.04 amd64 容器照第 1~4、6 步操作:sha256sum -c OK、離線 pip 成功、systemd-analyze verify 通過;以 healthcheck 帳號、unit 的工作目錄與設定檔啟動,啟動行顯示 mm_healthcheck 0.1.1;DB 故意不存在時 GET /health 回 {"status":"500","message":"DB連線異常"}、log 為 reason=connect。

實測 2026-11-02 正式 VM CA53101L,以改名前的 0.1.0、路徑 /opt/mm_healthcheck(repo commit 98ba0b4 的 dist/):

實測 2026-11-02 正式 VM CA53101L,0.1.1、新路徑 /opt/mattermost_healthcheck(安裝檔 mm-healthcheck-0.1.1.zip,SHA256 6cf2a92d…):

DBA 放行後不需重啟服務即可生效(每次檢查都新建連線);但改了 healthcheck.env 一定要 restart,設定只在啟動時讀一次。

從舊目錄 /opt/mm_healthcheck 改名(0.1.0 → 0.1.1)

只有安裝目錄改名;Python 套件 mm_healthcheck、unit 名 mm-healthcheck.service、系統帳號 healthcheck、環境變數 MMHC_* 都不變。

# 0) 若舊服務已啟用,先停掉並移除舊 unit(未啟用則略過)
sudo systemctl disable --now mm-healthcheck.service 2>/dev/null; sudo rm -f /etc/systemd/system/mm-healthcheck.service; sudo systemctl daemon-reload
# 1) 系統帳號改 home 目錄(帳號不必重建)
sudo usermod -d /opt/mattermost_healthcheck healthcheck
# 2) 照第 2~4 步以新路徑建目錄、解壓 0.1.1、建 venv、離線 pip、建設定檔
# 3) 確認新目錄可用後刪除舊目錄
sudo rm -rf /opt/mm_healthcheck

實測 2026-11-02 正式 VM CA53101L:舊服務未曾啟用(無 unit,步驟 0 略過);usermod -d 後 uid 994/gid 986 不變;新路徑 sha256sum -c OK、離線 pip 後 pip freeze 與 requirements.txt 一致、healthcheck 帳號 import 0.1.1 成功;etc/healthcheck.env 重建為 root:healthcheck 640(DB 帳密未填);舊目錄 /opt/mm_healthcheck 與舊 zip 已刪除。

5. 設定(etc/healthcheck.env)

由 systemd EnvironmentFile 載入。缺必填或格式錯誤時服務啟動即失敗,原因看 journalctl -u mm-healthcheck。

變數預設說明
MMHC_DB_HOST/MMHC_DB_PORT/MMHC_DB_NAME必填/5432/必填正式:CD53101L、50419、postgres(2026-11-02 起;只做 SELECT 1,不連 mmdb)
MMHC_DB_USER/MMHC_DB_PASSWORD必填DBA 提供的帳號 mm_healthcheck(2026-11-02;與系統帳號 healthcheck 不同名);pg_hba.conf 已放行連 postgres 實測 2026-11-02。密碼含 $、#、空白時以雙引號包住(systemd 語法)
MMHC_DB_SSLMODErequire與 MM 本身相同。要驗證 DB 憑證改 verify-full 並設 PGSSLROOTCERT
MMHC_ALLOWED_NETWORKS127.0.0.1/32,::1/128來源 IP 白名單,逗號分隔 CIDR 待提供
MMHC_ERROR_HTTP_STATUS200DB 異常時的 HTTP 狀態碼,只能 200 或 5xx。body 一律 status=500 待確認
MMHC_CACHE_SECONDS50~300;0 為每次都查
MMHC_CONNECT_TIMEOUT/MMHC_STATEMENT_TIMEOUT_MS3/2000libpq 的 connect_timeout 最小 2 秒

6. 驗證

# VM 本機(預設白名單只放本機)
curl -si http://127.0.0.1:19999/health     # 改成 HTTPS 後:curl -si --resolve EE531.intra3.moea.gov.tw:19999:127.0.0.1 https://EE531.intra3.moea.gov.tw:19999/health
# HTTP/1.1 200 OK
# content-type: application/json; charset=utf-8
# {"status":"000","message":"正常運作"}

journalctl -u mm-healthcheck -n 20 --no-pager   # 啟動行會列出 DB、白名單、快取、異常 HTTP 碼(不含密碼)

異常時 journald 會有一行 DB 檢查失敗 reason=… latency_ms=… 與原始錯誤。實測 2026-10-30 對 dev PostgreSQL 18.6 的分類結果:

情境reason耗時
正常—(回 000)32 ms
密碼錯/帳號不存在auth< 10 ms
DB 名稱不存在、port 沒在聽、主機名解析失敗、要求 SSL 但 DB 不支援connect< 60 ms
主機不回應(封包被丟)timeout3.0 秒
查詢超過 statement_timeout(以 pg_sleep 模擬)timeout分類已驗證,耗時未計(設定值 2 秒)

同日 HTTP 層 實測:密碼錯時回 {"status":"500","message":"DB連線異常"}+HTTP 200,設 MMHC_ERROR_HTTP_STATUS=503 後回 503;來源 IP 不在白名單回 403;/docs 404、HEAD 405;50 個同時請求後 DB 端沒有殘留連線。

7. 日常維運

要做的事指令
看狀態/logsystemctl status mm-healthcheck、journalctl -u mm-healthcheck -f(每次請求一行 access log,含來源 IP)
改設定(例如加白名單)sudoedit /opt/mattermost_healthcheck/etc/healthcheck.env → sudo systemctl restart mm-healthcheck
DB 換密碼同上;改完立刻 curl 確認回 000
升級升 __version__ 並 commit → 開發機 make package HC=1 NO_BRIDGE=1 WHEELS=1 → 上傳驗證 → 第 4 節第 3 步(解壓、pip)→ unit 有變才重做第 6 步 → sudo systemctl restart mm-healthcheck
暫停sudo systemctl stop mm-healthcheck(監控端會看到連不上,先通知經濟部)

8. 上線前要取得的事項

#事項向誰影響
1DB 帳號 mm_healthcheck 已提供、pg_hba.conf 已放行 10.140.0.4 連 postgres(2026-11-02,已完成)經濟部/DBA第 4 節第 5 步起都要它
2監控機制的來源 IP經濟部MMHC_ALLOWED_NETWORKS、GCP 防火牆
3HTTPS 憑證(網址 https://EE531.intra3.moea.gov.tw:19999/health 已定,2026-11-02);是否經內網 LB 轉送經濟部drop-in tls.conf;憑證須涵蓋該主機名並被監控機制信任;經 LB 時白名單改填 LB IP
4DB 異常時的 HTTP 狀態碼經濟部MMHC_ERROR_HTTP_STATUS(只改設定,不改程式)
5呼叫頻率經濟部是否調整 MMHC_CACHE_SECONDS

給 DBA 的帳號建議 推論

-- 只有 LOGIN,不給任何資料表權限:SELECT 1 不需要
CREATE ROLE mm_healthcheck LOGIN PASSWORD '…';

# pg_hba.conf:只允許從 AP VM(CA53101L,10.140.0.4)以 SSL 連 postgres(放在其他會比對到的規則之前)
hostssl  postgres  mm_healthcheck  10.140.0.4/32  scram-sha-256
# 改完重新載入,不需重啟 DB
SELECT pg_reload_conf();

AP VM 的內網 IP 10.140.0.4 取自 DB 端的錯誤訊息 實測 2026-11-02。

實測 2026-10-30 dev PostgreSQL 18.6:只有 LOGIN 的帳號 SELECT 1 成功、讀 users 表回 permission denied;但它也連得進同機其他 DB(PostgreSQL 預設 PUBLIC 對每個 DB 都有 CONNECT),所以要靠 pg_hba.conf 限縮。

HTTPS 憑證待取得

內網網址為 https://EE531.intra3.moea.gov.tw:19999/health(主機名 2026-11-02 使用者提供;路徑固定為 /health,/healthcheck 等其他路徑回 404)。實測 2026-11-02 在 VM 上 getent hosts 解析為 10.140.0.4(即 CA53101L);這是 VM 本機的解析結果,監控機制那端能否解析到同一 IP 待確認。uvicorn 可直接加 --ssl-certfile/--ssl-keyfile,程式不用改 實測 2026-10-30 dev 以自簽憑證聽 19999:信任該憑證時回 000,不信任時 curl 驗證失敗。

放置憑證(etc/ 為 750,一般帳號看不到裡面,不可用 *.pem 萬用字元:會由呼叫者的 shell 展開失敗,chown 回 No such file or directory 推論):

sudo install -d -o root -g healthcheck -m 750 /opt/mattermost_healthcheck/etc/tls
sudo cp <憑證檔> /opt/mattermost_healthcheck/etc/tls/cert.pem
sudo cp <私鑰檔> /opt/mattermost_healthcheck/etc/tls/key.pem
sudo chown root:healthcheck /opt/mattermost_healthcheck/etc/tls/cert.pem \
    /opt/mattermost_healthcheck/etc/tls/key.pem
sudo chmod 644 /opt/mattermost_healthcheck/etc/tls/cert.pem
sudo chmod 640 /opt/mattermost_healthcheck/etc/tls/key.pem

啟用 HTTPS 用 systemd drop-in,不直接改 unit(升級時 unit 會被覆蓋)。空白的 ExecStart= 用來清掉原本的啟動指令,不可省略 推論,正式 VM 未實測:

sudo install -d -m 755 /etc/systemd/system/mm-healthcheck.service.d
sudo tee /etc/systemd/system/mm-healthcheck.service.d/tls.conf > /dev/null <<'EOF'
[Service]
ExecStart=
ExecStart=/opt/mattermost_healthcheck/venv/bin/uvicorn --factory mm_healthcheck.app:create_app \
    --host 0.0.0.0 --port 19999 --no-proxy-headers --no-server-header \
    --ssl-certfile /opt/mattermost_healthcheck/etc/tls/cert.pem \
    --ssl-keyfile /opt/mattermost_healthcheck/etc/tls/key.pem
EOF
sudo systemctl daemon-reload
sudo systemctl restart mm-healthcheck
systemctl cat mm-healthcheck.service      # 確認 tls.conf 有套用

# 驗證:--resolve 讓本機以憑證上的主機名連線(內部 CA 另加 --cacert <CA 檔>)
curl -si --resolve EE531.intra3.moea.gov.tw:19999:127.0.0.1 https://EE531.intra3.moea.gov.tw:19999/health