AI 證據自動分類 — 部署指引

適用版本:v1.2.1+ 狀態:experimental,適用 dev / STG;production 部署等 DB 化(v1)後再評估 相關文件:spec.md(行為規格)、design.md(設計決策)

┌─────────────────────────────────────────────────┐
│  BE host(STG 主機)                              │
│                                                 │
│  ┌──────────────┐   spawn      ┌──────────────┐│
│  │ BE process   │─────────────▶│ Docker daemon││
│  │ (Flask)      │              │              ││
│  │              │              │ ┌──────────┐ ││
│  │ ANTHROPIC_   │              │ │ classifier│││
│  │ API_KEY env  │              │ │ container│ ││
│  └──────┬───────┘              │ │ (-rm)    │ ││
│         │                      │ └──────────┘ ││
│         │ shell out            └──────────────┘│
│         │ libreoffice --convert                 │
│         ▼                                       │
│  ┌──────────────┐                              │
│  │ LibreOffice  │ (預覽 docx→pdf 用)            │
│  └──────────────┘                              │
└─────────────────────────────────────────────────┘
         │
         │ HTTPS
         ▼
┌──────────────────┐        ┌────────────────────┐
│ Google Drive API │        │ Anthropic Claude API│
└──────────────────┘        └────────────────────┘

重點:

• Classifier docker container 跑在 BE host 本機 daemon(同機),不另外起 registry / orchestrator
• BE 用 subprocess.run(["docker", "run", "--rm", ...]) 拉起 → 拿結果 → container 自動清掉
• BE 跑的 user 必須在 docker group(可不用 sudo 起 container)

2.1 Docker daemon

docker ps           # 不該噴 permission denied / cannot connect
docker info         # 應正常列出 daemon 資訊

如果 BE 跑的 user 沒權限:

sudo usermod -aG docker <BE-user>
# 重新登入該 user(group 變更需要新 session)

2.2 LibreOffice(預覽 docx → PDF 用)

which libreoffice || which soffice
# 應該回 /usr/bin/libreoffice 或類似
libreoffice --version    # 確認版本

如果未安裝:

• Ubuntu/Debian:sudo apt install -y libreoffice --no-install-recommends
• 與 SSP 匯出共用,通常 STG 已有

2.3 環境變數

BE process 必須能讀到:

ANTHROPIC_API_KEY=sk-ant-...    # Anthropic API key,classifier 用

放法(擇一):

• systemd service 用 EnvironmentFile=/etc/guidant/.env
• supervisord environment=ANTHROPIC_API_KEY=...
• 直接寫進啟動 script 的 export

禁止 commit .env / API key 任何含憑證的檔到 git(per CLAUDE.md)。

2.4 磁碟空間

Container 跑時會在 BE host /tmp/cm-jobs/<job_uid>/ 放 catalog.json + _state.json + _report-original.json(每 job 約 1-2 MB)。

df -h /tmp     # 至少預留 1GB,長期堆積要加定期清理(下方 §6)

2.5 Drive OAuth Redirect URI

進 Google Cloud Console → 該 OAuth Client 的 Authorized redirect URIs,加上 STG 域名的 callback,例如:

https://stg.your-domain.com/api/1.0/integrations/google-drive/oauth-callback

否則 STG 連 Drive 時會被 Google 擋掉。

v0.4 init folders 流程才會建 Evidences/ subfolder。v0.3 之前 init 的專案沒有,要重跑 init 補上。

由 PM 在 UI 操作:

1. 進專案 → ProjectPlanning → Cloud Integrations tab
2. 點「初始化專案資料夾」(POST /api/1.0/integrations/google-drive/projects/<project_uid>/init-folders)
3. handler 是 idempotent — 既有的資料夾用 find-or-create 接管,只多建 Evidences/(以及對應的 EVIDENCES drive_folder_mappings 紀錄)

不重跑的話 → 該專案的「自動分類證據」按鈕不會顯示(drive_ready=false,因為 _derive_evidence_folder_id 找不到 Evidences 資料夾)。

6.1 Container 殘留清理

--rm 旗標讓 container 跑完自動刪,但偶發 daemon crash 可能留 dead container:

docker container prune -f     # 清掉所有 stopped containers

6.2 /tmp/cm-jobs/ 清理

每跑一次分類會留 catalog + state + report,長期堆積。建議排程清理:

# 例:每週清 7 天前的 job dir
find /tmp/cm-jobs -mindepth 1 -maxdepth 1 -type d -mtime +7 -exec rm -rf {} +

放 cron 或 systemd timer。

6.3 BE log 監控

關鍵 log pattern(log/app.log):

• [classifier] job=<uid> container done — 容器成功跑完
• [classifier] job=<uid> completed; run_folder=<id> classified=N — 整個 job 收尾完成
• [classifier] job=<uid> container failed / unexpected failure — 失敗

grep 查最近狀態:

grep "\[classifier\]" log/app.log | tail -20

6.4 並發監控

目前無全機資源上限。多 user 同時觸發不同 project 會同時起多個 container:

docker ps --filter "ancestor=cmmc-classifier:latest"

每個 container 跑時用 ~500MB RAM + 1 vCPU。若 STG 規格小,建議目前限 demo 用戶,觀察行為再考慮加 queue。

6.5 API quota

• Anthropic API:跟 user 自己的 plan 走;134 檔 ~ $0.5-1 USD(含 prompt caching)
• Google Drive API:每 tenant 一個 OAuth,daily quota 充足
• 監控:Anthropic console / Google Cloud Console

若 v1.2.1 上 STG 出問題:

# 1. 切回上一版 tag
git checkout v1.2.0
poetry update

# 2. DB migration 是 ADD ONLY(只擴 CHECK constraint 允許值),無需 rollback
#    但若要乾淨 rollback CHECK:
PGPASSWORD='...' psql -h ... -U cmmgr -d ... -c "
ALTER TABLE compliance.drive_folder_mappings
    DROP CONSTRAINT IF EXISTS chk_drive_folder_mappings_scope;
ALTER TABLE compliance.drive_folder_mappings
    ADD CONSTRAINT chk_drive_folder_mappings_scope
    CHECK (scope_type IN ('ROOT','PROJECT','AP','CONTROL_GROUP','CONTROL','AO','TASK','ARCHIVE'));
"
# (若已有 EVIDENCES scope row,DROP CHECK 不會擋,但加回去會;需先 DELETE row)
DELETE FROM compliance.drive_folder_mappings WHERE scope_type = 'EVIDENCES';

# 3. 重啟 BE
lsof -ti :8000 | xargs -r kill -9 && nohup python main_socketio.py > log/app.log 2>&1 &

# 4. 既有 Drive 上的 Evidences 資料夾不會自動刪,人工處理(或保留)

目前 STG 是 premise(BE 跑在 VM),docker 在本機。若改用 STAGING_AWS_BILLOWS 之類:

這是非平凡的改動,正式遷移時要規劃 infra/evidence_classification/classifier_container_runner.py 抽象化(目前只有 subprocess 一條路徑)。先列在 follow-up。