编写系统定义文件

如何编写系统定义文件

该文档描述了 functioncat.yaml 文件的结构，用于定义系统的环境、路由、应用、服务等。

有关详细的配置信息，请参考 系统定义 Schema。

系统定义文件示例

请参考系统 AIChat 系统模板 和对应的 系统定义文件

system: 1.0.0
info:
  name: ai chat tool
  vars:
    BAIDU_API_KEY:
      description: >-
        百度千帆ModelBuilder>应用接入>应用API Key, 
        https://console.bce.baidu.com/qianfan/ais/console/applicationConsole/application/v1
    BAIDU_SECRET_KEY:
      description: >-
        百度千帆ModelBuilder>应用接入>Secret Key, 
        https://console.bce.baidu.com/qianfan/ais/console/applicationConsole/application/v1
    STORE_SVC_API_KEY:
      description: “Store 服务的API KEY。”
envs:
  dev:
    branch: dev
  prod:
    branch: main
routes:
  main_env: prod
  main_app: chatui
auths:
  apikey:
    type: api_key
    envs:
      dev:
        in: header
        name: API-KEY
        value: ${{vars.STORE_SVC_API_KEY}}
      prod:
        in: header
        name: API-KEY
        value: ${{vars.STORE_SVC_API_KEY}}
apps:
  chatui:
    type: web_frontend
    envs:
      dev:
        build:
          root_path: apps/chat-ui
          script: npm install; npm run build
        provision:
          root_path: apps/chat-ui/dist
          type: nodejs18x
      prod:
        build:
          root_path: apps/chat-ui
          script: npm install; npm run build
        provision:
          root_path: apps/chat-ui/dist
          type: nodejs18x
  chatapi:
    type: web_api
    envs:
      dev:
        build:
          root_path: apps/chat-api
          script: npm install
        provision:
          type: nodejs18x
          root_path: apps/chat-api
          start_command: node server.js
          timeout: 120
          vars:
            - BAIDU_API_KEY
            - BAIDU_SECRET_KEY
            - STORE_SVC_API_KEY
      prod:
        build:
          root_path: apps/chat-api
          script: npm install
        provision:
          type: nodejs18x
          root_path: apps/chat-api
          start_command: node server.js
          timeout: 120
          vars:
            - BAIDU_API_KEY
            - BAIDU_SECRET_KEY
            - STORE_SVC_API_KEY
services:
  store:
    type: kv_store
    envs:
      dev:
        auths:
          - apikey
        provision:
          type: kv_store_v1
          namespaces:
            - dailycounter
      prod:
        auths:
          - apikey
        provision:
          type: kv_store_v1
          namespaces:
            - dailycounter
            - counter2

定义字段说明

系统版本（system）

system: 1.0.0
  • 名称: 系统
  • 必填: 是
  • 描述: 系统定义文件的版本号，目前为 ‘1.0.0’。用于标识当前系统定义文件的版本，确保兼容性和版本控制。

信息（info）

info:
  name: ai chat tool
  vars:
    BAIDU_API_KEY:
      description: >-
        百度千帆ModelBuilder>应用接入>应用API Key, 
        https://console.bce.baidu.com/qianfan/ais/console/applicationConsole/application/v1
    BAIDU_SECRET_KEY:
      description: >-
        百度千帆ModelBuilder>应用接入>Secret Key, 
        https://console.bce.baidu.com/qianfan/ais/console/applicationConsole/application/v1
    STORE_SVC_API_KEY:
      description: “Store 服务的API KEY。”
  • 名称: 信息
  • 必填: 是
  • 描述: 提供系统的基本信息。
    • name: 系统的名称，便于识别和管理。
    • vars: 环境变量的定义，允许在不同环境中配置变量。
      • description: 描述每个变量的用途和重要性。

环境（envs）

envs:
  dev:
    branch: dev
  prod:
    branch: main
  • 名称: 环境
  • 必填: 是
  • 描述: 定义不同的部署环境及其特定设置，每个环境对应一个 Git 分支。
    • branch: 指定该环境所使用的 Git 分支，用于版本控制和环境隔离。

路由（routes）

routes:
  main_env: "prod"
  main_app: "main-app"
  • 名称: 路由
  • 必填: 是
  • 描述: 定义系统的主要路由信息，包括主环境和主应用。这些设置用于生成系统 URL，确保请求正确路由到相应的服务。
    • main_env: 主环境，用于确定系统的默认访问路径。
    • main_app: 主应用，代表系统的主要功能入口。

