الأمان والنشر

تم تصميم DevUI كتطبيق عينة للتنمية المحلية. تغطي هذه الصفحة اعتبارات الأمان وأفضل الممارسات إذا كنت بحاجة إلى كشف DevUI خارج المضيف المحلي.

تحذير

DevUI غير مخصص لاستخدام الإنتاج. بالنسبة إلى عمليات نشر الإنتاج، قم بإنشاء واجهة مخصصة خاصة بك باستخدام Agent Framework SDK مع مقاييس الأمان المناسبة.

قريباً

ستتوفر وثائق DevUI ل C# قريبا. يرجى التحقق مرة أخرى لاحقا أو الرجوع إلى وثائق Python للحصول على إرشادات تصورية.

أوضاع واجهة المستخدم

يوفر DevUI وضعين يتحكمان في الوصول إلى الميزات:

وضع المطور (افتراضي)

الوصول الكامل إلى جميع الميزات:

• لوحة تتبع الأخطاء مع معلومات التتبع
• إعادة التحميل السريع للتطوير السريع (/v1/entities/{id}/reload)
• أدوات التوزيع (/v1/deployments)
• رسائل الخطأ المطولة لتصحيح الأخطاء

devui ./agents  # Developer mode is the default

وضع المستخدم

واجهة مبسطة ومقيدة:

• واجهة الدردشة وإدارة المحادثة
• قائمة الكيانات والمعلومات الأساسية
• تم تعطيل واجهات برمجة تطبيقات المطور (إعادة التحميل السريع، النشر)
• رسائل الخطأ العامة (التفاصيل المسجلة من جانب الخادم)

devui ./agents --mode user

Authentication

يتم تمكين مصادقة الرمز المميز للحامل بشكل افتراضي. بالنسبة لربط التكرار الحلقي، تنشئ DevUI رمزا مميزا وتعرضه في وحدة التحكم:

devui ./agents

للحصول على رمز مميز قابل للتكرار، قم بتعيين DEVUI_AUTH_TOKEN أو استخدام --auth-token. يتطلب ربط عدم التكرار رمزا مميزا صريحا ويفشل في الإغلاق دون واحد:

# Custom token via CLI
devui ./agents --auth-token "your-secure-token"

# Custom token via environment variable
export DEVUI_AUTH_TOKEN="your-secure-token"
devui ./agents --host 0.0.0.0

يجب أن تتضمن جميع طلبات واجهة برمجة التطبيقات الرمز المميز في Authorization العنوان:

curl http://localhost:8080/v1/entities \
  -H "Authorization: Bearer your-secure-token"

استخدم --no-auth فقط لتطوير التراجع المعزول. ترفض DevUI الارتباطات غير المصادق عليها غير المصادق عليها، وحتى التراجع عن وضع عدم المصادقة يزيل الحماية من الطلبات المرسلة من قبل مواقع الويب المعادية.

تكوين النشر الموصى به

إذا كنت بحاجة إلى عرض DevUI للمستخدمين النهائيين (غير مستحسن للإنتاج):

DEVUI_AUTH_TOKEN="<secure-dev-token>" devui ./agents --mode user --host 0.0.0.0

هذَا التَكوِين:

• تقييد واجهات برمجة التطبيقات التي تواجه المطور
• يتطلب المصادقة
• ربط بجميع واجهات الشبكة

ميزات الأمان

يتضمن DevUI العديد من التدابير الأمنية:

الميزة	Description
ربط المضيف المحلي	ربط إلى 127.0.0.1 بشكل افتراضي
وضع المستخدم	تقييد واجهات برمجة تطبيقات المطور
Authentication	يتم تمكين مصادقة الرمز المميز للحامل بشكل افتراضي
وضع عدم المصادقة	مسموح به فقط في localhost أو 127.0.0.1
ربطات الشبكة	طلب DEVUI_AUTH_TOKEN أو --auth-token
تحميل الكيان المحلي	تحميل الكيانات فقط من الدلائل المحلية أو في الذاكرة
لا يوجد تنفيذ عن بعد	لا توجد قدرات تنفيذ التعليمات البرمجية عن بعد

أفضل الممارسات

إدارة بيانات الاعتماد

• تخزين مفاتيح API والأسرار في .env الملفات
• عدم تثبيت .env الملفات أبدا بالتحكم بالمصادر
• استخدام .env.example الملفات لتوثيق المتغيرات المطلوبة

# .env.example (safe to commit)
OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

# .env (never commit)
OPENAI_API_KEY=sk-actual-key
AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/

أمان الشبكة

• الاحتفاظ بواجهة DevUI مرتبطة ب localhost للتطوير
• استخدام وكيل عكسي (nginx، Caddy) إذا كانت هناك حاجة إلى الوصول الخارجي
• تمكين HTTPS من خلال الوكيل العكسي
• تنفيذ المصادقة المناسبة على مستوى الوكيل

أمان الكيان

• مراجعة كافة التعليمات البرمجية للعامل/سير العمل قبل التشغيل
• تحميل الكيانات فقط من مصادر موثوق بها
• كن حذرا مع الأدوات التي لها آثار جانبية (الوصول إلى الملفات، مكالمات الشبكة)

تنظيف الموارد

تسجيل خطافات التنظيف لإغلاق بيانات الاعتماد والموارد بشكل صحيح عند إيقاف التشغيل:

import os
from azure.identity.aio import DefaultAzureCredential
from agent_framework import Agent
from agent_framework.openai import OpenAIChatCompletionClient
from agent_framework_devui import register_cleanup, serve

credential = DefaultAzureCredential()
client = OpenAIChatCompletionClient(
    model=os.environ["AZURE_OPENAI_CHAT_COMPLETION_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=credential,
)
agent = Agent(name="MyAgent", client=client)

# Register cleanup hook - credential will be closed on shutdown
register_cleanup(agent, credential.close)
serve(entities=[agent])

اعتبارات أدوات MCP

عند استخدام أدوات MCP (بروتوكول سياق النموذج) مع DevUI:

# Correct - DevUI handles cleanup automatically
mcp_tool = MCPStreamableHTTPTool(url="http://localhost:8011/mcp", client=chat_client)
agent = Agent(tools=mcp_tool)
serve(entities=[agent])

Important

لا تستخدم async with مديري السياق عند إنشاء عوامل باستخدام أدوات MCP ل DevUI. سيتم إغلاق الاتصالات قبل التنفيذ. تستخدم أدوات MCP التهيئة البطيئة وتتصل تلقائيا عند الاستخدام الأول.

Note

سيتوفر الدعم لهذه الميزة قريبا. راجع مستودع Agent Framework Go للحصول على أحدث حالة.

الخطوات التالية

• عينات - استعراض نماذج العوامل ومهام سير العمل
• مرجع واجهة برمجة التطبيقات - تعرف على نقاط نهاية واجهة برمجة التطبيقات