Instalare
Cum rulezi tot stack-ul pe un laptop. Dacă vrei doar să apelezi API-ul unei instalări existente, nu ai nevoie de nimic de aici — treci la Pornire rapidă.
Cerințe
| Versiune | De ce | |
|---|---|---|
| PHP | 8.3 sau mai nou; se dezvoltă pe 8.4 | Control plane-ul e Laravel 13. |
| Node | 22 sau mai nou; se dezvoltă pe 24 | Gateway-ul, SDK-ul și CLI-ul sunt doar ESM. |
| pnpm | 11 | Managerul de pachete al workspace-ului. |
| Docker | orice versiune recentă | Postgres 17 + pgvector, Redis, NATS JetStream, MinIO, FreeSWITCH și stack-ul de observabilitate. |
CallAgent se dezvoltă pe Laravel Herd pentru PHP și pe Docker pentru serviciile de suport.
Stack-ul
git clone <repo> callagent
cd callagent
pnpm install
pnpm infra:up # docker compose up -d
cp apps/control-plane/.env.example apps/control-plane/.env
php apps/control-plane/artisan key:generate
php apps/control-plane/artisan callagent:generate-credential-key
php apps/control-plane/artisan migrate --seedpnpm infra:up pornește Postgres, Redis, NATS, MinIO, FreeSWITCH și stack-ul Prometheus / Loki / Tempo / Grafana. Peer-ul SIP de test și SIPp stau în spatele unui profil de compose numit sip-lab și nu pornesc implicit:
docker compose --profile sip-lab up -dPorturile sunt mutate intenționat
Postgres e pe 5433, Redis pe 6380, MinIO pe 9002/9003, ESL-ul FreeSWITCH pe 8022. Sunt mutate de pe porturile standard ca să nu umbrească un Postgres sau un Redis pe care îl rulezi deja local. .env.example arată deja spre porturile mutate; dacă schimbi unul în docker-compose.yml, schimbă-l și în .env.
callagent:generate-credential-key nu e opțional. Credențialele de furnizor ale tenanților se criptează cu o cheie ținută intenționat separat de APP_KEY, ca rotirea cheii aplicației să nu însemne recriptarea secretelor fiecărui tenant. Fără ea, salvarea unei credențiale eșuează.
Verifică înainte să mergi mai departe
php apps/control-plane/artisan callagent:check+-----------------------+--------+----------------------------------+
| Component | Status | Detail |
+-----------------------+--------+----------------------------------+
| PostgreSQL | OK | v17.11 |
| pgvector | OK | v0.8.6 |
| Redis | OK | reachable |
| Object storage | OK | read/write ok |
| Credential encryption | OK | key valid, round-trip ok |
| Voice Gateway | OK | healthy |
| NATS | OK | healthy |
| FreeSWITCH ESL | OK | port open |
+-----------------------+--------+----------------------------------+E cel mai rapid mod de a găsi un port greșit sau o cheie lipsă. Repară fiecare rând înainte să urmezi pornirea rapidă.
php artisan callagent:doctor e următorul la care apelezi: diagnostichează erorile de încărcare a claselor care împiedică aplicația să pornească.
doctor poate fi omorât chiar de eroarea pe care ar trebui să o raporteze
Încarcă clasele aplicației ca să o găsească pe cea stricată, deci o eroare fatală de încărcare îl doboară cu tot cu ea și primești eroarea PHP brută în loc de un raport. Tot ăla e răspunsul — citește eroarea fatală, îți spune fișierul și linia. callagent:check nu încarcă dashboard-ul și continuă să funcționeze când doctor nu.
Rulează-l
Trei procese, trei terminale:
pnpm cp:serve # control plane pe :8000
pnpm --filter @callagent/voice-gateway dev # voice gateway pe :3010
php apps/control-plane/artisan horizon # job-uri: webhooks, artefacte, retențieWorker-ul de cozi contează mai mult decât pare. Livrarea de webhooks, relocarea artefactelor, retenția și transcrierea de după apel sunt toate puse pe coadă în Redis. Fără un worker nu se întâmplă niciodată, și nimic din API nu îți spune asta. php artisan queue:work face aceeași treabă dacă preferi să nu rulezi Horizon.
Health:
curl http://localhost:8000/api/health
curl http://localhost:3010/health # listează și fiecare adaptor de furnizor înregistratRăspunsul de health al gateway-ului e răspunsul autoritar la întrebarea „cu ce furnizori știe build-ul ăsta să vorbească".
migrate:fresh nu e sigur într-un checkout partajat
migrate:fresh, migrate:rollback și db:wipe șterg date pe care altcineva le poate folosi chiar acum. php artisan migrate simplu e idempotent.
Munca programată
Câteva lucruri se întâmplă doar pe bază de schedule. În dezvoltare, rulează scheduler-ul:
php apps/control-plane/artisan schedule:workEl conduce retenția (zilnic la 03:15), rollup-urile de analytics, reintroducerea în coadă a webhook-urilor de reîncercat, tick-ul cozilor din contact center, evaluarea monitoarelor, sondarea SIP OPTIONS și dispecerizarea campaniilor. O coadă care nu oferă niciodată un apel unui operator e de obicei asta.
Pachete
pnpm build # tot
pnpm --filter @callagent/web-sdk build # SDK-ul de browser + bundle-urile de widget
pnpm --filter @callagent/cli build # binarul `callagent`
pnpm --filter @callagent/docs-site build # site-ul ăstaCLI-ul
Nu e publicat pe npm
@callagent/cli și @callagent/web-sdk sunt pachete de workspace cu private: true. Nu există npm i -g @callagent/cli și nu există un bundle public pe CDN. Construiește-le din workspace:
pnpm --filter @callagent/cli build
node apps/cli/dist/index.js --versionFă-i link dacă vrei comanda simplă callagent:
cd apps/cli && npm linkApoi:
callagent login # cere cheia, fără ecou pe ecran
callagent whoamiVezi referința CLI pentru fiecare comandă și flag.
SDK-ul de browser
Aceeași observație — construiește-l din workspace și servește tu bundle-ul:
pnpm --filter @callagent/web-sdk build
# dist/index.js și dist/widget.js<script src="/calea-ta/widget.js"
data-public-key="ca_pk_…"
data-assistant-id="01JQ…"></script>Prefixul cheii publice e ca_pk_. Vezi referința widget-ului.
Teste
pnpm test # fiecare pachet din workspace
pnpm cp:test # suita Pest a control plane-ului
pnpm --filter @callagent/voice-gateway testMai departe
- Pornire rapidă — un asistent publicat, cu un număr pe el.
- Ce nu este construit — citește înainte să îți faci planuri în jurul unei funcționalități.