Modo Servidor (chatcli server)

​

Início rápido

export ANTHROPIC_API_KEY=sk-ant-xxx
chatcli server --provider CLAUDEAI

🚀 ChatCLI server listening on 127.0.0.1:50051
📊 Prometheus metrics on :9090/metrics

CHATCLI_ALLOW_INSECURE=true chatcli connect localhost:50051

export CHATCLI_SERVER_TOKEN="$(openssl rand -hex 32)"
CHATCLI_BIND_ADDRESS=0.0.0.0 chatcli server --provider CLAUDEAI \
  --tls-cert server.crt --tls-key server.key

chatcli connect chatcli.example.com:50051 --tls --ca-cert ca.crt --token "$CHATCLI_SERVER_TOKEN"

​

Endereço de bind e a regra da credencial

refusing to serve an unauthenticated API on 0.0.0.0: every caller that can reach it would be admitted as an administrator. Set CHATCLI_SERVER_TOKEN (or --token) for a shared token, CHATCLI_JWT_SECRET for HS256 JWTs, CHATCLI_JWT_PUBLIC_KEY for RS256 JWTs, or CHATCLI_SERVER_TLS_CLIENT_CA (--tls-client-ca) for mTLS. To run without authentication, bind loopback instead (CHATCLI_BIND_ADDRESS=127.0.0.1)

​

Flags

​

Variáveis de ambiente

​

Autenticação do servidor

export CHATCLI_SERVER_TOKEN="$(openssl rand -hex 32)"
chatcli server

# HS256: um segredo compartilhado assina e verifica
export CHATCLI_JWT_SECRET="$(openssl rand -hex 32)"

# ou RS256: o servidor guarda só a chave pública
# export CHATCLI_JWT_PUBLIC_KEY=/etc/chatcli/jwt-public.pem

export CHATCLI_JWT_ISSUER=chatcli          # opcional
export CHATCLI_JWT_AUDIENCE=chatcli-api    # opcional
chatcli server

b64url() { openssl base64 -A | tr '+/' '-_' | tr -d '='; }
HEADER=$(printf '{"alg":"HS256","typ":"JWT"}' | b64url)
PAYLOAD=$(printf '{"sub":"alice@example.com","role":"user","iss":"chatcli","aud":"chatcli-api","exp":%d}' \
  $(( $(date +%s) + 3600 )) | b64url)
SIG=$(printf '%s.%s' "$HEADER" "$PAYLOAD" \
  | openssl dgst -sha256 -hmac "$CHATCLI_JWT_SECRET" -binary | b64url)
JWT="$HEADER.$PAYLOAD.$SIG"

CHATCLI_ALLOW_INSECURE=true chatcli connect localhost:50051 --token "$JWT"

claims := jwt.MapClaims{
    "sub":  "alice@example.com",
    "role": "user",
    "iss":  "chatcli",
    "aud":  "chatcli-api",
    "exp":  time.Now().Add(time.Hour).Unix(),
}
signed, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).
    SignedString([]byte(os.Getenv("CHATCLI_JWT_SECRET")))

chatcli server --tls-cert server.crt --tls-key server.key --tls-client-ca clients-ca.crt

CHATCLI_TLS_CLIENT_CERT=alice.crt CHATCLI_TLS_CLIENT_KEY=alice.key \
  chatcli connect chatcli.example.com:50051 --tls --ca-cert ca.crt

​

Roles

​

Limitador de falhas de autenticação

​

TLS

openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
  -keyout ca.key -out ca.crt -subj "/CN=chatcli-ca"
openssl req -newkey rsa:2048 -nodes \
  -keyout server.key -out server.csr -subj "/CN=chatcli.example.com"
printf "subjectAltName=DNS:chatcli.example.com,DNS:localhost,IP:127.0.0.1\n" > server.ext
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -days 365 -extfile server.ext -out server.crt

# Opcional: certificado de cliente para mTLS
openssl req -newkey rsa:2048 -nodes -keyout alice.key -out alice.csr -subj "/CN=alice"
printf "extendedKeyUsage=clientAuth\n" > client.ext
openssl x509 -req -in alice.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -days 365 -extfile client.ext -out alice.crt

​

Credenciais do LLM

​

Roteamento de requisições

