SSO Bridge 部署手冊

經濟部 即時訊息工具建置案 · 正式環境 GCP(Ubuntu 26.04,無 Docker)· 程式版本 0.3.0· 更新 2026-10-30

文件狀態:草案。本文的步驟尚未在正式 VM 上跑過。各項以標籤區分: 實測 已在 ubuntu:26.04(amd64)容器內驗證; 推論 依程式碼或文件推得、未實機驗證; 待確認 需向客戶/PM 取得。實機部署後請回頭更正。

1. 部署方式總覽

Bridge 是一次性執行的程式(方案 B,2026-10-12 定案):每次被排程叫起來,向經濟部 API A/B 取資料、同步到 Mattermost、寫 status.json 後結束。排程交給 systemd timer,不常駐。

正式環境沒有 Docker,因此採 Readme 的「方案 2」:系統 Python 3.14 + venv,進入點為 venv/bin/python -m sso_bridge。程式與 Docker 版完全相同,只差在進入點與路徑。

2. 版本與環境

項目值依據
作業系統Ubuntu 26.04.1 LTS(resolute,amd64)已確認 2026-09-21;實測 正式 VM /etc/lsb-release(2026-10-27)
Python3.14.4(系統內建 python3)實測 正式 VM python3 -V(2026-10-27);與 Docker image 同一 minor
venv 模組python3-venv 3.14.3-0ubuntu2、python3.14-venv 3.14.4-1ubuntu0.2 已安裝實測 正式 VM dpkg -l(2026-10-27)
Python 依賴requirements.txt(版號以 == 鎖定)實測 全部以 wheel 安裝,不需編譯器;單元測試全過
Mattermost11.7.9 ESR(同一台 AP VM),聽 *:10011(HTTPS,Cloudflare Origin 憑證)版本已確認 2026-09-21;port 與 TLS 實測 2026-10-28(ss -ltnp、curl -k 回 status: OK)
PostgreSQL18.6(另一台 DB VM)已確認 2026-09-21
系統時區Asia/Taipei(CST, +0800)實測 正式 VM timedatectl(2026-10-27);ubuntu:26.04 容器預設為 UTC
對外網路連不到 PyPI,須走離線安裝實測 正式 VM 2026-10-28:sudo pip install 回 Network is unreachable;一般帳號 curl -4 逾時、curl -6 立即失敗,無 proxy 環境變數。2026-10-27 曾查得 HTTP/2 200。同日經 GCP 管理員暫時開放後線上安裝成功;開放是暫時的,日後重裝請先跑第 4 節第 4 步確認,不通就用 WHEELS=1 的 zip
時區必須是 Asia/Taipei。正式 VM 系統時區已是 Asia/Taipei(實測),但 Docker 版靠 image 的 TZ=Asia/Taipei,venv 部署沒有這層,系統時區若日後被改回 UTC: 本文仍在 systemd unit 設 TZ、timer 指定 Asia/Taipei,不依賴系統設定。

3. 部署檔案與目錄配置

3.1 打包(在開發機)

在 repo 根目錄執行,產出放在 dist/(已列入 .gitignore):

make package            # = scripts/package.sh
make package MOCK=1     # 另出模擬 API 的 zip(經濟部 API 到位前才需要)
make package WHEELS=1   # zip 內附 wheels/,VM 不能連 PyPI 時用(需 Docker;可與 MOCK=1 併用)

同檔名的 zip 已存在時腳本中止,不覆蓋(2026-11-05 起)。已交付或部署的 zip 被蓋掉,dist/ 就對不回 VM 上的版本(2026-10-30 打包 Health Check 時曾蓋掉 Bridge 0.2.0 的 zip)。程式有改就先升版號;要重出已發行的版本,從 tag bridge-v<版號> checkout 再打包;確定要覆蓋才加 FORCE=1。只打包 mock 或 Health Check 時加 NO_BRIDGE=1。

正式 VM 預設連不到 PyPI(2026-10-28 實測;當次由 GCP 管理員暫時開放),建議一律加 WHEELS=1,不論網路通不通都能安裝。

產出內容解壓到 VM
mattermost_sso_bridge-<版號>.zipsso_bridge/(程式)、requirements.txt(相依套件)、pyproject.toml(版號)、config.example.json(組態範本)、ops/systemd/(第 7 節的 unit/timer、mock 的 unit)/opt/mattermost_sso_bridge/app/
moea-mock-<版號>.zip(MOCK=1)app.py、mock-config.json、fixtures/(假資料)、requirements.txt/opt/moea-mock/
SHA256SUMS-<版號>上述 zip 的雜湊值(只更新這次產出的 zip 那幾行,其他行保留)與 zip 放同一目錄,用來驗證傳輸

