跳到主要内容

部署概览

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

选择部署方式​

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

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

Agent 沙箱​

CubePlex 在沙箱里执行 agent 的工具调用（bash、文件读写等）。基础安装只提供 对话能力，在配置好沙箱之前工具调用都会失败——所以大多数部署都会需要它。 两篇指南都把它作为清晰标注的步骤：内置的 alibaba OpenSandbox（Kubernetes 上是子 chart， Docker Compose 上是 overlay），或一个外部沙箱端点。沙箱镜像默认走 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 也会在安装时拒绝这些占位符。

下一步​