CLI ja seadistuse juurutamine

Avaldatud @openstaticfish/chattybox-cli@0.3.1 ja @openstaticfish/chattybox-config@0.3.1 artefaktid rakendavad seadistuse/backendi lepingut 0.3.0 ning lükkavad tundmatud võtmed tagasi nii lokaalselt kui ka backendis. Avalikus registris on ka JavaScripti SDK @openstaticfish/chattybox@0.1.4. status näitab keskkonna versiooni, samal ajal kui runtimeConfigVersionId on jagatud runtime’i viimati rakendatud seadistus ja võib erineda. Kui mode jäetakse välja, valitakse crawl ning selgesõnaline maxDepth: 0 säilib.

CLI loob, valideerib, juurutab, promoveerib ja ennistab muutumatuid ChattyBoxi seadistuse versioone. Iga juurutustoken on seotud täpselt ühe olemasoleva projekti ja valitud keskkonnasiltidega; käsitlege üht seadistusfaili ning üht projektipõhist tokenit ühe hallatava ChattyBoxi projektina.

Seadistuse loomine

bunx @openstaticfish/chattybox-cli init

See loob faili chattybox.config.json:

{
  "schemaVersion": "1",
  "assistant": {
    "name": "Support"
  },
  "knowledge": {
    "sources": [
      {
        "type": "website",
        "url": "https://example.com"
      }
    ]
  },
  "widget": {
    "enabled": true
  }
}

Kasutage kohandatud teed, kui seadistus peab asuma alamkataloogis:

bunx @openstaticfish/chattybox-cli init config/chattybox.config.json

Kohalik või CI-s valideerimine

bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json

Valideerimine kontrollib objektide kuju, nõutavat assistendi nime, enum’e, HTTP(S)-URL-e, täisarvulisi piire, lokaadikombinatsioone ja kuuekohalisi hex-värve. knowledge võib lokaalseks valideerimiseks või developmenti jaoks puududa, kuid olemasolul peab sellel olema täpselt üks website-allikas; preview ja production nõuavad seda. Edukas kohalik valideerimine ei juuruta, ei kontrolli tokenit, paketti ega õigusi ega taga kaugjuurutuse õnnestumist.

Juurutustokeni loomine

Avage projekti vahekaart Settings, leidke Config deployment tokens ja looge token nende keskkondade jaoks, mida teie töövoog võib muuta. Kopeerige see kohe; ChattyBox talletab ainult selle räsi ega saa seda enam näidata.

Määrake token ja vidina API URL projekti vahekaardil Embed:

export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'

Ärge kunagi commitige tokenit. Hoidke seda oma CI-teenusepakkuja krüptitud saladuste hoidlas.

Pärast juurutuse töövoo kontrollimist võite samas seadete jaotises lubada Config-as-code lock. Seda ei saa praeguse juhtpaneeli, CLI ega avaliku API kaudu avada. Lukk keelab juhtpaneeli konfiguratsioonimuudatused, ikooni üleslaadimise ning käsitsi korpuse toimingud, näiteks kraapimise, lehtede kustutamise ja embeddingute taasloomise. Tokenite loomine/tühistamine, avalike võtmete haldamine ja töösoleku lugemine jäävad kättesaadavaks; paketiga lubatud branding-eelistus on erand.

Seadistuse juurutamine

Juurutamine loob muutumatu versiooni ja promoveerib selle valitud keskkonda:

bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production

development salvestab ainult versiooni/osuti (applied: false, indexingStatus: "not_required"). preview ja production kirjutavad üle sama projekti runtime’i seaded ning kasutavad sama korpust ja avalikke vidinavõtmeid; viimati toimunud runtime’i promotsioon võidab. Tegelikuks isoleerimiseks kasutage eraldi projekte. Mõlemad rakendavad seadistuse aatomiliselt ja panevad kraapimistöö järjekorda (applied: true, indexingStatus: "pending"), kuid ei oota kraapimise ega embeddingute lõppu. Värskendus uuendab lehti kohapeal ega kärbi vanu URL-e pelgalt sellepärast, et uus allikas või filter neid välja jätab. Korpus ei ole versioonitud hetkepilt ja ebaõnnestunud värskendus ei ennista rakendatud seadistust.

Kasutage automaatikas suvandit --json, et saada versioon, keskkond, rakenduse olek ja kraapimistöö ID struktureeritud väljundina.

Olek, promotsioon ja ennistamine

bunx @openstaticfish/chattybox-cli status --environment production

bunx @openstaticfish/chattybox-cli promote \
  --version '<config-version-id>' \
  --environment production

bunx @openstaticfish/chattybox-cli rollback \
  --version '<known-good-config-version-id>' \
  --environment production

