iyangsj · pull · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026
diff --git a/.gitignore b/.gitignore
@@ -15,7 +15,7 @@
 .svn
 .tmp
 .download
-output
+output/
 .*.swp
 .*.swo
 /**/y.output
@@ -25,7 +25,6 @@ profile.out
 coverage.txt
 .idea/*
 .vscode/*
-bfe
 dist/*
 conf/wasm_plugin
 

diff --git a/Dockerfile b/Dockerfile
@@ -12,20 +12,134 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-FROM --platform=${BUILDPLATFORM} golang:1.17.5-alpine3.15 AS build
+FROM --platform=${BUILDPLATFORM} golang:1.22.2-alpine3.19 AS build
 ARG TARGETARCH
 ARG TARGETOS
 
-WORKDIR /bfe
+WORKDIR /src
 COPY . .
-RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags "-X main.version=`cat VERSION`"
 
-FROM alpine:3.15 AS run
-RUN apk update && apk add --no-cache ca-certificates
-COPY --from=build /bfe/bfe /bfe/bin/
-COPY conf /bfe/conf/
+RUN set -ex; \
+	mkdir -p /out; \
+	CGO_ENABLED=0 \
+	GOOS=${TARGETOS:-linux} \
+	GOARCH=${TARGETARCH:-$(go env GOARCH)} \
+	go build -ldflags "-X main.version=$(cat VERSION)" -o /out/bfe
+
+FROM alpine:3.19 AS confagent
+ARG TARGETARCH
+ARG CONF_AGENT_VERSION=0.0.2
+
+RUN apk add --no-cache ca-certificates wget tar
+
+RUN set -ex; \
+	CONF_AGENT_VERSION_NO_V="${CONF_AGENT_VERSION#v}"; \
+	CONF_AGENT_VERSION_TAG="v${CONF_AGENT_VERSION_NO_V}"; \
+	ARCH="${TARGETARCH:-}"; \
+	if [ -z "${ARCH}" ]; then \
+		ARCH="$(uname -m)"; \
+	fi; \
+	case "${ARCH}" in \
+		amd64|x86_64) CONF_AGENT_ARCH="amd64" ;; \
+		arm64|aarch64) CONF_AGENT_ARCH="arm64" ;; \
+		*) echo "Unsupported architecture: ${ARCH}"; exit 1 ;; \
+	esac; \
+	CONF_AGENT_URL="https://github.com/bfenetworks/conf-agent/releases/download/${CONF_AGENT_VERSION_TAG}/conf-agent_${CONF_AGENT_VERSION_NO_V}_linux_${CONF_AGENT_ARCH}.tar.gz"; \
+	wget -O /tmp/conf-agent.tar.gz "${CONF_AGENT_URL}"; \
+	tar -xzf /tmp/conf-agent.tar.gz -C /tmp; \
+	mkdir -p /out; \
+	mv /tmp/conf-agent /out/conf-agent; \
+	if [ -d /tmp/conf ]; then mv /tmp/conf /out/conf-agent-conf; else mkdir -p /out/conf-agent-conf; fi; \
+	chmod +x /out/conf-agent
+
+FROM alpine:3.19
+ARG VARIANT=prod
+
+RUN set -ex; \
+	apk add --no-cache ca-certificates; \
+	if [ "${VARIANT}" = "debug" ]; then \
+		apk add --no-cache bash curl wget vim; \
+	fi
+
+RUN mkdir -p /home/work/conf-agent/conf \
+	&& mkdir -p /home/work/conf-agent/log \
+	&& mkdir -p /home/work/bfe/bin \
+	&& mkdir -p /home/work/bfe/conf \
+	&& mkdir -p /home/work/bfe/log
+
+COPY --from=confagent /out/conf-agent /home/work/conf-agent/conf-agent
+COPY --from=confagent /out/conf-agent-conf /home/work/conf-agent/conf
+COPY --from=build /out/bfe /home/work/bfe/bin/bfe
+COPY --from=build /src/conf /home/work/bfe/conf/
+
+# COPY deploy/docker/entrypoint.sh /home/work/entrypoint.sh
+# Generate entrypoint.sh inside the image to avoid external file dependency
+RUN set -ex; \
+    cat > /home/work/entrypoint.sh <<'EOF'
+#!/bin/sh
+set -eu
+
+# Log function
+log() {
+    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $*"
+}
+
+# Start conf-agent in background
+start_conf_agent() {
+    if [ -f "/home/work/conf-agent/conf-agent" ]; then
+        log "Starting conf-agent..."
+        cd /home/work/conf-agent
+        nohup ./conf-agent -c ./conf > /home/work/conf-agent/log/stdout.log 2>&1 &
+        CONF_AGENT_PID=$!
+        log "conf-agent started, PID: $CONF_AGENT_PID"
+        cd /home/work
+    else
+        log "Warning: conf-agent binary not found, skipping startup"
+    fi
+}
+
+# Start bfe in foreground
+start_bfe() {
+    log "Starting bfe..."
+    cd /home/work/bfe/bin
+    exec ./bfe -c ../conf/ -l ../log/ -s
+}
+
+# Signal handler
+handle_signal() {
+    log "Received termination signal, shutting down..."
+
+    # Terminate conf-agent
+    if [ -n "$CONF_AGENT_PID" ]; then
+        log "Stopping conf-agent (PID: $CONF_AGENT_PID)..."
+        kill -TERM "$CONF_AGENT_PID" 2>/dev/null || true
+        wait "$CONF_AGENT_PID" 2>/dev/null || true
+    fi
+
+    exit 0
+}
+
+# Register signal handlers
+trap 'handle_signal' TERM INT
+
+# Main process
+log "========================================"
+log "BFE Container Startup Script"
+log "========================================"
+
+# 1. Start conf-agent if exists
+start_conf_agent
+
+# Wait for conf-agent initialization
+sleep 2
+
+# 2. Start bfe in foreground
+start_bfe
+EOF
+
+RUN chmod +x /home/work/entrypoint.sh
+
 EXPOSE 8080 8443 8421
 
-WORKDIR /bfe/bin
-ENTRYPOINT ["./bfe"]
-CMD ["-c", "../conf/", "-l", "../log"]
+WORKDIR /home/work
+ENTRYPOINT ["/home/work/entrypoint.sh"]
diff --git a/Makefile b/Makefile
@@ -138,12 +138,120 @@ license-check:
 license-fix:
 	$(LICENSEEYE) header fix
 
-# make docker
+
+# Docker image build targets
+BFE_IMAGE_NAME ?= bfe
+# conf-agent version used in Docker image build.
+# Default: 0.0.2
+# Override example: make docker CONF_AGENT_VERSION=0.0.2
+CONF_AGENT_VERSION ?= 0.0.2
+NO_CACHE ?= false
+
+# Optional cleanup controls
+# - CLEAN_DANGLING=true will remove dangling images ("<none>:<none>") after build.
+# - CLEAN_BUILDKIT_CACHE=true will prune build cache (can slow down next builds).
+CLEAN_DANGLING ?= false
+CLEAN_BUILDKIT_CACHE ?= false
+
+# Optional buildx (multi-arch) settings
+PLATFORMS ?= linux/amd64,linux/arm64
+BUILDER_NAME ?= bfe-builder
+
+# buildx helpers
+# - make docker (local build) does NOT require buildx.
+# - make docker-push (multi-arch push) requires buildx and will auto-init a builder.
+buildx-check:
+	@docker buildx version >/dev/null 2>&1 || ( \
+		echo "Error: docker buildx is not available."; \
+		echo "- If you use Docker Desktop: update/enable BuildKit/buildx."; \
+		echo "- If you use docker-ce: install the buildx plugin."; \
+		exit 1; \
+	)
+
+buildx-init: buildx-check
+	@docker buildx inspect $(BUILDER_NAME) >/dev/null 2>&1 || docker buildx create --name $(BUILDER_NAME) --driver docker-container --use
+	@docker buildx use $(BUILDER_NAME)
+	@docker buildx inspect --bootstrap >/dev/null 2>&1 || true
+
+# make docker: Build BFE docker images (prod + debug)
 docker:
+	@echo "Building BFE docker images (prod + debug)..."
+	@NORM_BFE_VERSION=$$(echo "$(BFE_VERSION)" | sed 's/^v*/v/'); \
+	NORM_CONF_VERSION=$$(echo "$(CONF_AGENT_VERSION)" | sed 's/^v*/v/'); \
+	echo "BFE version: $$NORM_BFE_VERSION"; \
+	echo "conf-agent version: $$NORM_CONF_VERSION"; \
+	echo "Step 1/2: build prod image"; \
 	docker build \
-		-t bfe:$(BFE_VERSION) \
+		$$(if [ "$(NO_CACHE)" = "true" ]; then echo "--no-cache"; fi) \
+		--build-arg VARIANT=prod \
+		--build-arg CONF_AGENT_VERSION=$$NORM_CONF_VERSION \
+		-t $(BFE_IMAGE_NAME):$$NORM_BFE_VERSION \
+		-t $(BFE_IMAGE_NAME):latest \
+		-f Dockerfile \
+		.; \
+	echo "Step 2/2: build debug image"; \
+	docker build \
+		$$(if [ "$(NO_CACHE)" = "true" ]; then echo "--no-cache"; fi) \
+		--build-arg VARIANT=debug \
+		--build-arg CONF_AGENT_VERSION=$$NORM_CONF_VERSION \
+		-t $(BFE_IMAGE_NAME):$$NORM_BFE_VERSION-debug \
 		-f Dockerfile \
 		.
