@cogitator-ai/部署

一号指令部署引擎 用于协作者特工 分析您的项目,生成一个多克文件并指定目标文物,进行飞行前检查并部署到多克或Fly.io.

指南 : 协调人员.app/docs/部署/部署包

安装

pnpm add @cogitator-ai/deploy

快速启动

通过 CLI

cogitator deploy --dry-run            # analyze + preflight, change nothing
cogitator deploy                      # Docker: build image, start the compose stack
cogitator deploy --target fly         # Fly.io
cogitator deploy status
cogitator deploy logs -f              # docker compose logs / flyctl logs
cogitator deploy destroy

程序化 API

import { Deployer } from '@cogitator-ai/deploy';

const deployer = new Deployer();

const plan = await deployer.plan({
  projectDir: process.cwd(),
  target: 'docker',
  noPush: true,
  configOverrides: { port: 8080, secrets: ['OPENAI_API_KEY'] },
});

console.log(plan.config); // resolved DeployConfig (image, port, services, secrets, ...)
console.log(plan.warnings); // e.g. missing start script, local Ollama on a cloud target
console.log(plan.preflight.passed, plan.preflight.checks);

const result = await deployer.deploy({ projectDir: process.cwd(), target: 'fly' });
if (!result.success) throw new Error(result.error);
console.log(result.url); // https://my-app.fly.dev

