把 LlamaCloud helm chart 装进你的 Kubernetes 环境后，立刻就能用下面这条命令把 frontend 服务端口转发到本机来测试这次部署：

终端窗口

kubectl --namespace <your-namespace> port-forward svc/llamacloud-web 3000:80

该命令跑起来后，就能在 http://localhost:3000 访问 LlamaCloud 界面。

初期测试或许够用，但当你把部署推向生产、并把 LlamaCloud 当作 API 服务来用时，最终还是要配好 ingress。

要求

• 一个 super-cool.domain 域名
• 已在你的 Kubernetes 集群里部署好 ingress 控制器
  • 常见的选择是 ingress-nginx

Helm chart 的配置

自 0.1.47 版本起，LlamaCloud 的 helm chart 支持为你的部署配置一个 ingress 资源。chart 支持下列配置：

values.yaml

ingress:
  enabled: true
  host: "<YOUR-HOSTNAME>"
  tlsSecretName: "ingress-nginx-secret"
  ingressClassName: "nginx"
  annotations: {}

我们推荐就用上面这套 helm chart 配置来建 ingress 资源。

ingress 端点配好后，就能在 https://<your-domain-name> 访问 LlamaCloud 界面。你也可以查看 ingress 资源的状态：

终端窗口

kubectl -n llamacloud get ingress

# Example output
NAME                 CLASS    HOSTS                ADDRESS                              PORTS    AGE
llamacloud-ingress   nginx    llamacloud.example   <ip-or-load-balancer-address>        80, 443  10m

ingress 的路由明细

• /api：把所有路径前缀为 /api 的请求路由到 llamacloud 服务
• /deployments：把智能体 deployment 的请求路由到 llamacloud 服务
• /：把其余所有请求路由到 llamacloud-web 服务

如果你启用 MCP 服务并在 config.mcp.publicUrl 里给它一个自己的域名，chart 会新增一个 host 而不是多加若干路径 —— 因为 MCP 响应的路径正是 Web 界面已经在用的。DNS 与证书方面的要求见那一页。

TLS 配置

视你的 ingress 控制器而定，你可能需要给 ingress 资源加一个 TLS secret，这可以写在 .Values.ingress.tlsSecretName 字段里。chart 使用单个 TLS secret：它既覆盖 ingress 的 host，也在 MCP 用自己的域名启用时覆盖 MCP 的域名 —— 所以证书需要为每一个名字准备一个使用者替代名（SAN），或者用通配证书。关于 TLS Secret 的更多信息，见 Kubernetes Ingress 文档。

自行管理的 ingress

要为你这次部署配置 ingress，请把下面这份 ingress 资源应用到集群：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: llamacloud
  namespace: llamacloud
spec:
  ingressClassName: <YOUR-INGRESS-CLASS-NAME>
  rules:
    http:
      paths:
      - backend:
          service:
            name: llamacloud
            port:
              number: 80
        path: /api
        pathType: Prefix
      - backend:
          service:
            name: llamacloud-web
            port:
              number: 80
        path: /
        pathType: Prefix

关于 ingress 资源的配置，见 Kubernetes Ingress 文档。

BACKEND_URL 配置

BACKEND_URL 环境变量供 Frontend 服务用来决定把 /api 请求发往何处。当你自行管理 ingress 资源时，建议显式设置这个环境变量，这样 Frontend 就不必依赖内部的 NextJS 代理去把请求路由到 Backend 服务。

# The helm charts will automatically configure the BACKEND_URL environment variable for the Frontend service to point to the ingress host.
ingress:
  enabled: true
  host: <YOUR-DOMAIN-NAME>
  tlsSecretName: "tls-secret-name"

# alternative values.yaml
frontend:
  extraEnvVariables:
    - name: BACKEND_URL
      value: "https://<your-domain-name>"
  volumeMounts:
    - mountPath: "/mount/path/to/your/certificate-mount-path/cert.pem"
      name: ca-certs
      readOnly: true
  volumes:
    - name: ca-certs
      secret:
        secretName: ca-cert-secret

常见问题

• ingress 资源创建后，frontend 服务有时无法完成对证书的校验。若如此，用户会感到登录流程变慢或失败，并可能在 frontend 日志里看到 UNABLE_TO_VERIFY_LEAF_SIGNATURE 错误。

  • 这个问题有省事与彻底两种解法。

  • 省事的做法是在 Frontend 部署里设 NODE_TLS_REJECT_UNAUTHORIZED=0（通过 .Values.frontend.extraEnvVariables）。这会让 Frontend 忽略证书错误。这一做法的代价是：它可能不被你组织的安全策略接受。

  • 彻底的做法是让 Frontend pod 能够校验你用来签署 ingress 域名的那张证书。你可以把证书挂载进 Frontend pod 来实现。

  • 若你用的是自签证书，可以用下面的命令生成证书与私钥：

    终端窗口

    # create a configmap with the Certificate Authority
    kubectl create configmap ca-cert-config --from-file=<certificate-authority-name>.pem=/local/path/to/your/<certificate-authority-name>.pem

  • 然后，把这份 configmap 挂载进 Frontend pod，并添加 NODE_EXTRA_CA_CERTS 环境变量：

    # In the values.yaml file:
    frontend:
      extraEnvVariables:
        - name: NODE_EXTRA_CA_CERTS
          value: "/mount/path/to/your/certificate-mount-path/cert.pem"

• 若你没有自动化的 DNS 配置，就需要把 ingress 资源的 IP 地址提供给你的 DNS 服务商。

在配置 ingress 资源方面需要帮助，请通过 support at llamaindex.ai 联系我们。