Μετάβαση στο περιεχόμενο

Ρύθμιση περιβαλλόντων

Ένα περιβάλλον είναι η στοίβα σε λειτουργία ενός χώρου: οι υπηρεσίες που χρειάζεται ένας κλάδος, απομονωμένες από όλους τους άλλους χώρους, ορατές στην πλαϊνή γραμμή και προσβάσιμες στους πράκτορες. Τα pull request αποκτούν επίσης ένα, επειδή ένα PR έχει ήδη δικό του χώρο.

Ένας διαχειριστής του χώρου εργασίας γράφει έναν ορισμό μία φορά. Στη συνέχεια τα μέλη πατούν Έναρξη στην ενότητα Περιβάλλον της πλαϊνής γραμμής ενός χώρου ή PR. Οι ορισμοί βρίσκονται στη βάση δεδομένων του χώρου εργασίας, οπότε ένας κλάδος λειτουργίας δεν αλλάζει ποτέ τι εκτελεί το Control Center, αν και τα εργαλεία εξακολουθούν να εκτελούν τον κώδικα αυτού του κλάδου.

  1. Ανοίξτε Ρυθμίσεις → Χώρος εργασίας → Περιβάλλοντα. Μόνο οι διαχειριστές του χώρου εργασίας μπορούν να αλλάξουν ορισμούς, και μόνο ο κάτοχος του διακομιστή μπορεί να αποθηκεύσει έναν που τρέχει στον κεντρικό υπολογιστή του διακομιστή (δείτε Ποιος μπορεί να αποθηκεύσει τι).
  2. Κάντε κλικ στο Νέος ορισμός και μετά στο Κενός ορισμός ή Πρόχειρο από αποθετήριο. Ένα πρόχειρο αναζητά στο αποθετήριο αρχεία compose, ένα Procfile και σενάρια package.json, και εσείς ελέγχετε το αποτέλεσμα.
  3. Συμπληρώστε τη φόρμα ή χρησιμοποιήστε την καρτέλα JSON. Τα παραδείγματα αυτής της σελίδας είναι αυτό το JSON.
  4. Κάντε κλικ στο Εκτέλεση δοκιμής. Ξεκινά ένα περιβάλλον μιας χρήσης, περιμένει μέχρι να είναι έτοιμο και το καταστρέφει.

Η αποθήκευση ελέγχει αυστηρά έναν ορισμό. Ένα άγνωστο πεδίο, τιμή λάθος τύπου ή λανθασμένα γραμμένη επιλογή απορρίπτονται, με τη διαδρομή τους και το πλησιέστερο έγκυρο όνομα, για παράδειγμα repos.app.requird: Unknown field. Did you mean "required"?. Το $schema στο ανώτατο επίπεδο επιτρέπεται.

Για να κρατήσετε έναν ορισμό σε αποθετήριο, χρησιμοποιήστε το Σύνδεση αρχείου αποθετηρίου. Το Control Center διαβάζει το αρχείο μόνο από τον προεπιλεγμένο κλάδο και εκτελεί μόνο την έκδοση που εγκρίθηκε από διαχειριστή του χώρου εργασίας ή, όταν ο ορισμός τρέχει στον κεντρικό υπολογιστή, από τον κάτοχο του διακομιστή. Μια νεότερη έκδοση εμφανίζει Διαθέσιμη ενημέρωση και δεν αλλάζει τίποτα μέχρι να εγκριθεί.

Ένας ορισμός περιβάλλοντος μπορεί να τρέχει εντολές στον κεντρικό υπολογιστή του διακομιστή, ως ο ίδιος ο χρήστης του διακομιστή. Αυτό είναι απόφαση του κατόχου του διακομιστή, όχι ρόλος χώρου εργασίας:

  • Ένας ορισμός τρέχει στον κεντρικό υπολογιστή όταν έχει τοποθέτηση σε host, έναν έλεγχο που τρέχει εντολή, ή μια εργασία provision ή archive. Αυτές οι εργασίες τρέχουν στο worktree του χώρου στον κεντρικό υπολογιστή, όποια κι αν είναι η τοποθέτηση.
  • Μόνο ο κάτοχος του διακομιστή μπορεί να αποθηκεύσει ή να εγκρίνει ορισμό που τρέχει στον κεντρικό υπολογιστή. Αυτό περιλαμβάνει την έγκριση νέας έκδοσης ενός συνδεδεμένου αρχείου αποθετηρίου. Ένας διαχειριστής χώρου εργασίας που το επιχειρεί βλέπει «Μόνο ο κάτοχος του διακομιστή μπορεί να αποθηκεύσει ή να εγκρίνει περιβάλλον που τρέχει στον κεντρικό υπολογιστή του διακομιστή. Ένας διαχειριστής χώρου εργασίας μπορεί να χρησιμοποιεί ένα που τρέχει σε rig.»
  • Ένας διαχειριστής χώρου εργασίας μπορεί να αποθηκεύσει και να εγκρίνει έναν ορισμό που τρέχει εξ ολοκλήρου σε rig: "placement": "rig", χωρίς εντολή ελέγχου και χωρίς εργασία provision ή archive.
  • Τα μέλη ξεκινούν, σταματούν και χρησιμοποιούν περιβάλλοντα και με τους δύο τρόπους.
  • Ένας ορισμός που τρέχει στον κεντρικό υπολογιστή εκτελείται μόνο αφού τον έχει αποθηκεύσει ή εγκρίνει ο τρέχων κάτοχος του διακομιστή. Ο διακομιστής καταγράφει μόνος του αυτή την έγκριση και την ελέγχει πριν από κάθε έναρξη, έλεγχο, εργασία και συγχρονισμό της κεφαλής pull request. Ένας ορισμός που ο τρέχων κάτοχος δεν έχει εγκρίνει, όπως ένας που αποθήκευσε προηγούμενος κάτοχος, περιμένει κάτω από τη γραμμή του στη λίστα περιβαλλόντων και στον επεξεργαστή. Ο κάτοχος του διακομιστή βλέπει «Εκτελείται σε αυτόν τον διακομιστή. Εγκρίνετέ το για να μπορέσει να ξεκινήσει.» με Έγκριση, που τον αποθηκεύει αμετάβλητο· όλοι οι άλλοι βλέπουν «Εκτελείται σε αυτόν τον διακομιστή. Ο κάτοχος του διακομιστή πρέπει να το εγκρίνει πριν μπορέσει να ξεκινήσει.»
  • Ένα περιβάλλον που περιμένει αυτή την έγκριση λέει «Ο κάτοχος του διακομιστή δεν έχει εγκρίνει ακόμη αυτό το περιβάλλον, γι’ αυτό δεν μπορεί να εκτελεστεί σε αυτόν τον διακομιστή.» Ο κάτοχος του διακομιστή βλέπει αντί αυτού «Δεν έχετε εγκρίνει ακόμη αυτό το περιβάλλον. Εκτελείται σε αυτόν τον διακομιστή, οπότε θα ξεκινήσει αφού εγκρίνετε τον ορισμό του.» με Έλεγχος και έγκριση, που ανοίγει τον ορισμό.
  • Οι τερματικοί των διεργασιών ενός περιβάλλοντος και ο τερματικός που ανοίγει μια έναρξη όταν χρειάζεται εσάς τρέχουν στον κεντρικό υπολογιστή του διακομιστή. Η πληκτρολόγηση σε έναν, η αλλαγή μεγέθους του ή το κλείσιμό του απαιτεί δικαίωμα εγγραφής σε κάθε αποθετήριο που εκθέτει ο χώρος, αναγνώσιμο μέσω της δικής σας σύνδεσης στη φιλοξενία κώδικα: το ίδιο με την έναρξη του περιβάλλοντος. Κανείς άλλος δεν μπορεί καν να φτάσει σε αυτούς τους τερματικούς.