• Uma requisição que encaminha credencial (--llm-key, --use-local-auth, campos da StackSpot, URL do Ollama) ou que nomeia provedor ou modelo ganha um cliente dedicado só para ela.
• Uma requisição que não nomeia nada nem encaminha nada passa pela cadeia de fallback quando há uma instalada; senão, usa o provedor e o modelo padrão do servidor.
• max_tokens é o valor da requisição quando definido; senão o override *_MAX_TOKENS do provedor (ANTHROPIC_MAX_TOKENS, OPENAI_MAX_TOKENS, BEDROCK_MAX_TOKENS, …); senão o teto do catálogo para o modelo.
• Um 401/403 do provedor nas credenciais do servidor reconstrói os provedores uma vez e tenta de novo; as reconstruções são limitadas a uma a cada 30 segundos no processo inteiro. Credenciais encaminhadas pelo chamador nunca são renovadas.
• Uma resposta interrompida por classificador de segurança (stop_reason: refusal) é reenviada uma vez para o modelo irmão do mesmo provedor; em stream, só enquanto nenhum texto foi enviado.

​

Cadeia de fallback

export ANTHROPIC_API_KEY=sk-ant-xxx OPENAI_API_KEY=sk-xxx GOOGLEAI_API_KEY=xxx
export CHATCLI_FALLBACK_MODEL_OPENAI=gpt-6-sol
chatcli server --provider CLAUDEAI --fallback-providers CLAUDEAI,OPENAI,GOOGLEAI

• A cadeia é montada só a partir de --fallback-providers / CHATCLI_FALLBACK_PROVIDERS, nessa ordem. O servidor não acrescenta o --provider: coloque você mesmo o primário na frente. O Helm chart e o spec.fallback do operator já colocam o primário na frente para você.
• Cada entrada usa CHATCLI_FALLBACK_MODEL_<PROVEDOR> quando definido. Sem ela, o provedor primário (--provider) fica com o modelo do servidor (--model), e qualquer outro provedor roda o próprio modelo padrão: a variável de modelo dele (por exemplo OPENAI_MODEL), depois o padrão embutido. Um provedor de fallback nunca recebe o id de modelo do primário.
• Um provedor cujo cliente não pode ser criado (sem chave) é pulado com um aviso. A cadeia só é instalada com pelo menos duas entradas restantes; aí o log mostra Fallback chain initialized.
• Ela atende só requisições que não trazem credenciais nem nomeiam provedor ou modelo. A resposta informa o provedor e o modelo que de fato responderam.
• Um CHATCLI_FALLBACK_PROVIDERS não vazio é o único interruptor. CHATCLI_FALLBACK_ENABLED não é lida pelo servidor, e nem o Helm chart nem o operator a definem; o /config a marca como não lida quando ela está definida.

​

API gRPC

​

Streaming

​

Atribuição da resposta e uso de tokens

message TokenUsage {
  int32 prompt_tokens = 1;
  int32 completion_tokens = 2;
  int32 cache_read_tokens = 3;
  int32 cache_write_tokens = 4;
  int32 reasoning_tokens = 5;
  bool estimated = 6;   // provedor não devolveu usage; contagem derivada do tamanho
  double cost_usd = 7;  // precificado com as mesmas tabelas do /cost
  bool cost_known = 8;  // false quando o modelo não tem preço publicado
}

​

RPCs de pipeline

CHATCLI_SERVER_PIPELINE=true LLM_PROVIDER=CLAUDEAI chatcli server --token "$CHATCLI_SERVER_TOKEN"

• O motor lê o provedor e o modelo padrão de LLM_PROVIDER / LLM_MODEL, não de --provider / --model.
• As sessões ficam no namespace do principal autenticado (<subject>/<sessão>), então dois chamadores nunca dividem uma conversa por escolherem o mesmo id.
• Sem CHATCLI_SERVER_PIPELINE=true os RPCs devolvem Unavailable: the pipeline RPCs are not enabled on this server (start it with CHATCLI_SERVER_PIPELINE=true).
• GetServerInfo.pipeline_enabled informa se eles estão ativos.

​

RPCs de AIOps

message WatcherAlert {
  string type = 1;            // HighRestartCount, OOMKilled, PodNotReady, DeploymentFailing, JobFailed, CronJobMissed, NodeNotReady, ...
  string severity = 2;        // INFO, WARNING, CRITICAL
  string message = 3;
  string object = 4;          // nome do pod, ou Kind/nome
  string namespace = 5;
  string deployment = 6;
  int64 timestamp_unix = 7;
}

message GetAlertsRequest {
  string namespace = 1;       // filtro opcional
  string deployment = 2;      // filtro opcional
}
message GetAlertsResponse { repeated WatcherAlert alerts = 1; }

​

StreamAlerts

rpc StreamAlerts(StreamAlertsRequest) returns (stream StreamAlertsResponse);

message StreamAlertsRequest {
  string namespace = 1;       // filtro opcional
  string deployment = 2;      // filtro opcional
  bool include_current = 3;   // abre com os alertas ativos agora
}
message StreamAlertsResponse {
  WatcherAlert alert = 1;     // vazio num heartbeat
  bool heartbeat = 2;         // a cada 15s enquanto o watcher está quieto
}

