部署¶

選擇部署路徑¶

Provisa 支援六條部署路徑。請依你的受眾與營運脈絡選擇：

路徑	構件／腳本	最適用於
開發	`start-ui.sh`	從原始碼開發、附完整示範數據的評估
macOS 安裝程式	`Provisa-<version>-macOS.dmg`	開發者工作站、評估
Windows 安裝程式	`Provisa-<version>-windows-x64.exe`	開發者工作站、評估
Linux AppImage	`Provisa.AppImage`	內部部署伺服器、雲端 VM、氣隙環境
雲端 VM（AWS）	`terraform/deploy.sh`	帶負載平衡器的多節點雲端部署
Kubernetes	`helm/provisa/`	已在營運 K8s 的團隊

VM 對比 Kubernetes¶

兩者都適用於生產環境。VM／AppImage 路徑較簡單：毋須佈建叢集、毋須設定 CNI 或 RBAC 政策，且 AppImage 完全自足。它自然地融入既有的伺服器管理工具（Ansible、Puppet、Datadog agent、Splunk forwarder 等）。

只有當團隊已經在營運 K8s 叢集、並希望 Provisa 融入這套營運方式（滾動部署、HPA、統一可觀測性）時，才選擇 Kubernetes。兩者能力相同；Kubernetes 只會增加營運負擔。

映像取得與安全掃描¶

每條生產路徑都要先取得 Provisa 的製品，任何部署才能執行。「Air-gapped」（隔離環境）描述的是在目標機器上安裝時的情形，所以製品要先準備好。

macOS 及 Windows 安裝程式： 從 GitHub 發佈頁面下載。它們是完整打包的，下載後毋須連網。它們面向開發及評估，所以不需要映像掃描關卡。

AppImage 路徑： 從 GitHub 發佈頁面下載，並複製到目標機器。AppImage 把每個元件映像以 tarball 形式打包在 squashfs 檔案系統中，大多數映像登錄庫掃描器無法就地檢查。請向您的 Provisa 客戶團隊索取元件映像的摘要，以便自行用掃描器核對。

Terraform 路徑： 在執行 terraform/deploy.sh 之前，先把 AppImage 上載到 S3。EC2 節點會在啟動時經其 IAM 角色下載它，所以它們需要能對外存取 S3，可以直連，亦可以經 VPC 閘道端點。掃描政策與 AppImage 路徑相同。

Helm / Kubernetes 路徑： 把各個映像推送到叢集能存取的映像登錄庫。這條路徑與基於映像登錄庫的掃描（Prisma Cloud、Aqua、Trivy、AWS Inspector）最契合，因為映像本來就是掃描器理解的物件。對於隔離叢集，把映像同步到內部映像登錄庫，並在 values.yaml 中覆寫參照。

開發（從原始碼）¶

建議：`start-ui.sh`¶

這是從原始碼執行 Provisa 最簡單的方式。一道命令啟動所有基礎設施、後端 API 與 UI 開發伺服器。Ctrl+C 會乾淨地關閉一切。

先決條件： Docker Desktop、Node.js、位於 .venv/ 的 Python virtualenv

./start-ui.sh

它做什麼：

啟動 docker-compose.core.yml + docker-compose.dev.yml（所有核心 + 示範服務）並等待其健康
以示範數據播種 Kafka
從 .venv/ 同步 Python 相依項
在連接埠 8001 啟動後端 API（記錄至 .logs/server.log）
在連接埠 3000 啟動 Vite UI 開發伺服器
印出各 URL 並等待；Ctrl+C 停止一切並拆除 compose

Backend: http://localhost:8001
UI:      http://localhost:3000

選項：

--reset-volumes — 啟動前先執行 docker compose down -v，銷毀所有 Docker 磁碟區（PostgreSQL 數據、MinIO 物件、Redis 狀態等）。當你想要一張完全乾淨的白紙時使用，例如開發期間更改結構描述之後，或 Docker 當掉並留下損毀的磁碟區時。所有數據都會遺失。

--observability — 加入完整的追蹤與量度檢測。它下載 OpenTelemetry Java agent 並修補 Trino 的 jvm.config 以載入它，以 OTLP 匯出檢測 Provisa 後端，並啟動 OTel collector、Prometheus、Tempo 與 Grafana（http://localhost:3100）。該 jvm.config 修補會在 Ctrl+C 時自動還原。

手動步驟（僅後端，無 UI）¶

如果你只需要 API：

安裝 Docker Desktop
啟動核心服務：

docker compose -f docker-compose.core.yml up -d

啟動 API：

uvicorn main:app --reload --port 8001

驗證：curl http://localhost:8001/health

完整堆疊（Provisa 在容器中）¶

若要以容器而非在主機上執行 API：

docker compose -f docker-compose.core.yml -f docker-compose.app.yml up -d

各項服務¶

核心（docker-compose.core.yml）——一律必要：

服務	連接埠	用途
PostgreSQL	5432	設定中繼資料 + Iceberg 目錄
PgBouncer	6432	連線池
聯邦引擎	8080	查詢聯邦
Redis	6379	查詢結果快取
MinIO	9000/9001	相容 S3 的物件儲存

示範（docker-compose.dev.yml）——選用，由 start-ui.sh 一併納入：

