Brama
Czym jest brama?
Brama to serce Neotask -- pojedyncza długo działająca usługa, która zarządza wszystkimi sesjami agentów, kanałami komunikacyjnymi, wykonywaniem narzędzi i połączeniami urządzeń. Wszystko przepływa przez bramę.
To serwer WebSocket, który nasłuchuje połączeń od klientów (aplikacja desktopowa, aplikacje mobilne, panel internetowy) i zarządza całym cyklem życia asystenta AI.
Architektura
Komponenty
- Serwer WebSocket -- Akceptuje połączenia klientów (domyślny port 18789)
- Serwer HTTP -- Obsługuje interfejs sterowania, hosta kanwy i punkty końcowe stanu
- Adaptery kanałów -- Utrzymują połączenia z platformami komunikacyjnymi (WhatsApp, Telegram, Discord itp.)
- Menedżer sesji -- Utrzymuje i zarządza stanem rozmów agentów
- Harmonogram Cron -- Uruchamia zaplanowane zadania i przebudzenia heartbeat
- Środowisko uruchomieniowe wtyczek -- Ładuje i zarządza cyklem życia wtyczek
- Usługa przeglądarki -- Steruje instancjami Chromium do automatyzacji sieci
Tryby powiązania
| Tryb | Opis |
|---|---|
| Pętla zwrotna | Domyślny. Dostępny tylko z localhost (127.0.0.1) |
| LAN | Dostępny w lokalnej sieci. Automatycznie wykrywalny przez Bonjour/mDNS |
| Tailnet | Dostępny przez VPN Tailscale z MagicDNS |
| Niestandardowy | Powiąż z określonym adresem |
Uwierzytelnianie
| Metoda | Opis |
|---|---|
| Token | Bearer token WebSocket (UUID lub niestandardowy ciąg) |
| Hasło | Uwierzytelnianie oparte na haśle (haszowane bcrypt) |
| Zaufany proxy | Dla odwrotnych proxy z wstępnie uwierzytelnionym nagłówkiem |
| Lokalne zaufanie | Połączenia z pętlą zwrotną automatycznie zatwierdzone |
Konfiguracja
Brama jest konfigurowana przez neotask.json (format JSON5). Kluczowe sekcje:
| Sekcja | Kontroluje |
|---|---|
agents |
Lista agentów, wartości domyślne, przestrzenie robocze |
gateway |
Port, tryb powiązania, uwierzytelnianie, zachowanie przeładowania |
channels |
Konfiguracja per kanał i dane uwierzytelniające |
tools |
Uprawnienia narzędzi, profile, bezpieczeństwo |
plugins |
Ładowanie wtyczek, włączanie, konfiguracja per wtyczka |
models |
Uwierzytelnianie dostawcy, mechanizmy awaryjne, ustawienia dostawcy |
skills |
Katalogi umiejętności, konfiguracja per umiejętność |
browser |
Profile przeglądarki, porty, tryb bezgłowy |
cron |
Konfiguracja harmonogramu |
session |
Reguły resetowania, progi kompakcji |
messages |
Ustawienia TTS, zasady mediów |
memory |
Konfiguracja indeksowania pamięci |
security |
Sandboxing, tryb podwyższony, zatwierdzenia |
Gorące przeładowanie
Zmiany konfiguracji można stosować bez ponownego uruchamiania:
| Tryb | Zachowanie |
|---|---|
| Hybrydowy (domyślny) | Zastosuj bezpieczne zmiany na gorąco, uruchom ponownie dla pozostałych |
| Gorący | Zastosuj tylko zmiany bezpieczne na gorąco, ignoruj pozostałe |
| Restart | Uruchom ponownie przy każdej zmianie wymagającej przeładowania |
| Wył. | Brak automatycznego przeładowania |
Zdalny dostęp
Tailscale (zalecany)
Tailscale zapewnia bezpieczny, bezproblemowy zdalny dostęp:
- Powiąż bramę z Twoją siecią Tailnet
- Uzyskuj dostęp z dowolnego urządzenia w tej samej sieci Tailscale
- Automatyczny DNS przez MagicDNS
- Tailscale Serve może udostępniać panel sterowania z HTTPS
Tunel SSH
Przekaż port bramy przez SSH:
- Prosty, bezpieczny, bez zmian konfiguracji
- Działa z dowolną maszyną z obsługą SSH
- Obsługuje pełny protokół WebSocket i interfejs sterowania
Zasady bezpieczeństwa
- Pętla zwrotna + SSH/Tailscale to najbezpieczniejsza kombinacja
- Powiązanie inne niż pętla zwrotna wymaga konfiguracji tokenu uwierzytelniającego
- Dostępne przypinanie odcisku TLS dla dodatkowego bezpieczeństwa
- Sterowanie przeglądarką jest domyślnie wyłączone dla połączeń zdalnych
Monitorowanie stanu
Punkt końcowy stanu
Punkt końcowy HTTP /health zwraca:
- Status bramy
- Liveness RPC
- Stan kanału per (połączony, status uwierzytelniania, liczba kont)
- Gotowość przeglądarki
- Aktywni agenci i podłączone węzły
- Czas działania
Sondy
- Liveness RPC -- Połączenie WebSocket + test echo
- Stan kanału -- Sprawdzenie uwierzytelniania + ping API per kanał
- Gotowość przeglądarki -- Sprawdzenie portu, sprawdzenie procesu
- Łączność węzła -- Znacznik czasu ostatniego heartbeat
Odkrywanie
Bonjour/mDNS
Gdy jest powiązana z LAN, brama reklamuje się przez wielodostępny DNS:
- Typ usługi:
_neotask-gw._tcp - Zawiera port, transport, status TLS i informacje DNS Tailscale
- Aplikacje towarzyszące automatycznie odkrywają bramę
Odkrywanie w szerokim obszarze
Odkrywaj bramy w całej sieci z konfigurowalnymi limitami czasu. Obsługuje zarówno lokalne Bonjour, jak i odkrywanie DNS Tailscale.
Wiele bram
Możesz uruchamiać wiele instancji bramy na tej samej maszynie używając profili:
- Każdy profil ma oddzielną konfigurację, przestrzeń roboczą, sesje i stan
- Różne porty dla każdej bramy
- Przydatne do izolacji (osobistej vs służbowej) lub testowania
Diagnostyka
Doctor
Wbudowane narzędzie diagnostyczne sprawdza:
- Poprawność konfiguracji
- Uprawnienia plików
- Łączność kanałów
- Status uwierzytelniania modelu
- Kompatybilność wersji Node.js
- Typowe błędne konfiguracje
Może automatycznie naprawić wiele problemów po udzieleniu pozwolenia.
Logowanie
Logi bramy są zapisywane do dziennych plików JSONL:
- Śledzenie użycia tokenów per uzupełnienie
- Logi zdarzeń kanałów
- Logowanie błędów ze strukturyzowanym kontekstem
- Konfigurowalne poziomy logowania