+	@$(MAKE) docker-prune
+
+# docker-prune: optional post-build cleanup (safe-by-default)
+docker-prune:
+	@if [ "$(CLEAN_DANGLING)" = "true" ]; then \
+		echo "Pruning dangling images (<none>)..."; \
+		docker image prune -f; \
+	fi
+	@if [ "$(CLEAN_BUILDKIT_CACHE)" = "true" ]; then \
+		echo "Pruning build cache (BuildKit)..."; \
+		docker builder prune -f; \
+	fi
+
+# make docker-push: Build & push multi-arch images using buildx (REGISTRY is required)
+# Usage: make docker-push REGISTRY=ghcr.io/your-org
+docker-push:
+	@if [ -z "$(REGISTRY)" ]; then \
+		echo "Error: REGISTRY is required"; \
+		echo "Usage: make docker-push REGISTRY=ghcr.io/your-org"; \
+		exit 1; \
+	fi
+	@echo "Building and pushing multi-arch images via buildx..."
+	@echo "Platforms: $(PLATFORMS)"
+	@$(MAKE) buildx-init
+	@NORM_BFE_VERSION=$$(echo "$(BFE_VERSION)" | sed 's/^v*/v/'); \
+	NORM_CONF_VERSION=$$(echo "$(CONF_AGENT_VERSION)" | sed 's/^v*/v/'); \
+	NO_CACHE_OPT=$$(if [ "$(NO_CACHE)" = "true" ]; then echo "--no-cache"; fi); \
+	echo "BFE version: $$NORM_BFE_VERSION"; \
+	echo "conf-agent version: $$NORM_CONF_VERSION"; \
+	echo "Step 1/2: build+push prod (multi-arch)"; \
+	docker buildx build \
+		--platform $(PLATFORMS) \
+		$$NO_CACHE_OPT \
+		--build-arg VARIANT=prod \
+		--build-arg CONF_AGENT_VERSION=$$NORM_CONF_VERSION \
+		-t $(REGISTRY)/$(BFE_IMAGE_NAME):$$NORM_BFE_VERSION \
+		-t $(REGISTRY)/$(BFE_IMAGE_NAME):latest \
+		-f Dockerfile \
+		--push \
+		.; \
+	echo "Step 2/2: build+push debug (multi-arch)"; \
+	docker buildx build \
+		--platform $(PLATFORMS) \
+		$$NO_CACHE_OPT \
+		--build-arg VARIANT=debug \
+		--build-arg CONF_AGENT_VERSION=$$NORM_CONF_VERSION \
+		-t $(REGISTRY)/$(BFE_IMAGE_NAME):$$NORM_BFE_VERSION-debug \
+		-f Dockerfile \
+		--push \
+		.; \
+	echo "Pushed multi-arch:"; \
+	echo "  - $(REGISTRY)/$(BFE_IMAGE_NAME):$$NORM_BFE_VERSION"; \
+	echo "  - $(REGISTRY)/$(BFE_IMAGE_NAME):$$NORM_BFE_VERSION-debug"; \
+	echo "  - $(REGISTRY)/$(BFE_IMAGE_NAME):latest (prod)"
+	@$(MAKE) docker-prune
 
 # make clean
 clean:
@@ -153,4 +261,4 @@ clean:
 	rm -rf $(GOPATH)/pkg/linux_amd64
 
 # avoid filename conflict and speed up build 
-.PHONY: all prepare compile test package clean build
+.PHONY: all prepare compile test package clean build docker docker-push docker-prune buildx-check buildx-init
diff --git a/README-CN.md b/README-CN.md
@@ -50,6 +50,7 @@ BFE的架构说明见[概览](docs/zh_cn/introduction/overview.md)文档
 
 - 数据平面：BFE核心转发引擎的[编译及运行](docs/zh_cn/installation/install_from_source.md)
 - 控制平面：请参考控制平面的[部署说明](https://github.com/bfenetworks/api-server/blob/develop/docs/zh_cn/deploy.md)
+- Kubernetes 部署示例（kustomize）：[examples/kubernetes/README.md](examples/kubernetes/README.md)
 
 ## 运行测试
 

diff --git a/README.md b/README.md
@@ -49,6 +49,7 @@ Besides, we also implement [BFE Ingress Controller](https://github.com/bfenetwor
 
 - Data plane: BFE Server [build and run](docs/en_us/installation/install_from_source.md)
 - Control plane: English document coming soon.  [Chinese version](https://github.com/bfenetworks/api-server/blob/develop/docs/zh_cn/deploy.md)
+- Kubernetes example (kustomize): [examples/kubernetes/README.md](examples/kubernetes/README.md)
 
 ## Running the tests
 

diff --git a/docs/images/bfe-k8s.png b/docs/images/bfe-k8s.png
diff --git a/docs/zh_cn/installation/install_using_docker.md b/docs/zh_cn/installation/install_using_docker.md
@@ -1,22 +1,60 @@
-# docker安装
+# Docker 安装
 
-## 安装 && 运行
+本章介绍如何通过 Docker 运行 BFE。
 
-- 基于示例配置运行BFE:
+## 方式一：直接运行已有镜像
+
+如果你已经有可用镜像（例如 `bfenetworks/bfe`，或你自己构建并推送到私有仓库的镜像），可以直接运行：
 
 ```bash
-docker run -p 8080:8080 -p 8443:8443 -p 8421:8421 bfenetworks/bfe
+docker run --rm \
+	-p 8080:8080 -p 8443:8443 -p 8421:8421 \
+	<your-image>
 ```
 
-你可以访问 http://127.0.0.1:8080/ 因为没有匹配的配置，将得到 status code 500
-你可以访问 http://127.0.0.1:8421/ 查看监控信息
+你可以访问：
+- http://127.0.0.1:8080/ （如果配置未命中，可能返回 500）
+- http://127.0.0.1:8421/monitor （监控信息）
+
+## 方式二：从源码构建镜像（推荐）
 
-- 自定义配置文件路径
+在仓库根目录执行：
 
 ```bash
-// 事先准备好你自己的配置放到 (可以参考 配置 章节) /Users/BFE/conf
+# 一次构建 prod + debug 两个镜像
+make docker
+
+# 可选：指定 conf-agent 版本（默认 0.0.2）
+make docker CONF_AGENT_VERSION=0.0.2
+```
+
+构建后的镜像标签（以 VERSION=1.8.0 为例）：
+- `bfe:v1.8.0`（prod）
+- `bfe:v1.8.0-debug`（debug）
+- `bfe:latest`（始终指向 prod）
 
-docker run -p 8080:8080 -p 8443:8443 -p 8421:8421 -v /Users/BFE/Desktop/log:/bfe/log -v /Users/BFE/Desktop/conf:/bfe/conf bfenetworks/bfe
+## 自定义配置（挂载本地目录）
+
+镜像内目录约定：
+- BFE 配置目录：`/home/work/bfe/conf`
+- BFE 日志目录：`/home/work/bfe/log`
+- conf-agent 配置目录：`/home/work/conf-agent/conf`
+- conf-agent 日志目录：`/home/work/conf-agent/log`
+
+示例：挂载你本地准备好的配置与日志目录（按需修改路径）：
+
+```bash
+# 事先准备好你自己的配置：
+#   - /Users/BFE/Desktop/conf/         (BFE 配置目录)
+#   - /Users/BFE/Desktop/conf-agent/   (conf-agent 配置目录，里面放 conf-agent.toml)
+#   - /Users/BFE/Desktop/log/          (BFE 日志目录)
+
+docker run --rm \
+	-p 8080:8080 -p 8443:8443 -p 8421:8421 \
+	-v /Users/BFE/Desktop/conf:/home/work/bfe/conf \
+	-v /Users/BFE/Desktop/log:/home/work/bfe/log \
+	-v /Users/BFE/Desktop/conf-agent:/home/work/conf-agent/conf \
+	bfe:latest
 ```
 
 ## 下一步