服務	連接埠	用途
MongoDB	27017	示範 NoSQL 數據來源
Kafka	9092	示範串流數據來源
Schema Registry	8081	示範 Avro／Protobuf 結構描述管理
Debezium	—	示範 CDC 連接器
Elasticsearch	9200	示範搜尋數據來源
Neo4j	7474/7687	示範圖形數據來源
Fuseki	3030	示範 SPARQL 三元組儲存
OpenTelemetry Collector	—	追蹤收集（搭配 `--observability`）
Prometheus	9090	量度（搭配 `--observability`）
Tempo	—	追蹤儲存（搭配 `--observability`）
Grafana	3100	儀表板（搭配 `--observability`）

儲存區、聯邦引擎與這些遙測服務在 PROVISA_STORE_BIND_IP（未設定時為 127.0.0.1）上發佈，密碼為該部署產生。參見部署加固。

遙測後端（`otlp2sql`）¶

上述的 --observability 堆疊（Collector → Tempo／Prometheus／Grafana）是其中一條遙測路徑。另一條是 otlp2sql（provisa.observability.otlp2sql）：一個 OTLP/HTTP 接收器，把追蹤、量度與記錄寫入由 SQLAlchemy URL 選定的 SQL 資料庫，並在擷取時抽出 provisa.* span 屬性，因此毋須另跑壓實作業。寫入是批次的（OTLP2SQL_BATCH_MAX_ROWS，預設 1000；OTLP2SQL_BATCH_MAX_SECS，預設 2 秒）。

遙測有自己的儲存區，與控制平面資料庫分開。以 PROVISA_OPS_DB_URL 選定後端：

`PROVISA_OPS_DB_URL`	後端	備註
（未設定）	`~/.provisa/telemetry/` 之下的專用 DuckDB	預設；無伺服器、無 Docker
`clickhouse+native://user@host/otel`	ClickHouse	高速率擷取，帶自動背景合併
`postgresql+psycopg2://user@host/otel`	PostgreSQL	中等量
`trino://user@host:8080/otel`	Trino／Iceberg	技術上可行，不建議——見下文

使用 trino:// 時： SQLAlchemy 的 Trino 方言能產生合法的 Trino DDL 及 INSERT，所以可以充當 otlp2sql 的後端，但我們只建議在低寫入速率下使用。每次批次清空都會變成一次分散式 Trino INSERT 外加一個 Iceberg 快照，所以高速率遙測會產生大量小檔案及快照，而且仍需要定期執行 ALTER TABLE ... EXECUTE optimize / expire_snapshots，而 otlp2sql 不會執行這些。它亦會把查詢引擎放到寫入的熱路徑上。

要把大量遙測送進 Trino／Iceberg，請改用 otlp2parquet：它不經 Trino 就把 parquet 寫入物件儲存，再由排程的 Trino 壓實把原始檔案捲進上線中的 Iceberg 表。若要單一引擎同時處理高速率擷取與壓實，優先選 ClickHouse。

把應用程式與 Trino 的 OTLP 匯出器（OTEL_EXPORTER_OTLP_ENDPOINT）指向 otlp2sql 端點，並以同一個 PROVISA_OPS_DB_URL 註冊 ops 網域，好讓它讀到接收器所寫入的內容。

macOS 安裝程式¶

適用於開發工作站及評估。完全離線運作，下載後毋須連網。

基礎安裝程式是一種原生安裝：DuckDB 聯邦引擎、內嵌 PostgreSQL 控制平面（pgserver）及記憶體快取（fakeredis），不需要 Docker、虛擬機器、Trino、Redis 或 MinIO。聯邦引擎在精靈中選擇：DuckDB（原生，預設）、Docker 上的 Trino，或外部引擎。可觀測性是一直開啟的自身遙測，可在 Admin 中查看；Docker 的 collector、Prometheus 及 Grafana 組合是另一個可選的示範，不負責開關它。示範數據包是可選的，預設關閉。Trino、Docker 可觀測性組合及示範都是較重的附加元件。它們會先在本機尋找（安裝程式旁的目錄、已掛載的磁碟區、~/Downloads），找不到才從 GitHub release 取得，所以企業可以為離線安裝預先準備好 tarball。

步驟¶

自 GitHub 發行頁面下載 Provisa-<version>-macOS.dmg
開啟該 DMG，把 Provisa.app 拖到 /Applications
按兩下 Provisa.app。首次啟動設定執行一次，精靈會提供上述的引擎、可觀測性與示範選項
開啟終端機：

provisa start    # start all services
provisa status   # confirm all services are running
provisa open     # open the UI in the browser

數據持續性¶

所有數據儲存在 ~/.provisa/。若要移除一切：provisa uninstall。

Windows 安裝程式¶

適用於開發工作站及評估。完全離線運作，下載後毋須連網。

與 macOS 一樣，基礎的 Windows 安裝程式是原生層：一份獨立的 Python 執行階段 + provisa wheel + DuckDB/pg_duckdb + 內嵌 PostgreSQL 控制平面（pgserver），不隨附 Docker、不隨附 VM，也不隨附容器映像。聯邦引擎（Trino）、可觀測性堆疊與示範數據包，稍後經個別的分層安裝程式依序加入：先是 Container 安裝程式（Provisa-Container-<version>.exe，它加入 WSL2 + containerd + Trino），然後是 Obs 安裝程式（需要容器層），最後是 Demo 安裝程式（需要 Core + Obs）。首次啟動的指引會說明如何執行 Container 安裝程式來初始化聯邦引擎。

步驟¶

自 GitHub 發行頁面下載 Provisa-<version>-windows-x64.exe
執行該安裝程式。它毋須管理員權限，會安裝到 %LOCALAPPDATA%\Programs\Provisa\
自「開始」功能表開啟 Provisa First Launch。原生設定執行一次，並印出分層附加元件的後續步驟指引
開啟一個新的終端機：

