Argus

Appearance

管理 instance / 環境 ​

何時用這份文件 你要：新接一個 DB server、調整 environment、把資料庫納入某個 project、或重新同步 schema。

前置條件 ​

  • 角色：workspaceAdmin 或 workspaceDBA
  • 對目標 DB 有「Argus 專用 user」的權限

核心結構 ​

text
Environment (Dev / Staging / Prod ...)
   └── Instance (一個 DB server)
         └── Database (一個 logical DB)
                │
                └── transfer
                       ▼
                    Project (變更與審批的範圍)
名詞含意
Environment邏輯環境分組；決定 approval policy / 風險係數 / 凍結期
Instance實體 / 雲端 DB server（一台 PG / MySQL / TiDB ...）
DatabaseInstance 上的一個 logical DB
Project變更與審批的範圍；Database 屬於某 project 才能被開 Plan

Environment ​

規劃 ​

經典三層變更頻率審批嚴格度
dev高低（self-approve 可開）
staging中中（peer review）
prod低高（多步審批 + 窗口）

建議：

  • 不要超過 5 個 environment（太多反而失去意義）
  • 每個 environment 配套：approval policy、SQL review rule、maintenance window
  • environment 順序（order 欄位）對應推進方向，影響 Release 推進

新增 ​

Settings → Environments → Add Environment：

欄位例
IDprod
TitleProduction
Order300（數字大 = 越下游）
Color紅色（給 UI 警示）

ID 一旦建立不可改（會影響 setting / IAM 引用）。先定義好。

改 Environment 的審批 policy ​

Settings → Environments → <env> → Approval Policy：

例：prod policy

yaml
rules:
  - condition: 'source == "CHANGE_DATABASE" && database_change_type == "DDL"'
    template:
      title: Prod DDL approval
      steps:
        - role: workspaceDBA
        - role: securityOfficer
  - condition: 'source == "CHANGE_DATABASE" && affected_rows > 100000'
    template:
      title: Large DML
      steps:
        - role: projectOwner
        - role: workspaceDBA

詳見 審批流程。

Instance ​

新增 ​

Settings → Instances → Add Instance：

欄位說明
EnginePostgreSQL / MySQL / TiDB / ... (完整支援)
Name顯示名（如 prod-pg-orders）
Environment從上一節建好的 environment 選
Host / Port連線位址
Username專用 user，不要用 superuser
Password / SSL / SSH依需求設
External link跳到外部監控 / Wiki 的 URL（選填）

「Argus 專用 user」最小權限 ​

對目標 DB 建一個 Argus 專用 user，給：

權限為什麼
CONNECT / USAGE基本連線
SELECT on metadata viewssync schema
待會兒要變更的 schema 上的 CREATE / ALTER / DROP執行 DDL
待會兒要動的 table 上的 INSERT / UPDATE / DELETE / SELECTDML
不給 SUPERUSER / 全 schema 寫權限最小權限

PG 範例：

sql
CREATE USER argus_app WITH PASSWORD '<strong>' NOSUPERUSER;
GRANT CONNECT ON DATABASE orders TO argus_app;
GRANT USAGE ON SCHEMA public TO argus_app;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO argus_app;
GRANT CREATE ON SCHEMA public TO argus_app;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO argus_app;

測試連線 ​

Test Connection：綠勾再 Create。

紅叉常見原因：

原因排除
網路不通在 Argus server 上 psql -h <host> -U <user> 直連
pg_hba加上 Argus server 的 IP / subnet
密碼錯reset
SSL 不對engine 設定改 sslmode=require / 自簽 CA

編輯 / 刪除 / Undelete ​

動作影響
Edit改 host / port / credentials；不會碰已存的 Plan / Issue
DeleteSoft delete；instance 進入「已刪除」狀態，相關 Plan / Issue 仍可閱讀但不能執行
Undelete復原 soft delete

不要為了「換 host」而 delete + 重建。Edit 即可，保留所有歷史關聯。

TLS 憑證輪替 ​

Argus 連 DB 走的 TLS 憑證（ssl_ca / ssl_cert / ssl_key 三欄）放在 DataSource 上，DBA 可以隨時透過「編輯 instance → 進階 → SSL」更新。但是：Go database/sql 內部會按 DSN 快取 *sql.DB 連線池；更新憑證後，已建立的 idle 連線會繼續使用舊憑證直到自然淘汰（預設約 5 分鐘）。

情境是否需要重啟 Argus
計畫性輪替（舊憑證仍有效）❌ 不需要。Edit 即可，5 分鐘內全 pool 自然替換
緊急輪替（憑證已外洩 / 確認被盜）✅ 需要。Edit 後立刻 systemctl restart argus（或 K8s rolling restart）強制 flush pool，否則 5 分鐘窗口內被盜憑證仍可在已 idle 的連線上被 MITM 利用
對方 DB CA 過期被換❌ 不需要。新連線會用新 CA；舊連線淘汰後 pool 自然乾淨

推薦做法：搭配 tls_mode = VERIFY_FULL（Sprint 7.4 已是新建 DataSource 的預設）+ 中央 CA。輪替時改的多半是 server cert 不是 CA，DataSource 端通常無需動作。

詳見 audit 報告 §A6（docs/system-review/2026-06-13-sql-editor-review.md）。

Database ​

Sync ​

Argus 自動定期 sync database 清單與 schema：

  • 預設每 30 分鐘 sync 一次
  • 手動：Instance → Databases → Sync

Sync 會抓：

  • DB 清單
  • table / column / index / constraint
  • DDL（用 dump 或 information_schema）

Transfer to Project ​

Database 必須屬於某個 project 才能被開 Plan。

bash
# UI
Instance → Databases → 找 <db> → Transfer to Project → 選 project

# API
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -d '{"database":{"project":"projects/play"}}' \
  "$ARGUS/v1/instances/<inst>/databases/<db>?updateMask=database.project"

Transfer 後：

  • 該 project 的 member 可在這個 DB 上開 Plan
  • 該 DB 開的所有變更走該 project 的 approval policy

Transfer 之間注意 ​

情境注意事項
一個 DB 從 project A 換到 project B既有 Plan / Issue 不會跟著遷移；建議先 cancel pending issue
一個 instance 含多個 DB，分屬不同 project完全可行，這是正常用法
把 sample / template DB 留在「unassigned」OK，不會被誤改

健康檢查 ​

Instances → <inst> 顯示：

  • 最近 sync 成功 / 失敗
  • 平均 query latency（最近一週）
  • 連線 pool 狀態
  • 連線錯誤計數

如果某 instance 出現連續連線錯誤 → 警報接通的話會自動通知；走 二線運維 SOP。

Audit log ​

text
bb.instance.create / update / delete / undelete
bb.database.transfer / sync
bb.environment.create / update / delete

bb.instance.update 含 credentials 異動會被 redact（Audit Log）。

不要做的事 ​

反模式為什麼
用 superuser 接 instance違反最小權限；一旦 Argus 出問題影響面巨大
把 metastore（Argus 自己的 PG）接成 instance 來管自管自 = 循環依賴，極危險
不分 environment 全丟同一個失去 approval policy 差異化能力
為了測試 delete instanceSoft delete 保留歷史指向，但會把 UI 弄亂；先確認需求
直接改 metastore 的 instance / database 表違反 Migration 規則

相關 ​

Argus — 公司內部資料庫變更審計平台