跳到主要内容

部署概览

CubePlex 可以部署在你自己的基础设施上。下面两种部署模式使用完全相同的 backend / frontend 容器镜像——只是编排方式不同。

选择部署方式​

Docker ComposeKubernetes (Helm)
适用场景单机部署——快速自托管、小团队、内部演示多节点集群、生产规模、自动扩缩容
编排方式docker compose up -dhelm upgrade --install
内置基础设施Postgres、Redis、rustfs（S3 兼容对象存储）、OpenSandbox、TempoPostgres、Redis、rustfs、Tempo、alibaba OpenSandbox 全家桶
指南Docker Compose 安装指南Kubernetes 安装指南

如果不确定选哪个，从 Docker Compose 开始——它更简单，除了跨多机的水平扩展外， 其他能力都具备。

Agent 沙箱​

CubePlex 在 OpenSandbox 沙箱里执行 agent 的工具调用（bash、文件读写等）。它是每种部署方式的必需组成部分：Docker Compose 会部署该服务，Helm 默认打包它。Helm 也可以改为连接外部托管的 OpenSandbox，但 backend 始终要求非空的 endpoint、沙箱镜像和 API key。沙箱镜像 默认走 Docker Hub（opensandbox/*）和 GHCR（ghcr.io/cubeplexai/cubeplex-sandbox）； 国内镜像源在各指南中就地标注。

LLM Provider 配置​

两种部署模式配置 LLM provider 的方式完全一致，都是 backend 密钥配置里的 llm 字段块。无论你编辑的是 config.production.secrets.yaml（Docker Compose）还是 values.local.yaml（Kubernetes），都适用这份参考——两份指南 都会链接回这里，而不是各自重复一遍。

最通用的配置方式，是指向任意 OpenAI 兼容（api: openai-completions）或 Anthropic 兼容（api: anthropic-messages）端点。它覆盖 OpenAI、Anthropic、 Azure OpenAI、大多数云厂商，以及自托管网关（vLLM、LiteLLM、Ollama 等）——你 只需提供 base_url、api_key 和该端点暴露的模型。

llm:
  # 必须配置一个默认 preset。后端在启动时从 model_presets 生成它，聊天路径
  # 也通过它解析模型——没有默认 preset 时后端仍能启动，但每条消息都会在运行
  # 时报 NoDefaultPresetError（HTTP 500）。每个 tier 的 primary / fallbacks
  # 都是 "<provider_name>/<model_id>"，provider_name 必须出现在下方 providers 下。
  model_presets:
    tiers:
      lite:  { enabled: true,  primary: "openai/gpt-5.6-terra", fallbacks: ["anthropic/claude-opus-4.8"] }
      flash: { enabled: true,  primary: "openai/gpt-5.6-terra", fallbacks: ["anthropic/claude-opus-4.8"] }
      pro:   { enabled: true,  primary: "openai/gpt-5.6-terra", fallbacks: ["anthropic/claude-opus-4.8"] }
      max:   { enabled: false, primary: null, fallbacks: [] }
    default_preset: pro
  providers:
    # 任意 OpenAI 兼容的 chat-completions 端点。
    openai:
      base_url: "https://api.openai.com/v1"   # 带 /v1
      api_key: "sk-..."
      api: "openai-completions"
      models:
        - id: "gpt-5.6-terra"
          name: "GPT-5.6 Terra"
          input: ["text", "image"]
          context_window: 128000
          max_tokens: 16384

    # 任意 Anthropic 兼容的 Messages 端点。
    anthropic:
      base_url: "https://api.anthropic.com"   # host 根，不带 /v1
      api_key: "sk-ant-..."
      api: "anthropic-messages"
      models:
        - id: "claude-opus-4.8"
          name: "Claude Opus 4.8"
          reasoning: true
          input: ["text", "image"]
          context_window: 200000
          max_tokens: 64000
  • model_presets.tiers 定义可选的模型档位（lite / flash / pro / max），default_preset 指定未显式指定时用哪个档位。至少要启用一个 tier。 每个 primary / fallbacks 都是 "<provider_name>/<model_id>"， provider_name 必须出现在 providers 下，fallback 会在 primary 失败时 按顺序尝试。用不到的 tier 可以保持 enabled: false。
  • 每个 provider 声明 base_url、api_key、api （openai-completions | anthropic-messages | openai-responses），以及 至少一个 models 条目。base_url 遵循各 SDK 约定——OpenAI 风格带 /v1， Anthropic 风格是 host 根。
  • 只有推理模型才设 reasoning: true；input 列出模型接受的模态 （text、image）。

最小可用配置（一个 provider、一个模型）：

llm:
  model_presets:
    tiers:
      pro: { enabled: true, primary: "openai/gpt-5.6-terra", fallbacks: [] }
    default_preset: pro
  providers:
    openai:
      base_url: "https://api.openai.com/v1"
      api_key: "sk-..."
      api: "openai-completions"
      models:
        - id: "gpt-5.6-terra"
          name: "GPT-5.6 Terra"
          input: ["text", "image"]
          context_window: 128000
          max_tokens: 16384

快捷方式：内置厂商 preset​

对已知厂商，可以省掉 base_url / api / models，改用内置 preset——它会 帮你填好端点和模型列表：

llm:
  model_presets:
    tiers:
      pro: { enabled: true, primary: "deepseek/deepseek-v4-flash", fallbacks: [] }
    default_preset: pro
  providers:
    deepseek:
      preset: "deepseek/cn/anthropic-messages"
      api_key: "sk-..."

preset key 格式为 vendor/region/protocol[/plan]，列在 backend/cubeplex/llm/catalog/data/vendors.yaml 中（deepseek / aliyun / volcengine / moonshot / zhipu / minimax / openrouter / anthropic / openai 等等）。

必需的密钥​

无论哪种部署模式，都需要以下三个认证密钥：

密钥用途生成命令
jwt_secret签发 / 校验用户会话 JWTopenssl rand -hex 32
csrf_secretCSRF 双提交 cookieopenssl rand -hex 32
vault_key加密 MCP / 凭证 vault 的 Fernet keypython -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

三者都是必填项。测试环境以外，任一签名密钥为空、少于 32 个字符，或使用 REPLACE_ME、USE ENV、CHANGE_ME… 等已知占位符时，后端都会拒绝启动。 Helm 也会在安装时拒绝这些占位符。

指标​

后端在 GET /metrics 提供 Prometheus 文本格式的指标，无需应用层认证。 请分别抓取每个后端实例。指标标签不包含租户、用户、对话、运行、模型或原始工具名称。 后端进程重启后计数器会重置；历史用量仍以计费记录为准。

指标含义
cubeplex_http_requests_total按路由模板、方法和状态统计已完成的 HTTP 请求。SSE 请求在流关闭时计数。
cubeplex_http_request_duration_seconds已完成的非 SSE HTTP 请求耗时，不包含健康探针和 /metrics。
cubeplex_http_requests_in_flight当前处理中的 HTTP 请求，包括 SSE 流。
cubeplex_sse_connections_active、cubeplex_sse_connections_opened_total当前打开的 SSE 流，以及进程启动以来打开的流总数。
cubeplex_agent_run_attempts_active、cubeplex_agent_run_attempts_started_total正在执行或清理的工作任务，以及按触发来源和阶段统计的已调度任务。HITL 暂停时没有活跃工作任务。
cubeplex_agent_run_attempt_duration_seconds工作任务耗时，包含清理，不包含等待 HITL 回答的时间。
cubeplex_agent_runs_finished_total本进程记录的持久化终态：completed、cancelled、errored、failed。
cubeplex_agent_hitl_pauses_total进入 HITL 暂停的运行尝试次数。
cubeplex_llm_calls_total、cubeplex_llm_tokens_total已提交的 LLM 计费事件及 token 用量。调用结果为 success 或 fallback_failed。
cubeplex_tool_calls_total按固定类别及成功或错误结果统计的已完成工具调用。

Prometheus Python 客户端还会导出 process_cpu_seconds_total、 process_resident_memory_bytes 和 process_open_fds。机器和容器资源请使用宿主机或容器 exporter， Postgres、Redis 也应使用各自的 exporter。

抓取配置参见 Docker Compose 和 Kubernetes 指南。

下一步​