provisa status
provisa open

數據持續性¶

所有數據儲存在 %USERPROFILE%\.provisa\。

Linux AppImage——單節點或多節點 VM¶

它是什麼¶

Provisa.AppImage 是單一自足的可執行檔，打包了：

一個無 root 的 Docker 常駐程式（dockerd-rootless.sh + rootlesskit），因此毋須系統 Docker 或 root
所有容器映像 tarball（PostgreSQL、PgBouncer、MinIO、Redis、聯邦引擎、Provisa API）
Provisa CLI 包裝器與首次啟動設定腳本

Provisa 映像在打包時建構，從不包含 Python 原始碼。

何時使用¶

內部部署的裸機或 VM（單節點或多節點）
沒有 K8s 叢集的雲端 VM
氣隙環境
當你想要比 Kubernetes 更簡單的營運時

步驟——單節點¶

自 GitHub 發行頁面下載 Provisa.AppImage 並傳輸到目標機器
賦予執行權限：

chmod +x Provisa.AppImage

執行首次啟動設定：

./Provisa.AppImage

設定精靈會詢問：
角色 → 選 primary
RAM 預算 → 要配置的 RAM 量（0 = 全部可用）；決定 Trino 工作處理程序數量
主機名稱 → 此節點對外通告的位址
API 連接埠 → 預設 8000
設定會載入所有容器映像（約 2–5 分鐘）、寫入設定並啟動各項服務
驗證：

provisa status
curl -k https://localhost:8000/health   # -k: the node generates a self-signed certificate unless PROVISA_TLS_CERT/KEY supply one

步驟——多節點（primary）¶

先在 primary 節點上執行這些步驟。secondary 必須在 primary 執行起來之後才設定。

下載 Provisa.AppImage 並傳輸到 primary 機器
只向 secondary 開放所需的防火牆連接埠（它們會經這些連接埠以入站方式連線）：

連接埠	服務
5432	PostgreSQL
6379	Redis
9000	MinIO
8080	聯邦引擎協調器
8000	Provisa API

賦予執行權限，並讓資料儲存發佈在節點的私有位址上後執行，secondary 會在該位址連線它們。沒有 secondary 的節點只在 127.0.0.1 上發佈它們：

chmod +x Provisa.AppImage
PROVISA_STORE_BIND_IP=<this node's private IP> ./Provisa.AppImage

設定精靈會詢問：
角色 → 選 primary
RAM 預算、主機名稱、API 連接埠 → 與單節點相同作答
設定完成後，記下此機器的私有 IP。secondary 需要它，也需要 primary 產生的資料儲存憑據：~/.provisa/store-credentials.env（PROVISA_PG_PASSWORD, PROVISA_REDIS_PASSWORD, PROVISA_MINIO_ROOT_PASSWORD, PROVISA_GRAFANA_ADMIN_PASSWORD, PROVISA_TRINO_SHARED_SECRET）。經安全通道將該檔案複製到每個 secondary
精靈會印出一段 nginx upstream 區塊，請保存下來供你的負載平衡器設定使用
驗證：

provisa status
curl -k https://localhost:8000/health   # -k: the node generates a self-signed certificate unless PROVISA_TLS_CERT/KEY supply one

步驟——多節點（每個 secondary）¶

在 primary 執行起來且可觸及之後，於每個額外節點上重複這些步驟。

下載 Provisa.AppImage 並傳輸到 secondary 機器
確認 secondary 可觸及 primary：

curl -k https://<primary-ip>:8000/health

賦予執行權限，並在環境中帶上 primary 的資料儲存憑據（從 primary 複製的檔案）後執行。未獲提供憑據的 secondary 不會啟動：

chmod +x Provisa.AppImage
set -a; . ./store-credentials.env; set +a
./Provisa.AppImage

設定精靈會詢問：
角色 → 選 secondary
Primary IP → 輸入 primary 節點的 IP（連通性會即時驗證）
RAM 預算、主機名稱、API 連接埠 → 同上作答
設定載入縮減後的映像集（沒有 PostgreSQL、PgBouncer、MinIO、Redis，那些只在 primary 上執行），並啟動 Provisa API 與一個聯邦引擎工作處理程序
驗證：

provisa status
curl -k https://localhost:8000/health

把此節點加入你的負載平衡器 upstream

primary／secondary 拓撲¶

primary 節點執行所有單例服務：

服務	為何是單例
PostgreSQL	共用結構描述、應用程式設定、語意模型
Redis	共用查詢結果快取與訂閱狀態
MinIO	供重新導向結果與 MV 快照使用的共用物件儲存區
聯邦引擎協調器	所有工作處理程序（primary + secondary）都在此註冊

secondary 節點只執行：

Provisa API——無狀態；啟動時從 primary 上的 PostgreSQL 讀取所有設定
聯邦引擎工作處理程序——向 primary 上的協調器自我註冊

所有應用程式狀態都流經 primary 的 PostgreSQL。毋須手動同步。

非互動式（自動化）首次啟動¶

供 Terraform、cloud-init 或 Ansible 使用時，請以旗標取代回答提示：

# Primary
./Provisa.AppImage --non-interactive --role primary --ram-gb 32

# Secondary
./Provisa.AppImage --non-interactive --role secondary --primary-ip 10.0.0.10 --ram-gb 32

非互動模式會安裝一個 systemd 單元（/etc/systemd/system/provisa.service）以便開機即啟動。

