部署 LogBamboo¶

本指南介绍如何在 Kubernetes 中部署单节点 LogBamboo，并准备数据转发所需的连接信息。完成后，可继续配置数据转发。

LogBamboo 的后端与 Web UI 使用同一个容器镜像，社区版与商业版通过授权区分，商业版通过管理界面激活。部署方式与版本能力可参考 LogBamboo 产品介绍。

本文示例面向全新单节点部署，以 S3 主存储为主，同时给出本地存储和 OSS 的替换方法。域名、镜像地址、存储地址及所有 REPLACE_WITH_ 内容均需替换；已有部署应保留原配置、存储前缀和身份，不能用新部署模板直接覆盖。

部署前准备¶

开始前，请准备：

准备项	要求
Kubernetes 集群	准备命名空间、可用节点、CSI / StorageClass；使用 Ingress 时，集群中需已部署可用入口控制器
容器镜像	获取与节点 CPU 架构匹配的 LogBamboo 镜像，确认集群能够拉取；镜像仓库需要认证时，准备对应的拉取凭据
持久化存储	本文示例使用 200 GiB PVC，保存 state、WAL 和临时构建数据；若使用本地主存储，还需容纳最终日志数据。容量须按写入量、故障缓存时间及保留策略规划
对象存储（可选）	使用 S3 时，准备 Endpoint、Region、Bucket、当前部署独占的新 Prefix、AK/SK，以及该前缀所需的列举、读取、写入、分片上传和清理权限；Pod 必须能访问 Endpoint
登录与接口凭据	管理员密码、写入 Token、查询 Token 分别准备；管理员密码为 12–128 UTF-8 字节，两个 Token 至少 16 字节且互不相同
HTTPS 入口	准备域名解析、覆盖该域名的有效证书与私钥，由已有 Ingress 控制器终止 TLS
网络访问	管理人员和数据转发服务均需能够访问正式 HTTPS 域名；后端 8080 仅供受控网络内访问

还未获取容器镜像或需要确认资源规格时，请联系销售或部署支持。

单节点无需额外部署 Redis。使用 S3 也必须保留 PVC：远端保存日志对象，PVC 中的 state_dir 保存 WAL、节点身份和单节点控制状态，两者不可互相替代。本地主存储仅支持单节点；多节点需要另外规划共享对象存储、Redis 控制面及相应授权，不能直接将本文副本数改为 2。

第一步：获取镜像并准备部署资源¶

请联系销售或部署支持获取 LogBamboo 容器镜像及对应版本的部署说明，并确认镜像支持的节点架构。将提供的完整镜像地址（含版本号）填入下方 Deployment 的 image: REPLACE_WITH_IMAGE；

先只读核对目标集群和可用资源：

kubectl config current-context
kubectl get storageclass
kubectl get ingressclass
kubectl get namespace utils

本文以 utils 命名空间为例。CPU / 内存上限 2 CPU / 4 GiB、PVC 200 GiB 是示例规格，不是生产容量承诺。请先确定目标 StorageClass、IngressClass、域名和证书，第二步给出完整资源清单。

第二步：配置存储、凭据和 HTTPS，并启动服务¶

S3 信息具体填在哪里¶

将以下连接参数写入 ConfigMap/logbamboo-config 的 logbamboo.toml 中的 [storage] 段。AK/SK 的值放在 Secret/logbamboo-object-storage 中，由 Deployment 注入环境变量；TOML 中只写环境变量名称。

