跳至主要內容
翻譯頁面

本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。

srv

用於將 StackQL 作為服務啟動的命令,啟動後可由使用 mTLS 驗證的 Postgres 線路協定 用戶端存取。srv 命令也可以在 PostgreSQL 線路協定伺服器之外,同時執行 Model Context Protocol (MCP) 伺服器,讓傳統資料庫用戶端與 AI 代理程式都能透過雙協定存取。


語法​

stackql srv [server_options] [flags]


備註

雖然 StackQL 伺服器使用 Postgres 線路協定,但它不是 Postgres 伺服器,也不需要 Postgres 伺服器。用戶端使用線路協定與伺服器通訊,而伺服器使用 StackQL 對遠端雲端與 SaaS 供應商執行查詢或 DML 作業,並將結果傳回用戶端。

透過延伸查詢協定(Parse / Bind / Execute,psycopg 3、pgx 和 JDBC 使用此協定)傳送的參數,會在伺服器端繫結為字串常值。自 v0.12.742 起,字串常值、加上引號的識別碼或註解中的 $n 預留位置會保持不變,參數值中的反斜線會被逸出,而文字值 NULL 仍為字串 NULL(SQL NULL 另行傳遞)。

伺服器選項​

選項描述預設
--pgsrv.address伺服器接聽的位址。0.0.0.0
--pgsrv.port伺服器接聽的 TCP 連接埠。5466
--pgsrv.tlsJSON TLS 設定物件。請參閱下方的 mTLS 範例。無
--pgsrv.debug.enable為 PostgreSQL 用戶端啟用查詢偵錯輸出,例如 stackql srv --pgsrv.debug.enable=true。除非用戶端應接收偵錯資訊,否則請保持關閉。false
--pgsrv.sundry進階 JSON 或 YAML 對應,僅在未設定 --pgsrv.tls 時傳遞給 PostgreSQL 線路伺服器。{}
--pgsrv.loglevel可接受此選項,但在目前的引擎中不會設定記錄器層級。請改用 --loglevel。WARN

如需其他選項,請參閱全域旗標

MCP 伺服器選項​

以 MCP 支援執行 srv 命令時,可使用下列額外選項:

選項描述
--mcp.server.typeMCP 伺服器類型:http(記憶體內)或 reverse_proxy(以 TCP 為基礎)
--mcp.configMCP 伺服器的 JSON 設定物件(請參閱 MCP 文件)
--mcp.log.formatMCP 稽核記錄編碼:jsonl(預設)或 otel(OTLP/JSON 記錄項目);會覆寫設定物件中的 server.audit.format
--mcp.protocol.version宣告的最新 MCP 協定修訂版:auto(預設)、2026-07-28(僅限無工作階段)或較舊的修訂版,例如 2025-11-25;會覆寫設定物件中的 server.protocol_version

v0.12.742 中的重大變更

自 v0.12.742 起,除非設定物件以 server.auth_token_env_var 指定 bearer 權杖,或以 "allow_unauthenticated": true 明確選擇退出,否則 MCP HTTP 傳輸方式(--mcp.server.type=http 或 reverse_proxy)會拒絕啟動。請參閱 HTTP 用戶端驗證。

提示

如需設定和使用 MCP 伺服器的詳細資訊,包括部署模式、設定選項以及與 AI 助理的整合,請參閱 MCP 命令文件。

資訊

啟動伺服器之前,您需要設定 Provider 驗證所需的環境變數,如需詳細資訊,請參閱使用 Provider。

對於長時間執行的伺服器,--env.file 旗標可讓您在啟動前,將憑證寫入或輪替至磁碟上的 dotenv 樣式檔案,而不必將變數匯出到 shell 中:

stackql srv --pgsrv.port 5444 --env.file /etc/stackql/credentials.env

對於 stackql srv,此檔案只會在啟動時讀取一次;工作階段中途重新讀取憑證的途徑是 MCP reload_credentials 工具。

旗標​

旗標描述
-h,--help顯示說明資訊
-v,--verbose以詳細模式執行查詢,並將額外輸出傳送至 stdout;若設定了全域 -f(--outfile)旗標,
這些額外的記錄資訊會連同查詢結果一起寫入輸出檔案

如需其他選項,請參閱全域旗標


範例​

啟動 StackQL 伺服器處理程序,並使用 psql 命令列用戶端連線。

首先,從 stackql/stackql 下載 openssl.cnf 設定檔。

接著,產生伺服器和用戶端用於相互 TLS 驗證(mTLS)的憑證與金鑰檔案。

openssl req -x509 -keyout ~/stackqlcreds/server_key.pem -out ~/stackqlcreds/server_cert.pem -config ./openssl.cnf -days 365
openssl req -x509 -keyout ~/stackqlcreds/client_key.pem -out ~/stackqlcreds/client_cert.pem -config ./openssl.cnf -days 365
chmod 400 ~/stackqlcreds/client_key.pem

現在設定環境變數;如果用戶端和伺服器位於同一部主機上,這些變數可以共用。

export PGPORT=5444
export PGSSLCERT=~/stackqlcreds/client_cert.pem
export PGSSLKEY=~/stackqlcreds/client_key.pem
export PGSSLROOTCERT=~/stackqlcreds/server_cert.pem
export PGSSLSRVKEY=~/stackqlcreds/server_key.pem
export CLIENT_CERT=$(base64 -w 0 ~/stackqlcreds/client_cert.pem)
export PGSSLMODE=allow

設定伺服器所需 Provider 的憑證。以 GitHub 為例,該 Provider 會從下列兩個變數讀取使用者名稱和個人存取權杖:

export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken

現在在一個終端機中啟動伺服器。

stackql srv \
--pgsrv.address=0.0.0.0 \
--pgsrv.port=$PGPORT \
--pgsrv.tls='{ "keyFilePath": "'${PGSSLSRVKEY}'", "certFilePath": "'${PGSSLROOTCERT}'", "clientCAs": [ "'${CLIENT_CERT}'" ] }'

在另一個終端機中,使用 psql 命令列用戶端連線到伺服器。

psql -h 127.0.0.1 -d stackql

現在對已驗證的 Provider 執行 StackQL 查詢。

psql (12.11 (Ubuntu 12.11-0ubuntu0.20.04.1), server 0.0.0)
Type "help" for help.

stackql=> SHOW SERVICES IN github LIKE '%repos%';
id | name | title
--------------+-------+----------------------------
repos:v0.3.3 | repos | GitHub v3 REST API - repos
(1 row)

stackql=>