Ένα απλό αποθετήριο compose χρειάζεται μόνο αυτό:

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [ { "kind": "compose", "id": "stack" } ]
}

Όλα τα υπόλοιπα έχουν προεπιλογή: το αρχείο compose εντοπίζεται, κάθε υπηρεσία εκτελείται, οι θύρες εκχωρούνται, τα τελικά σημεία HTTP ανιχνεύονται και το περιβάλλον παίρνει το όνομα του κλάδου.

Ένα περιβάλλον είναι μια διατεταγμένη λίστα στοιχείων. Το καθένα περιμένει να είναι έτοιμο το προηγούμενο, εκτός αν το after ορίζει άλλα, και η διακοπή γίνεται αντίστροφα. Το enabledWhen εξαρτά ένα στοιχείο από μια επιλογή ή έναν ρόλο, για παράδειγμα opt.seed, !opt.seed ή repo.web. Ένα στοιχείο του οποίου ο ρόλος είναι προαιρετικός και λείπει από τον χώρο παραλείπεται με τον ίδιο τρόπο, χωρίς να χρειάζεται enabledWhen: δεν ξεκινά και δεν έχει {port.*} ή {url.*}, οπότε ένα άλλο στοιχείο που τα διαβάζει αποτυγχάνει στην έναρξη.

Είδος Ποιος το εκτελεί Χρήση
compose Το πρόγραμμα οδήγησης compose του Control Center Οποιοδήποτε αρχείο compose, ένα ανά περιβάλλον
cli Το εργαλείο σας. Το Control Center καλεί αντιστοιχισμένα ρήματα και διαβάζει JSON Εργαλείο που διαχειρίζεται το δικό του κύκλο ζωής, τομείς και δεδομένα
process Το Control Center, σε εποπτευόμενη συνεδρία τερματικού Διακομιστές ανάπτυξης και workers
task Το Control Center, μία φορά ανά έναυσμα Εγκαταστάσεις, μεταναστεύσεις, δοκιμές
app Το Control Center, όταν κάποιος πατήσει Εκκίνηση εφαρμογής Εφαρμογή επιφάνειας εργασίας

Τα στοιχεία task δέχονται μια λίστα when:

Έναυσμα Πότε εκτελείται
provision Όταν δημιουργείται το worktree (δείτε παρακάτω τις εργασίες worktree)
create Μία φορά ανά περιβάλλον και ξανά μετά από επαναφορά
start Σε κάθε εκκίνηση
change Μετά από συγχρονισμό, όταν μια αλλαγμένη διαδρομή ταιριάζει με το onChange
manual Κατ’ αίτηση: Εκτέλεση, cc-env run <id> ή environment_run_task
archive Ακριβώς πριν καταστραφεί το worktree

Μια εργασία που δεν έχει τίποτα να κάνει σε μια εκκίνηση εμφανίζεται ως Αδρανής και δεν συμπεριλαμβάνεται στη λίστα των βημάτων που εμφανίζεται όσο ξεκινά το περιβάλλον: μια εργασία manual ή change, ή μια εργασία create που έχει ήδη τρέξει.

Μια εντολή που δίνεται ως πίνακας είναι argv, οπότε οι τιμές επιλογών δεν περνούν ποτέ από κέλυφος. Μια συμβολοσειρά, ή script με πίνακα γραμμών, εκτελείται με bash -lc. Σύμβολα κράτησης όπως {name}, {branch}, {stateDir}, {repo.<role>}, {port.<key>}, {opt.<key>} και {url.<role>} αναπτύσσονται μόνο σε argv. Οι εντολές κελύφους διαβάζουν τις ίδιες τιμές ως μεταβλητές CC_ENV_*, όπως $CC_ENV_PORT_WEB. Ένα άγνωστο σύμβολο κράτησης σε στοιχείο που συμμετέχει σταματά την έναρξη προτού εκτελεστεί οτιδήποτε.

Κάθε εντολή και τερματικό χώρου παίρνει επίσης CC_ENV_NAME, CC_ENV_STATE_DIR, CC_ENV_URL, CC_SPACE_ID, CC_ENV_REPO_<ROLE> και, σε χώρους PR, CC_PR_NUMBER και CC_PR_IS_FORK. Με στοιχείο compose παίρνουν και COMPOSE_PROJECT_NAME και COMPOSE_FILE, ώστε το docker compose exec σε μια εργασία να φτάνει στο σωστό έργο.

