Trang này được dịch từ tiếng Anh với sự hỗ trợ của AI. Nếu hai bản có chỗ khác nhau, hãy lấy phiên bản tiếng Anh làm chuẩn.
srv
Lệnh dùng để khởi chạy StackQL dưới dạng một dịch vụ, sau đó các ứng dụng khách giao thức wire của Postgres được xác thực bằng mTLS có thể truy cập dịch vụ này. Lệnh srv cũng có thể chạy một máy chủ Model Context Protocol (MCP) song song với máy chủ giao thức wire của PostgreSQL, cho phép truy cập qua hai giao thức cho cả ứng dụng khách cơ sở dữ liệu truyền thống lẫn tác nhân AI.
Cú pháp
stackql srv [server_options] [flags]
Mặc dù máy chủ StackQL sử dụng giao thức wire của Postgres, nó không phải là máy chủ Postgres và cũng không cần đến một máy chủ Postgres. Ứng dụng khách dùng giao thức wire để giao tiếp với máy chủ; máy chủ này dùng StackQL để thực hiện truy vấn hoặc thao tác DML đối với các nhà cung cấp đám mây và SaaS từ xa, rồi trả kết quả về cho ứng dụng khách.
Các tham số được gửi qua giao thức truy vấn mở rộng (Parse / Bind / Execute, như psycopg 3, pgx và JDBC sử dụng) được liên kết ở phía máy chủ dưới dạng literal chuỗi. Từ v0.12.742, placeholder $n nằm bên trong một literal chuỗi, định danh trong dấu ngoặc kép hoặc chú thích sẽ được giữ nguyên, dấu gạch chéo ngược trong giá trị tham số được thoát và giá trị văn bản NULL vẫn là chuỗi NULL (NULL của SQL được truyền riêng).
Tùy chọn máy chủ
| Tùy chọn | Mô tả | Mặc định |
|---|---|---|
--pgsrv.address | Địa chỉ mà máy chủ lắng nghe. | 0.0.0.0 |
--pgsrv.port | Cổng TCP mà máy chủ lắng nghe. | 5466 |
--pgsrv.tls | Đối tượng cấu hình TLS dạng JSON. Xem ví dụ mTLS bên dưới. | không có |
--pgsrv.debug.enable | Bật đầu ra gỡ lỗi truy vấn cho các ứng dụng khách PostgreSQL, ví dụ với stackql srv --pgsrv.debug.enable=true. Hãy để tắt, trừ khi ứng dụng khách cần nhận thông tin gỡ lỗi. | false |
--pgsrv.sundry | Ánh xạ JSON hoặc YAML nâng cao, chỉ được truyền cho máy chủ wire PostgreSQL khi --pgsrv.tls không được đặt. | {} |
--pgsrv.loglevel | Được chấp nhận nhưng không đặt mức của trình ghi nhật ký trong công cụ hiện tại. Thay vào đó, hãy dùng --loglevel. | WARN |
xem Cờ toàn cục để biết các tùy chọn bổ sung
Tùy chọn máy chủ MCP
Khi chạy lệnh srv có hỗ trợ MCP, bạn có thể dùng các tùy chọn bổ sung sau:
| Tùy chọn | Mô tả |
|---|---|
--mcp.server.type | Loại máy chủ MCP: http (trong bộ nhớ) hoặc reverse_proxy (dựa trên TCP) |
--mcp.config | Đối tượng cấu hình JSON cho máy chủ MCP (xem tài liệu MCP) |
--mcp.log.format | Mã hóa nhật ký kiểm tra MCP: jsonl (mặc định) hoặc otel (bản ghi nhật ký OTLP/JSON); ghi đè server.audit.format trong đối tượng cấu hình |
--mcp.protocol.version | Bản sửa đổi giao thức MCP mới nhất được công bố: auto (mặc định), 2026-07-28 (chỉ chế độ không có phiên) hoặc một bản sửa đổi cũ hơn như 2025-11-25; ghi đè server.protocol_version trong đối tượng cấu hình |
Từ v0.12.742, phương thức truyền tải HTTP của MCP (--mcp.server.type=http hoặc reverse_proxy) từ chối khởi động trừ khi đối tượng cấu hình chỉ định một bearer token bằng server.auth_token_env_var hoặc chủ động tắt yêu cầu này một cách rõ ràng bằng "allow_unauthenticated": true. Xem Xác thực ứng dụng khách HTTP.
Xem tài liệu về lệnh MCP để biết thông tin chi tiết về cách cấu hình và sử dụng máy chủ MCP, bao gồm các chế độ triển khai, tùy chọn cấu hình và tích hợp với trợ lý AI.
Bạn cần đặt các biến môi trường cần thiết cho việc xác thực provider trước khi khởi động máy chủ; xem Sử dụng provider để biết thêm thông tin.
Đối với máy chủ chạy lâu dài, cờ --env.file cho phép bạn đặt sẵn hoặc xoay vòng thông tin xác thực trong một tệp kiểu dotenv trên đĩa trước khi khởi động, thay vì xuất biến vào shell:
stackql srv --pgsrv.port 5444 --env.file /etc/stackql/credentials.env
Với stackql srv, tệp được đọc một lần khi khởi động; cách nạp lại giữa phiên là công cụ MCP reload_credentials.
Cờ
| Cờ | Mô tả |
|---|---|
-h,--help | In thông tin trợ giúp |
-v,--verbose | Chạy truy vấn ở chế độ chi tiết với đầu ra bổ sung được gửi tới stdout; nếu cờ toàn cục -f (--outfile) được đặt,thông tin nhật ký bổ sung này sẽ được ghi vào tệp đầu ra cùng với kết quả truy vấn |
xem Cờ toàn cục để biết các tùy chọn bổ sung
Ví dụ
Khởi chạy một tiến trình máy chủ StackQL và kết nối bằng ứng dụng khách dòng lệnh psql.
Trước tiên, tải xuống tệp cấu hình openssl.cnf từ stackql/stackql.
Tiếp theo, tạo các tệp chứng chỉ và khóa mà máy chủ và ứng dụng khách sẽ dùng cho xác thực TLS hai chiều (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
Bây giờ, đặt các biến môi trường; nếu ứng dụng khách và máy chủ ở trên cùng một máy, có thể dùng chung các biến này.
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
Thiết lập thông tin xác thực cho các provider mà máy chủ cần. Với GitHub, provider đọc tên người dùng và token truy cập cá nhân từ hai biến sau:
export STACKQL_GITHUB_USERNAME=youruser
export STACKQL_GITHUB_PASSWORD=ghp_youraccesstoken
Bây giờ, khởi động máy chủ trong một terminal.
stackql srv \
--pgsrv.address=0.0.0.0 \
--pgsrv.port=$PGPORT \
--pgsrv.tls='{ "keyFilePath": "'${PGSSLSRVKEY}'", "certFilePath": "'${PGSSLROOTCERT}'", "clientCAs": [ "'${CLIENT_CERT}'" ] }'
Trong một terminal khác, kết nối tới máy chủ bằng ứng dụng khách dòng lệnh psql.
psql -h 127.0.0.1 -d stackql
Bây giờ, chạy một truy vấn StackQL đối với một provider đã được xác thực.
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=>