旗標	說明
`--non-interactive`	略過所有提示；安裝 systemd 單元
`--role primary\\|secondary`	節點角色
`--primary-ip <ip>`	primary 節點 IP（secondary 必填）
`--ram-gb <n>`	要配置的 RAM（0 = 全部可用）

雲端 VM 部署——Terraform（AWS）¶

一條互動式命令即可在 AWS 上建立完整的多節點 Provisa 叢集：VPC、安全群組、EC2 執行個體、ALB 及 NLB。

檔案¶

檔案	用途
`terraform/deploy.sh`	互動式包裝器——收集參數、驗證憑證、寫入 `terraform.tfvars`、執行 apply
`terraform/aws/variables.tf`	所有變數定義與預設值
`terraform/aws/main.tf`	VPC、子網路、安全群組、IAM、EC2、ALB、NLB
`terraform/aws/outputs.tf`	端點 URL 與節點 IP

步驟¶

自 GitHub 發行頁面下載 Provisa.AppImage
把它上載到你 AWS 帳戶中的一個 S3 貯體：

aws s3 cp Provisa.AppImage s3://<your-bucket>/releases/Provisa.AppImage

確保 AWS 憑證在你的 shell 中可用（以下任一）：
環境變數：AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
具名設定檔：export AWS_PROFILE=my-profile
使用中的 SSO 工作階段：aws sso login
（選用）若你想要 SSH 存取節點，請在目標區域建立一組 EC2 金鑰配對並記下該金鑰配對名稱
執行部署包裝器：

bash terraform/deploy.sh

回答精靈的問題（見下方參照表）。腳本會在繼續之前先驗證 AppImage 存在於 S3，不存在則中止
檢閱部署摘要並確認
Terraform 佈建所有基礎設施（約 5–10 分鐘）。apply 之後，腳本會印出：

api_endpoint      = "https://<alb-dns>:8000"
protocol_endpoints = { flight = "<alb-dns>:8815", ... }
primary_ip        = "10.0.x.x"
secondary_ips     = ["10.0.x.x", ...]

（選用）把 DNS 記錄指向 ALB 與 NLB 的 DNS 名稱
驗證：
```
curl http://<api_endpoint>/health
```

精靈問題¶

問題	預設	備註
雲端提供者	—	僅 AWS
AWS 憑證	—	先檢查使用中的工作階段
區域	`us-east-1`
節點數量	`2`	1 = 只有 primary，無 LB；2+ = primary + secondary + ALB/NLB
執行個體類型	`m7i.2xlarge`	見下方規格指南
根磁碟區大小	`100 GB`	每節點
RAM 預算	`0`（全部 RAM）	決定每節點的 Trino 工作處理程序數量
S3 貯體	—	繼續之前即時驗證
S3 索引鍵	`releases/Provisa.AppImage`
SSH 存取	否	需要既有的金鑰配對名稱 + 管理 CIDR
VPC CIDR	`10.0.0.0/16`

執行個體規格指南¶

類型	vCPU	RAM	每節點 Trino 工作處理程序	使用情境
`m7i.xlarge`	4	16 GB	0	開發／小型數據集
`m7i.2xlarge`	8	32 GB	1	小型正式環境
`m7i.4xlarge`	16	64 GB	2	中型正式環境
`m7i.8xlarge`	32	128 GB	4	大型正式環境

所有節點都把工作處理程序貢獻給 primary 上的同一個協調器。一個 3 節點的 m7i.4xlarge 叢集共產生 6 個 Trino 工作處理程序。

會佈建什麼¶

跨兩個可用區、含兩個公用子網路的 VPC
安全群組：LB 群組（8000/8815 上的公用輸入）、節點群組（LB → 節點、叢集內部、選用 SSH）
對 AppImage 貯體具備 S3 GetObject 的 IAM 角色 + 執行個體設定檔
primary EC2 執行個體——以 --non-interactive --role primary 模式執行首次啟動
secondary EC2 執行個體（node_count − 1）——以 --non-interactive --role secondary --primary-ip <primary private IP> 模式執行首次啟動；相依於 primary 先完成
連接埠 8000 上的 ALB——HTTP API，健康檢查 /health
連接埠 8815 上的 NLB——Arrow Flight／gRPC
兩個 LB 都附掛到所有節點

先決條件檢查清單¶

[ ] IAM 權限：EC2 完整、ELB 完整、VPC 完整、IAM 角色建立、AppImage 貯體上的 S3 GetObject
[ ] Provisa.AppImage 已上載到 S3
[ ] EC2 節點具備對外的 S3 存取（直接網際網路或 S3 VPC 閘道端點）
[ ] 目標區域中存在 EC2 金鑰配對（如需 SSH）
[ ] 本機已安裝 Terraform ≥ 1.5
[ ] 已規劃 ALB／NLB 的 DNS 記錄（選用但建議）
[ ] 若需要 HTTPS，已備妥 ACM 憑證（基礎 Terraform 未包含）

密鑰¶

內附資料儲存（PostgreSQL、Redis、MinIO、Grafana 管理員）的密碼與 Trino 叢集的共用密鑰由 Terraform（random_password）產生並交給每個節點，節點將其保存於 systemd 環境檔案中，權限為 600。它們保存於 Terraform 狀態中，因此應如保護密碼本身一般保護該狀態。不使用 Terraform 時，每個節點的啟動器會將它們產生至 ~/.provisa/store-credentials.env。其餘憑據由 AppImage 在首次啟動期間產生，並寫入每個節點的 ~/.provisa/config.yaml。正式環境請於部署後自 primary 節點取回管理權杖：