信息	TOML 字段	填写说明
S3 API 地址	`endpoint`	完整 URL，如 `https://s3.ap-southeast-1.amazonaws.com`；使用服务 API 地址，不是控制台网址，不在 URL 中拼接 Bucket 或 Prefix
区域	`region`	与 Bucket 所在区域和签名要求一致，如 `ap-southeast-1`
存储桶	`bucket`	已创建的桶名，部署模板不负责创建 Bucket
数据目录前缀	`prefix`	为本部署分配未使用的前缀，如 `logbamboo/prod-a`；后续升级必须复用原前缀
Access Key	`access_key_env`	固定引用 `LOGLAKE_OBJECT_ACCESS_KEY`；真实值放 Secret
Secret Key	`secret_key_env`	固定引用 `LOGLAKE_OBJECT_SECRET_KEY`；真实值放 Secret
寻址方式	`path_style`	示例 `false` 表示 virtual-hosted style；S3 兼容服务要求 path-style 时改为 `true`，并验证 DNS、证书与服务端支持
数据保护方式	`protection_mode`	示例为 `application_only`，表示应用侧保护，不表示已启用云端 WORM

S3 兼容性不仅是能连接 Endpoint，还需验证程序使用的条件写入、分片上传、读取和清理能力。内网 Endpoint 只适用于可达该内网的节点，跨云部署不能直接复用。主存储、冷归档与独立灾备是不同配置；本文仅配置主存储，后续数据转发规则不需要再次填写 S3 参数。

准备完整部署配置¶

下面是一份完整的单 Pod + S3 + PVC + HTTPS Ingress清单。保存为 logbamboo.yaml，替换所有占位符和 logbamboo.example.com。Ingress 注解适用于现有的 ingress-nginx 控制器；其他控制器应使用其对应配置。创建 Ingress 资源本身不会安装入口控制器，也不会自动创建证书或 DNS 记录。

凭据使用 Secret.stringData 便于说明对应关系；填写后的文件含明文凭据，应限制本地文件权限，并按凭据管理方式保存。没有任何实际 AK/SK 或 Token 包含在下列模板中。

apiVersion: v1
kind: Namespace
metadata:
  name: utils
---
apiVersion: v1
kind: Secret
metadata:
  name: logbamboo-auth
  namespace: utils
type: Opaque
stringData:
  admin-password: "REPLACE_WITH_ADMIN_PASSWORD"
  ingest-token: "REPLACE_WITH_UNIQUE_INGEST_TOKEN"
  search-token: "REPLACE_WITH_DIFFERENT_SEARCH_TOKEN"
---
apiVersion: v1
kind: Secret
metadata:
  name: logbamboo-object-storage
  namespace: utils
type: Opaque
stringData:
  access-key: "REPLACE_WITH_OBJECT_ACCESS_KEY"
  secret-key: "REPLACE_WITH_OBJECT_SECRET_KEY"
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: logbamboo-config
  namespace: utils
