نشر الحاويات

هذا الدليل يحدد عقد حاوية Decision Gate OSS ويوفر خطوات جاهزة للمشغل لبناء وتشغيل صورة خادم MCP.

صورة الحاوية هي أثر خادم. تقوم بتشغيل decision-gate serve ومخصصة للنشر بأسلوب الإنتاج.

ملخص العقد (موثوق)

• نقطة الدخول: decision-gate
• الأمر الافتراضي: serve --config /etc/decision-gate/decision-gate.toml --allow-non-loopback
• تكوين التركيب: /etc/decision-gate/decision-gate.toml
• النقل: HTTP (SSE اختياري)
• المصادقة: مطلوبة (رمز حامل أو رأس وكيل mTLS)
• TLS: تم إنهاؤه في الجهة العليا بشكل افتراضي (server.tls_termination = "upstream")
• الاستمرارية: بدون حالة بشكل افتراضي؛ SQLite صريح
• وقت التشغيل: غير جذر، امتيازات محدودة، سجلات stdout/stderr
• مسارات قابلة للكتابة: /var/lib/decision-gate (فقط عند تمكين SQLite)

بناء الصورة

البناء المحلي:

docker build -t decision-gate:dev .

بناء متعدد المعمارية (amd64 + arm64):

IMAGE_REPO=ghcr.io/your-org/decision-gate IMAGE_TAG=dev \
  scripts/container/build_container.sh

ادفع متعدد المعمارية:

IMAGE_REPO=ghcr.io/your-org/decision-gate IMAGE_TAG=dev PUSH=1 \
  scripts/container/build_container.sh

ملاحظات:

• IMAGE_REPO=ghcr.io/your-org/decision-gate is a placeholder. Replace your-org مع منظمة GitHub الخاصة بك أو المستخدم (على سبيل المثال، ghcr.io/decision-gate/decision-gate).
• IMAGE_TAG=dev is a local/dev example. For releases, use a version tag (على سبيل المثال، vX.Y.Z) وبدلاً من ذلك نشر latest.

العلامات وسياسة الإصدار

محلي/تطوير:

• decision-gate:dev للاختبار العشوائي.
• علامات Local/dev ليست مواد إصدار بمستوى السياسة.

الإصدار:

• ghcr.io/<org>/decision-gate:vX.Y.Z (علامة إصدار غير قابلة للتغيير).
• ghcr.io/<org>/decision-gate:latest (يشير إلى أحدث إصدار).
• Release workflows emit supply-chain evidence including SPDX SBOMs, SLSA provenance statements, and Sigstore/cosign signatures for release المواضيع (Rust، Python، TypeScript، وقطع الحاويات).

التكوين

يتوقع الحاوية وجود ملف تكوين في: /etc/decision-gate/decision-gate.toml.

استخدم إعداد الحاوية كخط أساس: configs/presets/container-prod.toml.

المتطلبات الرئيسية:

• server.bind يجب أن يكون غير حلقي (على سبيل المثال، 0.0.0.0:8080).
• server.auth.mode يجب أن يكون bearer_token أو mtls.
• server.tls_termination = "upstream" عندما يتم إنهاء TLS خارج الحاوية.

تشغيل الحاوية

أدنى تشغيل (مصادقة رمز الحامل، إنهاء TLS العلوي):

docker run --rm -p 8080:8080 \
  -v "$(pwd)/configs/presets/container-prod.toml:/etc/decision-gate/decision-gate.toml:ro" \
  decision-gate:dev

ملاحظات:

• استبدل رمز العرض التوضيحي في الإعدادات قبل استخدامه في الإنتاج.
• --allow-non-loopback is part of the default container command. If you override the command, include --allow-non-loopback or set DECISION_GATE_ALLOW_NON_LOOPBACK=1.

TLS داخل الحاوية (اختياري)

إذا كنت بحاجة إلى TLS داخل الحاوية، قم بتعيين:

[server]
tls_termination = "server"