ssh ubuntu@<primary-public-ip> cat ~/.provisa/config.yaml | grep admin_token

Kubernetes／Helm¶

何時使用¶

你的團隊已在營運 Kubernetes 叢集，並希望 Provisa 參與該營運模式。如果你正在評估 Provisa，或在沒有既有叢集的情況下作內部部署，AppImage 路徑較簡單。

注意：Provisa AppImage 無法在 Kubernetes Pod 內執行。它需要 FUSE 及無 root 的 Docker 守護程序，而標準 Pod 安全設定兩者都不容許。

步驟¶

確認可存取叢集：

kubectl cluster-info

把映像拉取並鏡像到你的內部登錄檔（氣隙或受掃描環境必要；若直接自公用登錄檔拉取則略過）：

映像	用於
`provisa/provisa:<version>`	Provisa API
`trinodb/trino:480`	聯邦引擎協調器 + 工作處理程序
`postgres:16`	叢集內 PostgreSQL（若 `postgresql.enabled`）
`edoburu/pgbouncer:latest`	叢集內 PgBouncer（若 `pgbouncer.enabled`）
`redis:7.2`	叢集內 Redis（若 `redis.enabled` 且無 `redis.host`）
`minio/minio:latest`	叢集內 MinIO（若 `minio.enabled`）

對於受登錄檔掃描的環境： - 把每個映像推送到你的暫存登錄檔 - 執行你的掃描器（Prisma Cloud、Aqua、Trivy、AWS Inspector）並取得批准 - 晉升到你的正式環境內部登錄檔

安裝之前先決定：
PostgreSQL — 叢集內（postgresql.enabled: true）或外部託管（postgresql.host）？正式環境建議外部
Redis — 叢集內或外部（redis.host）？
資料儲存憑據 — 建立 credentials.existingSecret 所指定的 Secret，包含鍵 pg-password、redis-password、minio-access-key、minio-secret-key、grafana-admin-password 及 trino-shared-secret。chart 本身不設定任何密碼，缺少該 Secret 則無法轉譯
TLS — 預設開啟（tls.enabled: true）：建立 tls.secretName 所指定的 kubernetes.io/tls Secret，或設定 tls.enabled: false
MinIO／S3 — 叢集內 MinIO 或原生 S3？在 AWS 上請以 IAM 角色使用 S3
密鑰 — 評估時經 --set 傳入；正式環境請用 External Secrets 或 Vault Agent
Trino 協調器快取——預設申請的 1Gi 磁碟區，掛載於 /data/trino/cache（trino.coordinator.cache.persistence：enabled、size、storageClass）。Salesforce 數據來源的 describe 結果存放於此，令重新啟動的協調器不會再次耗用該組織的 API 配額去描述它。只有在沒有數據來源需要它時才關閉
為部署提供其主金鑰。該金鑰加密密鑰庫；每個 API pod 都必須持有相同的金鑰，而且它必須比任何 pod 存活得更久。沒有它，chart 不會渲染。

kubectl create namespace provisa
kubectl create secret generic provisa-master-key --namespace provisa \
  --from-literal=master-key="$(openssl rand -base64 32)"

在叢集外保留該金鑰的副本。以其後遺失的金鑰寫入的密鑰庫無法開啟。Secret 的替代方案是持久數據磁碟區（encryption.dataVolume.enabled=true），產品會把它產生的金鑰存放於其中；請參閱 values.yaml 中的 encryption。

安裝 chart：

helm install provisa helm/provisa/ \
  --set encryption.existingSecret=provisa-master-key \
  --set auth.provider=oidc \
  --set auth.oidc.issuerUrl=https://login.example.com/realms/main \
  --set auth.oidc.clientId=provisa \
  --set config.pgPassword=<password> \
  --set config.adminToken=<token> \
  --set s3.endpoint=https://s3.amazonaws.com \
  --set s3.bucket=my-provisa-results \
  --namespace provisa --create-namespace

在選定 auth.provider 之前 chart 不會渲染：oidc（企業 OpenID Connect 簽發者）、saml（auth.saml.idpMetadataUrl 及 auth.saml.publicUrl）、ldap（auth.ldap.*）、 local（僅應急帳戶，auth.breakGlass.*）或 none（無身份驗證，僅供開發）。每個憑證都來自 Kubernetes Secret；ldap、saml 及 local 亦需要 auth.sessionSecret.existingSecret，即簽署瀏覽器工作階段的金鑰。請參閱 values.yaml 中的 auth。

Trino 協調器在每個組織自己的資源群組 global.tenant-<org> 中執行該組織的陳述式，資源群組來自 chart 提供的資源群組檔案。經由 Arrow Flight 代理的陳述式共用一個群組 global.flight：代理會開啟自己的 Trino 連線，無法攜帶組織。

若使用內部登錄檔，請加上映像覆寫：

--set image.repository=harbor.internal.example.com/provisa/provisa \
--set image.tag=1.2.3 \
--set trino.image.repository=harbor.internal.example.com/trinodb/trino \
--set trino.image.tag=480

驗證 pod 正在執行：

kubectl get pods -n provisa

檢查 API：

kubectl port-forward svc/provisa 8000:8000 -n provisa
curl http://localhost:8000/health

（選用）啟用 ingress 以供外部存取：設定 ingress.enabled: true 並設定你的 ingress 控制器

先決條件檢查清單¶