data:
  logbamboo.toml: |
    listen = "0.0.0.0:8080"
    allow_insecure_http = true
    state_dir = "/var/lib/logbamboo/state"
    require_state_dir_fsync = true

    # 示例按 200 GiB 持久化盘预留；不是业务容量承诺。
    state_max_bytes = 85899345920
    wal_max_bytes = 42949672960
    staging_max_bytes = 34359738368
    state_reserved_free_bytes = 10737418240
    staging_min_free_bytes = 5368709120
    wal_high_watermark_bytes = 32212254720
    wal_low_watermark_bytes = 21474836480

    # 单实例示例预算；需结合真实写入、查询负载观察 RSS 后调整。
    max_request_bytes = 67108864
    max_records_per_request = 1000000
    max_ingest_inflight_bytes = 268435456
    segment_build_concurrency = 1
    segment_index_workers = 1
    build_memory_max_bytes = 1073741824
    max_concurrent_queries = 1
    query_memory_max_bytes = 1073741824

    [cluster]
    maintenance_enabled = true

    [storage]
    type = "s3"
    endpoint = "https://REPLACE_WITH_S3_ENDPOINT"
    region = "REPLACE_WITH_REGION"
    bucket = "REPLACE_WITH_BUCKET"
    prefix = "REPLACE_WITH_NEW_DEDICATED_PREFIX"
    access_key_env = "LOGLAKE_OBJECT_ACCESS_KEY"
    secret_key_env = "LOGLAKE_OBJECT_SECRET_KEY"
    path_style = false
    protection_mode = "application_only"

    [[tenants]]
    id = "default"
    ingest_token_env = "LOGLAKE_TOKEN"
    search_token_env = "LOGLAKE_SEARCH_TOKEN"

    [[tenants.indexes]]
    name = "app"
    retention = "7d"
    retention_policy_revision = 1

    [web_ui]
    public_url = "https://logbamboo.example.com"
    # 按现场填写会覆盖 X-Real-IP 的可信代理的精确 IP；不要照抄回环地址。
    trusted_proxy_ips = []

    [web_ui.auth_state]
    mode = "memory"
    single_replica = true

    [web_ui.auth]
    mode = "local"
    admin_username = "admin"
    admin_password_env = "LOGLAKE_ADMIN_PASSWORD"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: logbamboo-data
  namespace: utils
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: REPLACE_WITH_STORAGE_CLASS
  resources:
    requests:
      storage: 200Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: logbamboo
  namespace: utils
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: logbamboo
  template:
    metadata:
      labels:
        app: logbamboo
    spec:
      terminationGracePeriodSeconds: 120
      securityContext:
        runAsNonRoot: true
        runAsUser: 10001
        runAsGroup: 10001
        fsGroup: 10001
        fsGroupChangePolicy: OnRootMismatch
      # 私有镜像仓库需在本命名空间准备凭据，再启用：
      # imagePullSecrets:
      #   - name: YOUR_IMAGE_PULL_SECRET
      containers:
        - name: logbamboo
          image: REPLACE_WITH_IMAGE
          imagePullPolicy: IfNotPresent
          command: ["/usr/local/bin/logbamboo"]
          args: ["--config", "/etc/logbamboo/logbamboo.toml"]
          ports:
            - name: http
              containerPort: 8080
          env:
            - name: LOGLAKE_UI_DIR
              value: /usr/share/logbamboo/ui
            - name: LOGLAKE_ADMIN_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: logbamboo-auth
                  key: admin-password
            - name: LOGLAKE_TOKEN
              valueFrom:
                secretKeyRef:
                  name: logbamboo-auth
                  key: ingest-token
            - name: LOGLAKE_SEARCH_TOKEN
              valueFrom:
                secretKeyRef:
                  name: logbamboo-auth
                  key: search-token
            - name: LOGLAKE_OBJECT_ACCESS_KEY
              valueFrom:
                secretKeyRef:
                  name: logbamboo-object-storage
                  key: access-key
            - name: LOGLAKE_OBJECT_SECRET_KEY
              valueFrom:
                secretKeyRef:
                  name: logbamboo-object-storage
                  key: secret-key
          resources:
            requests:
              cpu: "1"
              memory: 2Gi
            limits:
              cpu: "2"
              memory: 4Gi
          startupProbe:
            httpGet:
              path: /livez
              port: http
            periodSeconds: 10
            failureThreshold: 30
          livenessProbe:
            httpGet:
              path: /livez
              port: http
            periodSeconds: 20
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /readyz
              port: http
            periodSeconds: 10
            failureThreshold: 3
          volumeMounts:
            - name: config
              mountPath: /etc/logbamboo/logbamboo.toml
              subPath: logbamboo.toml
              readOnly: true
            - name: data
              mountPath: /var/lib/logbamboo
      volumes:
        - name: config
          configMap:
            name: logbamboo-config
        - name: data
          persistentVolumeClaim:
            claimName: logbamboo-data
---
apiVersion: v1
kind: Service
metadata:
  name: logbamboo
  namespace: utils
spec:
  type: ClusterIP
  selector:
    app: logbamboo
  ports:
    - name: http
      port: 8080
      targetPort: http
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: logbamboo
  namespace: utils
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "64m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
spec:
  ingressClassName: REPLACE_WITH_INGRESS_CLASS
  tls:
    - hosts:
        - logbamboo.example.com
      secretName: logbamboo-tls
  rules:
    - host: logbamboo.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: logbamboo
                port:
                  number: 8080

PVC、配置、凭据和入口的对应关系：

