LlamaCloud 开放了一小组可选的环境变量开关，用于在自托管部署里切换某些界面或行为。它们是在 Helm chart 已内置的默认值之外的补充。

所有开关都通过你 values.yaml 里相应 pod（通常是 frontend）的 extraEnvVariables 设置。

前端开关

前端开关是 LlamaCloud Web 应用读取的环境变量。不带 NEXT_PUBLIC_ 前缀的开关是在服务端按请求解析的，因此改 ConfigMap / extraEnvVariables 就能生效，无需重新构建镜像。NEXT_PUBLIC_* 类开关在构建时就被内联进客户端产物，运行时无法更改。

开关	默认值（BYOC）	作用
IS_INDEX_V1_ENABLED	true	在侧栏与 project 首页显示 Index 入口。设成 false 即隐藏。
NEXT_PUBLIC_IS_INDEX_PARSE_EDIT_DISABLED	false	禁止编辑已有索引的解析配置（构建时内联）。

覆盖某个前端开关

要覆盖默认值，把它加进 values.yaml 里的 frontend.extraEnvVariables：

frontend:
  extraEnvVariables:
    - name: IS_INDEX_V1_ENABLED
      value: "false"

取值必须是字符串（"true" / "false"）。

后端开关

后端特性开关由 LlamaCloud API 从 backend pod 的环境变量读取。命名遵循 IS_*_ENABLED / IS_*_DISABLED 约定。

开关	默认值	作用
IS_INDEX_PARSE_EDIT_DISABLED	false	NEXT_PUBLIC_IS_INDEX_PARSE_EDIT_DISABLED 的服务端对应项。
IS_MANAGED_EMBEDDINGS_ENABLED	false	把托管嵌入作为新索引的默认选项开启。更推荐用下方 config.managedEmbeddings.enabled 这个 chart 值，它会同时为后端与前端设好该项。
IS_TEMPORAL_EXTRACT_ENABLED	false	让新的 extract 任务经 Temporal 路由。
IS_NEW_DATA_CONNECTION_SSRF_PROTECTION_ENABLED	自托管为 false	要求 data sink、data source 与嵌入模型配置的端点在其被创建或更新时只能解析到公网地址。自托管部署默认关闭，因为这些端点要连的网络本就归你所有。见数据连接的 SSRF 防护。

覆盖某个后端开关

backend:
  extraEnvVariables:
    - name: IS_INDEX_PARSE_EDIT_DISABLED
      value: "true"

LlamaParse worker 开关

由 LlamaParse worker 从 temporalWorkloads.llamaParse pod 的环境变量读取。

开关	默认值（BYOC）	作用
PARSE_URL_BLOCK_INTERNAL_TARGETS	true	拒绝抓取指向非公网网络目标的解析输入 URL，也包括它跟随的任何重定向。设成 false 才能从你自己内网上的 URL 解析。

temporalWorkloads:
  llamaParse:
    extraEnvVariables:
      - name: PARSE_URL_BLOCK_INTERNAL_TARGETS
        value: "false"

从内网的 URL 做解析

光设这个 worker 开关还不够。API 也会校验提交的 URL，并对非公网主机返回 400 Invalid source URL，因此还要在后端一并列出这些主机名：

backend:
  extraEnvVariables:
    - name: SSRF_ALLOWED_HOSTS
      value: "docs.internal.example.com,files.internal.example.com"

主机名是精确匹配、忽略大小写。不支持通配符、端口与协议前缀。

这两处设置覆盖的都是抓取输入 URL 这件事。把 HTML 渲染成 PDF 过程中加载的子资源（例如图片、样式表与 iframe）则始终被限定在公网主机上，所以来自内网主机的页面会缺少那里提供的素材。

这两处设置都不能替代 LlamaParse worker pod 上的网络出口策略。如果该 pod 能够到元数据服务或内部控制面，请在网络层限制这类访问。

数据连接的 SSRF 防护

data sink、data source 与嵌入模型配置都是用你提供的连接端点来配置的 —— Qdrant 的 url、Postgres 的 host、Astra DB 的 api_endpoint、Confluence 的 server_url、MongoDB 连接串、OpenAI 兼容的 api_base 等等。LlamaCloud 会从你的集群内部去拨通这些端点，因此一个指向内部服务或云元数据地址的端点就构成服务端请求伪造（SSRF）风险。

IS_NEW_DATA_CONNECTION_SSRF_PROTECTION_ENABLED 在自托管部署上默认为 false，因为你配置的端点本来就会合法地指向自己网络内的主机。设成 true 就会在所有提交连接详情的地方检查这些端点：

• 经 /api/v1/data-sinks、/api/v1/data-sources 或 /api/v1/embedding-model-configs 创建、更新或 upsert 时。
• 经 /api/v1/pipelines 创建或更新流水线、且带的是内联的 data_sink 或 embedding_config（而不是 id）时。
• 经 /api/v1/validate-data-sink-connection、/api/v1/validate-data-source-connection 或 /api/v1/validate-embedding-connection 测试连接时。

检查跑在 LlamaCloud 验证连接之前，因此被拒的端点根本不会被联系。被检查的字段包括 api_base（OpenAI 兼容与 Gemini）、azure_endpoint、VertexAI 的 token_uri，以及当 HuggingFace 的 model_name 装的是专用端点 URL（而非模型 id）时的它。端点里点名的每一个主机都必须只解析到可公网路由的地址；私有、回环、链路本地、保留与组播地址一律拒绝。创建或更新资源返回 400；validate-*-connection 这类端点则把它报成一次校验失败。mongodb+srv:// 连接串会经其 SRV 记录解析并逐个检查每个目标；点名超过 32 个主机的连接串会被拒绝。

诊断一次被拒的连接

