Skalieren von Copilot SDK-Bereitstellungen

Hinweis

          Copilot SDK ist zurzeit in Technische Preview. Funktionalität und Verfügbarkeit können geändert werden.

Berücksichtigen Sie die verschiedenen Isolationsmuster für CLI-Sitzungen und wie Sie gleichzeitige Sitzungen und Ressourcen verwalten möchten, wenn Sie Ihre Anwendung implementieren.

          **Am besten geeignet für:** Plattformentwickler, SaaS-Generatoren und jede Bereitstellung, die mehr als ein paar gleichzeitige Benutzer bedient.

Sitzungsisolationsmuster

Berücksichtigen Sie vor der Auswahl eines Musters drei Dimensionen:

        **Isolation**: Wer kann sehen, welche Sessions?

        **Parallelität**: Wie viele Sessions können gleichzeitig ausgeführt werden?

        **Persistenz**: Wie lange bleiben Sitzungen bestehen?

Diagramm mit den drei Skalierungsdimensionen für Copilot SDK-Bereitstellungen: Isolation, Parallelität und Persistenz.

Muster 1: Isolierte CLI pro Benutzer

Jeder Benutzer erhält eine eigene CLI-Serverinstanz. Dies ist die stärkste Isolation– Sitzungen, Arbeitsspeicher und Prozesse eines Benutzers werden vollständig getrennt.

Diagramm mit der isolierten CLI pro Benutzermuster, in dem jeder Benutzer eine dedizierte CLI-Serverinstanz erhält.

          **Verwendungsbedingungen:**

Mehrinstanzenfähige SaaS, bei denen die Datenisolation von entscheidender Bedeutung ist.
Benutzer mit unterschiedlichen Authentifizierungsanmeldeinformationen.
Complianceanforderungen wie SOC 2 oder HIPAA.

// CLI pool manager—one CLI per user
class CLIPool {
    private instances = new Map<string, { client: CopilotClient; port: number }>();
    private nextPort = 5000;

    async getClientForUser(userId: string, token?: string): Promise<CopilotClient> {
        if (this.instances.has(userId)) {
            return this.instances.get(userId)!.client;
        }

        const port = this.nextPort++;

        // Spawn a dedicated CLI for this user
        await spawnCLI(port, token);

        const client = new CopilotClient({
            cliUrl: `localhost:${port}`,
        });

        this.instances.set(userId, { client, port });
        return client;
    }

    async releaseUser(userId: string): Promise<void> {
        const instance = this.instances.get(userId);
        if (instance) {
            await instance.client.stop();
            this.instances.delete(userId);
        }
    }
}

Modell 2: Freigegebene CLI mit Sitzungsisolierung

Mehrere Benutzer teilen einen CLI-Server, weisen jedoch isolierte Sitzungen über eindeutige Sitzungs-IDs auf. Dies ist ressourcenschonender, bietet aber eine schwächere Isolation.

Diagramm mit dem freigegebenen CLI-Muster, in dem mehrere Benutzer einen CLI-Server mit isolierten Sitzungen teilen.

          **Verwendungsbedingungen:**

Interne Tools mit vertrauenswürdigen Benutzern.
Ressourcenbeschränkte Umgebungen.
Niedrigere Isolationsanforderungen.

const sharedClient = new CopilotClient({
    cliUrl: "localhost:4321",
});

// Enforce session isolation through naming conventions
function getSessionId(userId: string, purpose: string): string {
    return `${userId}-${purpose}-${Date.now()}`;
}

// Access control: ensure users can only access their own sessions
async function resumeSessionWithAuth(
    sessionId: string,
    currentUserId: string
): Promise<Session> {
    const [sessionUserId] = sessionId.split("-");
    if (sessionUserId !== currentUserId) {
        throw new Error("Access denied: session belongs to another user");
    }
    return sharedClient.resumeSession(sessionId);
}

Muster 3: Gemeinsame Sitzungen (kollaborativ)

Mehrere Benutzer interagieren mit derselben Sitzung, z. B. einem gemeinsam genutzten Chatraum mit Copilot. Für dieses Muster ist eine Sitzungssperrung auf Anwendungsebene erforderlich.

Diagramm mit dem Muster für geteilte Sitzungen, bei dem mehrere Benutzer über eine Nachrichtenwarteschlange und einen Session-Lock mit derselben Sitzung interagieren.

          **Verwendungsbedingungen:**

Tools für die Teamzusammenarbeit.
Gemeinsame Code-Review-Sitzungen.
Paarprogrammierung-Assistenten.

Hinweis

Das SDK bietet keine integrierte Sitzungssperre. Sie müssen den Zugriff serialisieren, um gleichzeitige Schreibvorgänge in derselben Sitzung zu verhindern.

import Redis from "ioredis";

const redis = new Redis();