實測 2026-10-27(commit 3b3cb7d):make package MOCK=1 產出兩個 zip,內容如上表、無機敏檔;有未 commit 修改時中止。再以 ubuntu:26.04(amd64)容器模擬 VM,照第 3.2、4.2(6~10)、5、6、7、10 節操作:雜湊 OK、pip 套件版本與 requirements.txt 一致、--version 0.1.0、mock 起得來、check 對 mock 的 API A(取得 5 筆)/API B/state.db 皆 OK(容器內沒有 Mattermost,該項失敗屬預期)、var/ 檔案擁有者為 bridge、systemd unit verify 通過。

3.2 上傳到 VM

# 開發機
scp dist/mattermost_sso_bridge-0.3.0.zip dist/SHA256SUMS-0.3.0 <帳號>@<VM>:~/
# VM:確認傳輸無誤(mock zip 沒上傳時加 --ignore-missing)
sha256sum -c --ignore-missing SHA256SUMS-0.3.0     # mattermost_sso_bridge-0.3.0.zip: OK

解壓與安裝見第 4 節第 8 步。

3.3 不在 zip 裡、要在 VM 上另外準備的

檔案位置來源
config.jsonetc/由 app/config.example.json 複製後填值(第 5 節)
bridge.envetc/Mattermost token、API A uuid。不進 git、不寄 email
金鑰(moea_public.pem 等)etc/keys/經濟部提供
systemd unit/timer/etc/systemd/system/由 app/ops/systemd/ 複製(第 7 節)

3.4 不要放上正式機的

temp/(含真實人員資料)、dev/(mock 例外,走 mock zip)、tests/、docs/、Dockerfile、Makefile、scripts/、requirements-dev.txt、.git/。用打包腳本就不會帶到,不要自己壓整個資料夾。

3.5 VM 上的目錄配置

/opt/mattermost_sso_bridge/
├── app/          zip 內容(sso_bridge/、requirements.txt、pyproject.toml、ops/…)  root 擁有,唯讀
├── venv/         Python 虛擬環境                                                 root 擁有
├── etc/          config.json、bridge.env、keys/                                 root:bridge,640/750
└── var/          state.db、status.json、sso_bridge.lock、log/                   bridge:bridge,750

執行身份為專用系統帳號 bridge,不用 root(對應 Dockerfile 的非 root 使用者)。var/ 內含帳號對照表與稽核紀錄,建議納入 GCP 磁碟快照 待確認。

4. 安裝步驟

每一步都是「先確認 → 已具備就跳過 → 未具備才執行」。重新安裝或換一台 VM 時照順序跑確認指令即可;所有執行指令重跑也不會壞(可重複執行)。

4.1 環境檢查一覽

先把下表的確認指令全部跑一次,就知道哪些步驟可以跳過。「正式 VM 紀錄」為 2026-10-27 在 CA53101L 查得的結果 實測。

#項目確認指令已具備的判斷正式 VM 紀錄
1作業系統/Pythoncat /etc/lsb-release
python3 -V
Ubuntu 26.04;Python 3.14.x26.04.1 LTS(resolute);3.14.4
2venv 模組dpkg -l python3-venv python3.14-venv 2>/dev/null | grep ^ii兩行皆 ii 開頭已安裝(3.14.3-0ubuntu2/3.14.4-1ubuntu0.2)
3unzipcommand -v unzip印出路徑已安裝(/usr/bin/unzip)
4對外網路sudo curl -sI --max-time 10 https://pypi.org/simple/ | head -1HTTP/2 20010-27 HTTP/2 200;10-28 逾時,經 GCP 管理員暫時開放後可連
5時區timedatectl | grep "Time zone"Asia/TaipeiAsia/Taipei(CST, +0800)
6執行帳號id bridge印出 uid/gid尚未建立
7目錄ls -ld /opt/mattermost_sso_bridge/{app,etc,etc/keys,var,var/log}五個都存在且擁有者正確尚未建立
8程式碼grep ^version /opt/mattermost_sso_bridge/app/pyproject.toml版號等於要部署的版本尚未部署
9venv/opt/mattermost_sso_bridge/venv/bin/python -V與第 1 項的 python3 -V 同一 minor(3.14)尚未建立

