[i18n] print_printable_section [i18n] print_click_to_print.

应用部署

1: 容器部署
2: 集群部署
3: 物理机部署

HUATUO (华佗) 社区提供多种部署方式，具体如下：

1 - 容器部署

镜像下载

镜像仓库地址：https://hub.docker.com/r/huatuo/huatuo-bamai/tags

使用 Docker 启动容器

docker run --detach \
  --name huatuo-bamai \
  --restart unless-stopped \
  --privileged \
  --pid=host \
  --cgroupns=host \
  --network=host \
  --cpus=2 \
  --memory=2g \
  --volume /sys:/sys \
  --volume /proc:/proc \
  --volume /run:/run \
  huatuo/huatuo-bamai:latest

注意：容器内置的默认配置不会连接 kubelet 和 Elasticsearch。

生产环境应限制 CPU 和内存，避免异常采集任务影响宿主机业务。Docker 的容器 cgroup 负责资源限制；Huatuo 默认不创建自身 cgroup，也不要在 Docker 部署中传入 --enable-cgroup。

通过以下命令确认限制已经生效，并观察实际使用量：

docker inspect huatuo-bamai \
  --format 'NanoCPUs={{.HostConfig.NanoCpus}} Memory={{.HostConfig.Memory}}'
docker stats huatuo-bamai

示例值为初始基线，应根据节点规格、采集任务和资源峰值调整。

使用 Docker Compose 启动容器

通过 Docker Compose 可在本地快速搭建一套完整环境，自行管理采集器、Elasticsearch、Prometheus、Grafana 等组件。

$ docker compose --project-directory ./build/docker up

Docker Compose 安装方法请参阅 https://docs.docker.com/compose/install/linux/。

2 - 集群部署

本文介绍如何通过 Kubernetes DaemonSet 将华佗采集器部署到集群。

1. Kubernetes 清单部署

1.1 获取配置文件

curl -L -o huatuo-bamai.conf https://github.com/ccfos/huatuo/raw/main/huatuo-bamai.conf

1.2 修改配置文件

根据实际部署环境修改配置文件，例如调整存储后端、Pod 信息获取方式等配置项，详见配置指南。

1.3 创建 ConfigMap

kubectl create configmap huatuo-bamai-config \
  --namespace default \
  --from-file=./huatuo-bamai.conf \
  --dry-run=client -o yaml |
kubectl apply -f -

1.4 部署采集器

下载 DaemonSet 清单：

curl -L -o huatuo-daemonset.yaml \
  https://raw.githubusercontent.com/ccfos/huatuo/main/build/huatuo-daemonset.minimal.yaml

部署到生产环境前，将 huatuo 容器的 resources 调整为以下初始基线：

resources:
  limits:
    cpu: "2"
    memory: 2Gi
  requests:
    cpu: "2"
    memory: 2Gi

应用修改后的清单：

kubectl apply -f ./huatuo-daemonset.yaml

requests 提供调度保障，limits 由 kubelet 写入 Pod cgroup，负责限制 Huatuo 的 CPU 和内存。Huatuo 默认不创建自身 cgroup，因此不会把进程移出 kubepods 层级，containerd 重启和 Pod 删除时可以正常回收进程。

示例值为初始基线，requests 与 limits 相同，因此 Pod 为 Guaranteed QoS。只有显式传入 --enable-cgroup 时 [Runtime] 才生效；Kubernetes 部署不要传入该参数。

1.5 验证部署

kubectl rollout status daemonset/huatuo \
  --namespace default \
  --timeout=10m

kubectl get pods \
  --namespace default \
  --selector app=huatuo \
  --output wide

kubectl get daemonset huatuo \
  --namespace default \
  --output jsonpath='{.spec.template.spec.containers[?(@.name=="huatuo")].resources}'

更新 huatuo-bamai.conf 后，重新执行 1.3 节更新 ConfigMap，并手工触发滚动更新：

kubectl rollout restart daemonset/huatuo --namespace default

2. Helm 部署