• Com include_current o stream começa com o que o GetAlerts devolveria e depois só chegam alertas novos. O watcher deduplica por tipo e objeto dentro da janela, então cada alerta é enviado uma vez.
• Heartbeats a cada 15 segundos distinguem um watcher quieto de uma conexão morta. Sem watcher, o stream só traz heartbeats.
• Um assinante que estoura o buffer limitado é derrubado com ABORTED; reabra com include_current para ressincronizar.

​

AnalyzeIssue

message AnalyzeIssueRequest {
  string issue_name = 1;
  string namespace = 2;
  string resource_kind = 3;
  string resource_name = 4;
  string signal_type = 5;              // error_rate, oom_kill, pod_restart, ...
  string severity = 6;                 // low, medium, high, critical
  string description = 7;
  int32 risk_score = 8;
  string provider = 9;                 // override opcional
  string model = 10;                   // override opcional
  string kubernetes_context = 11;      // status do deployment, pods, eventos, revisões
  string previous_failure_context = 12; // tentativas de remediação anteriores que falharam
}

message AnalyzeIssueResponse {
  string analysis = 1;
  float confidence = 2;                // 0.0 a 1.0
  repeated string recommendations = 3;
  string model = 4;
  string provider = 5;
  repeated SuggestedAction suggested_actions = 6;
  TokenUsage usage = 7;
}

​

Descoberta de recursos

​

Health checks

grpc-health-probe -addr=localhost:50051                                  # texto puro
grpc-health-probe -addr=chatcli.example.com:50051 -tls -tls-ca-cert ca.crt  # TLS
curl -s http://localhost:9090/healthz

​

Métricas

​

Exportação OpenTelemetry (OTLP)

export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20token"
export OTEL_SERVICE_NAME="chatcli"          # padrão
export OTEL_METRIC_EXPORT_INTERVAL=60000    # ms, padrão

​

Limites e keepalive

​

Proteção contra SSRF

• só https://; http:// exige CHATCLI_ALLOW_HTTP_PROVIDERS=true no servidor;
• o host (ou cada endereço para o qual ele resolve) não pode estar em 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16, 100.64.0.0/10, ::1, fc00::/7, fe80::/10, ff00::/8 ou faixas IPv4 mapeadas; não há override para endereços privados;
• hostnames de metadata de nuvem (metadata.google.internal, metadata.goog, instance-data) são recusados.

​

Log de auditoria

export CHATCLI_AUDIT_LOG_PATH=/var/log/chatcli/audit.jsonl   # precisa ser absoluto

​

Logs

• Toda entrada vai para o arquivo rotativo LOG_FILE (padrão ~/.chatcli/app.log; CHATCLI_LOG_FILE é um alias).
• chatcli server e chatcli gateway também escrevem as mesmas entradas como linhas JSON no stderr sempre que o stderr não é um terminal — container, unit do systemd, pipe — então docker logs, kubectl logs e coletores de log recebem as recusas de inicialização e tudo o que vem depois sem configuração extra. Num terminal interativo o arquivo é o único destino. CHATCLI_LOG_STDERR=true|false força de um jeito ou de outro. O stdout fica livre para os transportes stdio.
• CHATCLI_ENV=dev troca para o console de desenvolvimento (colorido, no stdout) mais o arquivo; as linhas JSON no stderr não são duplicadas nesse caso.
• LOG_LEVEL define o nível. Rotação: LOG_MAX_SIZE (ou CHATCLI_LOG_MAX_SIZE_MB, em MB), CHATCLI_LOG_MAX_BACKUPS (padrão 3), CHATCLI_LOG_MAX_AGE_DAYS (padrão 28), CHATCLI_LOG_COMPRESS (padrão true, gzip). São essas as variáveis que o spec.features.logRotation da Instance do operator define; o Helm chart do servidor as define pelo bloco logging (20 MB, 3 backups por padrão, para o log caber no volume de dados de 200Mi do pod; veja Logs, health e métricas).

LOG_LEVEL=debug chatcli server 2>server.log      # linhas JSON no stderr, já que ele não é um terminal
CHATCLI_ENV=dev LOG_LEVEL=debug chatcli server    # console colorido para desenvolvimento

​

gRPC reflection

CHATCLI_GRPC_REFLECTION=true chatcli server --token "$CHATCLI_SERVER_TOKEN"
grpcurl -plaintext -H "authorization: Bearer $CHATCLI_SERVER_TOKEN" localhost:50051 list

​

Múltiplas réplicas

​

Operando o servidor

​

Solução de problemas

​

Próximos passos