管理设计篇之"边车模式" [2026重制版]

# docker-compose-sidecar.yml
version: '3.8'

services:
  app:
    image: my-app:latest
    ports:
      - "8080:8080"
    networks:
      - sidecar-network

  envoy:
    image: envoyproxy/envoy-dev:v1.29.0
    volumes:
      - ./envoy.yaml:/etc/envoy/envoy.yaml
    ports:
      - "10000:10000"   # 入站端口 (Admin)
      - "8000:8000"     # 出站代理端口
      - "9901:9901"     # Admin API
    depends_on:
      - app
    networks:
      - sidecar-network

networks:
  sidecar-network:
    driver: bridge

# envoy.yaml - 边车代理配置
static_resources:
  listeners:
    - name: listener_inbound
      address:
        socket_address:
          address: 0.0.0.0
          port_value: 10000
      filter_chains:
        - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                stat_prefix: ingress_http
                route_config:
                  name: local_route
                  virtual_hosts:
                    - name: backend
                      domains: ["*"]
                      routes:
                        - match:
                            prefix: "/"
                          route:
                            cluster: app_cluster
                http_filters:
                  - name: envoy.filters.http.router
                    typed_config:
                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

  clusters:
    - name: app_cluster
      connect_timeout: 5s
      type: STATIC
      lb_policy: ROUND_ROBIN
      load_assignment:
        cluster_name: app_cluster
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address:
                      address: 127.0.0.1
                      port_value: 8080

admin:
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 9901

# envoy-dynamic.yaml - 使用 xDS API 动态配置
dynamic_resources:
  lds_config:
    resource_api_version: V3
    api_config_source:
      api_type: GRPC
      transport_api_version: V3
      grpc_services:
        - envoy_grpc:
            cluster_name: xds_cluster
  cds_config:
    resource_api_version: V3
    api_config_source:
      api_type: GRPC
      transport_api_version: V3
      grpc_services:
        - envoy_grpc:
            cluster_name: xds_cluster

static_resources:
  clusters:
    - name: xds_cluster
      connect_timeout: 5s
      type: STATIC
      lb_policy: ROUND_ROBIN
      load_assignment:
        cluster_name: xds_cluster
        endpoints:
          - lb_endpoints:
              - endpoint:
                  address:
                    socket_address:
                      address: control-plane.example.com
                      port_value: 18000

admin:
  address:
    socket_address:
      address: 0.0.0.0
      port_value: 9901

# deployment-with-sidecar.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  labels:
    app: order-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: order-service
  template:
    metadata:
      labels:
        app: order-service
    spec:
      # ====== 业务容器 ======
      containers:
        - name: order-app
          image: my-registry/order-service:v2.1.0
          ports:
            - containerPort: 8080
              protocol: TCP
          env:
            - name: SERVICE_NAME
              value: "order-service"
            - name: LOG_LEVEL
              value: "INFO"
          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
            limits:
              memory: "512Mi"
              cpu: "500m"
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /health/live
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 20

      # ====== Sidecar 容器 (Envoy) ======
        - name: envoy-sidecar
          image: envoyproxy/envoy:v1.29.0
          ports:
            - containerPort: 15001   # 出站流量 (Virtual Outbound)
              name: env-out
              protocol: TCP
            - containerPort: 15006   # 入站流量 (Inbound)
              name: env-in
              protocol: TCP
            - containerPort: 15000   # Envoy Admin
              name: env-admin
              protocol: TCP
          volumeMounts:
            - name: envoy-config
              mountPath: /etc/envoy
              readOnly: true
          resources:
            requests:
              memory: "64Mi"
              cpu: "100m"
            limits:
              memory: "128Mi"
              cpu: "200m"

      volumes:
        - name: envoy-config
          configMap:
            name: envoy-sidecar-config

spec:
  initContainers:
    - name: istio-init
      image: istio/proxyv2:1.21.0
      args:
        - istio-iptables
        - "-p"             # 端口重定向所有入站流量到 15006
        - "15001"
        - "-z"             # 端口重定向所有出站流量到 15001
        - "15006"
        - "-u"             # 不重定向 UID 1337 的流量 (Envoy自身)
        - "1337"
        - "-m"             # 模式: REDIRECT
        - "REDIRECT"
        - "-i"             # 入站重定向端口范围
        - "*"
        - "-x"             # 出站重定向端口范围
        - ""
        - "-b"             # 应用程序端口
        - "8080"
        - "-d"             # 排除的端口 (如 SSH)
        - "15090,15021,15020"
      securityContext:
        capabilities:
          add:
            - NET_ADMIN
            - NET_RAW
        privileged: true

// main.go - COBOL Legacy Sidecar Adapter
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"strconv"
	"time"

	"github.com/golang-jwt/jwt/v5"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)

var (
	cobolAddr = os.Getenv("COBOL_SERVICE_ADDR") // 如 "cobol-service:7000"
	listenPort = os.Getenv("LISTEN_PORT")       // 如 "8080"
	jwtSecret  = os.Getenv("JWT_SECRET")
)