项目	本清单中的配置与作用
PVC 声明	`PersistentVolumeClaim/logbamboo-data` 向指定 StorageClass 申请 200 GiB 卷。使用支持动态供给的 StorageClass 时，无需再手写 PV；若不支持，需先由集群管理员准备匹配的 PV
Deployment 引用 PVC	`volumes[].persistentVolumeClaim.claimName: logbamboo-data` 引用上述 PVC，`volumeMounts` 挂载到 `/var/lib/logbamboo`；TOML 的 `state_dir` 位于该挂载内
为什么使用 S3 还要 PVC	S3 保存主日志对象，PVC 保存尚未发布的 WAL、节点身份、单节点控制状态和临时文件；删除 PVC 后重建 Pod 不能保证恢复原部署
单实例更新	`replicas: 1` 配合 `Recreate`，避免常规滚动更新时两个实例同时使用同一状态目录；不配置 HPA。`ReadWriteOnce` 限制的是节点挂载，不是单 Pod 锁
写盘权限	镜像以 UID/GID `10001` 运行，`fsGroup: 10001` 需得到 CSI 支持；若不能写入，先核对存储驱动和目录权限
TOML 挂载	ConfigMap 文件挂载到 `/etc/logbamboo/logbamboo.toml`，容器明确以 `--config` 读取；不是挂到数据目录，也不会进入首次向导
环境变量注入	`logbamboo-auth` 注入管理员密码和两个 Token；`logbamboo-object-storage` 注入 S3 AK/SK。名称与 TOML 的 `*_env` 引用完全对应
服务与域名	`Ingress /` → `Service/logbamboo:8080` → Pod `8080`。Service 为 ClusterIP，不单独开放公网 8080
TLS	`utils/logbamboo-tls` 保存证书与私钥；`spec.tls.hosts`、`rules.host`、证书域名和 `web_ui.public_url` 必须对应
真实来源 IP	示例不猜测 Ingress 源 IP，因此 `trusted_proxy_ips = []`；部署后应按会覆盖 `X-Real-IP` 的可信代理精确 IP 配置，否则代理后的用户会共享来源 IP 登录限流

PVC 访问模式与动态供给说明见 Kubernetes 持久卷文档；HTTPS 跳转和请求体大小注解见 ingress-nginx 官方说明。

准备证书并部署¶

先创建或确认命名空间；将证书文件路径替换为实际路径。已有覆盖该域名的 TLS Secret 时，直接在 Ingress 中引用它，无需重新创建。

kubectl create namespace utils --dry-run=client -o yaml | kubectl apply -f -
kubectl -n utils create secret tls logbamboo-tls \
  --cert=/path/to/fullchain.pem \
  --key=/path/to/privkey.pem

将 DNS 指向实际 Ingress 对外 IP 或负载均衡地址。填写完成后检查占位符；如仍有输出，先补齐，不要应用：

grep -nE 'REPLACE_WITH_|logbamboo\.example\.com' logbamboo.yaml
chmod 0600 logbamboo.yaml

按目标环境的变更流程执行校验、审查和部署：

kubectl apply --dry-run=server -f logbamboo.yaml
kubectl diff -f logbamboo.yaml
# diff 返回 1 通常表示存在待应用差异；确认差异后再继续。
kubectl apply -f logbamboo.yaml
kubectl -n utils rollout status deployment/logbamboo --timeout=300s
kubectl -n utils get pvc/logbamboo-data
kubectl -n utils get pods -l app=logbamboo
kubectl -n utils get service/logbamboo ingress/logbamboo
kubectl -n utils logs deployment/logbamboo --tail=100

确认 PVC 为 Bound、Pod 为 1/1 Ready。延迟绑定 StorageClass 可能在 Pod 调度后才绑定 PVC；持续 Pending 时检查 PVC / Pod 事件及 CSI。镜像拉取失败先检查实际版本、架构和仓库认证。此处 dry-run 只校验 API 接受情况，不能替代存储及服务运行验收。