Ένας ορισμός δεσμεύει ρόλους σε αποθετήρια του χώρου εργασίας, ώστε μια στοίβα να καλύπτει πολλά αποθετήρια:

"repos": {
"api": { "repoId": "<api>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true },
"e2e": { "repoId": "<e2e>", "whenMissing": "useSource" }
}
  • anchor: ένας χώρος μπορεί να ξεκινήσει το περιβάλλον όταν έχει τουλάχιστον έναν ρόλο άγκυρα. Αν ταιριάζουν δύο ορισμοί, επιλέγει αυτός που ξεκινά.
  • required: η στοίβα δεν μπορεί να εκτελεστεί χωρίς αυτό το αποθετήριο.
  • whenMissing: τι συμβαίνει όταν λείπει ο ρόλος από τον χώρο. Το addToSpace προσθέτει το αποθετήριο στον προεπιλεγμένο κλάδο και είναι η προεπιλογή για ρόλους required. Το useSource περνά το καταχωρισμένο checkout σας, που πρέπει να θεωρείται μόνο για ανάγνωση. Το skip αφήνει τη μεταβλητή κενή και είναι η προεπιλογή στις υπόλοιπες περιπτώσεις.
  • Η εκκίνηση απαιτεί δικαίωμα write σε αποθετήριο άγκυρα του χώρου και πρόσβαση ανάγνωσης σε κάθε άλλο δεσμευμένο αποθετήριο.

Μια εντολή εκτελείται στον πρώτο ρόλο που δηλώνεται στο repos, και ποτέ σε άλλον ρόλο που τυχαίνει να έχει ο χώρος, οπότε ένας ορισμός με ένα αποθετήριο δεν το αναφέρει ποτέ. Κάθε στοιχείο μπορεί να το αλλάξει με "cwd": { "role": "e2e", "path": "packages/ui" }. Και τα δύο πεδία είναι προαιρετικά. Αν ο πρώτος ρόλος μπορεί να λείπει από έναν χώρο, επειδή δεν είναι ούτε required ούτε η μοναδική άγκυρα, κάθε στοιχείο πρέπει να δηλώνει τον ρόλο του.

Το Control Center εκχωρεί θύρες κεντρικού υπολογιστή πριν ξεκινήσει οτιδήποτε, από ένα εύρος κοινό για όλο τον κεντρικό υπολογιστή (από 42000 έως 49999 από προεπιλογή, σε μπλοκ των 32). Μια θύρα μένει ίδια σε όλη τη ζωή του περιβάλλοντος και οι θύρες compose δεσμεύονται μόνο στο 127.0.0.1.

  • Οι θύρες compose δεν χρειάζονται δήλωση. Διαβάστε τις ως {port.postgres.5432} ή CC_ENV_PORT_POSTGRES_5432.
  • Οι άλλες θύρες δηλώνονται εκεί όπου χρησιμοποιούνται, με "port": "web" ή "ports": ["web", "hmr"], και διαβάζονται ως {port.web}. Μια διεργασία με θύρα παίρνει επίσης PORT και HOST=127.0.0.1.

Τα τελικά σημεία HTTP παίρνουν URL στον δρομολογητή του διακομιστή, ο οποίος ακούει σε μία θύρα loopback:

http://<endpoint>--<name>--<project>.localhost:<router port>
http://web--fix-login--shop.localhost:7355
  • Το <name> είναι ο κλάδος ως slug ή pr-<n> σε χώρο PR. Το <project> είναι το naming.project, αλλιώς το όνομα του ορισμού.
  • Τα ονόματα *.localhost δείχνουν στο loopback, οπότε δεν χρειάζονται καταχωρίσεις hosts ή DNS, και το όνομα κεντρικού υπολογιστή κρατά τα cookies χωριστά μεταξύ περιβαλλόντων.
  • Οι θύρες compose που απαντούν σε HTTP ανιχνεύονται και το http στο στοιχείο παρακάμπτει την εκτίμηση. Μια διεργασία χρειάζεται "endpoint": { "role": "web", "primary": true }, που κάνει διαθέσιμο και το {url.web}.
  • Στο πρόγραμμα περιήγησης (VM), χρησιμοποιήστε το Άνοιγμα στο Browser (VM). Το https://web--fix-login--shop.localhost/ φτάνει εκεί στην ίδια διαδρομή.
  • Ολόκληρη η ετικέτα μένει εντός 63 χαρακτήρων, οπότε τα μεγάλα ονόματα συντομεύονται με hash.
  • Δύο τελικά σημεία δεν μοιράζονται γονικό τομέα. Μια εφαρμογή που χρειάζεται ένα cookie και στα δύο πρέπει να τα σερβίρει από ένα τελικό σημείο.

Για URL που πρέπει να καταχωριστούν εκ των προτέρων, όπως ανακατευθύνσεις OAuth, το "naming": { "pool": { "names": "cc{n}", "size": 8 }, "project": "shop" } δίνει ένα σταθερό σύνολο ονομάτων.

Το policy αποφασίζει πότε εκτελούνται τα περιβάλλοντα. Το autoCreate είναι off, prSpaces ή allSpaces, το idleStopMinutes είναι 240 από προεπιλογή, το followPrHead συγχρονίζει ένα περιβάλλον PR όταν μετακινείται το head του, και με το maxRunning (προεπιλογή 6) το Έναρξη προτείνει τη διακοπή του περιβάλλοντος που χρησιμοποιήθηκε λιγότερο πρόσφατα.

Μια εφαρμογή web και Postgres από ένα αρχείο compose, με .env που αγνοεί το git, μεταναστεύσεις και εργασία δοκιμών. Το seedFiles αντιγράφει ονομασμένα αρχεία από το καταχωρισμένο checkout σας σε κάθε νέο worktree.

{
"contract": 1,
"name": "Shop",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "shop" },
"seedFiles": [".env"],
"components": [
{ "kind": "compose", "id": "stack",
"services": ["postgres", "web"],
"healthchecks": { "postgres": ["pg_isready", "-U", "postgres"] } },
{ "kind": "task", "id": "migrate", "when": ["create", "change"],
"onChange": ["db/migrations/**"],
"command": "docker compose exec -T web bin/migrate" },
{ "kind": "task", "id": "test", "when": ["manual"],
"command": "docker compose exec -T web bin/test" }
]
}

