SSO Bridge 部署手冊
ubuntu:26.04(amd64)容器內驗證;
推論 依程式碼或文件推得、未實機驗證;
待確認 需向客戶/PM 取得。實機部署後請回頭更正。
1. 部署方式總覽
Bridge 是一次性執行的程式(方案 B,2026-10-12 定案):每次被排程叫起來,向經濟部 API A/B 取資料、同步到 Mattermost、寫 status.json 後結束。排程交給 systemd timer,不常駐。
- 差異同步:
sync --mode delta,每 30 分鐘。 - 每日完整同步:
sync --mode full,每日 03:00(台灣時間),含全員密碼重設。首次初始化也跑這個。 - 兩者共用程式內建的執行鎖(
fcntl.flock),撞期時後到者以 exit 3 結束,不會同時寫入。
正式環境沒有 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) |
| Python | 3.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 安裝,不需編譯器;單元測試全過 |
| Mattermost | 11.7.9 ESR(同一台 AP VM),聽 *:10011(HTTPS,Cloudflare Origin 憑證) | 版本已確認 2026-09-21;port 與 TLS 實測 2026-10-28(ss -ltnp、curl -k 回 status: OK) |
| PostgreSQL | 18.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 |
TZ=Asia/Taipei,venv 部署沒有這層,系統時區若日後被改回 UTC:
- 離職判斷(
sso_bridge/util.py的today_local())在台灣時間 00:00–08:00 會晚一天; bridge.log在台灣早上 8 點才換日;- 排程寫 03:00 實際是台灣時間 11:00。
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-<版號>.zip | sso_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 放同一目錄,用來驗證傳輸 |
- 腳本用
git archive從 HEAD 取檔,只收已 commit 的檔案,所以temp/(含真實人員資料)、config.json、金鑰、state.db、__pycache__不可能被打包進去。 - 要打包的路徑有未 commit 的修改時,腳本會列出檔案並中止,避免 zip 內容與工作目錄不一致。
- zip 名稱的版號取自
pyproject.toml;腳本輸出會印 commit hash,請記在交付紀錄。
實測 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.json | etc/ | 由 app/config.example.json 複製後填值(第 5 節) |
bridge.env | etc/ | 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 | 作業系統/Python | cat /etc/lsb-releasepython3 -V | Ubuntu 26.04;Python 3.14.x | 26.04.1 LTS(resolute);3.14.4 |
| 2 | venv 模組 | dpkg -l python3-venv python3.14-venv 2>/dev/null | grep ^ii | 兩行皆 ii 開頭 | 已安裝(3.14.3-0ubuntu2/3.14.4-1ubuntu0.2) |
| 3 | unzip | command -v unzip | 印出路徑 | 已安裝(/usr/bin/unzip) |
| 4 | 對外網路 | sudo curl -sI --max-time 10 https://pypi.org/simple/ | head -1 | HTTP/2 200 | 10-27 HTTP/2 200;10-28 逾時,經 GCP 管理員暫時開放後可連 |
| 5 | 時區 | timedatectl | grep "Time zone" | Asia/Taipei | Asia/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 | 版號等於要部署的版本 | 尚未部署 |
| 9 | venv | /opt/mattermost_sso_bridge/venv/bin/python -V | 與第 1 項的 python3 -V 同一 minor(3.14) | 尚未建立 |
4.2 逐步執行
- 作業系統與 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 重新驗證(跑單元測試)後才能部署。 - 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 節)。 - unzip
command -v unzip已具備:印出
/usr/bin/unzip→ 跳過。未具備:沒有輸出(Ubuntu minimal 映像預設不裝):sudo apt install -y unzip - 對外網路
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"。 - 時區
timedatectl | grep "Time zone"已具備:
Asia/Taipei (CST, +0800)→ 跳過。未具備:例如Etc/UTC:sudo timedatectl set-timezone Asia/Taipei若 VM 上其他服務要求維持 UTC,可不改系統時區;第 7 節 unit 內的
TZ與 timer 的時區本來就不依賴系統設定,不可省。 - 執行帳號
id bridge已具備:印出
uid=...(bridge) gid=...(bridge)→ 跳過。未具備:no such user:sudo useradd --system --home-dir /opt/mattermost_sso_bridge --shell /usr/sbin/nologin bridge - 目錄與權限
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/logvar/內有帳號對照、密碼 HMAC(0.2.0 起)與稽核紀錄,Bridge 建檔是 644,靠目錄 750 擋住其他帳號。正式 VM 0.1.0 部署時var/是 755,2026-10-29 改為 750(實測 改後status、sync正常)。 - 程式碼(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/appzip 必須是第 3.1 節打包腳本的產出,內容見該節。升級時舊版已刪除的檔案不會被
-o清掉;版本跨度大時可先sudo rm -rf /opt/mattermost_sso_bridge/app/*再解壓(etc/、var/不在app/內,不受影響)。 - 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 一致 - 確認可執行(每次安裝或升級後都要跑,不可跳過)
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
- Mattermost token 必須是 system admin 的 personal access token,否則無法代改他人密碼(
check會擋下)。 - Bridge 與 Mattermost 同機,但正式 VM 的 Mattermost 不是預設的 8065,而是聽
*:10011(實測 2026-10-28sudo ss -ltnp,前面沒有 nginx)。Mattermost 自己提供 TLS(ConnectionSecurity: TLS),憑證為 Cloudflare Origin Certificate(只有 Cloudflare 信任,一般 CA 清單不認),使用者經 Cloudflare 連SiteURL。因此:- 暫行:
base_url填https://127.0.0.1:10011、verify_tls填false(只走本機迴路,仍加密,只是不驗證對方身分)。 - 不要用
SiteURL:會繞出 VM 經 Cloudflare 再回來,受對外網路限制影響。 - 不要在
/etc/hosts把SiteURL網域指到 127.0.0.1:本機 443 沒有服務,Mattermost 自己或其他程式連SiteURL時會壞掉。 - 正式上線前改為驗證憑證:需程式支援指定 CA(Cloudflare Origin CA 根憑證)與 TLS 主機名稱 待實作。
sudo ss -ltnp | grep mattermost確認 port。 - 暫行:
- 團隊:
mattermost.add_to_team=true時,新建與重新啟用的帳號依處室(goid_org)查team_map加入團隊,查不到用team_name,兩者都沒有就不加入。值一律填團隊的 URL 名稱(正式 MM「資訊處」是isc,實測 2026-10-29),不是顯示名稱。任何一個團隊查不到,check失敗、sync整輪中止(0.3.0 起)。 sync.dry_run保持true,正式啟用前再改(見第 11 節)。- 金鑰有效期(筆記:預設半年)填
crypto.key_not_after,到期程式會拒絕執行。
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 "$@"' _ "$@"
}
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,讀得到)。實測bridge check— 組態、金鑰、Mattermost(含 system_admin 權限)、API A、API B 連線、state.db。全部通過才 exit 0。bridge sync --mode full --triage-only— 只抓取與排查,列出排除名單(格式錯誤、重複、沒信箱、離職、MM 已有同名帳號),不寫入。bridge sync --mode full --dry-run --limit 1→ 再拿掉--limit— 看var/log/audit.jsonl的動作清單是否合理。bridge sync --mode full --no-dry-run --emp-no <測試帳號員編>— 先寫一個人,用該帳號登入 Mattermost 確認。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 也沒變。
- 暫停排程並備份
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 - 程式碼:依第 3.2 節上傳
mattermost_sso_bridge-0.3.0.zip,第 4 節第 8~10 步解壓、安裝套件、確認--version為0.3.0。 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- 確認:
bridge check印「密碼策略:full=on_change,delta=on_change,HMAC 金鑰已設定」、「團隊 isc 的 id=…」且通過;bridge sync --mode delta --dry-run與--mode full --dry-run正常。 - 恢復排程:
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)。
- 暫停排程並備份
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 - 程式碼:依第 3.2 節上傳
mattermost_sso_bridge-0.2.0.zip,第 4 節第 8~10 步解壓、安裝套件(requirements.txt與 0.1.0 相同)、確認--version為0.2.0。 - 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 config.json:sync.full_password_policy改on_change、加password_hmac_key_envsudo 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- 確認:
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 已更新)。 - 恢復排程:
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)。
- 只能綁 127.0.0.1。mock 的
/_mock/*控制端點沒有驗證,可重設資料、刪人、注入故障。 - 寫入的是正式 Mattermost。fixture 的假職員(
example.gov.tw)會變成真帳號。先用 dry run,真的要寫入時用--emp-no/--limit控制範圍。 - 只有在經濟部或其他廠商需要從外部連進來打 mock 時,才值得另架主機,屆時必須加驗證或限制來源 IP。
11. 上線檢查清單
- 若曾用 mock:
systemctl disable --now moea-mock並刪除/opt/moea-mock。 - 刪除 mock 建立的假帳號(永久刪除需先開
ServiceSettings.EnableAPIUserDeletion,用完再關)。 - 清空
var/state.db、status.json,避免假資料的對照殘留。 - config 換成正式 API 網址、
crypto.mode、正式金鑰與key_not_after。 - 重跑第 6 節全部步驟;
--triage-only的排除名單請 PM/客戶確認。 - 首次完整同步確認無誤後,
sync.dry_run改為false,再啟用兩個 timer。 - 確認
systemctl list-timers的時間是台灣時間。
12. 待確認事項
- 網路(影響能否上線):GCP VM 如何連到經濟部內網的 API A/B——VPN,或對方防火牆開白名單給我方固定出口 IP(Cloud NAT/靜態 IP)。建議現在就問,不必等 API 文件。
- 「沒有 Docker」是沒裝還是不允許裝。本文已以 venv 為正式方案,此項僅影響是否保留 Docker 選項。
var/是否納入 GCP 快照;完整同步在正式資料量下的耗時。- Health Check Service 的網址/port、經濟部來源 IP(白名單)、DB 帳號密碼(對方日後提供)。檢查方式已定:只查 Mattermost 的 PostgreSQL
SELECT 1。 - 同步頻率(API A 的
type=update只回當日異動,30 分鐘差異同步是否仍成立)。 - 改密碼的人會不會出現在
type=update。0.3.0 先假設會(差異同步比對密碼 HMAC);若不會,流程不用改,新密碼改由每日完整同步套用。 - 團隊:對照表(
team_map)以外的處室是否仍加入isc;換處室時是否移團隊;科別對應頻道的名稱與換科處理。