Health Check Service 部署手冊
/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 |
- 端點只有
GET /health(路徑待網址確定後可改);HEAD/POST回 405,/docs、/openapi.json不提供。 - 錯誤細節(分類
timeout/connect/auth/query、耗時、原始訊息)只寫 journald,不回給呼叫端:原始訊息含 DB 主機與帳號。 - 連線逾時 3 秒+查詢逾時 2 秒,單次檢查最長約 5 秒。結果快取 5 秒、同時只跑一個檢查:監控同時打進多個請求只會連一次 DB。
- 只提供內網呼叫(2026-10-30 確認),不經 Cloudflare、不對外開放。
- 沒有反向代理,白名單看的是直連對端 IP;unit 以
--no-proxy-headers啟動,不信任X-Forwarded-For。
2. 版本與環境
| 項目 | 值 | 依據 |
|---|---|---|
| 作業系統/Python | Ubuntu 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 DB | PostgreSQL 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 port | 19999,只提供內網呼叫 | 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)。
- 系統帳號(已存在就跳過:
id healthcheck)sudo useradd -r -s /usr/sbin/nologin -d /opt/mattermost_healthcheck healthcheck - 目錄
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 - 解壓與安裝相依(離線)
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 - 設定檔(第 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 - 先手動確認 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→ 帳密錯;逾時 → 網路/防火牆。 - 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 - 防火牆: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/):
- 第 1 步:
healthcheck原本不存在,建立後 uid 994/gid 986,shell/usr/sbin/nologin。 - 第 2 步:三個目錄的擁有者與權限與上方配置一致(
etc/為root:healthcheck 750)。 - 第 3 步:
sha256sum -c為mm-healthcheck-0.1.0.zip: OK(bd507808…3d2fba);離線 pip 成功,pip freeze與requirements.txt完全一致;以healthcheck帳號 import 成功(psycopg3.3.6,pq.__impl__=binary)。 - 第 4 步:
healthcheck.env已建立,root:healthcheck 640,登入帳號直接讀被拒;DB 帳密尚未填入。 - 第 5 步:DBA 提供的帳號為
mm_healthcheck。psql 回FATAL: no pg_hba.conf entry for host "10.140.0.4", user "mm_healthcheck", database "mmdb", SSL encryption:已連到CD53101L(10.140.0.5)且 SSL 已建立,只差pg_hba.conf放行;密碼尚未驗到。 - 第 6、7 步尚未執行(必填欄位空白時服務會啟動失敗)。
實測 2026-11-02 正式 VM CA53101L,0.1.1、新路徑 /opt/mattermost_healthcheck(安裝檔 mm-healthcheck-0.1.1.zip,SHA256 6cf2a92d…):
- 第 5 步:DBA 放行後提供的截圖:在
CA53101L以mm_healthcheck連CD53101L:50419的postgres資料庫,SELECT 1回1,TLSv1.3(DBA 截圖)。mmdb是否放行未測,改連postgres後不需要。 - 第 4 步:使用者以
sudoedit填入 DB 帳密(Claude 未經手密碼)。 - 第 6 步:
systemd-analyze verify無輸出;enable --now建立multi-user.target.wantssymlink,狀態active (running),18:44:20 CST 啟動。 - 驗證:
curl -s http://127.0.0.1:19999/health回{"status":"000","message":"正常運作"}。服務啟動前同一指令無輸出(連不上 port,屬預期)。 - 尚未完成:HTTPS(等憑證)、白名單仍為本機(等監控來源 IP)、防火牆。
DBA 放行後不需重啟服務即可生效(每次檢查都新建連線);但改了 healthcheck.env 一定要 restart,設定只在啟動時讀一次。
從舊目錄 /opt/mm_healthcheck 改名(0.1.0 → 0.1.1)
只有安裝目錄改名;Python 套件 mm_healthcheck、unit 名 mm-healthcheck.service、系統帳號 healthcheck、環境變數 MMHC_* 都不變。
- venv 不能用
mv搬:venv/bin/下的pip、uvicorn等腳本開頭寫死舊路徑的 python,搬過去就失效,一律重建。 - unit 與目錄要一起換:0.1.0 的 unit 指向舊路徑,與新目錄混用會因
WorkingDirectory/EnvironmentFile不存在而啟動失敗。 - 舊
etc/healthcheck.env若已填 DB 帳密,刪除前先sudo cp -p到新的etc/,避免重填。
# 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_SSLMODE | require | 與 MM 本身相同。要驗證 DB 憑證改 verify-full 並設 PGSSLROOTCERT |
MMHC_ALLOWED_NETWORKS | 127.0.0.1/32,::1/128 | 來源 IP 白名單,逗號分隔 CIDR 待提供 |
MMHC_ERROR_HTTP_STATUS | 200 | DB 異常時的 HTTP 狀態碼,只能 200 或 5xx。body 一律 status=500 待確認 |
MMHC_CACHE_SECONDS | 5 | 0~300;0 為每次都查 |
MMHC_CONNECT_TIMEOUT/MMHC_STATEMENT_TIMEOUT_MS | 3/2000 | libpq 的 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 |
| 主機不回應(封包被丟) | timeout | 3.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. 日常維運
| 要做的事 | 指令 |
|---|---|
| 看狀態/log | systemctl 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. 上線前要取得的事項
| # | 事項 | 向誰 | 影響 |
|---|---|---|---|
| 1 | DB 帳號 mm_healthcheck 已提供、pg_hba.conf 已放行 10.140.0.4 連 postgres(2026-11-02,已完成) | 經濟部/DBA | 第 4 節第 5 步起都要它 |
| 2 | 監控機制的來源 IP | 經濟部 | MMHC_ALLOWED_NETWORKS、GCP 防火牆 |
| 3 | HTTPS 憑證(網址 https://EE531.intra3.moea.gov.tw:19999/health 已定,2026-11-02);是否經內網 LB 轉送 | 經濟部 | drop-in tls.conf;憑證須涵蓋該主機名並被監控機制信任;經 LB 時白名單改填 LB IP |
| 4 | DB 異常時的 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 驗證失敗。
- 憑證必須涵蓋
EE531.intra3.moea.gov.tw,且被監控機制信任。MM 現用的 Cloudflare Origin 憑證一般客戶端不信任,不能共用 推論。可行做法:經濟部內部 CA 簽發,或確認監控機制不驗憑證 待確認。 - 若監控機制實際是經內網 Load Balancer 轉到 VM(而非直連),TLS 在 LB 終止、VM 不必放憑證,但
MMHC_ALLOWED_NETWORKS要填 LB 的 IP(unit 不信任X-Forwarded-For) 待確認架構。以下為直連 VM 的做法。
放置憑證(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
- 防火牆兩層:GCP(點對點申請)與 VM 本機(2026-09-01 會議:「本機也需要設定」)。