Το healthchecks επιτρέπει σε μια υπηρεσία χωρίς δικό της έλεγχο υγείας να κρατά το επόμενο στοιχείο. Χωρίς αυτό, ένα κοντέινερ σε λειτουργία μετρά ως έτοιμο και οι μεταναστεύσεις μπορεί να προλάβουν μια βάση δεδομένων που ακόμα ξεκινά.

Κάθε έναρξη και ανανέωση εκτελεί το up με --remove-orphans, έτσι ώστε μια υπηρεσία που αφαιρέθηκε από το αρχείο compose να σταματά και να αποδεσμεύει τη θύρα της. Οι εικόνες χτίζονται κατά την έναρξη και την ανανέωση, εκτός αν το στοιχείο ορίζει "build": false.

Ένα φανταστικό εργαλείο acme που διαχειρίζεται τα δικά του κοντέινερ, τομείς και TLS. Το Control Center δίνει το {name} και μαθαίνει όλα τα υπόλοιπα από το status. Δεν συνάγει ποτέ τα ονόματα κεντρικών υπολογιστών ενός εργαλείου και δεν επεξεργάζεται ποτέ το /etc/hosts.

{
"contract": 1,
"name": "Acme",
"repos": {
"server": { "repoId": "<server>", "anchor": true, "required": true },
"web": { "repoId": "<web>", "anchor": true }
},
"routing": { "mode": "tool", "domain": "acme.test", "upstream": "127.0.0.1:443",
"tls": true, "caFile": "~/.acme/tls/ca.crt" },
"components": [
{ "kind": "cli", "id": "acme",
"verbs": {
"create": ["acme", "env", "create", "{name}",
{ "if": "!interactive", "args": ["--json"] },
{ "if": "repo.web", "args": ["--web-dir", "{repo.web}"] }],
"start": ["acme", "env", "start", "{name}"],
"stop": ["acme", "env", "stop", "{name}"],
"destroy": ["acme", "env", "destroy", "{name}", "--yes"],
"reset": ["acme", "env", "reset-db", "{name}"],
"status": ["acme", "env", "status", "{name}", "--json"],
"list": ["acme", "env", "ls", "--json"],
"logs": ["acme", "env", "logs", "{name}",
{ "if": "service", "args": ["{service}"] },
"--tail", "{tail}",
{ "if": "follow", "args": ["--follow"] }],
"exec": ["acme", "env", "exec", "{name}", "{service}", "{command}"]
},
"interactive": ["create"],
"keepsDataOnStop": false,
"statusMap": {
"state": [
{ "when": { "path": "/status/ready", "equals": true }, "state": "ready" },
{ "when": { "none": "/status/containers", "where": { "state": "running" } },
"state": "stopped" },
{ "when": { "path": "/status/phase", "equals": "failed" }, "state": "failed" },
{ "state": "starting" }
],
"detail": "phase: {/status/phase}",
"warnings": [
{ "when": { "path": "/status/dnsWorking", "equals": false },
"message": "Not resolvable on this host" }
],
"endpoints": [
{ "role": "app", "label": "App", "url": "/urls/app", "primary": true },
{ "role": "db", "hostPort": "/ports/db" }
],
"services": "/status/containers/*/service",
"list": "/*/slug",
"missingErrorCodes": ["env.not-found"]
} }
]
}
  • Τα create, status και destroy είναι υποχρεωτικά. Το Control Center επιλέγει create ή start από την κατάσταση που διαβάζει. Κάθε ρήμα μπορεί να είναι { "shell": "…" } αντί για argv.
  • Το interactive ονομάζει τα ρήματα, από τα create, start και reset, που μπορούν να ζητήσουν ό,τι χρειάζονται σε τερματικό. Όταν ένα τέτοιο ρήμα τερματίζει με κωδικό 3 για το άτομο που πάτησε Έναρξη, το Control Center εκτελεί ξανά το ίδιο ρήμα σε καρτέλα τερματικού, και η έναρξη συνεχίζεται όταν τερματίσει με κωδικό 0. Εκεί η συνθήκη interactive είναι αληθής και έχει οριστεί CC_ENV_INTERACTIVE=1, άρα το { "if": "!interactive", "args": ["--json"] } διατηρεί την έξοδο μηχανής για τη μη διαδραστική εκτέλεση. Μια έναρξη από πράκτορα ή μια αυτόματη έναρξη δεν ανοίγει ποτέ τερματικό: το περιβάλλον δείχνει Απαιτείται ενέργεια και περιμένει.
  • Ένα destroy που αποτυγχάνει εξακολουθεί να αφαιρεί το περιβάλλον όταν το status στη συνέχεια αναφέρει missing, έτσι ένα περιβάλλον που το εργαλείο δεν έχει πια μπορεί πάντα να αφαιρεθεί.
  • Το list επιτρέπει στο Control Center να εντοπίσει ένα περιβάλλον που έχει χάσει το εργαλείο. Επισημαίνεται ως χαμένο μόνο όταν το όνομά του λείπει από το list και το status τότε δείχνει missing. Η έξοδος που δεν μπορεί να διαβαστεί ως λίστα δεν αλλάζει τίποτα.
  • Το {service} στα logs και exec πρέπει να είναι μία λέξη που δεν αρχίζει με -, και μία από τις υπηρεσίες που ανέφερε τελευταία φορά το εργαλείο, αν ανέφερε κάποια.
  • Το statusMap διαβάζει το JSON του εργαλείου με δείκτες JSON, όπου το * ταιριάζει με κάθε στοιχείο. Οι κανόνες κατάστασης είναι διατεταγμένοι και κερδίζει η πρώτη αντιστοιχία. Μια συνθήκη είναι path με equals, ή any ή none με where.
  • Το keepsDataOnStop: false απενεργοποιεί τη διακοπή λόγω αδράνειας και προσθέτει στο Διακοπή προειδοποίηση απώλειας δεδομένων. Ορίστε το όταν η διακοπή χάνει δεδομένα.
  • Το routing.mode: "tool" συνδέει τα ονόματα κεντρικών υπολογιστών του εργαλείου με το πρόγραμμα περιήγησης (VM) και τους πράκτορες. Ο τομέας πρέπει να τελειώνει σε .test, .localhost ή .internal, και ένα αναφερόμενο URL εκτός του απορρίπτεται.

