版本：8.2.0

GuanMCP 部署指南

更新时间：2026-06-25 10:58:15

部署概述

本文介绍 GuanMCP 的两种部署方式：本地 stdio 模式和生产 streamable-http 模式。

模式	适用场景	说明
`stdio`	个人桌面客户端、演示、开发联调	MCP 客户端在本机启动 GuanMCP 进程，通常代表一个固定用户访问一个 BI 站点。
`streamable-http`	企业 AI 平台或网关统一接入	GuanMCP 作为 HTTP 服务常驻运行，客户端通过 `POST /mcp` 调用。

stdio 是本地固定用户方案，不适合作为企业多用户接入方案。企业多用户场景建议使用 streamable-http 模式，并通过 Kubernetes、企业容器平台或网关部署。

Kubernetes 部署中的 ConfigMap、Secret、Deployment 和 Service 是基础部署文件。对接飞书 Aily 时，只需要在基础部署文件上追加少量配置。

本地 stdio 部署

本地 stdio 模式适合个人桌面客户端、演示和开发联调。客户端启动一个本地 GuanMCP 进程，代表一个固定用户访问一个 BI 站点。

登录方式

本地模式登录方式二选一：

登录方式	说明
`BI_UID_TOKEN`	使用当前用户 token 登录。
`BI_LOGIN_DOMAIN`、`BI_LOGIN_ID`、`BI_LOGIN_PASSWORD`	使用账号密码登录。

客户端配置示例

在支持 MCP 的客户端中添加服务配置，核心是 BI 地址和当前用户登录信息。

{
  "mcpServers": {
    "guanbi": {
      "command": "npx",
      "args": ["-y", "@guandata/guanbi-mcp-server@latest"],
      "env": {
        "BI_BASE_URL": "https://your-bi-host.example.com",
        "BI_UID_TOKEN": "current-user-token"
      }
    }
  }
}

如果使用账号密码登录，请将 BI_UID_TOKEN 替换为对应的账号密码环境变量。

生产 HTTP 部署

生产环境建议使用 streamable-http 模式。镜像默认监听 0.0.0.0:9090。

关键端点

端点	用途
`POST /mcp`	MCP 调用入口
`GET /healthz`	健康检查
`GET /sysmon/health/liveness`	存活探针
`GET /sysmon/health/readiness`	就绪探针

路由建议

优先使用独立域名，例如 https://guanbi-mcp.example.com/mcp。
复用 BI 域名时，使用独立前缀，并在网关 rewrite 到后端 /mcp。
多副本需要按 Mcp-Session-Id 做粘性路由；无法配置粘性路由时，建议先使用单副本。

部署前准备

确认 BI 访问地址

在 guanbi-mcp-server-configmap.yaml 中，将 BI_BASE_URL 修改为客户实际可访问的 BI 地址。

BI_BASE_URL: "https://your-bi-host.example.com"

同时根据客户 BI 的访问路径配置 BI_PUBLIC_PATH：

BI 访问方式	BI_PUBLIC_PATH 配置
无前缀路径，例如 `https://bi.example.com`	`/`
有前缀路径，例如 `https://bi.example.com/guanbi`	`/guanbi`

示例：

BI_PUBLIC_PATH: "/"
# 或
BI_PUBLIC_PATH: "/guanbi"

生成 MCP 入口 Token

MCP_ENTRYPOINT_TOKEN 用于客户端连接 MCP 服务，需要单独生成，并通过 Kubernetes Secret 注入。

生成随机 token：

openssl rand -base64 32

创建 guanbi-mcp-server-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: guanbi-mcp-server
type: Opaque
stringData:
  MCP_ENTRYPOINT_TOKEN: "<替换为上一步生成的 token>"

生成后的 token 需要通过安全方式发送给客户。不要将真实 token 提交到代码仓库、工单附件或公开文档中。

Kubernetes 配置文件

guanbi-mcp-server-configmap.yaml

kind: ConfigMap
apiVersion: v1
metadata:
  name: guanbi-mcp-server
data:
  MCP_TRANSPORT: streamable-http
  MCP_HTTP_HOST: "0.0.0.0"
  MCP_HTTP_PORT: "9090"
  BI_BASE_URL: "https://your-bi-host.example.com"
  BI_PUBLIC_PATH: "/"
  BI_REQUEST_TIMEOUT_MS: "120000"
  BI_MAX_ROWS: "1000"
  GUANBI_MCP_USAGE_STATS: ""
  MCP_TRUSTED_GATEWAY: "false"

guanbi-mcp-server-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: guanbi-mcp-server
type: Opaque
stringData:
  MCP_ENTRYPOINT_TOKEN: "<替换为生成的 MCP 入口 token>"

guanbi-mcp-server-controller.yaml

kind: Deployment
apiVersion: apps/v1
metadata:
  name: guanbi-mcp-server-controller