4.2 逐步執行

  1. 作業系統與 Python
    cat /etc/lsb-release      # DISTRIB_DESCRIPTION="Ubuntu 26.04.x LTS"
    python3 -V                # Python 3.14.x

    已具備:符合就往下。不符:先停下。Python minor 版號不同(例如 3.15)時,requirements.txt 鎖定的版本需在新版 Python 重新驗證(跑單元測試)後才能部署。

  2. venv 模組
    dpkg -l python3-venv python3.14-venv 2>/dev/null | grep ^ii
    # 進一步確認:實際建一個暫存 venv(不影響系統)
    python3 -m venv /tmp/venvtest && /tmp/venvtest/bin/pip --version; rm -rf /tmp/venvtest

    已具備:兩行 ii,且暫存 venv 印出 pip ... (python 3.14) → 跳過。未具備:沒有輸出,或出現 ensurepip is not available:

    sudo apt update && sudo apt install -y python3-venv

    不通外網時改用預先下載的 .deb(見第 9 節)。

  3. unzip
    command -v unzip

    已具備:印出 /usr/bin/unzip → 跳過。未具備:沒有輸出(Ubuntu minimal 映像預設不裝):

    sudo apt install -y unzip
  4. 對外網路
    sudo curl -sI --max-time 10 https://pypi.org/simple/ | head -1

    已具備:HTTP/2 200 → 第 9 步直接線上安裝。未具備:10 秒內沒有回應 → 第 9 步改用離線指令(zip 需以 WHEELS=1 打包)。

    用 sudo 測,是因為安裝時 pip 也是以 root 執行;--max-time 避免連不到時一直卡住。若一般帳號通、sudo 不通,多半是 proxy 環境變數被 sudo 清掉(env | grep -i proxy 確認),pip 加 --proxy "$https_proxy"。

  5. 時區
    timedatectl | grep "Time zone"

    已具備:Asia/Taipei (CST, +0800) → 跳過。未具備:例如 Etc/UTC:

    sudo timedatectl set-timezone Asia/Taipei

    若 VM 上其他服務要求維持 UTC,可不改系統時區;第 7 節 unit 內的 TZ 與 timer 的時區本來就不依賴系統設定,不可省。

  6. 執行帳號
    id bridge

    已具備:印出 uid=...(bridge) gid=...(bridge) → 跳過。未具備:no such user:

    sudo useradd --system --home-dir /opt/mattermost_sso_bridge --shell /usr/sbin/nologin bridge
  7. 目錄與權限
    ls -ld /opt/mattermost_sso_bridge/{app,etc,etc/keys,var,var/log}

    已具備:五個目錄都在,etc 為 root bridge、var 為 bridge bridge,etc、var、var/log 皆為 drwxr-x--- → 跳過。未具備:以下指令可重複執行,有缺就整段跑:

    sudo mkdir -p /opt/mattermost_sso_bridge/{app,etc/keys,var/log}
    sudo chown -R bridge:bridge /opt/mattermost_sso_bridge/var
    sudo chown -R root:bridge  /opt/mattermost_sso_bridge/etc
    sudo chmod 750 /opt/mattermost_sso_bridge/etc /opt/mattermost_sso_bridge/etc/keys
    sudo chmod 750 /opt/mattermost_sso_bridge/var /opt/mattermost_sso_bridge/var/log

    var/ 內有帳號對照、密碼 HMAC(0.2.0 起)與稽核紀錄,Bridge 建檔是 644,靠目錄 750 擋住其他帳號。正式 VM 0.1.0 部署時 var/ 是 755,2026-10-29 改為 750(實測 改後 status、sync 正常)。

  8. 程式碼(zip 依第 3.2 節上傳並驗證雜湊後)
    grep ^version /opt/mattermost_sso_bridge/app/pyproject.toml

    已具備:版號等於要部署的版本 → 跳過。未具備:檔案不存在或版號較舊(-o 直接覆蓋舊檔):

    sudo unzip -o ~/mattermost_sso_bridge-0.3.0.zip -d /opt/mattermost_sso_bridge/app

    zip 必須是第 3.1 節打包腳本的產出,內容見該節。升級時舊版已刪除的檔案不會被 -o 清掉;版本跨度大時可先 sudo rm -rf /opt/mattermost_sso_bridge/app/* 再解壓(etc/、var/ 不在 app/ 內,不受影響)。

  9. venv 與依賴套件
    /opt/mattermost_sso_bridge/venv/bin/python -V

    已具備:與 python3 -V 同一 minor → 不用重建 venv,只跑下面第二行(pip 只補缺的套件,已裝且版號相同會跳過)。未具備:檔案不存在 → 兩行都跑;minor 版號不同(換過 OS 版本)→ 先 sudo rm -rf /opt/mattermost_sso_bridge/venv 再兩行都跑:

    sudo python3 -m venv /opt/mattermost_sso_bridge/venv
    # 離線(第 4 步不通;正式 VM 目前屬此情況):只從 zip 內的 wheels/ 安裝
    sudo /opt/mattermost_sso_bridge/venv/bin/pip install --no-index \
        --find-links=/opt/mattermost_sso_bridge/app/wheels \
        -r /opt/mattermost_sso_bridge/app/requirements.txt
    # 線上(第 4 步通)
    sudo /opt/mattermost_sso_bridge/venv/bin/pip install -r /opt/mattermost_sso_bridge/app/requirements.txt

    離線指令出現 No matching distribution found 表示 zip 沒附 wheels/(打包時漏了 WHEELS=1)。線上指令若一直印 Retrying ... Network is unreachable,按 Ctrl+C 中斷改用離線指令即可,venv 不需重建。

    一律用 venv 內 pip 的絕對路徑。不要 sudo pip install:會裝到系統 Python,且 Ubuntu 26.04 受 PEP 668 保護會直接被擋(externally-managed-environment)。確認套件版本與 requirements.txt 一致:

    diff <(/opt/mattermost_sso_bridge/venv/bin/pip freeze | sort -f) \
         <(grep -Ev '^(#|$)' /opt/mattermost_sso_bridge/app/requirements.txt | sort -f) && echo 一致
  10. 確認可執行(每次安裝或升級後都要跑,不可跳過)
    cd /opt/mattermost_sso_bridge/app
    sudo -u bridge /opt/mattermost_sso_bridge/venv/bin/python -m sso_bridge --version   # sso_bridge 0.3.0

    實測 正式 VM 2026-10-28 輸出 sso_bridge 0.1.0。python -m 依目前目錄找到 sso_bridge 套件,必須先 cd 到 app/;在其他目錄執行會出現 No module named sso_bridge(正式 VM 實際遇到)。systemd 以 WorkingDirectory 處理。

5. 組態設定

從 config.example.json 複製成 etc/config.json。程式預設路徑是容器內的 /app/...,venv 部署時下列路徑必須全部改寫,否則會寫到不存在的 /app:

欄位容器預設venv 部署改為
crypto.key_path/app/etc/keys/moea_public.pem/opt/mattermost_sso_bridge/etc/keys/moea_public.pem
logging.dir/app/var/log/opt/mattermost_sso_bridge/var/log
state.path/app/var/state.db/opt/mattermost_sso_bridge/var/state.db
state.status_path/app/var/status.json/opt/mattermost_sso_bridge/var/status.json
lock.path/app/var/sso_bridge.lock/opt/mattermost_sso_bridge/var/sso_bridge.lock

組態檔本身的路徑也不是預設值,每次執行都要帶 --config /opt/mattermost_sso_bridge/etc/config.json(--config 寫在子命令之前)。

機敏值

Mattermost token、API A 的 uuid 與密碼比對用的 HMAC 金鑰不寫在 config.json,改由環境變數提供(config 內 *_env 欄位指定變數名),放在另一個檔案給 systemd 讀:

# /opt/mattermost_sso_bridge/etc/bridge.env
MMSSO_MM_TOKEN=xxxxxxxx
MMSSO_DIR_UUID=xxxxxxxx
MMSSO_PASSWORD_HMAC_KEY=xxxxxxxx

MMSSO_PASSWORD_HMAC_KEY:sync.full_password_policy/sync.delta_password_policy 為 on_change(兩者皆預設,差異同步自 0.3.0 起)時用來判斷密碼有沒有變,沒變就不重設——Mattermost 改密碼會撤銷該員所有登入。至少 16 字元,沒設 Bridge 無法啟動。用亂數產生、直接附加進檔案,不要顯示在畫面上:

echo "MMSSO_PASSWORD_HMAC_KEY=$(openssl rand -hex 32)" | sudo tee -a /opt/mattermost_sso_bridge/etc/bridge.env >/dev/null

金鑰遺失或更換不會壞資料,只會讓下一次完整同步把全員密碼重設一次(所有人被登出一次)。

sudo chown root:bridge /opt/mattermost_sso_bridge/etc/{config.json,bridge.env}
sudo chmod 640 /opt/mattermost_sso_bridge/etc/{config.json,bridge.env}
sudo chown root:bridge /opt/mattermost_sso_bridge/etc/keys/*.pem
sudo chmod 640 /opt/mattermost_sso_bridge/etc/keys/*.pem

6. 手動驗證

設排程前依序手動跑,每一步看到預期結果再往下。先在目前的 shell 定義 bridge 函式,條件與 systemd 執行時相同(bridge 帳號、TZ=Asia/Taipei、載入 bridge.env):

bridge() {
  sudo -u bridge env TZ=Asia/Taipei bash -c '
    set -a; . /opt/mattermost_sso_bridge/etc/bridge.env; set +a
    cd /opt/mattermost_sso_bridge/app &&
    exec /opt/mattermost_sso_bridge/venv/bin/python -m sso_bridge \
         --config /opt/mattermost_sso_bridge/etc/config.json "$@"' _ "$@"
}
Ubuntu 26.04 的 sudo 是 sudo-rs(容器實測 sudo-rs 0.2.13),不支援 sudo -E(preserving the entire environment is not supported, '-E' is ignored),在 root shell 載入的環境變數帶不到 bridge 身上。因此改由 bridge 自己讀 bridge.env(權限 root:bridge 640,讀得到)。實測
  1. bridge check — 組態、金鑰、Mattermost(含 system_admin 權限)、API A、API B 連線、state.db。全部通過才 exit 0。
  2. bridge sync --mode full --triage-only — 只抓取與排查,列出排除名單(格式錯誤、重複、沒信箱、離職、MM 已有同名帳號),不寫入。
  3. bridge sync --mode full --dry-run --limit 1 → 再拿掉 --limit — 看 var/log/audit.jsonl 的動作清單是否合理。
  4. bridge sync --mode full --no-dry-run --emp-no <測試帳號員編> — 先寫一個人,用該帳號登入 Mattermost 確認。
  5. bridge status — 確認 status.json 已寫入。

實測 正式 VM 2026-10-28:bridge check 回 Mattermost OK(roles=system_user system_admin)、state.db OK,log 時間為台灣時間;經濟部 API 與金鑰未到位,其餘項目報錯屬預期。

結束代碼意義
0成功
1完成,但有使用者失敗(見 audit.jsonl)
2組態或外部系統錯誤,本次未完成
3取不到執行鎖(前一輪仍在跑)

7. 排程(systemd timer)

採 systemd 而不用 cron:可設逾時、自動帶環境變數與時區、log 進 journald,權限也好收斂。

unit/timer 檔案在 zip 的 ops/systemd/(repo 同路徑),以檔案為準,下方內容僅供閱讀。實測 2026-10-27:ubuntu:26.04 容器內 systemd-analyze verify 無錯誤;systemd-analyze calendar 確認 03:00 Asia/Taipei=19:00 UTC。實機啟用與實際觸發 推論,尚未在正式 VM 驗證。

OnCalendar 帶時區需要 tzdata。缺少時 timer 會被拒絕載入(Failed to parse calendar specification),此為容器實測結果。正式 VM 系統時區已是 Asia/Taipei,表示 tzdata 已裝;換機時以 ls /usr/share/zoneinfo/Asia/Taipei 確認。

差異同步

# ops/systemd/sso-bridge-delta.service  →  /etc/systemd/system/
# 差異同步:由 sso-bridge-delta.timer 每 30 分鐘觸發,跑完即結束(方案 B)。
# 安裝:sudo cp ops/systemd/sso-bridge-*.{service,timer} /etc/systemd/system/
[Unit]
Description=SSO Bridge delta sync
After=network-online.target mattermost.service
Wants=network-online.target

[Service]
Type=oneshot
User=bridge
Group=bridge
WorkingDirectory=/opt/mattermost_sso_bridge/app
# 不依賴系統時區:today_local() 判斷離職日、log 換日都看這裡
Environment=TZ=Asia/Taipei PYTHONUNBUFFERED=1
EnvironmentFile=/opt/mattermost_sso_bridge/etc/bridge.env
ExecStart=/opt/mattermost_sso_bridge/venv/bin/python -m sso_bridge --config /opt/mattermost_sso_bridge/etc/config.json sync --mode delta
# exit 3=取不到執行鎖(與完整同步撞期),屬預期,不算失敗
SuccessExitStatus=3
TimeoutStartSec=25min
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=/opt/mattermost_sso_bridge/var
# ops/systemd/sso-bridge-delta.timer  →  /etc/systemd/system/
[Unit]
Description=SSO Bridge delta sync every 30 minutes

[Timer]
OnCalendar=*-*-* *:00,30:00 Asia/Taipei
Persistent=true

[Install]
WantedBy=timers.target

每日完整同步

sso-bridge-full.service 與上面相同,差別在這三處(完整同步含全員密碼重設,逾時放寬;沒有 SuccessExitStatus=3,撞期時讓失敗看得到):

Description=SSO Bridge full sync
ExecStart=/opt/mattermost_sso_bridge/venv/bin/python -m sso_bridge --config /opt/mattermost_sso_bridge/etc/config.json sync --mode full
TimeoutStartSec=3h
# ops/systemd/sso-bridge-full.timer  →  /etc/systemd/system/
[Unit]
Description=SSO Bridge full sync daily at 03:00

[Timer]
OnCalendar=*-*-* 03:00:00 Asia/Taipei
Persistent=true

[Install]
WantedBy=timers.target

03:00 與 03:30 的差異同步會撞到完整同步,差異同步以 exit 3 跳過,屬正常。完整同步實際耗時要在正式資料量下量測,再調整 TimeoutStartSec 待確認。

安裝與啟用

確認:已安裝且與 zip 內版本相同就跳過複製。

diff -r --exclude=moea-mock.service /opt/mattermost_sso_bridge/app/ops/systemd /etc/systemd/system 2>&1 | grep -v '^Only in /etc' \
  || echo 已是最新

未具備(檔案不存在或有差異):

sudo cp /opt/mattermost_sso_bridge/app/ops/systemd/sso-bridge-*.{service,timer} /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now sso-bridge-delta.timer sso-bridge-full.timer
systemctl list-timers 'sso-bridge-*'     # 確認下次執行時間是台灣時間

8. 日常維運

要做的事指令/位置
看最近一次結果bridge status;加 --max-age-minutes 90 可判斷是否逾時未跑。只有 ok 算健康,partial(有人同步失敗)與 failed 都回 exit 1。dry run/--triage-only 的結果另存 status.dry-run.json,用 bridge status --dry-run 看
看執行過程var/log/bridge.log(每日換檔,留 30 天)或 journalctl -u sso-bridge-delta
看帳號異動稽核var/log/audit.jsonl(一次異動一行,留 365 天)
手動補跑sudo systemctl start sso-bridge-full.service
暫停同步sudo systemctl stop sso-bridge-delta.timer sso-bridge-full.timer
Health check不由 Bridge 提供。經濟部呼叫的 Health Check 是另一個獨立服務,只對 Mattermost 的 PostgreSQL 執行 SELECT 1(2026-10-29 會議定案)。部署見 Health Check Service 部署手冊;網址與 DB 帳號 待確認。bridge status 只供本機維運

升級:開發機 make package → 依第 3.2 節上傳驗證 → 第 4 節第 8~10 步(解壓、pip、確認可執行)→ 第 7 節「安裝與啟用」(unit 有變才需複製)。Ubuntu 自動更新只會動 Python 的 patch 版號,不影響 venv 推論;若 Python minor 版號變了(換 OS 版本),venv 要重建。

從 0.2.0 升級到 0.3.0

0.3.0 的變更(推論 讀程式碼;單元測試 141 項全過,dev 環境實測團隊檢查,尚未在正式 VM 跑過):

變更影響
差異同步也比對密碼:delta_password_policy 預設由 never 改為 on_change每 30 分鐘 type=update 回來的在職者逐人呼叫 API B,密碼與上次寫入的 HMAC 不同才重設(該員被登出),相同記 update_password:skipped。0.2.0 已有 HMAC 紀錄,不會全員重設
依處室加入團隊:新增 mattermost.team_map沒設就跟 0.2.0 一樣,全部加入 team_name
同步開始前先查齊所有團隊 id(dry run 也查)團隊名稱填錯時整輪中止(exit 2),不再建出沒有團隊的帳號

requirements.txt 與 state.db schema 都沒變,systemd unit/timer 也沒變。

  1. 暫停排程並備份
    sudo systemctl stop sso-bridge-delta.timer sso-bridge-full.timer
    sudo -u bridge sh -c 'cd /opt/mattermost_sso_bridge/var &&
      for f in state.db state.db-wal; do [ -f "$f" ] && cp -p "$f" "$f.bak-0.2.0"; done; ls -l state.db*'
    sudo cp -a /opt/mattermost_sso_bridge/app /opt/mattermost_sso_bridge/app.bak-0.2.0
    sudo cp -p /opt/mattermost_sso_bridge/etc/config.json /opt/mattermost_sso_bridge/etc/config.json.bak-0.2.0
  2. 程式碼:依第 3.2 節上傳 mattermost_sso_bridge-0.3.0.zip,第 4 節第 8~10 步解壓、安裝套件、確認 --version 為 0.3.0。
  3. config.json:先看目前的密碼與團隊設定
    sudo python3 -c 'import json; d=json.load(open("/opt/mattermost_sso_bridge/etc/config.json")); s=d["sync"]; m=d["mattermost"]
    print("delta_password_policy =", s.get("delta_password_policy", "(未設定,用預設)"))
    print("team_name =", m.get("team_name"), " add_to_team =", m.get("add_to_team"), " team_map =", m.get("team_map"))'
    • delta_password_policy 若明寫 never,改為 on_change(或刪掉這行用預設);未設定則不用動。
    • team_map 視需要加,例如 {"20147": "isc"}。對照表以外的處室要不要仍加入 isc(保留 team_name)待確認;未決定前不加 team_map,行為與 0.2.0 相同。
    sudo python3 - <<'PY'
    import json
    p = "/opt/mattermost_sso_bridge/etc/config.json"
    d = json.load(open(p, encoding="utf-8"))
    d["sync"]["delta_password_policy"] = "on_change"
    # d["mattermost"]["team_map"] = {"20147": "isc"}   # 決定後再打開
    open(p, "w", encoding="utf-8").write(json.dumps(d, ensure_ascii=False, indent=4) + "\n")
    PY
  4. 確認:bridge check 印「密碼策略:full=on_change,delta=on_change,HMAC 金鑰已設定」、「團隊 isc 的 id=…」且通過;bridge sync --mode delta --dry-run 與 --mode full --dry-run 正常。
  5. 恢復排程:sudo systemctl start sso-bridge-delta.timer sso-bridge-full.timer

升級後第一次差異同步:type=update 回來的人會各呼叫一次 API B;密碼沒變的人記 update_password:skipped、不會被登出。

退回 0.2.0:停排程,還原 app.bak-0.2.0/ 與 config.json.bak-0.2.0;state.db 不用還原(schema 沒變),出問題時才還原 state.db.bak-0.2.0。

從 0.1.0 升級到 0.2.0

0.2.0 的密碼預設改為「有變才重設」(full_password_policy=on_change):Mattermost 改密碼會撤銷該員所有登入(實測 2026-10-29,密碼沒變也一樣),0.1.0 的 always 會讓全員每天 03:00 被登出。升級要多做設定,沒設 HMAC 金鑰 0.2.0 無法啟動。以下步驟 實測 2026-10-29 正式 VM 照做完成(commit 296f4f8)。

  1. 暫停排程並備份 state.db(0.2.0 第一次開啟時會自動加欄位,schema 1 → 2)
    sudo systemctl stop sso-bridge-delta.timer sso-bridge-full.timer
    sudo -u bridge sh -c 'cd /opt/mattermost_sso_bridge/var &&
      for f in state.db state.db-wal; do [ -f "$f" ] && cp -p "$f" "$f.bak-0.1.0"; done; ls -l state.db*'

    var/ 屬 bridge,一般帳號進不去,所以整段以 bridge 身分執行。

    退回要用的舊版程式:VM 上若還留著 0.1.0 的 zip 就保留它;沒有的話(正式 VM 屬此情況)先把整個 app/ 與 config.json 備份起來:

    sudo cp -a /opt/mattermost_sso_bridge/app /opt/mattermost_sso_bridge/app.bak-0.1.0
    sudo cp -p /opt/mattermost_sso_bridge/etc/config.json /opt/mattermost_sso_bridge/etc/config.json.bak-0.1.0
  2. 程式碼:依第 3.2 節上傳 mattermost_sso_bridge-0.2.0.zip,第 4 節第 8~10 步解壓、安裝套件(requirements.txt 與 0.1.0 相同)、確認 --version 為 0.2.0。
  3. HMAC 金鑰(亂數產生,直接附加,不顯示在畫面上)
    echo "MMSSO_PASSWORD_HMAC_KEY=$(openssl rand -hex 32)" | sudo tee -a /opt/mattermost_sso_bridge/etc/bridge.env >/dev/null
    sudo grep -c '^MMSSO_PASSWORD_HMAC_KEY=' /opt/mattermost_sso_bridge/etc/bridge.env   # 1
  4. config.json:sync.full_password_policy 改 on_change、加 password_hmac_key_env
    sudo python3 - <<'PY'
    import json
    p = "/opt/mattermost_sso_bridge/etc/config.json"
    d = json.load(open(p, encoding="utf-8"))
    d["sync"]["full_password_policy"] = "on_change"
    d["sync"]["password_hmac_key_env"] = "MMSSO_PASSWORD_HMAC_KEY"
    open(p, "w", encoding="utf-8").write(json.dumps(d, ensure_ascii=False, indent=4) + "\n")
    PY
  5. 確認:bridge check 多一行「密碼策略:full=on_change,delta=never,HMAC 金鑰已設定」且通過;bridge sync --mode full --dry-run 正常。config.json 的 sync._comment 仍是 0.1.0 的說明,不影響行為;要同步可從 app/config.example.json 複製(正式 VM 已更新)。
  6. 恢復排程:sudo systemctl start sso-bridge-delta.timer sso-bridge-full.timer

升級後第一次完整同步會把全員密碼重設一次(所有人被登出一次):0.1.0 建的帳號在 state.db 沒有 HMAC 紀錄,一律當作有變;第二次起才會出現 update_password:skipped。要避開上班時間,就讓它在 03:00 排程自然發生。之後換 HMAC 金鑰也會同樣全員重設一次。

實測 正式 VM 2026-10-29:第一次 full update_password:ok 4(原登入被撤銷);第二次 full update_password:skipped 4,4 個帳號原登入都仍有效;mock 改一人密碼後只有該員被登出。

退回 0.1.0:停排程、還原上面備份的 state.db、app/(或解壓 0.1.0 的 zip)與 config.json;bridge.env 多的金鑰行 0.1.0 不會讀,可留著。

9. 離線安裝

正式 VM 連不到 PyPI(2026-10-28 實測),目前採離線安裝。wheel 必須在與 VM 相同的 OS/Python/架構產出,否則 C 擴充套件(cryptography、cffi、mock 的 pydantic_core)會裝不起來;打包腳本已自動在 ubuntu:26.04(amd64、Python 3.14.4)容器內下載:

make package WHEELS=1            # Bridge zip 內附 wheels/(8 個)
make package MOCK=1 WHEELS=1     # 連同 mock zip 內附 wheels/(17 個)

解壓後 wheel 位於 /opt/mattermost_sso_bridge/app/wheels/、/opt/moea-mock/wheels/,安裝指令見第 4 節第 9 步與第 10 節。

實測 2026-10-28:以 --network none 的 ubuntu:26.04 容器(無任何網路)解壓兩個 zip 並離線安裝,Bridge --version 0.1.0、mock import app 皆成功。

系統套件(python3-venv、unzip)正式 VM 已安裝;換機時若缺,需另備 .deb(sudo dpkg -i *.deb)。

10. 模擬 API(經濟部 API 到位前)

經濟部 API 尚未提供,可先把開發環境的 dev/moea-mock 放在同一台 AP VM,驗證部署本身(systemd、時區、權限、連 Mattermost、log、status.json)。不另外架主機:mock 模擬不到真正的難點(GCP 連經濟部內網),多一台只多成本與防火牆設定。

開發機 make package MOCK=1 WHEELS=1 產出 moea-mock-<版號>.zip,與 SHA256SUMS 一起上傳後:

test -f /opt/moea-mock/app.py || {            # 已安裝就跳過
  sudo mkdir -p /opt/moea-mock
  sudo unzip -o ~/moea-mock-0.2.0.zip -d /opt/moea-mock
  sudo python3 -m venv /opt/moea-mock/venv
  sudo /opt/moea-mock/venv/bin/pip install --no-index --find-links=/opt/moea-mock/wheels \
       -r /opt/moea-mock/requirements.txt          # 線上安裝則拿掉 --no-index --find-links=…
}
sudo ss -ltnp | grep ':8001 ' || echo "8001 沒被佔用"   # 有輸出表示被佔用,要換 port(見下方說明)
sudo cp /opt/mattermost_sso_bridge/app/ops/systemd/moea-mock.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now moea-mock
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:8001/DIRS/getEmployeeList   # 有回 HTTP 狀態碼即表示服務已起來

unit 檔案內容(ops/systemd/moea-mock.service):

# ops/systemd/moea-mock.service  →  /etc/systemd/system/
# 模擬經濟部 API A/B:經濟部 API 到位前暫用,上線前必須停用並移除。
# 只綁 127.0.0.1:/_mock/* 控制端點沒有驗證(可重設資料、刪人、注入故障)。
[Unit]
Description=MOEA API mock (temporary, remove before go-live)
After=network.target

[Service]
User=bridge
Group=bridge
WorkingDirectory=/opt/moea-mock
Environment=TZ=Asia/Taipei
ExecStart=/opt/moea-mock/venv/bin/uvicorn app:app --host 127.0.0.1 --port 8001
Restart=on-failure
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes

[Install]
WantedBy=multi-user.target

Bridge 的 directory.base_url 與 password_api.base_url 改指 http://127.0.0.1:8001,crypto.mode 用 base64(mock 預設);directory.sys_code 填 MMSSO、bridge.env 的 MMSSO_DIR_UUID 填 mock 的假值 11111111-2222-4333-8444-555555555555(見 mock-config.json)。mock 套件在 26.04 可裝 實測。

port 是 8001,只寫在 unit 的 --port,mock 程式本身沒寫死(開發環境 Docker 仍用 8080,互不影響)。要換 port 時兩邊一起改:mock 用 sudo systemctl edit moea-mock 加覆寫(先寫一行空的 ExecStart= 清掉原值,再寫新的 ExecStart=…--port <新 port>),Bridge 的兩個 base_url 改成同一個 port。選 1024 以上(mock 以 bridge 執行,非 root),避開 VM 已用的 22、10011(Mattermost)、8067(Mattermost metrics)。

11. 上線檢查清單

  1. 若曾用 mock:systemctl disable --now moea-mock 並刪除 /opt/moea-mock。
  2. 刪除 mock 建立的假帳號(永久刪除需先開 ServiceSettings.EnableAPIUserDeletion,用完再關)。
  3. 清空 var/state.db、status.json,避免假資料的對照殘留。
  4. config 換成正式 API 網址、crypto.mode、正式金鑰與 key_not_after。
  5. 重跑第 6 節全部步驟;--triage-only 的排除名單請 PM/客戶確認。
  6. 首次完整同步確認無誤後,sync.dry_run 改為 false,再啟用兩個 timer。
  7. 確認 systemctl list-timers 的時間是台灣時間。

12. 待確認事項