Helm Chart 位于 build/charts/。

2.1 检查部署环境

管理机需要安装 Helm 和 kubectl，并能够访问目标 Kubernetes 集群。

(command -v helm || curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash) && helm version

TARGET_CONTEXT="$(kubectl config get-contexts -o name | sed -n '1p')"
kubectl --context "${TARGET_CONTEXT}" get nodes

确认目标 Node 状态为 Ready。

2.2 准备配置文件

按照 1.1 和 1.2 节获取并修改 huatuo-bamai.conf。

2.3 配置部署参数

创建 values-production.yaml：

image:
  repository: <所有Node均可访问的镜像仓库>/huatuo-bamai
  tag: "<固定发行版本>"
  pullPolicy: IfNotPresent

resources:
  limits:
    cpu: "2"
    memory: 2Gi
  requests:
    cpu: "2"
    memory: 2Gi

nodeSelector:
  kubernetes.io/os: linux

tolerations:
  - operator: Exists

hostPaths:
  proc: /proc
  sys: /sys
  run: /run
  var: /var
  etc: /etc
  data: /var/log/huatuo/huatuo-local

2.4 检查 Helm Chart

helm lint ./build/charts \
  -f ./values-production.yaml \
  --set-file config.content=./huatuo-bamai.conf

helm template huatuo ./build/charts \
  --namespace huatuo \
  -f ./values-production.yaml \
  --set-file config.content=./huatuo-bamai.conf \
  >/dev/null

2.5 部署采集器

helm upgrade --install huatuo ./build/charts \
  --kube-context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  --create-namespace \
  -f ./values-production.yaml \
  --set-file config.content=./huatuo-bamai.conf \
  --atomic \
  --timeout 10m

2.6 验证部署

helm status huatuo \
  --kube-context "${TARGET_CONTEXT}" \
  --namespace huatuo

kubectl --context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  get daemonset,configmap,pod --output wide

kubectl --context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  rollout status daemonset/huatuo \
  --timeout=10m

查看采集器日志：

kubectl --context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  logs \
  --selector app.kubernetes.io/name=huatuo \
  --prefix \
  --tail=100

2.7 更新和回滚

修改镜像版本或 huatuo-bamai.conf 后，重新执行 2.5 节的命令。

查看发布历史并回滚到指定版本：

helm history huatuo \
  --kube-context "${TARGET_CONTEXT}" \
  --namespace huatuo

helm rollback huatuo <Revision> \
  --kube-context "${TARGET_CONTEXT}" \
  --namespace huatuo \
  --wait \
  --timeout 10m

3 - 物理机部署

生产环境资源限制

huatuo-bamai.service 由 systemd 负责资源限制和进程生命周期。服务单元默认不启用 Huatuo 自身 cgroup，使用以下原生配置：

[Service]
CPUAccounting=yes
CPUQuota=200%
MemoryAccounting=yes
MemoryMax=2G
TasksAccounting=yes
TasksMax=32768
KillMode=control-group

CPUQuota=200% 表示最多使用 2 个 CPU 核，MemoryMax=2G 限制服务内存。根据主机规格、采集任务和资源峰值调整这些值。systemd 部署不要传入 --enable-cgroup，否则进程会脱离 service cgroup。

服务启动后，检查状态和 cgroup：

systemctl status huatuo-bamai --no-pager
systemd-cgls --unit huatuo-bamai.service

二进制

HUATUO Release 提供 amd64 和 arm64 的 Linux 静态 tar 包。tar 包包含 huatuo-bamai 和 huatuo-apiserver 二进制文件、配置文件和 BPF 对象。

本节命令适用于发布资产名为 huatuo-bamai-<version>-static-linux-<arch>.tar.gz 的版本。当前该命名从 v2.2.0 开始提供；v2.0.0 和 v2.1.0 的 tar 包名不同，不能直接套用以下命令。

以下命令使用 HUATUO_VERSION 表示目标版本，可按实际发行版本调整，例如 v2.2.0：