spec:
  replicas: 1
  selector:
    matchLabels:
      app: guanbi-mcp-server
  template:
    metadata:
      labels:
        app: guanbi-mcp-server
    spec:
      imagePullSecrets:
        - name: gd-cr-registry
      containers:
        - name: guanbi-mcp-server
          image: guandata-registry.cn-hangzhou.cr.aliyuncs.com/guandata/guanbi-mcp-server:0.1.14
          imagePullPolicy: IfNotPresent
          envFrom:
            - configMapRef:
                name: guanbi-mcp-server
          env:
            - name: TZ
              value: Asia/Shanghai
            - name: MCP_ENTRYPOINT_TOKEN
              valueFrom:
                secretKeyRef:
                  name: guanbi-mcp-server
                  key: MCP_ENTRYPOINT_TOKEN
                  optional: false
          ports:
            - name: http
              containerPort: 9090
          livenessProbe:
            httpGet:
              path: /sysmon/health/liveness
              port: 9090
            initialDelaySeconds: 10
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /sysmon/health/readiness
              port: 9090
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          resources:
            requests:
              cpu: 100m
              memory: 256Mi
            limits:
              cpu: 1000m
              memory: 1Gi

image 需要按客户环境替换为实际镜像地址和版本。若客户使用私有镜像仓库，请确认集群已配置拉取凭证。

guanbi-mcp-server-service.yaml

kind: Service
apiVersion: v1
metadata:
  name: guanbi-mcp-server
spec:
  type: ClusterIP
  ports:
    - name: http
      port: 9090
      targetPort: 9090
  selector:
    app: guanbi-mcp-server

当前示例使用 ClusterIP。如果需要对外暴露，请结合客户环境配置 Ingress、网关或其他暴露方式。

部署步骤

建议按以下顺序执行：

kubectl apply -f guanbi-mcp-server-configmap.yaml
kubectl apply -f guanbi-mcp-server-secret.yaml
kubectl apply -f guanbi-mcp-server-controller.yaml
kubectl apply -f guanbi-mcp-server-service.yaml

部署后检查 Pod 和 Service 状态：

kubectl get pod -l app=guanbi-mcp-server
kubectl get svc guanbi-mcp-server

如需查看启动日志：

kubectl logs -l app=guanbi-mcp-server --tail=200

如果客户集群使用非默认命名空间，请在所有 kubectl apply 和检查命令中增加 -n <namespace>。

对接飞书 Aily

如需对接飞书 Aily，需要在基础部署配置上额外调整 ConfigMap、Secret 和 Deployment。

以下配置是 Aily 对接场景的补充配置，不是基础部署的必填项。

修改 ConfigMap

在 guanbi-mcp-server-configmap.yaml 的 data 中添加以下配置：

BI_LOGIN_ID_HEADER: ""
BI_USER_PROPERTY_HEADER: "x-aily-user"
BI_USER_PROPERTY_KEY: "feishu"

这几项配置用于飞书 Aily 用户身份映射。对接其他渠道时，请先确认对应 header 和用户属性 key。

获取账号同步令牌

在观远 BI 的对应页面获取账号同步令牌。该令牌用于将外部账号映射到 GuanBI 用户。

账号同步令牌属于敏感信息，需要写入 Secret，不要写入普通 ConfigMap。

修改 Secret

将账号同步令牌写入 guanbi-mcp-server-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: guanbi-mcp-server
type: Opaque
stringData:
  MCP_ENTRYPOINT_TOKEN: "<之前创建的 MCP 入口 token>"
  BI_APP_TOKEN: "<账号同步令牌>"

修改 Deployment

在 guanbi-mcp-server-controller.yaml 的 env 中添加 BI_APP_TOKEN：

            - name: BI_APP_TOKEN
              valueFrom:
                secretKeyRef:
                  name: guanbi-mcp-server
                  key: BI_APP_TOKEN
                  optional: true

修改完成后重新应用配置：

kubectl apply -f guanbi-mcp-server-configmap.yaml
kubectl apply -f guanbi-mcp-server-secret.yaml
kubectl apply -f guanbi-mcp-server-controller.yaml

客户端接入配置

HTTP 客户端

HTTP 客户端访问 MCP 服务入口：

POST https://guanbi-mcp.example.com/mcp

未启用可信网关时，需要携带入口凭证：

Authorization: Bearer <mcp_service_token>

再按身份方案携带当前真实用户身份，常见方式如下：

身份方式	请求侧携带	适用场景
直传 uIdToken	`X-GuanBI-Uid-Token: <current_user_uid_token>`	上游已拿到 GuanBI 用户 token。
loginId 换 token	`X-GuanBI-Login-Id: <current_user_login_id>`	上游能确认 GuanBI loginId。
外部账号映射	`<external-user-header>: <external_user_id>`	上游只有飞书账号等外部 ID。