async function withSessionLock<T>(
    sessionId: string,
    fn: () => Promise<T>,
    timeoutSec = 300
): Promise<T> {
    const lockKey = `session-lock:${sessionId}`;
    const lockId = crypto.randomUUID();

    // Acquire lock
    const acquired = await redis.set(lockKey, lockId, "NX", "EX", timeoutSec);
    if (!acquired) {
        throw new Error("Session is in use by another user");
    }

    try {
        return await fn();
    } finally {
        // Release lock only if we still own it
        const currentLock = await redis.get(lockKey);
        if (currentLock === lockId) {
            await redis.del(lockKey);
        }
    }
}

// Serialize access to a shared session
app.post("/team-chat", authMiddleware, async (req, res) => {
    const result = await withSessionLock("team-project-review", async () => {
        const session = await client.resumeSession("team-project-review");
        return session.sendAndWait({ prompt: req.body.message });
    });

    res.json({ content: result?.data.content });
});

Vergleich von Isolationsmustern

	Isolierte CLI pro Benutzer	Gemeinsame Befehlszeilenschnittstelle (CLI) + Sitzungsisolation	Freigegebene Sitzungen

          **Isolation** | Abgeschlossen | Logisch | Shared |

Horizontale Skalierung

Mehrere CLI-Server hinter einem Lastverteiler

Um mehr gleichzeitige Benutzer zu bedienen, betreiben Sie mehrere Instanzen des CLI-Servers hinter einem Lastverteiler. Der Sitzungszustand muss sich im freigegebenen Speicher befinden, damit jeder CLI-Server jede Sitzung fortsetzen kann.

Diagramm mit mehreren CLI-Servern hinter einem Lastenausgleichsmodul mit gemeinsam genutztem Speicher für den Sitzungszustand.

// Route sessions across CLI servers
class CLILoadBalancer {
    private servers: string[];
    private currentIndex = 0;

    constructor(servers: string[]) {
        this.servers = servers;
    }

    // Round-robin selection
    getNextServer(): string {
        const server = this.servers[this.currentIndex];
        this.currentIndex = (this.currentIndex + 1) % this.servers.length;
        return server;
    }

    // Sticky sessions: same user always hits same server
    getServerForUser(userId: string): string {
        const hash = this.hashCode(userId);
        return this.servers[hash % this.servers.length];
    }

    private hashCode(str: string): number {
        let hash = 0;
        for (let i = 0; i < str.length; i++) {
            hash = (hash << 5) - hash + str.charCodeAt(i);
            hash |= 0;
        }
        return Math.abs(hash);
    }
}

const lb = new CLILoadBalancer([
    "cli-1:4321",
    "cli-2:4321",
    "cli-3:4321",
]);

app.post("/chat", async (req, res) => {
    const server = lb.getServerForUser(req.user.id);
    const client = new CopilotClient({ cliUrl: server });

    const session = await client.createSession({
        sessionId: `user-${req.user.id}-chat`,
        model: "gpt-4.1",
    });

    const response = await session.sendAndWait({ prompt: req.body.message });
    res.json({ content: response?.data.content });
});

Persistente Sitzungen im Vergleich zu freigegebenem Speicher

Diagramm, das Sticky Sessions und gemeinsame Speicheransätze zur Skalierung von Bereitstellungen des Copilot SDK vergleicht.

          **Sticky Sessions** binden jeden Benutzer an einen bestimmten CLI-Server. Es ist kein freigegebener Speicher erforderlich, aber die Auslastungsverteilung kann ungleich sein, wenn der Benutzerdatenverkehr erheblich variiert.

          **Der freigegebene Speicher** ermöglicht es jeder CLI, jede Sitzung zu verarbeiten. Die Lastverteilung ist gleichmäßiger, erfordert jedoch Netzwerkspeicher für `~/.copilot/session-state/`.

Vertikale Skalierung

Optimieren eines einzelnen CLI-Servers

Ein einzelner CLI-Server kann viele gleichzeitige Sitzungen verarbeiten. Der Schlüssel besteht darin, den Sitzungslebenszyklus zu verwalten, um Ressourcenerschöpfung zu vermeiden:

Diagramm mit den Ressourcendimensionen für die vertikale Skalierung: CPU, Arbeitsspeicher, Datenträger-E/A und Netzwerk.

// Limit concurrent active sessions
class SessionManager {
    private activeSessions = new Map<string, Session>();
    private maxConcurrent: number;

    constructor(maxConcurrent = 50) {
        this.maxConcurrent = maxConcurrent;
    }

    async getSession(sessionId: string): Promise<Session> {
        // Return existing active session
        if (this.activeSessions.has(sessionId)) {
            return this.activeSessions.get(sessionId)!;
        }

        // Enforce concurrency limit
        if (this.activeSessions.size >= this.maxConcurrent) {
            await this.evictOldestSession();
        }

        // Create or resume
        const session = await client.createSession({
            sessionId,
            model: "gpt-4.1",
        });

        this.activeSessions.set(sessionId, session);
        return session;
    }

    private async evictOldestSession(): Promise<void> {
        const [oldestId] = this.activeSessions.keys();
        const session = this.activeSessions.get(oldestId)!;
        // Session state is persisted automatically—safe to disconnect
        await session.disconnect();
        this.activeSessions.delete(oldestId);
    }
}

Ephemerale vs. persistente Sitzungen