HUATUO_VERSION="<release-version>"

1. 下载 tar 包

x86_64 主机下载 amd64 包：

wget "https://github.com/ccfos/huatuo/releases/download/${HUATUO_VERSION}/huatuo-bamai-${HUATUO_VERSION}-static-linux-amd64.tar.gz"

aarch64 主机下载 arm64 包：

wget "https://github.com/ccfos/huatuo/releases/download/${HUATUO_VERSION}/huatuo-bamai-${HUATUO_VERSION}-static-linux-arm64.tar.gz"

2. 安装 tar 包

创建安装、日志和数据目录：

sudo install -d -m 0755 /opt/huatuo-bamai /var/log/huatuo-bamai /var/lib/huatuo-bamai

amd64：

sudo tar -xzf "huatuo-bamai-${HUATUO_VERSION}-static-linux-amd64.tar.gz" --strip-components=1 --no-same-owner -C /opt/huatuo-bamai

arm64：

sudo tar -xzf "huatuo-bamai-${HUATUO_VERSION}-static-linux-arm64.tar.gz" --strip-components=1 --no-same-owner -C /opt/huatuo-bamai

3. 安装服务单元文件

从对应版本源码下载服务单元文件：

sudo wget -O /etc/systemd/system/huatuo-bamai.service "https://raw.githubusercontent.com/ccfos/huatuo/${HUATUO_VERSION}/build/rpm/huatuo-bamai.service"
sudo wget -O /etc/systemd/system/huatuo-apiserver.service "https://raw.githubusercontent.com/ccfos/huatuo/${HUATUO_VERSION}/build/rpm/huatuo-apiserver.service"

4. 修改配置

根据实际部署环境编辑 /opt/huatuo-bamai/conf/huatuo-bamai.conf 和 /opt/huatuo-bamai/conf/huatuo-apiserver.conf。详细配置项说明请参见 huatuo-bamai 配置和 huatuo-apiserver 配置。

根据 service unit 中的 CPUQuota、MemoryMax 和 TasksMax 设置资源上限。只有直接运行且传入 --enable-cgroup 时才配置 [Runtime]。

5. 注册 HUATUO 服务

重新加载 systemd 配置：

sudo systemctl daemon-reload

6. 启动 HUATUO 服务

启动服务并设置开机启动：

sudo systemctl enable --now huatuo-bamai huatuo-apiserver

RPM 包

OpenCloudOS 镜像仓库提供 HUATUO v2.1.0 的 x86_64 和 aarch64 RPM 包。RPM 包会安装 HUATUO 文件和 systemd 服务单元文件。

1. 下载 RPM 包

根据主机架构下载对应的 RPM 包：

x86_64：

wget https://mirrors.opencloudos.tech/epol/9/Everything/x86_64/os/Packages/huatuo-bamai-2.1.0-2.oc9.x86_64.rpm

aarch64：

wget https://mirrors.opencloudos.tech/epol/9/Everything/aarch64/os/Packages/huatuo-bamai-2.1.0-2.oc9.aarch64.rpm

2. 安装 RPM 包

x86_64：

sudo dnf install ./huatuo-bamai-2.1.0-2.oc9.x86_64.rpm

aarch64：

sudo dnf install ./huatuo-bamai-2.1.0-2.oc9.aarch64.rpm

3. 修改配置

根据实际部署环境编辑 /etc/huatuo-bamai/huatuo-bamai.conf。详细配置项说明请参见 huatuo-bamai 配置。

根据 service unit 中的 CPUQuota、MemoryMax 和 TasksMax 设置资源上限。只有直接运行且传入 --enable-cgroup 时才配置 [Runtime]。

4. 启动 HUATUO 服务

RPM 包会安装 huatuo-bamai.service 服务单元文件。启动服务并设置开机启动：

sudo systemctl enable --now huatuo-bamai

完整的 RPM 安装指引请参阅 https://mp.weixin.qq.com/s/Gmst4_FsbXUIhuJw1BXNnQ。