CLI ja seadistuse juurutamine

CLI loob, valideerib, juurutab, promoveerib ja ennistab muutumatuid ChattyBoxi seadistuse versioone. Juurutustokenid on seotud ühe projekti ja valitud keskkondadega, mistõttu sobib sama töövoog nii kohalikuks arenduseks kui ka CI jaoks.

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 skeemi, nõutavat assistendi nime, toetatud allikatüüpe, HTTP-allikate URL-e, positiivseid lehepiiranguid ja vidina värve. Edukas valideerimine ei juuruta ega muuda kaugolekut.

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 lubage samas seadete jaotises Config-as-code lock. Lukk keelab juhtpaneeli konfiguratsiooni ja korpuse muutmise, nii et käitusaega saavad muuta ainult vastava ulatusega juurutustokenid. Tokenite loomine ja tühistamine jäävad kättesaadavaks juhuks, kui CI-mandaat tuleb roteerida.

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

Arendus- ja eelvaatepromotsioonid salvestatakse ülevaatamiseks. Tootmisepromotsioonid rakendavad aktiivses projektis aatomiliselt assistendi viiba, varuvastuse, vidina sätted, lokaadi ja veebisaidi allika. Tootmise seadistus peab sisaldama täpselt üht veebisaidi allikat. Juurutus lisab järjekorda versiooniga seotud kraapimistöö, mis käivitatakse pärast varasemate tööde lõppu. Seejärel asendab juurutus vana korpuse ja genereerib embeddingud uuesti. Praegune runtime lükkab mitme allikaga seadistused tagasi.

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

Ennistamine promoveerib vanema muutumatu versiooni ja rakendab selle uuesti; see ei kirjuta juurutuste ajalugu kunagi ümber. Seadistus taastatakse kohe, kuid vajalik sisu värskendamine jätkub asünkroonselt.

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
      - 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
      - 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 @openstaticfish/chattybox-cli validate

deploy_chattybox:
  stage: deploy
  environment: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - bunx @openstaticfish/chattybox-cli validate
    - bunx @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 @openstaticfish/chattybox-cli validate
  branches:
    main:
      - step:
          name: Deploy ChattyBox configuration
          deployment: Production
          script:
            - bunx @openstaticfish/chattybox-cli validate
            - bunx @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	Deklareerib veebisaidi allikad ning valikulised kaasamis- ja välistamismustrid.
runtime	Sisaldab käituskeskkonna vaikeväärtusi, näiteks lokaati.
widget	Kirjeldab majutatud vidina valikulisi esitlussätteid.

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.