Ένα δικό σας εργαλείο μπορεί να παραλείψει το statusMap και να εκτυπώνει το συμβόλαιο κατάστασης που περιγράφεται στο τέλος αυτής της σελίδας.

Μόνο διεργασίες και εργασίες, χωρίς κοντέινερ. Η εφαρμογή web βρίσκει το API μέσω του {url.api}.

{
"contract": 1,
"name": "Monorepo",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"naming": { "project": "mono" },
"options": [ { "key": "seed", "type": "bool", "default": true, "agentDefault": false } ],
"components": [
{ "kind": "task", "id": "install", "when": ["provision", "change"],
"onChange": ["pnpm-lock.yaml"],
"command": ["pnpm", "install", "--frozen-lockfile"] },
{ "kind": "process", "id": "api", "label": "API", "port": "api",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "dev"],
"endpoint": { "role": "api" },
"ready": { "http": "http://127.0.0.1:{port.api}/health", "timeout": 120 },
"restartOn": ["pnpm-lock.yaml"] },
{ "kind": "task", "id": "seed", "when": ["create"], "enabledWhen": "opt.seed",
"cwd": { "path": "apps/api" },
"command": ["pnpm", "db:seed"] },
{ "kind": "process", "id": "web", "label": "Dev server", "port": "web",
"cwd": { "path": "apps/web" },
"env": { "API_URL": "{url.api}" },
"command": ["pnpm", "dev", "--port", "{port.web}", "--host", "127.0.0.1"],
"endpoint": { "role": "web", "primary": true },
"ready": { "http": "http://127.0.0.1:{port.web}/" } },
{ "kind": "task", "id": "lint", "when": ["manual"], "command": ["pnpm", "lint"] }
]
}
  • Κάθε διεργασία είναι μια καρτέλα τερματικού που μπορείτε να ανοίξετε, να διαβάσετε και να πληκτρολογήσετε σε αυτή, αν έχετε δικαίωμα εγγραφής σε κάθε αποθετήριο του χώρου (δείτε Ποιος μπορεί να αποθηκεύσει τι). Το κλείσιμο της καρτέλας δεν τη σταματά.
  • Το ready δέχεται http (πλήρες URL), tcp (host:port) ή logMatch (κανονική έκφραση). Το restart είναι on-failure (προεπιλογή), always ή never. Το restartOn επανεκκινεί τη διεργασία όταν ταιριάζει μια αλλαγμένη διαδρομή.
  • Τα options γίνονται φόρμα στο Έναρξη και το agentDefault ισχύει για εκτελέσεις που ξεκινά πράκτορας.

Παράδειγμα: εφαρμογή επιφάνειας εργασίας

Ενότητα με τίτλο «Παράδειγμα: εφαρμογή επιφάνειας εργασίας»

Μια εφαρμογή επιφάνειας εργασίας με βήμα δόμησης. Μια εφαρμογή λειτουργεί το ίδιο όποια τεχνολογία κι αν χρησιμοποιεί, επειδή το Control Center δουλεύει σε επίπεδο παραθύρων του λειτουργικού και δεν χρειάζεται hook ή SDK στην εφαρμογή.

{
"contract": 1,
"name": "Studio",
"repos": { "app": { "repoId": "<id>", "anchor": true, "required": true } },
"components": [
{ "kind": "task", "id": "build", "when": ["manual"], "command": ["pnpm", "build"] },
{ "kind": "app", "id": "desktop", "label": "Studio", "prepare": "build",
"command": ["dist/mac-arm64/Studio.app/Contents/MacOS/Studio"],
"isolate": "home" }
]
}

Μια εφαρμογή δεν ξεκινά με το περιβάλλον. Κάποιος πατά Εκκίνηση εφαρμογής και πρώτα εκτελείται το prepare. Το Νέα δόμηση και επανεκκίνηση εκτελεί ξανά αυτό το ζεύγος. Το enabledWhen ισχύει για την εφαρμογή και για την εργασία prepare της, και το Εκκίνηση εφαρμογής απορρίπτεται όσο είναι απενεργοποιημένο κάτι από τα δύο. Η εφαρμογή θεωρείται σε λειτουργία όσο τρέχει οποιαδήποτε διεργασία στην ομάδα διεργασιών της, άρα ένας εκκινητής που ξεκινά την εφαρμογή και τερματίζει είναι εντάξει. Αν όλα έχουν εξαφανιστεί μέσα σε περίπου 5 δευτερόλεπτα από το Εκκίνηση εφαρμογής, η εφαρμογή εμφανίζεται ως αποτυχημένη με τις τελευταίες γραμμές αρχείου καταγραφής. Μετά από αυτό, μια καθαρή έξοδος εμφανίζεται ως κλειστή και μια κατάρρευση δείχνει τις τελευταίες γραμμές αρχείου καταγραφής, και τίποτα από τα δύο δεν την επανεκκινεί. Μια επανεκκίνηση του διακομιστή κλείνει την εφαρμογή και δεν την ξανανοίγει ποτέ, και η διακοπή λόγω αδράνειας αφήνει ήσυχη μια εφαρμογή σε λειτουργία.

Δικαιώματα και όρια εφαρμογών επιφάνειας εργασίας

