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	服务器监听的端口（例如 5444）
--pgsrv.tls	mTLS 配置对象，参阅下面的示例
--pgsrv.loglevel	日志级别（默认 WARN）

更多选项参阅全局标志

MCP 服务器选项

运行带 MCP 支持的 srv 命令时，可以使用以下附加选项：

选项	说明
--mcp.server.type	MCP 服务器类型：http（内存中）或 reverse_proxy（基于 TCP）
--mcp.config	MCP 服务器的 JSON 配置对象（参阅 MCP 文档）
--mcp.log.format	MCP 审计日志的编码：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 起，MCP HTTP 传输方式（--mcp.server.type=http 或 reverse_proxy）会拒绝启动，除非配置对象通过 server.auth_token_env_var 指定了 bearer 令牌，或通过 "allow_unauthenticated": true 显式选择退出。参阅 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 选项， 这些额外的日志信息将与查询结果一起写入输出文件

更多选项参阅全局标志

---

示例

启动 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。

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 127.0.0.1

现在对已通过身份验证的 Provider 运行 StackQL 查询。

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

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

127.0.0.1=>