Das C4-Container-Diagramm (C4-Modell-Ebene 2) zeigt die deploybaren Bausteine Ihres Systems: Web-Apps, APIs, Datenbanken, Queues. Dieser Leitfaden erklärt, was ein Container-Diagramm ist, was hineingehört, ein vollständig durchgearbeitetes Beispiel, häufige Fehler und wie Sie es mit Ihrem Code synchron halten.

C4 Container Diagram: Vollständiger Leitfaden mit Beispielen

Wenn Sie für Ihr System nur ein einziges Architekturdiagramm zeichnen, dann machen Sie es zum Container-Diagramm. Es ist Ebene 2 des C4-Modells, und in der Praxis ist es das meistgenutzte der vier Ebenen -- weil es direkt auf die Dinge abbildet, die Engineering-Teams tatsächlich bauen, deployen und betreiben: Web-Apps, APIs, Datenbanken, Message Broker.

Dieser Leitfaden deckt alles ab, was Sie zum Erstellen eines guten C4-Container-Diagramms brauchen: was es ist (und was nicht -- nein, ein C4-Container ist kein Docker-Container), was darauf gehört, ein vollständig durchgearbeitetes Beispiel für ein typisches SaaS-Produkt, die Fehler, die die meisten Container-Diagramme ruinieren, und wie Sie eines manuell erstellen oder aus Ihrer Codebasis generieren.

Wenn Sie mit dem C4-Modell überhaupt noch nicht vertraut sind, beginnen Sie mit unserem vollständigen Leitfaden zum C4-Modell und kommen Sie dann hierher zurück.

Was ist ein C4-Container-Diagramm?

Das Container-Diagramm ist Ebene 2 des C4-Modells, das von Simon Brown geschaffen wurde. Es zoomt in die einzelne Box hinein, die Ihr System im System-Context-Diagramm repräsentiert, und enthüllt die übergeordneten technischen Bausteine darin.

In der C4-Terminologie ist ein Container jede separat deploybare oder ausführbare Einheit: etwas, das Code ausführt oder Daten speichert, in einem eigenen Prozess läuft (oder einen eigenen Speicher-Lebenszyklus hat) und im Prinzip unabhängig vom Rest des Systems deploybar wäre.

Diese Definition deckt Dinge ab wie:

Eine Single-Page-Application (React, Vue, Angular), die im Browser des Nutzers läuft
Eine serverseitige Webanwendung (Next.js, Rails, Django)
Eine mobile Anwendung (iOS-App, Android-App)
Einen Backend-API-Service (Go-API, Node.js-Server, Spring-Boot-Service)
Eine Datenbank (PostgreSQL, MongoDB, MySQL)
Einen Cache (Redis, Memcached)
Einen Message Broker oder eine Queue (Kafka, RabbitMQ, SQS)
Einen Background Worker oder einen geplanten Job-Prozess
Einen Datei- oder Blob-Store (S3-Bucket, MinIO)
Eine Serverless-Function (AWS Lambda, Cloud Functions)

Der Lackmustest ist einfach: Läuft es in einem eigenen Prozess oder hält es eigene Daten? Zwei Go-Packages, die in eine Binary kompiliert werden, gehören zum selben Container. Zwei unabhängig deployte Services sind zwei Container -- selbst wenn sie ein Repository teilen.

Für eine knappe Referenzdefinition siehe den Container-Diagramm-Eintrag in unserem Glossar.

Ein C4-Container ist kein Docker-Container

Das ist der mit Abstand häufigste Verwirrungspunkt, also klären wir ihn ausdrücklich.

Das C4-Modell ist älter als die breite Verbreitung von Docker, und das Wort „Container" bedeutet in C4 etwas Breiteres: ein Baustein Ihres Systems auf Laufzeitebene. Die Überschneidung mit Docker ist zufällig und nur teilweise:

