إنتقل إلى المحتوى الرئيسي
صفحة مترجمة

تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.

srv

الأمر المستخدم لتشغيل StackQL كخدمة يمكن بعد ذلك الوصول إليها من خلال عملاء بروتوكول الاتصال الخاص بـ Postgres الذين تتم مصادقتهم باستخدام mTLS. يمكن للأمر srv أيضًا تشغيل خادم Model Context Protocol (MCP) إلى جانب خادم بروتوكول الاتصال الخاص بـ PostgreSQL، مما يتيح الوصول عبر بروتوكولين لكل من عملاء قواعد البيانات التقليدية ووكلاء الذكاء الاصطناعي.


بناء الجملة​

stackql srv [server_options] [flags]


ملاحظة

على الرغم من أن خادم StackQL يستخدم بروتوكول الاتصال الخاص بـ Postgres، فإنه ليس خادم Postgres ولا يتطلب وجود خادم منه. يستخدم العميل بروتوكول الاتصال للتواصل مع الخادم، الذي يستخدم StackQL لتنفيذ الاستعلامات أو عمليات DML على مزودي الخدمات السحابية ومزودي خدمات SaaS البعيدين وإعادة النتائج إلى العميل.

يتم ربط المعلمات المرسلة عبر بروتوكول الاستعلام الموسع (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.tlsكائن تكوين TLS بتنسيق JSON. راجع مثال mTLS أدناه.لا يوجد
--pgsrv.debug.enableتمكين إخراج تصحيح أخطاء الاستعلامات لعملاء PostgreSQL، على سبيل المثال باستخدام stackql srv --pgsrv.debug.enable=true. اترك هذا الخيار دون تمكين ما لم يكن من المفترض أن يتلقى العملاء معلومات تصحيح الأخطاء.false
--pgsrv.sundryتعيين متقدم بتنسيق JSON أو YAML يتم تمريره إلى خادم بروتوكول الاتصال الخاص بـ PostgreSQL فقط عندما لا يتم تحديد الخيار --pgsrv.tls.{}
--pgsrv.loglevelمقبول لكنه لا يعين مستوى أداة التسجيل في المحرك الحالي. استخدم --loglevel بدلًا من ذلك.WARN

راجع العلامات العامة للاطلاع على خيارات إضافية

خيارات خادم MCP​

عند تشغيل الأمر srv مع دعم MCP، تتوفر الخيارات الإضافية التالية:

الخيارالوصف
--mcp.server.typeنوع خادم MCP: http (في الذاكرة) أو reverse_proxy (يعتمد على TCP)
--mcp.configكائن تكوين بتنسيق JSON لخادم MCP (راجع وثائق 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، ترفض وسيلة النقل HTTP في MCP (--mcp.server.type=http أو reverse_proxy) بدء التشغيل إلا إذا حدد كائن التكوين الرمز المميز من نوع bearer باستخدام server.auth_token_env_var أو اختار بشكل صريح الاستغناء عن المصادقة باستخدام "allow_unauthenticated": true. راجع مصادقة عملاء HTTP.

تلميح

راجع وثائق أمر MCP للحصول على معلومات مفصلة حول تكوين خادم MCP واستخدامه، بما في ذلك أوضاع النشر وخيارات التكوين والتكامل مع مساعدي الذكاء الاصطناعي.

معلومات

يجب عليك تعيين متغيرات البيئة المطلوبة لمصادقة الموفرين قبل بدء تشغيل الخادم، وراجع استخدام موفر لمزيد من المعلومات.

بالنسبة إلى الخوادم التي تعمل لفترات طويلة، تتيح لك العلامة --env.file وضع بيانات الاعتماد أو تدويرها في ملف بنمط dotenv على القرص قبل بدء التشغيل بدلًا من تصدير المتغيرات إلى واجهة الأوامر:

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.

أولًا، نزّل ملف التكوين openssl.cnf من stackql/stackql.

بعد ذلك، أنشئ ملفات الشهادة والمفتاح التي سيستخدمها الخادم والعميل لمصادقة 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

عيّن بيانات الاعتماد للموفرين الذين يحتاجهم الخادم. بالنسبة إلى 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 -h 127.0.0.1 -d stackql

الآن شغّل استعلام 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=>