Ενότητα με τίτλο «Δικαιώματα και όρια εφαρμογών επιφάνειας εργασίας»
  • Στο macOS, δώστε μία φορά στο Control Center τα δικαιώματα Εγγραφή οθόνης και Προσβασιμότητα στις Ρυθμίσεις συστήματος. Ο κεντρικός υπολογιστής του διακομιστή χρειάζεται γραφική συνεδρία: ένας headless διακομιστής αρνείται να εκκινήσει εφαρμογή.
  • Εκκινήστε απευθείας το εκτελέσιμο. Το open -a παραδίδει την εφαρμογή στο LaunchServices και αυτή φεύγει από το δέντρο διεργασιών που παρακολουθεί το Control Center, άρα η εφαρμογή εμφανίζεται ως αποτυχημένη αμέσως μετά την εκκίνηση.
  • Τα παράθυρα μένουν σε οθόνη. Το macOS δεν καταγράφει παράθυρο τοποθετημένο έξω από όλες τις οθόνες, οπότε μια εφαρμογή που χρησιμοποιεί πράκτορας είναι ορατή στην οθόνη του διακομιστή. Δεν χρειάζεται εστίαση.
  • Το "isolate": "home" δίνει στην εφαρμογή ιδιωτικό αρχικό κατάλογο μέσω HOME, XDG_* και CFFIXED_USER_HOME, ώστε αντίγραφα από δύο χώρους να τρέχουν δίπλα δίπλα. Το NSUserDefaults δεν απομονώνεται, οπότε οι προτιμήσεις Cocoa και το shared_preferences του Flutter μένουν κοινά μεταξύ αντιγράφων.
  • Το isolate ισχύει μόνο για την εκκινούμενη διεργασία. Ένας εκκινητής εργαλειοθήκης όπως το flutter run χρειάζεται τον πραγματικό αρχικό κατάλογο, οπότε συνδυάστε το isolate με δομημένο εκτελέσιμο. Αν η εφαρμογή έχει δική της ρύθμιση, όπως --user-data-dir, προτιμήστε την.
  • Οι πράκτορες χειρίζονται το παράθυρο με το app_use, που φτάνει μόνο στο δέντρο διεργασιών αυτού του περιβάλλοντος. Ένας πράκτορας βλέπει το παράθυρο, όχι την επιφάνεια εργασίας. Οι εκκινήσεις από πράκτορες περνούν από την πολιτική ενεργειών και από προεπιλογή ρωτούν, και η είσοδος του πράκτορα σταματά όσο ένας άνθρωπος έχει τον έλεγχο.
  • Το "input": "background" (προεπιλογή) στέλνει συμβάντα στη διεργασία. Το "foreground" ενεργοποιεί το παράθυρο και παίρνει τον δρομέα.

Οι εργασίες provision και archive εκτελούν τη ρύθμιση και τον τερματισμό ενός αποθετηρίου μαζί με το worktree του. Το εικονίδιο στη γραμμή ενός αποθετηρίου στο Ρυθμίσεις → Χώρος εργασίας → Αποθετήρια ανοίγει τον ορισμό του αποθετηρίου.

Αυτές οι εργασίες ακολουθούν το worktree, όχι το περιβάλλον, οπότε εκτελούνται σε χώρους όπου κανείς δεν πατά Έναρξη:

provision archive
Εκτελείται Όταν δημιουργείται το worktree του ρόλου, σε οποιονδήποτε χώρο Ακριβώς πριν καταστραφεί αυτό το worktree
Σε αποτυχία Η προετοιμασία αποτυγχάνει και το worktree καταστρέφεται Καταγράφεται, δεν εμποδίζει ποτέ τη διαγραφή
Προεπιλεγμένο χρονικό όριο 5 λεπτά 2 λεπτά
Βλέπει CC_WORKSPACE_PATH, CC_ROOT_PATH, CC_SPACE_*, CC_REPO_NAME Τα ίδια

Ένα αποθετήριο χωρίς στοίβα χρειάζεται μόνο έναν ορισμό με τις εργασίες του. Αφού δεν υπάρχει κάτι να ξεκινήσει, δεν χρειάζεται ρόλο άγκυρα:

{
"contract": 1,
"name": "Web",
"repos": { "app": { "repoId": "<id>" } },
"components": [
{ "kind": "task", "id": "setup", "when": ["provision"],
"script": ["pnpm install", "cp \"$CC_ROOT_PATH/.env\" .env"] }
]
}
  • Δεν υπάρχει ακόμα περιβάλλον, οπότε αυτές οι εργασίες δεν μπορούν να χρησιμοποιήσουν {name}, {port.*}, {url.*}, {opt.*} ή enabledWhen, και δεν παίρνουν το env του ορισμού.
  • Μόνο ένας ορισμός μπορεί να έχει εργασίες provision και archive για ένα αποθετήριο. Οι άλλοι μπορούν να το δεσμεύουν για όλα τα υπόλοιπα.
  • Το "when": ["provision", "change"] επανεγκαθιστά και όταν αλλάζει ένα lockfile.
  • Μια εργασία εκτελείται για το worktree του ρόλου cwd της, οπότε ένας ορισμός πολλών αποθετηρίων μπορεί να ρυθμίσει το καθένα χωριστά.
  • Μια δοκιμαστική εκτέλεση ορίζει CC_SCRIPT_TEST=1. Μια νέα προσπάθεια ξεκινά από καθαρό worktree, οπότε γράψτε εργασίες που αντέχουν επανεκτέλεση.

Οι πράκτορες δεν παίρνουν ποτέ την υποδοχή Docker. Σε χώρο με κατάλληλο ορισμό, μια εκτέλεση παίρνει το cc-env στο PATH της. Ο χώρος προκύπτει από την εκτέλεση, οπότε ένας πράκτορας μπορεί να ενεργεί μόνο στο δικό του περιβάλλον, και κάθε εντολή περνά από την πολιτική ενεργειών.

Παράθυρο τερματικού
cc-env status
cc-env up
cc-env down
cc-env reset
cc-env destroy
cc-env restart <process>
cc-env logs <name>
cc-env exec <service> -- <cmd>
cc-env run <task> -- <args>