--version kasutab läbipaistmatut konfiguratsiooniversiooni ID-d, mitte nähtavat numbrit. Rollback kasutab sama taustatoimingut nagu promote, ei pea valima vanemat versiooni ja kirjutab üle valitud keskkonna osuti ning promotsiooni metaandmed; append-only promotsiooniajalugu puudub. Preview või production rollback rakendab seadistuse kehtivate entitlementidega ja paneb uue värskenduse järjekorda, mitte ei taasta ajaloolist korpust.

CI/CD töövood

Lisage CHATTYBOX_DEPLOY_TOKEN oma CI-pakkujas krüptitud, tootmisega seotud saladusena. Lisage CHATTYBOX_API_URL saladuse või muutujana, kasutades projekti Embed-vahekaardilt pärit vidina API URL-i. Käivitage valideerimine pull request'ide korral, kuid piirake tootmise juurutamine kaitstud vaikeharu või heakskiidetud juurutuskeskkonnaga.

GitHub Actions

name: Deploy ChattyBox configuration

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - run: bunx @openstaticfish/chattybox-cli validate

  deploy:
    if: github.event_name == 'push'
    needs: validate
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - name: Validate and deploy
        env:
          CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
          CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
        run: |
          bunx @openstaticfish/chattybox-cli validate
          bunx @openstaticfish/chattybox-cli deploy --environment production --json

Kasutage keskkonnaga seotud tootmissaladust ja nõudke juurutamise kinnitamist, kui teie repositoorium seda toetab. CLI talletab tavalised CI commiti- ja harumuutujad koos muutumatu versiooniga.

GitLab CI/CD

Salvestage mõlemad väärtused jaotises Settings → CI/CD → Variables. Kaitske juurutustokenit, maskeerige see ja siduge see keskkonnaga production.

.gitlab-ci.yml

image: oven/bun:1

validate_chattybox:
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - bunx --bun @openstaticfish/chattybox-cli validate

deploy_chattybox:
  stage: deploy
  environment: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - bunx --bun @openstaticfish/chattybox-cli validate
    - bunx --bun @openstaticfish/chattybox-cli deploy --environment production --json

GitLab avaldab CHATTYBOX_DEPLOY_TOKEN ja CHATTYBOX_API_URL tööle automaatselt nende muutujanimede kaudu. Kasutage kaitstud vaikeharu, et kaitstud muutujad poleks usaldamata harudele saadaval.

Bitbucket Pipelines

Lisage mõlemad väärtused juurutusmuutujatena jaotises Repository settings → Pipelines → Deployments → Production. Märkige juurutustoken turvatuks.

bitbucket-pipelines.yml

image: oven/bun:1

pipelines:
  pull-requests:
    '**':
      - step:
          name: Validate ChattyBox configuration
          script:
            - bunx --bun @openstaticfish/chattybox-cli validate
  branches:
    main:
      - step:
          name: Deploy ChattyBox configuration
          deployment: Production
          script:
            - bunx --bun @openstaticfish/chattybox-cli validate
            - bunx --bun @openstaticfish/chattybox-cli deploy --environment production --json

Asendage main, kui teie vaikeharul on teine nimi. Bitbucket süstib juurutusmuutujad ainult sammudesse, mis on selle juurutuskeskkonnaga seotud.

Seadistuse jaotised

Jaotis	Otstarve
schemaVersion	Valib avaliku seadistuslepingu. Praegu toetatakse versiooni 1.
assistant	Määrab assistendi nime ning soovi korral selle viibaprofiili ja süsteemiviiba.
knowledge.sources	Valib avalehe, saidikaardi, käsitsi URL-id või crawl’i ning nende filtrid, piiri ja värskendusgraafiku.
runtime	Juhib automaatset või fikseeritud lokaati, vaikimisi lokaati ja lehepõhiseid lokaadi override’e.
widget	Juhib lubamist, asukohta, tekste, värve ja ikooni esitlust.

Tüübistatud seadistuse abifunktsioon

Installige seadistuspakett, kui loote skeemi ümber eraldi TypeScripti tööriistu:

bun add -d @openstaticfish/chattybox-config

import { defineConfig } from '@openstaticfish/chattybox-config';

const config = defineConfig({
  schemaVersion: '1',
  assistant: { name: 'Support' },
  knowledge: {
    sources: [{ type: 'website', url: 'https://docs.example.com' }],
  },
  widget: { enabled: true },
});

CLI ise loeb JSON-faile. defineConfig() on mõeldud tüübistatud rakendus- või koostetööriistadele; see ei muuda TypeScripti faile CLI jaoks otse laaditavaks.

Praegu toimiva tootmisintegratsiooni jaoks kasutage majutatud vidinat või looge JavaScripti SDK abil kohandatud liides.