DeployOptions数字 : projectDir, (中文(简体) ), target, (中文(简体) ), dryRun (计划并生成,然后返回) { success: true, url: '(dry run)' } - 不写文物或部署, noPush (放下登记册), configOverrides (单位:千美元) DeployConfig, (中文(简体) ), configPath (要读取的配置文件,默认为 cogitator.yml, (中文(简体) ), cogitator.yaml, (中文(简体) ), .cogitator.yml, (中文(简体) ), .cogitator.yaml 内 projectDir,与 loadConfig和 env (如果秘密来自何处, 默认项目 .env (a) 在进程环境中. status, (中文(简体) ), destroy 财务报告和审定财务报表 logsCommand 带 { configPath } 还有.. logsCommand 决定命令. deploy() 不丢弃失败的飞行前检查: 它返回 { success: false, error } 列出每个失败的检查及其修正.

ProjectAnalyzer (单位:千美元)analyze(projectDir, overrides?, { configPath, env }?), (中文(简体) ), detectBuild(projectDir), (中文(简体) ), ArtifactGenerator, (中文(简体) ), DockerProvider 财务报告和审定财务报表 FlyProvider 用于建造自己的管道.

配置

两者 cogitator deploy 和方案 Deployer 读取 deploy 区域. configOverrides 逐个字段胜出( 内部) services, (中文(简体) ), env, (中文(简体) ), health 财务报告和审定财务报表 resources 双方都赢得了自动探测:

deploy:
  target: fly # docker | fly (default: docker)
  kind: worker # server | worker (default: detected, see below)
  server: express # express | fastify | hono | koa | tetsu | next (default: detected)
  port: 3000 # default: 3000 for a server, none for a worker
  image: my-agent # Docker image (default: package.json name)
  app: my-agent-prod # Fly.io app name (default: image)
  org: acme # Fly.io organization a new app is created in (default: your default org)
  region: iad # Fly.io, default: iad
  instances: 2 # Fly.io only, docker runs one container
  registry: ghcr.io/myorg
  services: # default: detected from the memory adapter and the Ollama models
    redis: true
    postgres: true
    ollama: true # docker: an Ollama container next to the app
  env:
    LOG_LEVEL: info
  secrets: # default: detected, see below
    - OPENAI_API_KEY
  health: # defaults shown
    path: /cogitator/health
    interval: 30s
    timeout: 5s
  resources: # Fly.io VM, default: 256mb, 1 shared CPU
    memory: 512mb
    cpu: 1
  volumes: # default: the directory of a SQLite memory database
    - path: data # relative to the app directory, or absolute
      size: 1 # GB, Fly.io volume size
  hostGateway: true # docker: reach the host as host.docker.internal (set with services.ollama off)
  ollama: # docker, with services.ollama
    models: [qwen3:8b, nomic-embed-text] # default: the local Ollama models of the config
    gpu: true # reserve the host's NVIDIA GPUs (needs the NVIDIA Container Toolkit)
    image: ollama/ollama:0.40.10 # default shown

服务器或工人

kind 决定如何运行和检查应用程序 :

• server 解答 HTTP 打开 port进行健康检查HEALTHCHECK飞行 [checks])和在"Fly"上,一个HTTP服务,可以停止闲置的机器,并在下一个请求时启动. 从 Cogitator 服务器适配器检测( )@cogitator-ai/express, (中文(简体) ), fastify, (中文(简体) ), hono, (中文(简体) ), koa, (中文(简体) ), tetsu, (中文(简体) ), next),Next.js或平面HTTP框架(Express, fastify, Hono, Koa).
• worker 运行时不为HTTP服务,比如频道网关(英语:Telegram long power)或排队工人. 它没有健康检查,出版 port 只有在一个被设定,并且在"飞翔"上 从未被代理停止(auto_stop_machines = "off",没有端口的 HTTP 服务。 从 @cogitator-ai/channels 或者说 @cogitator-ai/worker。 。 。 .

一个既不是的工程,如一个使一个呼叫和退出的脚本,在飞行前失败:已经部署,将永远重启. 设定 deploy.kind 当发现错误.

health.path 对检测到的适配器路径的默认 : /cogitator/health 对于快车,快车,Hono和Koa的默认基础路径, /health 为哲也. 当适配器被安装在别处时设定它. Next.js没有自己的健康路线,所以没有已知路径的服务器得不到健康检查和警告. 项目来源 create-cogitator-app 已经设定 : api-server 模板在 /api 写作 health.path: /api/health。 。 。 .

秘诀

除非我们.. deploy.secrets 列出,发现秘密:

• 模型的提供者无法运行的, 路由像运行时的路线(meta-llama/Llama-3.3-70B-Instruct-Turbo 与 defaultProvider: together 需求 TOGETHER_API_KEY) (中文(简体) ). 阿祖尔需要钥匙和终点, Bedrock 一个区域和证书。 写入的值 llm.providers 按规定计算。 当一个别名被设定而不是主名时( NameGEMINI_API_KEY 页:1 GOOGLE_API_KEY),别名被通过. 设置的可选提供者设置( E)OPENAI_BASE_URL, (中文(简体) ), AWS_SESSION_TOKEN)也通过. PROVIDER_ENV 联 合 国 @cogitator-ai/config 这是后面的表格
• 代码传递给 requireEnv('NAME') 下级 src/
• 变量 .env.example 设定
• 配置读取的变量 loadConfig 读取: ${VAR} 文件的参考文献 COGITATOR_* 覆盖诸如 COGITATOR_LLM_DEFAULT_MODEL,因此应用程序解决了分析方式(在其中所取出的模式)的配置. 左边是 COGITATOR_DEPLOY_*,此机器的 Ollama URL 和 Compose 堆栈运行的服务 URL

当没有发现,但项目 .env 定义变量,飞行前失败而不是没有它们部署应用程序。 列出它所需要的内容 deploy.secrets (空列表无一部署).

从当前环境或项目中读取机密 .env 文档。 在飞行前对其进行检查,经过多克堆栈,然后与Fly.io一起进口 fly secrets import --stage。 。 。 .

超过部署的数据

SQLite 内存 (memory.adapter: sqlite)将其数据库目录保存在一卷上:取名为卷的多克克,或第一个部署时创建并挂载的飞行卷 [mounts],目录也保存在图像之外,因此本地数据从不出船. 工程根中的数据库无法获取音量并获得警告, 移动到目录中, 如 data/memory.db飞行机器挂起一卷, 更多的故障飞行前.

当地奥拉马