Diagramm, in dem kurzlebige Sitzungen und persistente Sitzungen für Copilot SDK-Bereitstellungen verglichen werden.

          **Ephemerale Sitzungen** werden pro Anforderung erstellt und nach der Verwendung zerstört. Sie sind ideal geeignet für Einmalaufgaben und zustandslose APIs.

          **Persistente Sitzungen** werden benannt, überstehen Neustarts und können fortgesetzt werden. Sie eignen sich ideal für Multi-Turn-Chats und lange Workflows.

Kurzlebige Sitzungen

app.post("/api/analyze", async (req, res) => {
    const session = await client.createSession({
        model: "gpt-4.1",
    });

    try {
        const response = await session.sendAndWait({
            prompt: req.body.prompt,
        });
        res.json({ result: response?.data.content });
    } finally {
        await session.disconnect();
    }
});

Persistente Sitzungen

// Start a conversation
app.post("/api/chat/start", async (req, res) => {
    const sessionId = `user-${req.user.id}-${Date.now()}`;

    const session = await client.createSession({
        sessionId,
        model: "gpt-4.1",
        infiniteSessions: {
            enabled: true,
            backgroundCompactionThreshold: 0.80,
        },
    });

    res.json({ sessionId });
});

// Continue the conversation
app.post("/api/chat/message", async (req, res) => {
    const session = await client.resumeSession(req.body.sessionId);
    const response = await session.sendAndWait({ prompt: req.body.message });

    res.json({ content: response?.data.content });
});

// Clean up when done
app.post("/api/chat/end", async (req, res) => {
    await client.deleteSession(req.body.sessionId);
    res.json({ success: true });
});

Containerbereitstellungen

Kubernetes mit persistentem Speicher

Im folgenden Beispiel werden drei CLI-Replikate bereitgestellt, die gemeinsam ein PersistentVolumeClaim verwenden, sodass jedes Replikat jede Sitzung fortsetzen kann.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: copilot-cli
spec:
  replicas: 3
  selector:
    matchLabels:
      app: copilot-cli
  template:
    metadata:
      labels:
        app: copilot-cli
    spec:
      containers:
        - name: copilot-cli
          image: ghcr.io/github/copilot-cli:latest
          args: ["--headless", "--port", "4321"]
          env:
            - name: COPILOT_GITHUB_TOKEN
              valueFrom:
                secretKeyRef:
                  name: copilot-secrets
                  key: github-token
          ports:
            - containerPort: 4321
          volumeMounts:
            - name: session-state
              mountPath: /root/.copilot/session-state
      volumes:
        - name: session-state
          persistentVolumeClaim:
            claimName: copilot-sessions-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: copilot-cli
spec:
  selector:
    app: copilot-cli
  ports:
    - port: 4321
      targetPort: 4321

Diagramm, das eine Kubernetes-Bereitstellung mit mehreren CLI-Server-Pods zeigt, die sich einen PersistentVolumeClaim für den Sitzungszustand teilen.

Produktionsprüfliste

Sorge	Empfehlung

          **Sitzungsbereinigung** | Führen Sie regelmäßige Bereinigung aus, um Sitzungen zu löschen, die älter als Ihre TTL sind. |

| Systemüberprüfungen | Pingen Sie den CLI-Server regelmäßig an; starten Sie ihn neu, wenn er nicht reagiert. | | Lagerung | Bereitstellen persistenter Volumes für ~/.copilot/session-state/. | | Geheimnisse | Verwenden Sie den Secret Manager Ihrer Plattform (Vault, Kubernetes Secrets usw.). | | Überwachung | Nachverfolgen der Anzahl der aktiven Sitzungen, Antwortlatenz und Fehlerraten. | | Locking | Verwenden Sie Redis oder Ähnliches für den Zugriff auf geteilte Sitzungen. | | Herunterfahren | Entwässern Sie aktive Sitzungen, bevor Sie CLI-Server beenden. |

Einschränkungen

Einschränkung	Einzelheiten

          **Keine integrierte Sitzungssperre** | Implementieren Sie die Sperrung auf Anwendungsebene für den gleichzeitigen Zugriff. |

| Kein integrierter Lastenausgleich | Verwenden Sie einen externen Lastenausgleich oder ein Service-Mesh. | | Sitzungszustand ist dateibasiert | Erfordert ein gemeinsam genutztes Dateisystem für Setups mit mehreren Servern. | | Leerlauf-Timeout von 30 Minuten | Sitzungen ohne Aktivität werden von der CLI automatisch bereinigt. | | CLI ist ein Einzelprozess | Skalieren Sie, indem Sie weitere CLI-Serverinstanzen und nicht Threads hinzufügen. |

Nächste Schritte

Informationen zum serverseitigen Kernsetup finden Sie unter Einrichten des Copilot SDK für Back-End-Dienste.
Informationen zur mehrbenutzerbasierten Authentifizierung finden Sie unter Verwenden von GitHub OAuth mit Copilot SDK.
Informationen zur Installation und ihrer ersten Nachricht finden Sie unter Erste Schritte mit dem Copilot SDK.