// 定义 Prometheus 指标
var (
	requestTotal = promauto.NewCounterVec(
		prometheus.CounterOpts{
			Name: "sidecar_requests_total",
			Help: "Total number of requests proxied to legacy system",
		},
		[]string{"method", "status"},
	)
	requestDuration = promauto.NewHistogramVec(
		prometheus.HistogramOpts{
			Name:    "sidecar_request_duration_seconds",
			Help:    "Request duration to legacy system",
			Buckets: prometheus.DefBuckets,
		},
		[]string{"method", "endpoint"},
	)
)

func main() {
	mux := http.NewServeMux()

	// 健康检查端点
	mux.HandleFunc("/health", healthHandler)

	// 业务 API 端点（需要认证）
	api := http.NewServeMux()
	api.HandleFunc("/api/account/balance", authMiddleware(balanceHandler))
	api.HandleFunc("/api/account/transfer", authMiddleware(transferHandler))

	// 包装日志中间件
	loggedAPI := loggingMiddleware(api)
	mux.Handle("/api/", loggedAPI)

	// Metrics 端点
	mux.Handle("/metrics", promhttp.Handler())

	addr := ":" + listenPort
	log.Printf("Sidecar adapter starting on %s, proxying to %s", addr, cobolAddr)
	if err := http.ListenAndServe(addr, mux); err != nil {
		log.Fatal(err)
	}
}

// authMiddleware - JWT 认证中间件
func authMiddleware(next http.HandlerFunc) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		tokenString := r.Header.Get("Authorization")
		if tokenString == "" {
			http.Error(w, `{"error":"missing authorization header"}`, http.StatusUnauthorized)
			return
		}

		token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
			return []byte(jwtSecret), nil
		})

		if err != nil || !token.Valid {
			http.Error(w, `{"error":"invalid token"}`, http.StatusUnauthorized)
			return
		}

		// 提取 claims 并放入 context
		if claims, ok := token.Claims.(jwt.MapClaims); ok {
			ctx := context.WithValue(r.Context(), "userId", claims["sub"])
			ctx = context.WithValue(ctx, "roles", claims["roles"])
			next.ServeHTTP(w, r.WithContext(ctx))
		} else {
			http.Error(w, `{"error":"invalid claims"}`, http.StatusUnauthorized)
		}
	})
}

// balanceHandler - 查询余额
func balanceHandler(w http.ResponseWriter, r *http.Request) {
	start := time.Now()
	defer func() {
		requestDuration.WithLabelValues("GET", "/balance").Observe(time.Since(start).Seconds())
	}()

	accountId := r.URL.Query().Get("account_id")
	if accountId == "" {
		writeError(w, http.StatusBadRequest, "account_id is required")
		return
	}

	// 通过 TCP 与 COBOL 服务通信
	conn, err := net.DialTimeout("tcp", cobolAddr, 5*time.Second)
	if err != nil {
		log.Printf("Failed to connect to COBOL service: %v", err)
		writeError(w, http.StatusBadGateway, "legacy system unavailable")
		return
	}
	defer conn.Close()

	// 发送查询命令（COBOL 自定义协议）
	cmd := fmt.Sprintf("BALANCE|%s\n", accountId)
	_, err = conn.Write([]byte(cmd))
	if err != nil {
		writeError(w, http.StatusInternalServerError, "communication error")
		return
	}

	// 读取响应
	buf := make([]byte, 1024)
	n, err := conn.Read(buf)
	if err != nil {
		writeError(w, http.StatusInternalServerError, "read error")
		return
	}

	// 解析响应并转换为 JSON
	response := parseCobolResponse(string(buf[:n]))
	json.NewEncoder(w).Encode(response)
	requestTotal.WithLabelValues("GET", strconv.Itoa(http.StatusOK)).Inc()
}

// loggingMiddleware - 结构化日志中间件
func loggingMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		wrapped := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
		next.ServeHTTP(wrapped, r)

		duration := time.Since(start)
		log.Printf("[SIDECAR] method=%s path=%s status=%d duration=%s remote=%s",
			r.Method,
			r.URL.Path,
			wrapped.statusCode,
			duration.String(),
			r.RemoteAddr,
		)
	})
}

// 辅助类型和函数
type responseWriter struct {
	http.ResponseWriter
	statusCode int
}

func (rw *responseWriter) WriteHeader(code int) {
	rw.statusCode = code
	rw.ResponseWriter.WriteHeader(code)
}

func writeError(w http.ResponseWriter, code int, message string) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(code)
	json.NewEncoder(w).Encode(map[string]string{"error": message})
	requestTotal.WithLabelValues("", strconv.Itoa(code)).Inc()
}

func healthHandler(w http.ResponseWriter, r *http.Request) {
	json.NewEncoder(w).Encode(map[string]string{
		"status":  "healthy",
		"version": "1.0.0",
		"sidecar": "cobol-adapter",
	})
}