改用本地磁盘、OSS 或其他对象存储¶

主存储只选一种。替换 ConfigMap 中整个 [storage] 块，不要在原块后再追加第二个同名块。已写入数据的部署切换存储属于迁移，不按新部署模板直接切换。

使用本地主存储时：

[storage]
type = "local"
root = "/var/lib/logbamboo/data"

此时同一 PVC 同时保存 state 和最终日志，容量要重新估算；可从清单中删除 logbamboo-object-storage Secret 及对应两个环境变量引用，仍须保留 PVC。

使用阿里云 OSS 原生接口时：

[storage]
type = "oss"
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
bucket = "REPLACE_WITH_OSS_BUCKET"
prefix = "REPLACE_WITH_NEW_DEDICATED_PREFIX"
access_key_env = "LOGLAKE_OBJECT_ACCESS_KEY"
secret_key_env = "LOGLAKE_OBJECT_SECRET_KEY"
protection_mode = "application_only"

OSS 不添加 S3 专用的 region、path_style 字段，AK/SK 的注入方式不变。火山 TOS 可通过对应 S3 API 使用 type = "s3"，填写实际 Region 和 S3 Endpoint；本文不把尚未现场验收的其他 S3 兼容服务视为已验证生产方案。

验证正式 HTTPS 入口¶

在能够访问正式入口的网络执行，域名替换为实际值；企业内部 CA 或自签证书需通过 --cacert 指定受信任 CA 文件：

curl --fail --show-error https://logbamboo.example.com/readyz
curl --fail --show-error https://logbamboo.example.com/ingest-readyz

两项请求应成功返回 2xx（可无正文）；再通过浏览器打开同一 HTTPS 域名，使用管理员账号登录，确认索引可见。仍需从数据转发服务所在网络验证可达性，并按第四步完成真实写入和查询验收；页面可访问或健康检查成功不代表完整数据链路已验收。

第三步：确认索引并准备连接信息¶

确认或新增索引¶

上述配置已定义租户 default 和索引 app，保留策略为 7d。索引由服务端 TOML 定义，当前管理页面不提供索引创建和删除功能。登录后先确认左侧列表中存在 app；保留期按业务要求修改。

Standalone 使用一个租户，可在该租户下配置多个索引。多个索引共享主存储、租户级 Token 和总容量，但分别保存数据并应用各自保留策略。新增索引时，保留原有块，在同一租户下追加，例如：

[[tenants.indexes]]
name = "audit"
retention = "7d"
retention_policy_revision = 1

修改前导出并审查当前配置，按所在环境的变更流程更新配置并重启服务。Kubernetes 中 TOML 以 subPath 挂载且服务启动时读取，单改 ConfigMap 不会让当前 Pod 立即加载新索引；需更新 ConfigMap 后受控重启 Deployment。单实例重启期间会短暂不可用，memory 模式的浏览器会话也需重新登录。

重启后核对就绪状态和索引列表，再向新索引转发。索引名仅允许 ASCII 字母、数字、.、_、-，长度不超过 128 个字符，不能为 . 或 ..。本地只读账号及 SSO 的新索引授权需另外确认。

准备管理员和数据面凭据¶

管理员登录密码用于管理页面；写入 Token 和查询 Token 用于数据接口。三者分别保管，不使用管理员密码或观测云工作空间 Token 代替接口 Token。

凭据	本文中的初始来源	用途
管理员密码	Secret `logbamboo-auth` 的 `admin-password`	管理页面登录
写入 Token	Secret `logbamboo-auth` 的 `ingest-token`	当前租户下各索引的数据写入
查询 Token	Secret `logbamboo-auth` 的 `search-token`	当前租户下各索引的数据查询接口

环境变量名不是 Token 实际值。管理员可在 设置 > 写入令牌生成或输入新值并替换：页面不会回显旧值，保存后立即替换，没有双 Token 过渡期。先安全保存新值，再同步更新全部转发规则；已通过 UI 轮换时，最初 Secret 中的值可能已不再有效，应交接实际生效的 Token。