Με στοιχείο compose, ένα shim docker επιτρέπει επίσης docker compose με ps, logs, exec, port, restart και top, και μόνο έναντι του δικού αυτού του περιβάλλοντος compose project. Δεν επιτρέπονται σημαίες πριν από το ρήμα, και κάθε ρήμα δέχεται μια σύντομη λίστα επιλογών: το logs δεν μπορεί να ακολουθεί, και το exec δέχεται μόνο -T (ή --no-tty). Οι επιλογές που στρέφουν το compose σε άλλο αρχείο ή project (-f, -p, --project-directory, --env-file, --profile) απορρίπτονται όπου κι αν εμφανιστούν. Οτιδήποτε άλλο τερματίζει με κωδικό 5 και «not available in Control Center agent runs».

Ένα αποθετήριο του οποίου οι δεξιότητες καλούν το δικό του εργαλείο μπορεί να συνεχίσει έτσι. Ένα μπλοκ agentPassthrough σε στοιχείο cli δηλώνει ποιες εντολές μπορούν να εκτελούν οι πράκτορες. Περνούν μόνο οι εντολές που δηλώνει ο εγκεκριμένος ορισμός, και καθεμία τρέχει στον κεντρικό υπολογιστή, οπότε υπόκειται στον κανόνα Εκτέλεση εντολών στον κεντρικό υπολογιστή, που ζητά πρώτα επιβεβαίωση από προεπιλογή:

"agentPassthrough": {
"binary": "acme",
"allow": [
{ "argv": ["env", "ls"], "maps": "status", "nameFilter": true },
{ "argv": ["env", "status|url"], "maps": "status", "positionalName": 2 },
{ "argv": ["env", "create"], "maps": "up", "positionalName": 2,
"pathFlags": ["--web-dir"], "denyFlags": ["--force"] },
{ "argv": ["env", "logs"], "maps": "logs", "positionalName": 2,
"denyFlags": ["--follow"] }
]
}

Το maps ονομάζει τη λειτουργία της οποίας η πολιτική ισχύει. Το positionalName επιβάλλει σε εκείνο το όρισμα το περιβάλλον αυτού του χώρου, το nameFilter φιλτράρει την έξοδο JSON σε αυτό και κάθε τιμή pathFlags πρέπει να καταλήγει μέσα στα worktree της εκτέλεσης. Μια εντολή που δεν ταιριάζει με κανόνα τερματίζει με κωδικό 5.

Οι ίδιες λειτουργίες υπάρχουν ως εργαλεία: environment_status, environment_up, environment_down, environment_reset, environment_destroy, environment_restart, environment_exec, environment_logs, environment_run_task, environment_launch_app και environment_stop_app. Οι πράκτορες σε sandbox φτάνουν απευθείας στις θύρες τους και στα ονόματα του περιβάλλοντός τους μέσω του διαμεσολαβητή της εκτέλεσης, οπότε ζητήστε τους να διαβάζουν τα τελικά σημεία από το environment_status αντί να μαντεύουν URL.

Ο κώδικας ενός PR από fork δεν είναι αξιόπιστος και στην τοποθέτηση στον κεντρικό υπολογιστή εκτελείται ως χρήστης συστήματος του διακομιστή. Το policy.forkPrs αποφασίζει τι συμβαίνει:

Τιμή Αποτέλεσμα Προεπιλογή για
rig Το αρχείο compose εκτελείται σε VM χωρίς ερώτηση Ορισμούς μόνο με στοιχεία compose και task
approval Κάθε εκκίνηση απαιτεί διαχειριστή Όλους τους άλλους ορισμούς
deny Απορρίπτεται Κανέναν
  • Τα seedFiles δεν αντιγράφονται ποτέ για fork, επειδή συνήθως είναι μυστικά. Ένα αρχείο compose που δεσμεύει κάποιο αναφέρει το αρχείο που λείπει με το όνομά του.
  • Οι εργασίες provision και archive παραλείπονται, εκτός αν η πολιτική είναι rig, οπότε εκτελούνται στη VM.
  • Στην τοποθέτηση στον κεντρικό υπολογιστή, τα privileged, οι χώροι ονομάτων του κεντρικού υπολογιστή, μια δέσμευση της υποδοχής Docker, τα devices και οι δεσμεύσεις εκτός των worktree του χώρου απορρίπτονται σε fork. Σε αξιόπιστους χώρους δίνουν μόνο προειδοποίηση.

Το "placement": "rig" εκτελεί στοιχεία compose και task σε αποκλειστική microVM. Οι ορισμοί με στοιχεία process, cli ή app δεν είναι κατάλληλοι. Το αρχείο compose εκτελείται αμετάβλητο, χωρίς την υποδοχή Docker του κεντρικού υπολογιστή και χωρίς διαπιστευτήρια χειριστή, και η πρόσβαση δικτύου περιορίζεται στα μητρώα που χρειάζονται οι εικόνες του. Το worktree προσαρτάται ζωντανά.

  • Επισκέπτες arm64. Οι επισκέπτες είναι arm64 σε Apple Silicon, οπότε οι εικόνες μόνο για amd64 δεν εκτελούνται.
  • Τα ιδιωτικά μητρώα απορρίπτονται. Οι επισκέπτες δεν έχουν διαπιστευτήρια μητρώων, οπότε μια εικόνα σε μητρώο εκτός των γνωστών δημόσιων απορρίπτεται πριν ξεκινήσει η VM. Ένα ιδιωτικό αποθετήριο σε δημόσιο μητρώο αποτυγχάνει όταν το τραβήξει ο επισκέπτης.
  • Αποθήκευση 16 GiB. Όλες οι εικόνες και οι τόμοι της στοίβας μοιράζονται έναν δίσκο 16 GiB, που δεν μπορεί να αυξηθεί.
  • Η πρώτη εκκίνηση είναι αργή. Τα επίπεδα εικόνων είναι ανά VM, οπότε η πρώτη εκκίνηση τα τραβά όλα. Ένα σταματημένο rig κρατά τον δίσκο του.
  • Οι βασικές εικόνες πρέπει να διαβάζονται. Ένα Dockerfile που ονομάζει τη βασική εικόνα μέσω μεταβλητής δεν μπορεί να προγραμματιστεί, επειδή η πρόσβαση δικτύου ορίζεται κατά την εκκίνηση.
  • Διάρκεια ζωής. Το policy.rigTtlHours τερματίζει τη VM, από προεπιλογή μετά από 24 ώρες.