[server.tls]
cert_path = "/etc/decision-gate/tls/server.crt"
key_path = "/etc/decision-gate/tls/server.key"

قم بتركيب الشهادات وتحديث وقت تشغيل الحاوية الخاص بك وفقًا لذلك.

وضع المتانة (SQLite)

بشكل افتراضي، يستخدم إعداد الحاوية تخزين البيانات في الذاكرة.

لتمكين متانة SQLite، قم بتحديث الإعدادات:

[schema_registry]
type = "sqlite"
path = "/var/lib/decision-gate/schema-registry.db"

[run_state_store]
type = "sqlite"
path = "/var/lib/decision-gate/decision-gate.db"
journal_mode = "wal"
sync_mode = "full"
busy_timeout_ms = 5000

تشغيل مع وحدة تخزين قابلة للكتابة:

docker run --rm -p 8080:8080 \
  -v "$(pwd)/configs/presets/container-prod.toml:/etc/decision-gate/decision-gate.toml:ro" \
  -v decision-gate-data:/var/lib/decision-gate \
  decision-gate:dev

توقعات المصادقة

مثال على رمز الحامل:

curl -sS -X POST http://127.0.0.1:8080/rpc \
  -H "Authorization: Bearer dg-container-demo-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

لوضع وضع وكيل mTLS، قم بتعيين:

[server.auth]
mode = "mtls"
mtls_subjects = ["CN=decision-gate-client,O=Example Corp"]

ثم قم بجعل وكيلك يقوم بإدخال x-decision-gate-client-subject.

نقاط النهاية الصحية

يظهر Decision Gate مجسات Kubernetes القياسية:

• GET /healthz للتحقق من الحيادية
• GET /readyz للتحقق من الجاهزية

هذه النقاط النهائية غير مصادق عليها عن عمد وتعيد حالة الحد الأدنى فقط. /readyz يقوم بإجراء فحوصات جاهزية خفيفة (تخزين الحالة + سجل المخطط) ويعيد HTTP 503 مع {"status":"not_ready"} إذا كانت التبعيات غير متاحة.

curl -sS http://127.0.0.1:8080/healthz
curl -sS http://127.0.0.1:8080/readyz

كلا نقطتي النهاية ترجعان HTTP 200 مع حمولة JSON.

مثال على Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: decision-gate
spec:
  replicas: 1
  selector:
    matchLabels:
      app: decision-gate
  template:
    metadata:
      labels:
        app: decision-gate
    spec:
      containers:
        - name: decision-gate
          image: ghcr.io/your-org/decision-gate:latest
          ports:
            - containerPort: 8080
          securityContext:
            runAsNonRoot: true
            runAsUser: 10001
            readOnlyRootFilesystem: true
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /readyz
              port: 8080
            initialDelaySeconds: 2
            periodSeconds: 5
          volumeMounts:
            - name: config
              mountPath: /etc/decision-gate/decision-gate.toml
              subPath: decision-gate.toml
              readOnly: true
            - name: data
              mountPath: /var/lib/decision-gate
      volumes:
        - name: config
          configMap:
            name: decision-gate-config
        - name: data
          emptyDir: {}

لضمان ديمومة SQLite، استبدل emptyDir بمطالبة حجم دائم.

آثار سلسلة التوريد

تولد وتحقق سير العمل لإصدار/نشر Decision Gate الآن من تلقاء نفسها مباشرةً. تظل الأوامر أدناه مفيدة للتحقق اليدوي.

حاوية SBOM (مثال باستخدام syft):

syft packages decision-gate:dev -o spdx-json > decision-gate.sbom.spdx.json

توقيع الكائن أو الأثر (cosign):

cosign sign-blob decision-gate.sbom.spdx.json

بيان مصدر التوقيع:

cosign sign-blob decision-gate.provenance.intoto.json

تمنع سياسة الإصدار عندما:

• أي ثغرة عالية/حرجة موجودة.
• أي CVE معروف تم استغلاله موجود.
• فشل التحقق من التوقيع أو الأصل.