Ein C4-Container könnte in einem Docker-Container laufen. Ihre Go-API tut das wahrscheinlich.
Ein C4-Container kann als einfacher Betriebssystemprozess, als Browser-Tab, als mobile App oder als verwalteter Cloud-Dienst laufen. Keines davon ist ein Docker-Container.
Ein Docker-Container könnte sogar mehrere C4-Container beherbergen (eine App plus eine eingebettete Datenbank in einem Dev-Image), auch wenn das ungewöhnlich ist.

Anders ausgedrückt: Docker-Container sind eine Packaging- und Deployment-Technologie. C4-Container sind eine architektonische Abstraktion. Eine React-SPA, die in Chrome läuft, ist ein C4-Container und wird niemals ein Docker-Container sein. Eine RDS-PostgreSQL-Instanz ist ein C4-Container, und Docker ist nirgends in Sicht.

Wenn Sie eine Box auf einem C4-Diagramm als „Container" beschriften, sagen Sie damit „dies ist ein separat ausführbarer oder deploybarer Teil meines Systems" -- nicht mehr.

Was auf ein Container-Diagramm gehört

Ein gutes Container-Diagramm zeigt genau drei Kategorien von Information:

1. Die Container selbst

Jede deploybare oder ausführbare Einheit innerhalb Ihrer Systemgrenze, jeweils beschriftet mit ihrem Namen, ihrer Verantwortlichkeit und ihrer Technologieentscheidung: „Order Service (Go)", „Session Cache (Redis)", „Web App (React SPA)". Die Technologiebeschriftung ist keine Dekoration -- sie ist die Hälfte des Werts des Diagramms. Sie ist das, was es einem neuen Entwickler oder einem Plattformteam ermöglicht, über das System nachzudenken, ohne zwölf Repositories zu öffnen.

2. Die Beziehungen und Protokolle

Pfeile zwischen Containern, jeweils beschriftet mit dem, was fließt und wie: „liest/schreibt Bestellungen (SQL)", „publiziert Events (AMQP)", „macht API-Aufrufe (HTTPS/JSON)". Kommunikationsprotokolle sind auf dieser Ebene wichtig, weil sie betriebliche Belange bestimmen -- Network Policies, Latenzbudgets, Retry-Semantik, Fehlermodi.

3. Der unmittelbare Kontext

Die Nutzer und externen Systeme aus Ihrem Context-Diagramm, an den Rändern beibehalten, damit der Leser sehen kann, wie Anfragen in das System hinein- und hinausgehen. Sie dokumentieren sie nicht erneut im Detail; sie sind Ankerpunkte.

Für wen ist dieses Diagramm?

Die Zielgruppe des Container-Diagramms ist technisch: Entwickler, die zum Team stoßen, Architekten, die strukturelle Entscheidungen treffen, und Operations-/Plattform-Ingenieure, die Deployments, Monitoring und Kapazität planen. Es ist die Ebene, auf der Gespräche wie „sollten sich diese beiden Services eine Datenbank teilen?" oder „was bricht, wenn Redis ausfällt?" tatsächlich stattfinden. Nicht-technische Stakeholder sollten stattdessen auf das Context-Diagramm schauen.

Was NICHT hineingehört

Interne Module, Klassen oder Packages -- die leben im Component-Diagramm (Ebene 3)
Infrastrukturdetails wie Load Balancer, VPCs, Kubernetes-Nodes -- die gehören auf ein Deployment-Diagramm
Jede Mikro-Interaktion -- wenn eine Beziehung nicht architektonisch bedeutsam ist, lassen Sie sie weg

Container-Diagramm-Beispiel: Ein SaaS-Web-Produkt

Bauen wir ein vollständiges Container-Diagramm-Beispiel für ein fiktives SaaS-Produkt -- „InvoiceHub", ein webbasiertes Rechnungstool. Diese Gestalt (SPA + API + Datenbank + Cache + Worker + Queue) beschreibt einen riesigen Anteil realer Web-Produkte, sodass Sie es wahrscheinlich direkt anpassen können.