错误信息只点名被拒的字段，不点名它解析到的地址，因此这个检查无法被用来探测你的内网。具体信息 —— 被拦的主机、project 与用户 —— 会写进后端日志，两者由一个关联 id 串起来：

The data sink field 'url' must point to a publicly routable host.
Contact support with correlation id 4f9a2c18-....

这个 id 也出现在每一个 API 响应的 X-Correlation-ID 响应头上。要找到那个惹事的主机，就用它去搜后端日志：

终端窗口

kubectl logs -n <namespace> deploy/backend | grep 4f9a2c18-

命中的那行带有 blocked_host、reason、field_name、component_type、project_id 与 user_id。

拦截也会被计数，这样不必读日志就能看到这个检查拒了多少连接。两个计数器都从后端的指标端点导出：

指标	标签	含义
llamacloud_ssrf_data_connection_ssrf_blocked_total	connection_kind, scope, reason	被该检查拒掉的连接端点。reason 取 value_too_long、no_readable_host、too_many_hosts、host_not_publicly_routable 之一。
llamacloud_ssrf_data_connection_ssrf_unregistered_total	component_type	某类组件其端点未被校验。预期应当恒为零。

开启这个检查后要盯着第一个计数器：跳升意味着原本能用的连接现在被拒了，而涉及的主机就在日志里。

放行内网主机

如果你打开了这个检查，自托管部署仍然要能连到私网上的向量库与 Confluence 实例。请为这些主机加白名单，而不是把检查再关回去。有两种做法，且它们会叠加生效。

按精确主机名 —— SSRF_ALLOWED_HOSTS，逗号分隔的列表。它作用于后端里的每一项 SSRF 检查，包括出站 webhook 与 Parse 输入 URL（见从内网的 URL 做解析）：

backend:
  extraEnvVariables:
    - name: SSRF_ALLOWED_HOSTS
      value: "qdrant.internal,postgres.svc.cluster.local"

按模式 —— DATA_CONNECTION_SSRF_ALLOWED_HOST_PATTERNS，用于多到无法穷举的主机族。每个条目都是对整个主机名做匹配的正则表达式，而且这份列表只作用于 data sink、data source 与嵌入模型配置的检查，因此不会不小心让某个 webhook 得以向内网地址投递。

backend:
  extraEnvVariables:
    - name: DATA_CONNECTION_SSRF_ALLOWED_HOST_PATTERNS
      value: ".+\\.svc\\.cluster\\.local;.+\\.internal;10\\.0\\.\\d{1,3}\\.\\d{1,3}"

关于模式列表，有三件事要知道：

• 条目之间用分号或换行分隔，不能用逗号 —— 逗号是正则量词的一部分，例如 \d{1,3}。
• 模式会被锚定。 模式必须匹配整个主机名，所以 internal 只放行主机 internal，而不放行 internal.evil.com。
• 非法模式会被忽略，并记一条警告日志。因此一个拼写错误导致的是拦住而非开了个洞 —— 但这也意味着一个写错的模式会悄无声息地没能放行你本想放行的主机，所以改完请查日志。

请用能覆盖你那些主机的最窄表达式。像 .* 这样的模式等于把检查整个关掉。

打开这个检查

在自托管部署上强制执行默认关闭。若你的端点理应只访问公网，或者你想让上面的白名单成为「这些端点可以连哪些内网主机」的明确记录，就把它打开：

backend:
  extraEnvVariables:
    - name: IS_NEW_DATA_CONNECTION_SSRF_PROTECTION_ENABLED
      value: "true"

在检查关闭期间保存下来的连接，之后不会被重新检查，除非你同时打开另一个独立开关 IS_EXISTING_DATA_CONNECTION_SSRF_PROTECTION_ENABLED（默认 false）—— 它会在 data sink 做健康检查时复检那个已存的连接。

这两个开关都不能替代后端 pod 上的网络出口策略。连接端点只是出集群的一条路，其余的请在网络层限制。

连接失败只做泛化报告

当某个连接无法到达时，响应只说明这一点、而不引用端点返回了什么 —— 否则一次失败的连接就会把应答者的内容转述出来。底层错误会带着同一个关联 id 写进后端日志，因此照上文所说去那里搜。无论 SSRF 检查是否开启，这一点都成立。

托管嵌入与托管 Qdrant

有两个建索引选项是通过 chart 值而非裸环境变量开关启用的，而且前端现在两者都是按请求读取 —— 不需要重新构建镜像。

• 托管嵌入 —— 设 config.managedEmbeddings.enabled: true。这会把 IS_MANAGED_EMBEDDINGS_ENABLED 写进共享的 feature-config ConfigMap，由后端与前端共同消费，从而在创建索引时把托管嵌入呈现为一个默认选项。它还需要你在 LLM 提供方配置里注册一个嵌入模型（例如 openai-text-embedding-3-small）。

  config:
    managedEmbeddings:
      enabled: true

• 托管 Qdrant（“Fully Managed” data sink） —— 设 qdrant.enabled: true。chart 随后会向前端发出仅供服务端使用的 BYOC_HAS_MANAGED_QDRANT 变量，Web 应用按请求读取它来显示全托管向量库这个选项。（此前它由一个构建时的 NEXT_PUBLIC_* 变量控制，所以预构建的 BYOC 镜像无论运行时怎么配置都不会渲染该项。）

  qdrant:
    enabled: true

说明

• 这些开关只控制自托管部署的默认值。在托管的 LlamaCloud 里，同样的特性开关是经 PostHog 解析的；在 BYOC / 自托管里，环境变量值才是权威。
• 当一个前端开关有后端对应项（例如 API 里的 IS_*）时，请把两边一致地设好，以免界面与 API 出现偏差。