当该项目的模型运行在本地Ollama上时,插头目标运行在app旁边(services.ollama,默认情况下). 每个角色都是靠自己看待的. 聊天角色是运行时间使用的每个 Ollama 模型: llm.defaultModel, (中文(简体) ), context.summaryModel 除非 context.enabled 假的, 设定的记忆阶段模型, reflection.reflectionModel 与 reflection.enabled, (中文(简体) ), guardrails.model 除非 guardrails.enabled 是虚假的,而且 security.promptInjection.llmModel 与 classifier: llm角色及其模型由部署得到的环境决定, deploy.env 列入defaultModel: ${CHAT_MODEL:-ollama/qwen3:8b} 拖动模型 deploy.env.CHAT_MODEL 名称),所以 deploy.env.COGITATOR_OLLAMA_BASE_URL 指着一个GPU盒子,就在那里保持聊天. 代码中的代理名的模型不在配置中,请在 ollama.models。嵌入式角色是 memory.embedding 与 provider: ollama (它的模型, nomic-embed-text (默认情况下). 奥拉马云模型(a) :cloud 标记,或没有 URL 的 API 密钥,这意味着 https://ollama.com as in the config schema)是聊天角色的一部分,从未被拉出. 当其 URL 指向此机时, 角色是本地的, 其 URL 指向 URL 之外 , 并保存 URL 及其 所跟踪的变量 GPU_OLLAMA 页:1 baseUrl: ${GPU_OLLAMA}与 llm.defaultProvider: ollama 而配置中没有模型(在代理代码中命名的模型),没有什么可拉动的,因此应用程序以警告到达了主机的奥拉马,除非 ollama.models 列出运行容器的模型。 一个模型名称 ollama pull 拒绝或读作一面旗帜,例如 ollama/--insecure,失败的飞行前.

编译文件获得一个 ollama 服务 ollama/ollama 带有模型的图像 ollama-data 体积、健康检查、一发 ollama-pull 第一次启动时拉动模型的服务:每个模型都是工作的一个参数,一个音量已经跳过,所以以后启动不需要网络. 应用等于二者. 本地聊天角色获得 COGITATOR_OLLAMA_BASE_URL, (中文(简体) ), OLLAMA_BASE_URL, (中文(简体) ), OLLAMA_URL 财务报告和审定财务报表 OLLAMA_HOST 指点 http://ollama:11434,也当其中之一被检测为具有本地主机值的秘密,以及一个在 deploy.env 或者说 deploy.secrets 留给你了。 第一次部署需要时间,只要下载, cogitator deploy logs ollama-pull -f 显示它,而下载失败会与任务最后一行一起失败部署。 与 services.ollama: true 没有一个模型运行在容器上, 分析员警告. ollama.models 替换检测到的列表, ollama.gpu: true 保留主机的NVIDIA GPU, ollama.image 运行另一个发布或 ollama/ollama:rocm。 。 。 .

嵌入服务读取其 URL memory.embedding.baseUrl 只有,所以部署时将显示在容器上的变量: ${OLLAMA_BASE_URL:-http://localhost:11434},或 ${OLLAMA_EMBEDDING_URL:-http://localhost:11434} 当聊天模式使用另一个Ollama时. 变量获得整个 URL, 或只获得主机(http://${EMBED_HOST:-localhost}:11434 获得 EMBED_HOST=ollama),以给定目标 URL者为准,在两者都不给时,则被单独警告。 另一个提供者参考的设置的变量(llm.providers.openai.baseUrl: ${OLLAMA_BASE_URL}/v1)永远不会被重写,一个变量只有在没有移动保持远程的角色时才会被设定,所以GPU盒上的一个聊天模型在嵌入器运行在容器中时会保留它的URL,当嵌入器无法被到达时分析器会发出警告(一个字面的本地主机URL,或者远程聊天URL读取的变量).

与 services.ollama: false 本地角色到达主机的 Ollama: 编译文件地图 host.docker.internal 到主机并指向相同的变量,每个角色都保留自己本地URL的端口,一个警告会列出要拉在那里的模型. 键 services 您设定将检测到的换成一个, 所以 services: { ollama: false } 使 Redis 和 Postgres 从内存适配器中检测到。 在Linux上,Ollama必须听从超越本地主机(OLLAMA_HOST=0.0.0.0 ollama serve) (中文(简体) ). 已经指向另一台机器的 Ollama URL 正在通过。 其他目标警告,因为他们没有奥拉玛.

自动检测

飞行前先检查每个目标份额: package.json 存在(a) cogitator wizard 助理没有,它运行 cogitator up 或者说 cogitator daemon start,项目是服务器或工人 start 脚本不装入 .env 文件为 --env-file (单位:千美元).env 远离图像, 使用 --env-file-if-exists发现了一些秘密 其他问题(无效配置, 无法解析) package.json,缺少开始脚本, tsconfig.json 无 build 脚本,一个没有已知健康路径的服务器, 本地 Ollama, Redis 或 Postgres on Fly, instances > 1 返回为 plan.warnings。 。 。 .

画面为生产建设分三个阶段. base 实值 node:24-alpine,或 oven/bun:1-alpine 当启动命令运行时 bun。 。 。 . builder 添加本地工具链( n)python3, (中文(简体) ), make, (中文(简体) ), g++),从锁文件中安装包管理器在BuildKit缓存挂载中的缓存,运行构建并去掉dev依赖. runtime 复制结果,作为图像的无特权用户运行(node 或者说 bun下 tini,因此,信号到达应用 和孩子进程 收获,并设定 NODE_ENV=production。服务器也会得到 PORT, (中文(简体) ), EXPOSE (单位:千美元) HEALTHCHECK 在健康之路上。 一个以 Bun 为软件包管理器的节点应用程序建立在节点图像上, Bun 复制到并且 node-gyp 已安装,因此本地依赖性如 better-sqlite3 编译. A 类 start 窗体脚本 node [flags] dist/index.js 成为 CMD 直接,没有它的 --env-file 旗帜:容器从部署中获得环境. file: 财务报告和审定财务报表 link: 在安装步骤前复制依赖性 。 在 Plug'n'Play (Yarn 默认链接器) 上的一个 Yarn Berry 工程将它的软件包档案安装到图像中 .yarn/cache中,只保留生产设备,并开始于装入的 PnP 解析器 NODE_OPTIONS (单位:千美元).pnp.cjs,以及 .pnp.loader.mjs 用于ES模块).

部署目标

夹克

手工制品被写到 .cogitator/数字 : Dockerfile, (中文(简体) ), .dockerignore, (中文(简体) ), Dockerfile.dockerignore 财务报告和审定财务报表 docker-compose.prod.yml词根 .dockerignore 当项目无时创建, 所以 .env 财务报告和审定财务报表 node_modules 从不输入图像.

deploy 构建并标记图像( n)<registry>/<image>:latest与 BuildKit (英语:DOCKER_BUILDKIT=1,然后运行 docker compose up -d 用于应用加Redis、PostgreSQL和Ollama服务,它需要这些服务(健康方面,数据以所命名的量表示)。 每个键都出现在应用程序的"编译"中 environment(单位:千美元) REDIS_URL 编号 : DATABASE_URL 内 env 替换已捆绑的服务 URL, 并在 secrets 从您的环境中读取捆绑的 URL 后退。 应用程序容器必须持续运行几秒钟(new DockerProvider({ startupCheckMs }), 默认 8 秒 : 一个退出或重新启动失败的部署与它的最后一个日志行, 因此报告一个缺失的秘密而不是重启循环 。 结果 url 实值 http://localhost:<port> 对于服务器,没有端口的工人没有. status 报告是否 app 服务正在运行, logsCommand 正在建设 docker compose logs (单位:千美元)--follow, (中文(简体) ), --tail,100行默认, --timestamps一个服务, destroy 运行 docker compose down 并保持体积,其中的被拉动的模型.

飞行前检查: 安装了 Docker, 守护进程运行, 配置 v2 可用, BuildKit ()docker buildx),可用于多克文件的缓存挂载,注册证书(从多克配置,证书助手和存储处读取),秘密.

飞.io

生成 .cogitator/fly.toml (你自己的) fly.toml 从未覆盖) [env], VM 大小从 resources页:1 [mounts] 音量,对于服务器来说,一个 HTTP 服务 health 财务报告和审定财务报表 min_machines_running 从 instances (机器自动停车和自动启动) 工人得不到支票 也不会被自动拦截 应用程序是 deploy.app,或者图像名称. deploy 需要时创建应用程序( e)fly apps create --org <org> 与 deploy.org及其数量 阶段 秘密 运行 fly deploy --config .cogitator/fly.toml --dockerfile .cogitator/Dockerfile缩放至 instances。对于服务器,结果列表 https://<app>.fly.dev、其健康URL和A2A代理卡(/.well-known/agent.json) (中文(简体) ). Fly在应用程序旁边没有Redis或Postgres:, REDIS_URL 编号 : DATABASE_URL 成为需要的秘密( 用 fly redis create, (中文(简体) ), fly postgres create 或任何托管服务). status 读取 fly status, (中文(简体) ), logsCommand 正在建设 fly logs --app <app> (单位:千美元)--no-tail 除非跟随,没有服务, tail 或者说 timestamps他不肯答应, destroy 运行 fly apps destroy. 飞行前检查:应用程序名称遵循了飞行规则(小写字母、数字和破折号,以字母或数字开头和结尾,最多63个字符)和 deploy.org 是一颗子弹, flyctl 已安装, fly auth whoami还有秘密 和谁一起工作 flyctl 或者说 fly 打开 PATH。 。 。 .

自定义提供者

import {
  ArtifactGenerator,
  Deployer,
  ProjectAnalyzer,
  type DeployCommand,
  type DeployLogsOptions,
  type DeployProvider,
} from '@cogitator-ai/deploy';
import type {
  DeployConfig,
  DeployResult,
  DeployStatus,
  GeneratedArtifacts,
  PreflightResult,
} from '@cogitator-ai/types';

class KubernetesProvider implements DeployProvider {
  readonly name = 'kubernetes';

  async preflight(config: DeployConfig, projectDir: string): Promise<PreflightResult> {
    return { checks: [], passed: true };
  }
  async generate(config: DeployConfig, projectDir: string): Promise<GeneratedArtifacts> {
    const build = new ProjectAnalyzer().detectBuild(projectDir);
    return new ArtifactGenerator().generate(config, build);
  }
  async deploy(
    config: DeployConfig,
    artifacts: GeneratedArtifacts,
    projectDir: string
  ): Promise<DeployResult> {
    // write artifacts.files to artifacts.outputDir, apply manifests, ...
    return { success: true, url: 'https://agents.example.com' };
  }
  async status(config: DeployConfig, projectDir: string): Promise<DeployStatus> {
    return { running: true };
  }
  async destroy(config: DeployConfig, projectDir: string): Promise<void> {}
  async logsCommand(
    config: DeployConfig,
    projectDir: string,
    options: DeployLogsOptions
  ): Promise<DeployCommand> {
    return {
      command: 'kubectl',
      args: ['logs', 'deploy/agents', ...(options.follow ? ['-f'] : [])],
    };
  }
}

const deployer = new Deployer();
deployer.registerProvider(new KubernetesProvider());
await deployer.deploy({ projectDir: process.cwd(), target: 'kubernetes' });

Deployer.deploy() 运行飞行前,打电话给你的供应商 generate(config, projectDir) 将结果交给它 deploy() (与 dryRun 它停止之后 generate()) (中文(简体) ). 将文件写入磁盘由提供者决定 . logsCommand 可选的,并可以返回命令或承诺: Deployer.logsCommand(target, config, projectDir, options) 决定呼叫者与接通的终端一起运行的命令 cogitator deploy logs 已经 实例重用内置多克文件 : ProjectAnalyzer.detectBuild(projectDir) 报告 TypeScript 设置、软件包管理器、锁定文件、构建脚本并启动命令 ArtifactGenerator 需要帮助.

所有外部命令都是在没有 shell 的情况下执行的,因此带有空格和用户提供值的路径是逐字传递的.

建筑

ProjectAnalyzer  →  DeployProvider.generate  →  DeployProvider.deploy  →  Result
(detect config)     (Dockerfile, etc.)            (docker/fly)              (url, status)

另见

• 部署软件包指南
• Docker 部署
• CLI 参考 —— 说 cogitator deploy

许可证

麻省理工学院