认证（auths）

auths:
  apikey:
    type: api_key
    envs:
      dev:
        in: header
        name: API-KEY
        value: ${{vars.STORE_SVC_API_KEY}}
      prod:
        in: header
        name: API-KEY
        value: ${{vars.STORE_SVC_API_KEY}}
  • 名称: 认证
  • 描述: 定义系统的认证机制，支持多种认证方式。
    • type: 指定认证类型，如 basic 或 api_key。
    • envs: 根据环境定义不同的认证参数。

应用（apps）

apps:
  chatui:
    type: web_frontend
    envs:
      dev:
        build:
          root_path: apps/chat-ui
          script: npm install; npm run build
        provision:
          root_path: apps/chat-ui/dist
          type: nodejs18x
      prod:
        build:
          root_path: apps/chat-ui
          script: npm install; npm run build
        provision:
          root_path: apps/chat-ui/dist
          type: nodejs18x
  chatapi:
    type: web_api
    envs:
      dev:
        build:
          root_path: apps/chat-api
          script: npm install
        provision:
          type: nodejs18x
          root_path: apps/chat-api
          start_command: node server.js
          timeout: 120
          vars:
            - BAIDU_API_KEY
            - BAIDU_SECRET_KEY
            - STORE_SVC_API_KEY
      prod:
        build:
          root_path: apps/chat-api
          script: npm install
        provision:
          type: nodejs18x
          root_path: apps/chat-api
          start_command: node server.js
          timeout: 120
          vars:
            - BAIDU_API_KEY
            - BAIDU_SECRET_KEY
            - STORE_SVC_API_KEY
  • 名称: 应用
  • 描述: 定义应用程序的定义，包括前端和后端应用。
    • type: 应用类型，如 web_frontend 或 web_api。
    • envs: 定义环境特定的构建和定义细节。

web_frontend 应用

build:
  root_path: "/root"
  script: "build-command"
  output_path: "/output"
  before_script: "before-script"
provision:
  type: "nodejs18x"
  root_path: "/provision-root"

  • build

    • 名称: 构建

    • 描述: 定义构建的详细的内容。

      键名必填描述
      root_path是构建的根路径，指向项目的构建目录。
      script是构建脚本，执行项目构建所需的命令。
      output_path否构建输出路径，指定构建结果的存放目录。
      before_script否构建前的脚本，可用于设置构建环境版本。

    • 默认构建环境版本:

      • NODE_VERSION="18"
      • RUBY_VERSION="2.7.2"
      • YARN_VERSION="1.22.19"
      • PNPM_VERSION="7.13.4"
      • GO_VERSION="1.19.x"
      • PYTHON_VERSION="3.8"

  • provision:

    • 名称: 布置

    • 描述: 定义布置的详细的内容。

      KeyRequiredDescription
      type是布置类型，当前只支持 nodejs18x。
      root_path是布置的根路径，指向项目的布置目录。

web_api 应用

provision:
  root_path: "/provision-root"
  type: "nodejs18x"
  start_command: "start.sh"
  vars: ["VAR1", "VAR2"]

  • provision:

    • 名称: 布置

    • 描述: 定义布置的详细的内容。

      键名必填描述
      root_path是布置的根路径，指向项目的布置目录。
      type是布置类型，当前只支持 nodejs18x。
      start_command是启动命令，用于启动应用程序。
      timeout是 ｜ 请求超时时间（秒）。
      port是 ｜ 应用兼听的端口号。
      vars否使用的环境变量，布置过程传递给应用环境变量。

服务 (services)

services:
  store:
    type: kv_store
    envs:
      dev:
        auths:
          - apikey
        provision:
          type: kv_store_v1
          namespaces:
            - dailycounter
      prod:
        auths:
          - apikey
        provision:
          type: kv_store_v1
          namespaces:
            - dailycounter
            - counter2
  • 名称: 服务
  • 描述: 服务定义，指定服务类型和环境设置。目前只支持 kv_store，其类型为 kv_store_v1。
    • type: 服务类型，如 kv_store_v1，定义服务的类别和功能。
    • envs: 定义服务在不同环境中的详细设置。

kv_store 服务

provision:
  type: kv_store_v1
  namespaces: ["chathistory", "dailycounter"]

  • provision:

    • 名称: 布置
    • 描述: 定义布置的详细的内容。
      键名必填描述
      type是服务类型，为 kv_store_v1。
      namespaces是命名空间列表，用于隔离不同的数据存储。
快速体验核心概念及其关系