Συμβόλαιο κατάστασης για δημιουργούς εργαλείων

Ενότητα με τίτλο «Συμβόλαιο κατάστασης για δημιουργούς εργαλείων»

Ένα στοιχείο cli χωρίς statusMap περιμένει το εγγενές συμβόλαιο, cc-env/1. Το ρήμα status εκτυπώνει αυτό το αντικείμενο στο stdout:

{
"state": "ready",
"detail": "migrations applied, HTTP 200",
"endpoints": [
{ "role": "app", "label": "App", "url": "https://fix-login.acme.test", "primary": true },
{ "role": "postgres", "label": "Postgres", "hostPort": 49213 }
],
"services": ["server", "postgres"],
"needsRecreate": false,
"error": { "code": "post-start-failed", "message": "…", "hint": "…", "command": "…" }
}
  • Το state είναι ready, starting, stopped, failed ή missing. Το missing οδηγεί σε create, τα stopped και failed οδηγούν σε start. Αναφέρετε missing με κωδικό εξόδου 0: ένα αποτυχημένο status μετρά ως failed.
  • Χρειάζεται μόνο το state. Τα άγνωστα πεδία αγνοούνται και η έξοδος που δεν αναλύεται εμφανίζεται ως υποβαθμισμένη, με το ακατέργαστο κείμενο ως λεπτομέρεια.
  • Ένα URL πρέπει να είναι loopback, *.localhost ή κάτω από το routing.domain, αλλιώς απορρίπτεται.
  • Το needsRecreate: true εμφανίζει το Εκ νέου δημιουργία, που απορρίπτει δεδομένα. Το Control Center δεν ενεργεί ποτέ μόνο του βάσει αυτού.
  • Το ρήμα list εκτυπώνει πίνακα JSON με ονόματα ή αντικείμενα με name.

Οι κωδικοί εξόδου ισχύουν για κάθε ρήμα:

Κωδικός Σημασία
0 OK
3 Απαιτείται απάντηση σε τερματικό, για παράδειγμα ο κωδικός sudo. Ένα ρήμα που αναφέρεται στο interactive εκτελείται ξανά σε καρτέλα τερματικού για το άτομο που πάτησε Έναρξη. Αλλιώς Το Εκτέλεση στο τερματικό ανοίγει τερματικό χώρου με την command του εργαλείου πληκτρολογημένη αλλά χωρίς εκτέλεση και έπειτα το Επανάληψη δοκιμάζει ξανά. Το Control Center δεν εκτελεί ποτέ sudo και δεν απαντά ποτέ σε προτροπή
4 Απαιτείται σύνδεση. Η command του εργαλείου δείχνει πώς
5 Δεν είναι διαθέσιμο κάτι από το οποίο εξαρτάται, για παράδειγμα ένα περιβάλλον εκτέλεσης κοντέινερ που δεν τρέχει
Άλλος Αποτυχία

Οι κωδικοί 3, 4 και 5 δεν είναι αποτυχίες. Το περιβάλλον δείχνει Απαιτείται ενέργεια και περιμένει, και η επόμενη έναρξη συνεχίζει από εκεί που σταμάτησε εκείνη. Μια εργασία που τερματίζει με έναν από αυτούς σημαίνει το ίδιο.

Η πρόοδος πηγαίνει στο stderr ως JSON οριοθετημένο με αλλαγές γραμμής:

{"type":"step","id":"images","label":"Pull images","state":"running"}
{"type":"log","stream":"stdout","line":"postgres Pulled"}
{"type":"step","id":"images","label":"Pulled 4 images","state":"done"}
{"type":"note","level":"warn","message":"Hosts entries stayed behind after destroy"}
{"type":"error","code":"hosts-missing","message":"Add the hosts entry","hint":"Needs sudo","command":"sudo acme hosts add fix-login"}

Όσο ένα περιβάλλον ξεκινά, το πάνελ εμφανίζει τα στοιχεία από τα οποία περνά η εκκίνηση, το καθένα με περιστρεφόμενο δείκτη, σημάδι ή σταυρό. Μια γραμμή step λέει τι κάνει τώρα το εργαλείο, και το label της εμφανίζεται κάτω από τη δική της γραμμή του εργαλείου· τα βήματα δεν προσθέτουν ποτέ γραμμές. Το πεδίο state ενός βήματος είναι pending, running, done ή failed, και ένα βήμα χωρίς state εκτελείται. Ένα βήμα που αναφέρει ξανά με το ίδιο id (συμβολοσειρά ή αριθμός, ή το ίδιο label αν δεν έχει), αντικαθιστά όσα είχε πει πριν, οπότε ένα εργαλείο με έναν δείκτη μπορεί να κρατά ένα id και να αλλάζει το label. Χωρίς id, τα βήματα ακολουθούν το ένα το άλλο: ένα νέο τερματίζει το προηγούμενο. Όταν τερματίζει η εντολή, ένα βήμα που εξακολουθεί να εκτελείται τερματίζει όπως τερματίστηκε η εντολή.

Μια γραμμή log περιέχει μία γραμμή εξόδου που τύλιξε το εργαλείο σε JSON και διαβάζεται ως απλή έξοδος. Μια γραμμή note πηγαίνει στην έξοδο της εκτέλεσης, και μία με "level": "warn" μένει επίσης στο περιβάλλον ως προειδοποίηση. Μια τελευταία γραμμή τύπου error γίνεται δομημένο σφάλμα, με το command διαθέσιμο για αντιγραφή, και οι τελευταίες 12 γραμμές της εξόδου εμφανίζονται κάτω από το message. Χωρίς αυτή, το Control Center δείχνει τις τελευταίες 20 γραμμές του stderr. Ό,τι δεν είναι JSON είναι απλή έξοδος καταγραφής.