交接连接信息¶

信息	提供内容
服务地址	数据转发服务可访问的根地址，如 `https://logbamboo.example.com`，不附加 `/v1/indexes/.../logs` 等接口路径
目标索引	已配置并加载的索引名，例如 `app`
写入 Token	当前生效、允许写入目标租户的凭据
查询 Token（可选）	在控制台查询历史数据时使用，必须与写入 Token 不同；仅转发时可不提供
信任证书（可选）	使用自签名或企业内部 HTTPS 证书时，提供 PEM 格式信任证书内容

同一 Kubernetes 集群内可按实际 Service 使用 http://logbamboo.utils.svc.cluster.local:8080；另一集群或公网调用方应使用已验证可达的 HTTPS 入口。完整 Token 通过受控渠道交付，不写入共享文档、截图或日志。

第四步：接入并验证数据转发¶

进入控制台的数据转发页面，新建规则，选择 LogBamboo 目的地；
填入上一步准备的连接信息，测试连接后保存并启用规则，详见数据转发至 LogBamboo；
让符合转发条件的数据进入规则，在 LogBamboo 的运行状态中检查接收和处理情况；
等待数据处理完成，再按服务端接收时间查询，核对是否包含预期数据。详细步骤见验证转发结果。

接收成功与可查询是两个阶段。生产默认低流量场景可能需要等待约一小时或更久；暂时查不到时，先核对时间范围和处理状态，不要整批重复发送。

容量与商业授权¶

社区版无需许可证，默认提供 5 TB 数据保留容量，按未压缩内容计算。达到上限时，会自动清理较早的已处理数据。使用前请根据业务需要确认保留时间和容量，5 TB 不代表压缩后的磁盘占用。

购买并激活许可证¶

如需更大容量，请联系销售购买商业授权。许可证绑定当前部署的集群 ID，操作如下：

使用管理员账号登录 LogBamboo，进入 设置 > 许可证；
查看并复制当前集群 ID，将其与所需授权容量、授权期限一并提供给销售，获取绑定该集群的离线许可证文件；
回到 设置 > 许可证，在离线许可证文件处点击选择文件，上传获取的许可证文件；
点击激活许可证，等待页面提示操作完成；
核对运行模式已变为商业版，且容量、到期时间与购买的授权一致。需要刷新时，点击重新加载状态。

离线许可证激活无需联网。使用支持授权的统一安装包时，无需重新安装或重启。

续期与授权到期¶

续期时，请联系销售获取绑定当前集群的新许可证，并在同一页面上传、激活，核对更新后的到期时间。更换部署或迁移服务前，请与部署支持确认集群身份及许可证的处理方式。

授权到期且已用容量仍超过社区版上限时，将暂停新数据写入并保留已有数据。请及时续期，或由管理员按已配置的保留策略处理容量。

常见问题¶

问题	检查与处理
找不到初始化入口	查看启动终端或服务安装输出，使用当前安装包提示的入口
管理页面无法打开	检查服务运行状态、监听地址、端口和网络访问规则
存储配置验证失败	核对存储目录权限，或对象存储的地址、存储桶和访问凭据，并检查服务器到存储服务的网络
测试连接失败	核对服务地址、目标索引、Token 及 HTTPS 证书；确认验证的是转发服务所在网络
已接收但暂时查询不到	查看处理状态，按服务端接收时间选择查询范围，并等待处理完成
许可证激活失败	核对许可证是否绑定当前页面显示的集群 ID，并请部署支持检查安装包与许可证是否匹配

后续维护¶

定期关注服务运行状态、可用磁盘空间、容量增长和数据保留范围；
更换写入或查询 Token 后，同步更新使用该 Token 的转发规则；
升级前保留配置与本机运行数据，并阅读对应版本的升级说明；
有灾难恢复要求时，单独规划恢复仓库和恢复点。归档冷存储和查询导出不能代替灾难恢复备份。