CLI a gosod ffurfweddiad

Mae'r CLI yn creu, yn dilysu, yn gosod, yn hyrwyddo ac yn dychwelyd fersiynau digyfnewid o ffurfweddiad ChattyBox. Mae tocynnau gosod wedi'u cyfyngu i un prosiect ac amgylcheddau dethol, gan wneud yr un llif gwaith yn addas ar gyfer datblygu lleol a CI.

Creu ffurfweddiad

bunx @openstaticfish/chattybox-cli init

Mae hyn yn creu chattybox.config.json:

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

Defnyddiwch lwybr personol pan fo'r ffurfweddiad yn perthyn mewn isgyfeiriadur:

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

Dilysu'n lleol neu mewn CI

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

Mae dilysu'n gwirio'r sgema, enw gofynnol y cynorthwyydd, mathau o ffynonellau a gefnogir, URLau ffynonellau HTTP, terfynau tudalennau positif a lliwiau'r widget. Nid yw dilysiad llwyddiannus yn gosod nac yn addasu cyflwr o bell.

Creu tocyn gosod

Agorwch dab Settings y prosiect, dewch o hyd i Config deployment tokens, ac yna crëwch docyn ar gyfer yr amgylcheddau y gall eich llif gwaith eu newid. Copïwch ef ar unwaith; dim ond ei hash y mae ChattyBox yn ei storio ac ni all ei ddangos eto.

Gosodwch y tocyn ac URL API y widget o dab Embed y prosiect:

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

Peidiwch byth â chyflwyno'r tocyn. Storiwch ef yn storfa gyfrinachau wedi'i hamgryptio gan eich darparwr CI.

Ar ôl gwirio'r llif gwaith gosod, galluogwch Config-as-code lock yn yr un adran gosodiadau. Mae'r clo'n analluogi newidiadau i ffurfweddiad a chorffws o'r dangosfwrdd, felly dim ond tocynnau gosod sydd â'r cwmpas priodol all newid y runtime. Mae creu a dirymu tocynnau yn parhau ar gael os bydd angen cylchdroi manylyn adnabod CI.

Gosod ffurfweddiad

Mae gosod yn creu fersiwn ddigynewid ac yn ei hyrwyddo i'r amgylchedd dethol:

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

Mae hyrwyddiadau datblygu a rhagolwg yn cael eu cofnodi i'w hadolygu. Mae hyrwyddiadau cynhyrchu yn cymhwyso anogwr y cynorthwyydd, yr ymateb wrth gefn, gosodiadau'r widget, y locale a ffynhonnell y wefan i'r prosiect byw yn atomig. Rhaid i ffurfweddiad cynhyrchu gynnwys union un ffynhonnell wefan. Mae gosodiad yn rhoi sgrapio wedi'i rwymo i fersiwn yn y ciw, i'w redeg ar ôl i dasgau blaenorol gwblhau. Yna mae'n disodli'r corffws blaenorol ac yn ailgynhyrchu'r embeddings. Mae'r runtime cyfredol yn gwrthod ffurfweddiadau aml-ffynhonnell.

Defnyddiwch --json mewn awtomeiddio i gael y fersiwn, yr amgylchedd, statws y rhaglen ac ID y job sgrapio fel allbwn strwythuredig.

Statws, hyrwyddo a dychwelyd

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

Mae dychweliad yn hyrwyddo ac yn ailgymhwyso fersiwn ddigynewid hŷn; nid yw byth yn ailysgrifennu hanes y gosodiadau. Mae'n adfer y ffurfweddiad ar unwaith, tra bod unrhyw adnewyddiad cynnwys gofynnol yn parhau'n anghydamserol.

Llifau gwaith CI/CD

Ychwanegwch CHATTYBOX_DEPLOY_TOKEN fel cyfrinach wedi'i hamgryptio wedi'i chwmpasu i gynhyrchu yn eich darparwr CI. Ychwanegwch CHATTYBOX_API_URL fel cyfrinach neu newidyn gan ddefnyddio URL API y widget o dab Embed y prosiect. Rhedwch ddilysiad ar pull requests, ond cyfyngwch osod cynhyrchu i'ch cangen ddiofyn warchodedig neu amgylchedd gosod a gymeradwywyd.

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

Defnyddiwch gyfrinach gynhyrchu wedi'i chwmpasu gan amgylchedd a gofynnwch am gymeradwyaeth i'r gosodiad pan fo'ch ystorfa'n ei gefnogi. Mae'r CLI yn cofnodi newidynnau cyffredin commit a changen CI gyda'r fersiwn ddigynewid.

GitLab CI/CD

Storiwch y ddau werth o dan Settings → CI/CD → Variables. Gwarchodwch gyfrinach y gosodiad, ei chuddio, a'i chwmpasu i'r amgylchedd 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

Mae GitLab yn datgelu CHATTYBOX_DEPLOY_TOKEN a CHATTYBOX_API_URL yn awtomatig i'r swydd gan ddefnyddio eu henwau newidynnau. Defnyddiwch gangen ddiofyn warchodedig fel nad yw newidynnau gwarchodedig ar gael i ganghennau annibynadwy.

Bitbucket Pipelines

Ychwanegwch y ddau werth fel newidynnau gosod o dan Repository settings → Pipelines → Deployments → Production. Marciwch gyfrinach y gosodiad fel un ddiogel.

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

Amnewidiwch main os oes gan eich cangen ddiofyn enw arall. Mae Bitbucket yn mewnosod newidynnau gosod i gamau sy'n gysylltiedig â'r amgylchedd gosod hwnnw yn unig.

Adrannau ffurfweddu

Adran	Diben
schemaVersion	Yn dewis y contract ffurfweddu cyhoeddus. Cefnogir fersiwn 1 ar hyn o bryd.
assistant	Yn enwi'r cynorthwyydd ac, yn ddewisol, yn diffinio ei broffil anogwr a'i anogwr system.
knowledge.sources	Yn datgan ffynonellau gwefannau a phatrymau cynnwys/eithrio dewisol.
runtime	Yn cadw rhagosodiadau amser rhedeg, megis locale.
widget	Yn disgrifio gosodiadau cyflwyno dewisol y widget lletyol.

Cynorthwyydd ffurfweddu wedi'i deipio

Gosodwch y pecyn ffurfweddu wrth adeiladu offer TypeScript ar wahân o amgylch y sgema:

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 },
});

Mae'r CLI ei hun yn darllen ffeiliau JSON. Mae defineConfig() ar gyfer offer rhaglen neu adeiladu wedi'u teipio; nid yw'n gwneud ffeiliau TypeScript yn rhai y gall y CLI eu llwytho'n uniongyrchol.

Ar gyfer integreiddiad cynhyrchu sy'n gweithio heddiw, defnyddiwch y widget lletyol neu adeiladwch ryngwyneb personol gyda'r SDK JavaScript.