Die Container

Container	Technologie	Verantwortlichkeit
Web Application	React SPA	Die UI, die Kunden zum Erstellen und Versenden von Rechnungen nutzen
API Application	Go (Fiber)	Geschäftslogik, Authentifizierung, REST-API, die von der SPA konsumiert wird
Database	PostgreSQL	System of Record für Konten, Rechnungen, Zahlungen
Cache	Redis	Session-Speicher und Hot-Path-Caching von Rechnungszusammenfassungen
Message Queue	RabbitMQ	Entkoppelt langsame Arbeit (PDF-Rendering, E-Mails) von API-Anfragen
Background Worker	Go	Konsumiert Queue-Nachrichten: rendert PDFs, sendet E-Mails, synchronisiert Zahlungsstatus

Die Beziehungen

[Customer] --> [Web Application (React SPA)] : Uses (HTTPS)
[Web Application] --> [API Application (Go)] : Makes API calls (HTTPS/JSON)
[API Application] --> [Database (PostgreSQL)] : Reads/writes invoices and accounts (SQL/TCP)
[API Application] --> [Cache (Redis)] : Reads/writes sessions and cached summaries (RESP)
[API Application] --> [Message Queue (RabbitMQ)] : Publishes invoice.created, email.requested (AMQP)
[Background Worker (Go)] --> [Message Queue] : Consumes jobs (AMQP)
[Background Worker] --> [Database (PostgreSQL)] : Updates job and payment status (SQL/TCP)
[Background Worker] --> [Email Service (SendGrid)] : Sends invoice emails (HTTPS/REST)
[API Application] --> [Payment Gateway (Stripe)] : Creates payment links, receives webhooks (HTTPS/REST)

Was Ihnen dieses Diagramm verrät

Lesen Sie diese Liste noch einmal durch und beachten Sie, wie viele konkrete Engineering-Fragen sie beantwortet:

Wo lebt der State? An zwei Orten: PostgreSQL (dauerhaft) und Redis (flüchtig). Falls Sie jemals diskutiert haben, ob Sessions einen Redis-Neustart überleben, macht das Diagramm die Frage sichtbar.
Wie groß ist der Failure-Blast-Radius? Der Worker und die API teilen sich die Datenbank. Ein RabbitMQ-Ausfall bedeutet, dass Rechnungen weiterhin erstellt werden, aber E-Mails sich anstauen -- so gewollt.
Was sind die Trust Boundaries? Die SPA läuft auf nicht vertrauenswürdigen Client-Geräten; alles, was sie tun kann, läuft über die Authentifizierung der API.
Was muss Ops betreiben? Sechs Dinge, mit ihren Protokollen. Das ist Ihre Monitoring-Checkliste und ungefähr Ihre docker-compose-Datei.

Ein neuer Entwickler kann das in zwei Minuten aufnehmen. Genau das ist der ganze Sinn von C4-Modell-Ebene 2.

Häufige Fehler bei Container-Diagrammen

Die meisten Container-Diagramme scheitern auf eine von wenigen vorhersehbaren Arten.

Container mit Komponenten verwechseln

Wenn Ihr Container-Diagramm „OrderController", „InvoiceRepository" oder „AuthMiddleware" zeigt, haben Sie eine Ebene zu weit hineingezoomt. Das sind Komponenten -- interne Bausteine innerhalb eines Containers -- und sie gehören auf ein Component-Diagramm der Ebene 3. Der Test: Lässt es sich für sich allein deployen oder ausführen? Eine Repository-Klasse nicht. Halten Sie jedes Diagramm auf einer Zoom-Ebene; das Vermischen von Ebenen ist der schnellste Weg, ein unlesbares Diagramm zu produzieren.

Datenspeicher weglassen