[ ] Kubernetes 1.26+、Helm 3.12+
[ ] 支援 ReadWriteOnce PVC 的儲存類別（供叢集內具狀態服務使用）
[ ] 叢集可取得各映像（公用或內部登錄檔）
[ ] PostgreSQL 端點 + 憑證（若為外部）
[ ] Redis 端點 + 憑證（若為外部）
[ ] S3 貯體 + 憑證或 IAM 角色
[ ] 已選定管理權杖
[ ] 已設定 ingress 控制器（若需要外部存取）

主要值¶

值	預設	說明
`replicaCount`	`2`	Provisa API 複本（無狀態）
`config.pgHost`	`postgres`	PostgreSQL 主機
`config.pgPassword`		PostgreSQL 密碼
`config.adminToken`		管理 API bearer 權杖
`redis.enabled`	`true`	部署叢集內 Redis StatefulSet
`redis.host`	`""`	設定後即使用外部 Redis
`redis.port`	`6379`
`credentials.existingSecret`		存放資料儲存密碼的 Secret（必需）
`tls.enabled`	`true`	透過 `tls.secretName` 中的憑證以 TLS 提供每個端點
`redis.tls`	`false`
`trino.enabled`	`true`	部署聯邦引擎
`trino.workers`	`2`	聯邦引擎工作處理程序複本
`trino.internalTls`	`false`	使用 chart 產生的證書加密協調器與工作節點之間的流量；使 shuffle 密集的查詢變慢 10% 至 100% 以上
`postgresql.enabled`	`true`	部署叢集內 PostgreSQL
`postgresql.host`	`""`	設定後即使用外部 PostgreSQL
`minio.enabled`	`true`	部署叢集內 MinIO
`s3.endpoint`		相容 S3 的端點 URL
`s3.bucket`	`provisa-results`	大型結果重新導向所用的貯體
`ingress.enabled`	`false`	啟用 ingress

擴展¶

kubectl scale deployment/provisa --replicas=5 --namespace provisa

聯邦引擎的 worker 可以獨立擴展，worker 越多，吞吐量及並行查詢數就越高。

更新設定¶

kubectl create configmap provisa-config \
  --from-file=config.yaml=./config.yaml \
  --namespace provisa --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment/provisa --namespace provisa

高可用性與復原¶

Provisa 在所有部署模式上套用一套雙層復原模型：

第 1 層——暫時性錯誤。 讀取操作在遇到暫時性錯誤時，以帶完整抖動的指數退避重試最多 30 秒。以 PROVISA_RETRY_BUDGET_SECS 調校該預算。寫入操作絕不在內部重試，且記憶體錯誤絕不可重試。
第 2 層——元件故障。 一個內部引擎監看器會在 2–3 分鐘內偵測並重新啟動故障的軟體元件。

機器級及叢集級故障仍由營運者負責。為了能承受節點遺失，請部署備援節點及負載平衡器（見上文的 Terraform 及 Helm 路徑）。

元資料缺失的遙測表¶

在 Trino 引擎上，遙測表（otel.signals.traces、metrics、logs）是 Iceberg 表。每張表的註冊是控制平面資料庫中的一行，其元資料和資料是遙測 bucket 中的檔案。當 bucket 在提供服務時缺少這些檔案，而資料庫仍保留着註冊時，對該表的每條語句都會以 ICEBERG_MISSING_METADATA 失敗。這會發生在物件儲存啟動時 bucket 的磁碟尚未掛載，或 bucket 被清空或取代時。

這種情況下 Provisa 不作任何更改。每次壓縮執行都會記錄一條 ERROR，指明該表以及 Trino 無法讀取的元資料位置（otel.signals.traces is registered but its metadata cannot be read …），略過該訊號，並將其原始檔案保留在 bucket 中供之後的執行使用。其他訊號照常壓縮。啟動時同樣把該表排除在其結構描述檢查之外。

請按以下次序手動復原：

確認元資料是否仍然存在。 ERROR 會指明位置。在 Terraform（GCP）協調器上，檢查物件儲存磁碟已掛載（findmnt /var/lib/provisa-object-store），且 MinIO 容器是在掛載之後啟動的。先啟動的 MinIO 會提供掛載點下的空目錄；在磁碟掛載後重新啟動它，該表即可連同其歷史完整地再次讀取。
如果元資料檔案存在但註冊指向別處，請在其位置重新註冊該表：

CALL otel.system.register_table(schema_name => 'signals', table_name => 'traces', table_location => 's3://<bucket>/warehouse/signals/<table directory>')

如果名稱已被佔用，請先取消註冊過時的行（CALL otel.system.unregister_table(schema_name => 'signals', table_name => 'traces')）。 3. 如果 bucket 的檔案確實已遺失，請取消註冊該表。下一次壓縮執行會重新建立它，為空表。它所保存的訊號無法再被讀取。

不要對正在復原的表執行 remove_orphan_files。它會刪除目前元資料未引用的檔案，而這些檔案可能正是你要復原的歷史。

聯邦引擎相依項¶

數據倉庫聯邦查詢引擎需要 Python 套件及系統級元件。Python 套件都宣告在 pyproject.toml 中，隨標準的 pip install provisa 或 pip install -e . 一起安裝，所以任何數倉引擎都不需要選用的額外套件。

系統級元件（ODBC 驅動程式、雲端 CLI、服務帳戶金鑰）需要另行安裝。

Python 套件（已在核心相依項中）¶