推荐由网关注入身份 header，并丢弃外部请求自带的同名 header。

飞书 Aily 客户端

Aily 场景建议走外部账号映射模式。Aily 侧只需要配置 MCP 服务地址和入口凭证：

客户端配置	说明
MCP 服务地址	例如 `https://guanbi-mcp.example.com/mcp`。
`Authorization`	`Bearer <mcp_service_token>`，与服务端 `MCP_ENTRYPOINT_TOKEN` 对应。

Aily 用户标识由平台自动带入，客户端侧不要配置 BI token、loginId 或 BI_APP_TOKEN。

关键配置

配置	说明
`BI_BASE_URL`	必填，绑定当前 MCP 服务访问的 BI 站点。
`BI_PUBLIC_PATH`	必填；无前缀路径填 `/`，部署在子路径下时填写对应前缀，例如 `/guanbi`。
`MCP_TRANSPORT`	`stdio` 或 `streamable-http`。
`BI_UID_TOKEN`	`stdio` 本地用户 token。
`BI_LOGIN_DOMAIN` / `BI_LOGIN_ID` / `BI_LOGIN_PASSWORD`	`stdio` 本地账号密码登录。
`MCP_ENTRYPOINT_TOKEN`	HTTP 入口凭证，建议放入 Secret。
`MCP_TRUSTED_GATEWAY`	设为 `true` 时不需要 `MCP_ENTRYPOINT_TOKEN`；只能在可信网关已鉴权、已注入身份时开启。
`BI_APP_TOKEN`	身份交换用服务端密钥，必须放入 Secret；基础部署不需要配置。
`BI_LOGIN_ID_HEADER`	loginId 身份 header，默认 `x-guanbi-login-id`。
`BI_USER_PROPERTY_HEADER` / `BI_USER_PROPERTY_KEY`	外部账号映射到 BI 用户时使用。
`BI_MAX_ROWS`	SQL 返回行数上限，默认 `1000`。
`GUANBI_MCP_USAGE_STATS`	设为 `0`、`false`、`off`、`no` 可关闭匿名统计。

权限和安全边界

MCP 入口凭证只证明调用方可以访问 MCP，不证明调用方可以查看 BI 数据。
BI 数据权限由 GuanBI 根据当前用户身份判断。
HTTP 模式每次请求都要解析出当前真实用户，不能用进程级固定用户代查。
x-tenant-id、x-end-user-id、x-trace-id 只用于观测，不能替代 BI 授权。
BI_APP_TOKEN 不能由客户端传入，只能由服务端保存。
身份交换 debug 只适合临时排查，排查后应关闭。
GuanMCP 默认只上报聚合 tool 调用统计，不采集问题、SQL、token、返回内容或用户身份。

上线验收

上线前完成以下检查：

健康检查返回正常。
get_bi_capabilities 能看到 BI 站点、运行模式和工具列表。
低权限用户只能访问自己在 BI 中有权限的资源。
HTTP 未带入口凭证时应被拒绝，除非已启用可信网关。
Aily 场景中，客户端只配置 Authorization；userId 由平台自动带入，并能映射到唯一 BI 用户。
卡片链路可完成：搜索资源 -> 读卡片信息 -> 只读取数。
指标链路可完成：搜索指标 -> 读口径 -> 查询数据。
ChatBI 链路可完成：列主题 -> 问数，或发起洞察 -> 轮询报告。
SQL 链路需确认 BI 版本和高级 SQL 开关；表名使用数据集显示名称。

常见误区

工具可见不等于用户有资源权限。
BI_APP_TOKEN 不能由客户端传，只能服务端保存。
普通卡片查询是只读读取已保存结果，不修改卡片。
SQL 查询不是默认一定可用，依赖 BI 能力和开关。

注意事项

BI_BASE_URL 必须填写客户实际可访问的 BI 地址。
BI_PUBLIC_PATH 需与客户 BI 的访问前缀保持一致；无前缀时配置为 /。
MCP_ENTRYPOINT_TOKEN 和 BI_APP_TOKEN 都属于敏感信息，需要通过 Secret 管理，不建议明文写入普通 YAML、代码仓库或公开文档。
BI_APP_TOKEN 仅在需要账号同步或外部账号映射时配置；基础部署不需要配置。
镜像版本当前示例为 0.1.14；如客户环境需要指定版本，部署前需确认镜像 tag。
当前 Service 类型为 ClusterIP；如果需要对外暴露，需要结合客户环境使用 Ingress、网关或其他暴露方式。
如果客户集群命名空间不是默认命名空间，所有 kubectl apply 和检查命令需要增加 -n <namespace>。

部署概述​

本地 stdio 部署​

登录方式​

客户端配置示例​

生产 HTTP 部署​

关键端点​

路由建议​

部署前准备​