Teams zeichnen oft nur die Dinge, für die sie Code geschrieben haben, und vergessen, dass Datenbanken, Caches und Queues ebenfalls Container sind. Ein Container-Diagramm ohne seine Datenspeicher verbirgt genau die Information, die Architekten und Ops-Ingenieure am meisten brauchen: wo der State lebt, was geteilt wird, was ein Single Point of Failure ist. Wenn Ihr System PostgreSQL, Redis und S3 nutzt, gehören alle drei aufs Diagramm.

Deployment statt Laufzeitstruktur zeichnen

Ein Container-Diagramm ist kein Infrastrukturdiagramm. Load Balancer, Kubernetes-Pods, Auto-Scaling-Gruppen, Availability Zones und die Anzahl der Replikate sind Deployment-Belange -- C4 hat dafür ein separates ergänzendes Deployment-Diagramm. Das Container-Diagramm beantwortet „was sind die logischen Laufzeitteile und wie reden sie miteinander?", nicht „wie viele Instanzen laufen wo?". Drei identische „API"-Boxen zu zeichnen, weil Sie drei Replikate betreiben, fügt Rauschen hinzu, keine Information.

Unbeschriftete oder vage Beziehungen

Ein Pfeil, der nur „verwendet" sagt, verschenkt das Potenzial des Diagramms. „Macht API-Aufrufe (HTTPS/JSON)", „publiziert Bestell-Events (AMQP)", „liest/schreibt Sessions (RESP)" -- das Verb und das Protokoll machen aus einem Bild eine Dokumentation.

Es vergammeln lassen

Der schädlichste Fehler steht gar nicht auf dem Diagramm. Ein Container-Diagramm, das vor achtzehn Monaten gezeichnet wurde und immer noch den Monolithen zeigt, den Sie seither in vier Services aufgeteilt haben, führt jeden neuen Leser aktiv in die Irre. Veraltete Architekturdokumentation ist schlimmer als keine -- weshalb es wichtiger ist, das Diagramm mit dem Code synchron zu halten, als wie hübsch es aussieht.

Wie man ein Container-Diagramm erstellt

Manuell

Sie können in unter einer Stunde ein solides Container-Diagramm bauen:

Beginnen Sie mit Ihrem Context-Diagramm. Behalten Sie die Nutzer und externen Systeme an den Rändern.
Listen Sie Ihre deploybaren Einheiten auf. Gehen Sie Ihre Repositories, Ihre docker-compose-Datei, Ihre Cloud-Konsole durch. Alles, was als eigener Prozess läuft oder Daten speichert, ist ein Kandidat.
Fügen Sie Datenspeicher explizit hinzu. Datenbanken, Caches, Queues, Blob-Storage.
Zeichnen Sie die Beziehungen. Für jedes Container-Paar, das kommuniziert, fügen Sie einen Pfeil mit einer Verbphrase und einem Protokoll hinzu.
Beschriften Sie Technologien. Name und Technologie in jeder Box.
Mit dem Team durchsehen. Die Diskussion, die das auslöst („Moment, der Worker spricht direkt mit Stripe?"), ist meist mehr wert als das Diagramm selbst.

Jedes Werkzeug funktioniert -- Structurizr, PlantUML mit der C4-Erweiterung, draw.io, sogar ein Whiteboard. Die Notation ist weit weniger wichtig als der Inhalt und die Disziplin, ihn aktuell zu halten.

Mit Archyl

Der manuelle Ansatz hat eine strukturelle Schwäche: Er erfasst eine Momentaufnahme, und Software hält nicht still. Archyl nähert sich dem Container-Diagramm aus der entgegengesetzten Richtung -- es leitet das Modell aus dem Code ab:

AI Discovery aus Ihrer Codebasis. Verbinden Sie ein Repository, und die AI Discovery von Archyl analysiert Ihre Codestruktur, Konfiguration und Abhängigkeits-Manifeste, um ein Entwurfs-C4-Modell vorzuschlagen -- Systeme, Container, Komponenten und die Beziehungen zwischen ihnen. Sie prüfen und genehmigen die Vorschläge, statt Boxen aus dem Gedächtnis zu zeichnen.
Drift-Erkennung hält es ehrlich. Sobald das Modell existiert, vergleicht Archyl kontinuierlich die dokumentierten Container mit dem, was die Codebasis tatsächlich zeigt, und liefert einen Drift-Score. Wenn jemand einen Service aufteilt oder RabbitMQ gegen Kafka tauscht, erfahren Sie es aus dem Dashboard, nicht aus einer verwirrten Onboarding-Sitzung sechs Monate später.
Architecture as Code. Bevorzugen Sie Text? Sie können Ihr vollständiges C4-Modell -- Container, Technologien, Beziehungen -- in YAML definieren, es neben Ihrem Code versionieren und Archyl die interaktiven Diagramme rendern lassen. Diagrammänderungen laufen wie alles andere über Pull Requests.

In beiden Fällen ist das Ziel dasselbe: ein Container-Diagramm, das heute korrekt ist und nächstes Quartal immer noch korrekt.

FAQ

Ist ein C4-Container dasselbe wie ein Docker-Container?

Nein. Ein C4-Container ist eine architektonische Abstraktion: jede separat deploybare oder ausführbare Einheit eines Systems, etwa eine Web-App, eine API, eine Datenbank oder ein Message Broker. Ein Docker-Container ist eine Packaging-Technologie. Viele C4-Container werden zufällig als Docker-Container deployt, aber viele auch nicht -- eine React-SPA läuft im Browser, eine mobile App läuft auf einem Telefon, und eine verwaltete Datenbank läuft als Cloud-Dienst. Der gemeinsame Name ist ein unglücklicher Zufall der Geschichte.

Was ist C4-Modell-Ebene 2?

Ebene 2 des C4-Modells ist das Container-Diagramm. Es zoomt in ein Softwaresystem hinein (die einzelne Box aus dem Context-Diagramm der Ebene 1) und zeigt die deploybaren/ausführbaren Einheiten darin, ihre Technologieentscheidungen und die Protokolle, die sie zur Kommunikation nutzen. Es liegt zwischen dem Context-Diagramm (Ebene 1) und dem Component-Diagramm (Ebene 3).

Wie viele Container sollte ein Container-Diagramm zeigen?

Es gibt keine feste Regel, aber die Lesbarkeit verschlechtert sich jenseits von 15-20 Containern schnell. Wenn Ihr System tatsächlich mehr hat, teilen Sie die Ansicht auf: ein Container-Diagramm pro Teilsystem, oder gruppieren Sie verwandte Container visuell. Wenn Sie Hunderte haben, dokumentieren Sie wahrscheinlich mehrere Systeme und brauchen separate C4-Modelle, die auf Context-Ebene verlinkt sind.

Sollte jeder Microservice ein eigener Container sein?

Ja -- per Definition. Jeder unabhängig deploybare Service ist ein eigener Container, ebenso die Datenbank jedes Services, wenn Sie dem Database-per-Service-Muster folgen. Das ist auch ein nützlicher Geruchstest: Wenn sich Ihre „Microservices" nicht als separate Container zeichnen lassen, weil sie einen Prozess teilen oder nicht unabhängig deployen können, könnten sie ein verteilter Monolith sein.

Bereit, Ihr Container-Diagramm zu generieren, statt es zu zeichnen? Probieren Sie Archyl kostenlos aus und erhalten Sie in Minuten ein C4-Modell aus Ihrer Codebasis. Erkunden Sie die C4-Serie weiter: Was ist das C4-Modell? Ein vollständiger Leitfaden | Leitfaden zum C4-System-Context-Diagramm | Leitfaden zum C4-Component-Diagramm.

C4 Container Diagram: Vollständiger Leitfaden mit Beispielen - Archyl Blog