套件	引擎	用途
`databricks-sql-connector`	Databricks	SQL 倉庫連線；Arrow Cloud Fetch
`snowflake-connector-python[pandas]`	Snowflake	連線 + Arrow 原生 `fetch_arrow_table`
`google-cloud-bigquery`	BigQuery	查詢執行
`google-cloud-bigquery-storage`	BigQuery	供 Arrow 原生讀取的 Storage Read API
`google-cloud-storage`	BigQuery	外部表連結所用的 GCS 暫存
`pyodbc`	Fabric、Synapse	連往 T-SQL 端點的 ODBC 連線
`azure-identity`	Fabric、Synapse	經 `DefaultAzureCredential` 取得 Azure AD 權杖
`clickhouse-connect`	ClickHouse	HTTP 資料行式讀取
`protobuf>=6.33.5,<7`	BigQuery、gRPC	相容性釘選——`google-cloud-*` 與 OTel 共用一份 protobuf 執行階段；`<7` 讓它們保持一致
`grpcio-status<1.82`	gRPC	與 `protobuf<7` 的釘選對齊

系統層級需求¶

這些不是 Python 套件，需要安裝在執行 Provisa 的主機或容器上。

Microsoft Fabric 與 Azure Synapse（ODBC）

pyodbc 經 Microsoft ODBC Driver for SQL Server（msodbcsql18）連接。請直接在主機上安裝該驅動程式；pip 無法安裝它。

macOS：

brew install microsoft/mssql-release/msodbcsql18

Linux（Ubuntu／Debian）：

curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add -
curl https://packages.microsoft.com/config/ubuntu/22.04/prod.list > /etc/apt/sources.list.d/mssql-release.list
apt-get update && ACCEPT_EULA=Y apt-get install -y msodbcsql18

Provisa 會自動取用該驅動程式。若要覆寫驅動程式名稱（供非標準安裝使用），請設定：

export PROVISA_MSSQL_ODBC_DRIVER="ODBC Driver 17 for SQL Server"

Azure AD 驗證（Fabric 與 Synapse）

兩個引擎都經 azure.identity.DefaultAzureCredential 驗證。DefaultAzureCredential 依序檢查各憑證來源：環境變數、工作負載身份、受管身份、VS Code、az login 等。

本機開發時，az login 是最簡單的路徑：

az login

在生產環境中，請使用受控識別（在 Azure 虛擬機器或 AKS 上），毋須管理憑證。如使用服務主體驗證，請設定：

export AZURE_TENANT_ID=<tenant>
export AZURE_CLIENT_ID=<app-id>
export AZURE_CLIENT_SECRET=<secret>

BigQuery（服務帳戶）

google-cloud-bigquery 使用應用程式預設憑證。本機開發時，請指向一份服務帳戶金鑰檔：

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa-key.json

在 GCP 生產環境中（Cloud Run、啟用 Workload Identity 的 GKE、Compute Engine），該程式庫會自動使用附加的服務帳戶，毋須環境變數。

該服務帳戶需要：

roles/bigquery.dataViewer — 讀取數據
roles/bigquery.jobUser — 執行查詢
roles/bigquery.dataEditor — 建立外部表（供 ATTACH 使用）
roles/storage.objectViewer — 為外部表讀取 GCS 物件

Databricks（開發代理環境中的 CA 憑證）

若 Provisa 執行在會攔截 TLS 的代理（Charles、mitmproxy、企業代理）之後，Databricks SQL 連接器可能會拒絕該代理的憑證。請傳入自訂的 CA 套組：

export REQUESTS_CA_BUNDLE=/path/to/your/proxy-ca.pem

Databricks 連接器從 requests 繼承這項設定，所以毋須 Databricks 專用的環境變數。

逐引擎檢查清單¶

Databricks

[ ] 已安裝 databricks-sql-connector（預設）
[ ] 帶 http_path 的引擎 URL：databricks://token:TOKEN@workspace.azuredatabricks.net?http_path=/sql/1.0/warehouses/xxx
[ ] 個人存取權杖或服務主體權杖
[ ] 若在會攔截 TLS 的代理之後，已設定 REQUESTS_CA_BUNDLE

Snowflake

[ ] 已安裝 snowflake-connector-python[pandas]（預設）
[ ] 引擎 URL：snowflake://user:pass@account.snowflakecomputing.com/database
[ ] PROVISA_ENGINE_URL 或 federation_hints 中有 account

BigQuery

[ ] 已安裝 google-cloud-bigquery、google-cloud-bigquery-storage、google-cloud-storage（預設）
[ ] 已設定 GOOGLE_APPLICATION_CREDENTIALS（開發）或已設定工作負載身份（正式環境）
[ ] 若無法自服務帳戶推斷專案，已設定 GOOGLE_CLOUD_PROJECT
[ ] 服務帳戶具備 BigQuery Data Viewer + Job User 角色

Microsoft Fabric

[ ] 已安裝 pyodbc + azure-identity（預設）
[ ] 已安裝 msodbcsql18 系統驅動程式
[ ] 已設定 FABRIC_SQL_SERVER 與 FABRIC_DATABASE
[ ] Azure AD 驗證：az login（開發）或受管身份／服務主體（正式環境）
[ ] 若使用外部物件儲存連結，已設定 FABRIC_WORKSPACE_ID

Azure Synapse

[ ] 與 Fabric 相同的 Python + 系統需求
[ ] 已設定 SYNAPSE_SQL_SERVER 與 SYNAPSE_DATABASE
[ ] 與 Fabric 相同的 Azure AD 驗證設定

ClickHouse

[ ] 已安裝 clickhouse-connect（預設）
[ ] 引擎 URL：clickhouse+http://user:pass@host:8123/database
[ ] TLS 時在 federation_hints 中設 secure: "true"（連接埠 8443）

環境變數¶

變數	預設	用途
`PG_PASSWORD`		PostgreSQL 密碼
`PROVISA_CONFIG`	`config/provisa.yaml`	設定檔路徑
`PROVISA_REDIRECT_ENABLED`	`false`	啟用大型結果重新導向至 S3
`PROVISA_REDIRECT_THRESHOLD`	`1000`	觸發重新導向的行數門檻
`PROVISA_REDIRECT_BUCKET`	`provisa-results`	S3 貯體
`PROVISA_REDIRECT_ENDPOINT`		相容 S3 的端點 URL
`PROVISA_REDIRECT_TTL`	`3600`	預簽署 URL 的 TTL（秒）
`REDIS_HOST`	`localhost`	Redis 主機
`REDIS_PORT`	`6379`	Redis 連接埠
`REDIS_PASSWORD`		Redis 密碼
`REDIS_TLS`	`false`	為 Redis 啟用 TLS
`TRINO_HOST`	`localhost`	Trino 聯邦引擎協調器主機
`TRINO_PORT`	`8080`	Trino 聯邦引擎協調器 HTTP 連接埠
`PROVISA_ENGINE`	`duckdb`	啟用中的聯邦引擎索引鍵；覆寫已保存的設定
`PROVISA_ENGINE_URL`		URL 驅動之引擎（Databricks、Snowflake、ClickHouse、BigQuery、Fabric、Synapse、SQLAlchemy）的連線 URL
`PROVISA_MATERIALIZE_URL`		具體化儲存區 URL 覆寫；預設為引擎自己的儲存區
`PROVISA_MSSQL_ODBC_DRIVER`	`ODBC Driver 18 for SQL Server`	供 Fabric／Synapse 使用的 ODBC 驅動程式名稱
`GOOGLE_APPLICATION_CREDENTIALS`		GCP 服務帳戶金鑰 JSON 的路徑（BigQuery）
`GOOGLE_CLOUD_PROJECT`		GCP 專案 ID（BigQuery；未設定時自服務帳戶推斷）
`FABRIC_SQL_SERVER`		Microsoft Fabric SQL 分析端點主機名稱
`FABRIC_DATABASE`		Fabric 資料庫名稱
`FABRIC_WORKSPACE_ID`		Fabric 工作區 GUID（外部物件儲存捷徑必填）
`SYNAPSE_SQL_SERVER`		Azure Synapse 專用 SQL 集區或無伺服器主機名稱
`SYNAPSE_DATABASE`		Synapse 資料庫名稱
`AZURE_TENANT_ID`		Azure AD 租用戶（Fabric／Synapse 的服務主體驗證）
`AZURE_CLIENT_ID`		Azure AD 應用程式用戶端 ID
`AZURE_CLIENT_SECRET`		Azure AD 應用程式用戶端密鑰
`REQUESTS_CA_BUNDLE`		自訂 CA 套組路徑（Databricks 連接器、開發 TLS 代理）

CLI 命令¶

provisa start              # Start all services
provisa stop               # Stop all services
provisa restart            # Restart
provisa status             # Show service health
provisa open               # Open the UI in the browser
provisa logs               # Tail service logs
provisa export             # Print current config as YAML to stdout
provisa export FILE        # Write current config as YAML to FILE
provisa import FILE        # Replace running config with YAML from FILE

設定晉升工作流程（dev → test → prod）¶

所有與環境相關的設定（連線字串、密鑰、連接埠）都應放在環境變數或密鑰管理器中，不放進匯出的設定。匯出的 YAML 記錄的是您的語義模型：數據來源、領域、角色及檢視。

# On dev — export after making changes in the UI
provisa export > config.yaml
git add config.yaml && git commit -m "chore: update semantic model"
git push

# On test/prod — pull and import
git pull
provisa import config.yaml

另見：環境說明如何管理具名、結構描述隔離的受治理模型副本。

部署¶

選擇部署路徑¶

VM 對比 Kubernetes¶

映像取得與安全掃描¶

開發（從原始碼）¶

建議：start-ui.sh¶

手動步驟（僅後端，無 UI）¶

完整堆疊（Provisa 在容器中）¶

各項服務¶

遙測後端（otlp2sql）¶

macOS 安裝程式¶

步驟¶

數據持續性¶

Windows 安裝程式¶

步驟¶

數據持續性¶

Linux AppImage——單節點或多節點 VM¶

它是什麼¶

何時使用¶

步驟——單節點¶

步驟——多節點（primary）¶

步驟——多節點（每個 secondary）¶

primary／secondary 拓撲¶

非互動式（自動化）首次啟動¶

雲端 VM 部署——Terraform（AWS）¶

檔案¶

步驟¶

精靈問題¶

執行個體規格指南¶

會佈建什麼¶

先決條件檢查清單¶

密鑰¶

Kubernetes／Helm¶

何時使用¶

步驟¶

先決條件檢查清單¶

主要值¶

擴展¶

更新設定¶

高可用性與復原¶

元資料缺失的遙測表¶

聯邦引擎相依項¶

Python 套件（已在核心相依項中）¶

系統層級需求¶

逐引擎檢查清單¶

環境變數¶

CLI 命令¶

設定晉升工作流程（dev → test → prod）¶

建議：`start-ui.sh`¶

遙測後端（`otlp2sql`）¶