Tongweb8 Helm Chart 使用说明
阿俊
|
|
74
|
0
|
东方通

2053 字
|
40 分钟

Tongweb8 Helm Chart 使用说明

通用的 TongWeb 应用 Helm Chart，支持多项目部署和完整的 Kubernetes 功能。

Chart 信息

  • 名称: gzeport-tongweb
  • 版本: 1.0.8
  • 应用版本: 1.0.8
  • 描述: 适用于 TongWeb 包的 Helm Chart

特性

  • ✅ 支持 TongWeb 应用快速部署
  • ✅ 集成 SkyWalking APM 监控（支持 Logback 兼容性配置和网关插件自动加载）
  • ✅ 完整的健康检查探针配置（启动/存活/就绪探针）
  • ✅ 灵活的资源管理（CPU、内存、临时存储）
  • ✅ 支持 HPA 自动扩缩容（自动适配 Kubernetes 版本）
  • ✅ 支持 Ingress 路径重写和多域名配置
  • ✅ 支持自定义 Host Aliases
  • ✅ 优化的命名逻辑，避免重复后缀
  • ✅ 支持多种卷挂载方式（HostPath、PVC、ConfigMap）
  • ✅ 支持生命周期钩子和安全上下文配置

快速开始

打包 Chart

# 语法检查
helm lint ./gzeport-tongweb-1.0.0/

# 打包到当前目录
helm package ./gzeport-tongweb-1.0.0/

# 查看生成的文件
ls -lh gzeport-tongweb-1.0.8.tgz

# 推送到 Harbor 仓库
helm push gzeport-tongweb-1.0.8.tgz oci://reg-hub.gzeport.com/chartrepo --insecure-skip-tls-verify

# 拉取 Chart
helm pull oci://reg-hub.gzeport.com/chartrepo/gzeport-tongweb --version 1.0.8 --insecure-skip-tls-verify

基本部署

# 1. 语法检查
helm lint ./gzeport-tongweb-1.0.0/

# 2. 生成模板预览
helm template my-app ./gzeport-tongweb-1.0.0/ -f my-values.yaml

# 3. 完整测试（dry-run）
helm install --debug --dry-run my-app ./gzeport-tongweb-1.0.0/ -f my-values.yaml -n dev

# 4. 正式部署 - 使用优化的命名逻辑
# 示例：部署 SSO Web 应用，Release Name 即为资源名称
helm install gzeport-sso-web ./gzeport-tongweb-1.0.0/ -f my-values.yaml -n dev --create-namespace

# 或者从 OCI 仓库安装
helm install gzeport-sso-web oci://reg-hub.gzeport.com/chartrepo/gzeport-tongweb --version 1.0.8 -f my-values.yaml -n dev --insecure-skip-tls-verify

# 5. 检查部署状态
helm status gzeport-sso-web -n dev
kubectl get pods -n dev -l app.kubernetes.io/instance=gzeport-sso-web

升级和回滚

# 升级应用
helm upgrade my-app ./gzeport-tongweb-1.0.0/ -f my-values.yaml -n dev

# 查看历史版本
helm history my-app -n dev

# 回滚到上一个版本
helm rollback my-app -n dev

# 回滚到指定版本
helm rollback my-app 2 -n dev

卸载

# 卸载应用
helm uninstall my-app -n dev

# 卸载并删除所有资源
helm uninstall my-app -n dev --wait

配置说明

命名规则

Chart 使用优化的命名逻辑，避免重复后缀：

  • 如果设置了 fullnameOverride，使用该值作为资源名称
  • 否则直接使用 Release Name 作为资源名称
  • 示例：helm install gzeport-sso-web ... 会创建名为 gzeport-sso-web 的 Deployment、Service 等资源

必填配置

以下配置项是必须填写的：

image:
  registry: reg-hub.gzeport.com      # 镜像仓库地址
  repository: jsb/gzeport/your-app   # 必填：镜像组和名称
  tag: "latest"                       # 必填：镜像标签
  pullSecrets: gzeport                # 镜像拉取凭证（支持字符串或数组）

基础配置示例

# 应用名称覆盖（推荐使用 Release Name 控制命名）
# 如果不设置，默认使用 Release Name 作为资源名称
fullnameOverride: my-app-name

# 命名空间覆盖（可选，默认使用 Release Namespace）
namespaceOverride: ""

# 应用端口配置
appConfig:
  port: 8088  # 容器声明端口，默认 8088
  # 额外的容器端口（如管理端口）
  extraContainerPort:
    - name: admin
      containerPort: 9060
      protocol: TCP
  # 是否为网关应用（自动加载 gateway 和 webflux 插件）
  isGateway: false

# 副本数和更新策略
replicaCount: 2
terminationGracePeriodSeconds: 30  # Pod 终止宽限期，默认 30 秒
revisionHistoryLimit: 5             # 保留的历史版本数，默认 5

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 70%
    maxUnavailable: 30%

# Pod 注解（可选）
podAnnotations: {}
#   prometheus.io/scrape: "true"
#   prometheus.io/port: "8088"

# Pod 标签（可选）
podLabels: {}

# JVM 配置
jvm:
  opts: "-Xms2g -Xmx4g -XX:+UseG1GC"

# 资源配置（推荐配置临时存储限制）
resources:
  requests:
    cpu: "1000m"
    memory: "2Gi"
    ephemeral-storage: "1Gi"
  limits:
    cpu: "2000m"
    memory: "4Gi"
    ephemeral-storage: "5Gi"

SkyWalking 监控配置

skywalking:
  enabled: true  # 是否启用 SkyWalking，默认 false
  agent:
    image:
      registry: reg-hub.gzeport.com
      repository: cicd/apache/skywalking-java-agent
      tag: "9.2.0-alpine"
    imagePullPolicy: Always  # 拉取策略，默认 IfNotPresent
    # Init 容器挂载路径（用于复制 agent 文件）
    initMountPath: /agent
    # 应用容器内 agent 挂载路径
    mountPath: /AppHome/skywalking-agent
    # agent.jar 相对路径
    agentPath: agent/skywalking-agent.jar
    # 禁用 Logback 插件，解决与低版本 Logback 的兼容性问题
    # 设置为 true 时会物理删除 Logback 插件 Jar 包
    disableLogbackPlugin: false  # 当应用使用 Logback 1.0.x 时设置为 true
    resources:
      requests:
        cpu: "200m"
        memory: "200Mi"
      limits:
        cpu: "200m"
        memory: "200Mi"
  collector:
    backendServices: "192.168.111.143:45482"  # SkyWalking OAP 地址
  logging:
    level: ERROR  # Agent 日志级别
    dir: /AppHome/logs/skywalking-agent  # Agent 日志目录

Logback 兼容性说明

  • Logback 1.0.x：与 SkyWalking Logback 插件不兼容，需要设置 disableLogbackPlugin: true
  • Logback 1.2.x：兼容，可以保持 disableLogbackPlugin: false（默认值）
  • Logback 1.3+：可能存在兼容性问题，建议测试后决定是否禁用

网关应用配置

对于 Spring Cloud Gateway 应用，启用 isGateway 会自动加载 gateway 和 webflux 插件：

appConfig:
  isGateway: true  # 启用网关模式

skywalking:
  enabled: true
  # Init 容器会自动复制 optional-plugins 中的 gateway 和 webflux 插件

环境变量配置

支持多种方式配置环境变量，包括直接设置值和从 Secret 引用：

env:
  # 直接设置值
  - name: TZ
    value: "Asia/Shanghai"
  # SkyWalking 采样率配置
  - name: SW_AGENT_SAMPLE_RATE
    value: "0.2"
  # SkyWalking Span 限制配置
  - name: SW_AGENT_SPAN_LIMIT_PER_SEGMENT
    value: "300"
  # 从 Secret 引用
  - name: SECRET_KEY
    valueFrom:
      secretKeyRef:
        name: my-secret
        key: password

注意：SkyWalking 相关的核心环境变量（如 SW_AGENT_COLLECTOR_BACKEND_SERVICES、SW_AGENT_NAME、SW_AGENT_NAMESPACE、SW_LOGGING_LEVEL、SW_LOGGING_DIR）会由 Chart 自动注入，无需手动配置。

卷挂载配置

mount:
  volumeMounts:
    # 时区同步
    - mountPath: /etc/localtime
      name: localtime
      readOnly: true
    # 日志持久化（使用 subPath 隔离不同应用）
    - mountPath: /AppHome/logs
      subPath: my-app
      name: log-data
    # TongWeb 许可证文件
    - mountPath: /AppHome/TongWeb8/license.dat
      name: license-configmap
      subPath: license.dat
      readOnly: true
  volumes:
    # 主机路径卷
    - name: localtime
      hostPath:
        path: /etc/localtime
    # PVC 持久化卷
    - name: log-data
      persistentVolumeClaim:
        claimName: app-log-pvc
    # ConfigMap 卷
    - name: license-configmap
      configMap:
        name: tongweb-license-configmap
        items:
          - key: license.dat
            path: license.dat

Service 配置

service:
  enabled: true  # 是否启用 Service，默认 true
  type: ClusterIP  # 服务类型：ClusterIP/NodePort/LoadBalancer，默认 ClusterIP
  annotations: {}  # Service 注解（可选）
  labels: {}       # Service 标签（可选）

  # 主端口配置
  ports:
    name: http  # 端口名称，默认 http
    port: ""    # 不填写则使用 appConfig.port（默认 8088）
    targetPort: ""  # 不填写则使用 appConfig.port（默认 8088）
    nodePort: ""    # type 为 NodePort 时，不填写则随机生成

  # 额外端口配置（如管理端口）
  extraPorts:
    - name: admin
      port: 9060
      targetPort: 9060
      protocol: TCP
      nodePort: 31112  # NodePort 类型时可指定端口

Ingress 配置

基础配置

ingress:
  enabled: true  # 是否启用 Ingress，默认 false
  className: nginx  # Ingress 类名
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "500m"
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
  hostname: app.example.com  # 主机名（必填）
  path: /  # 访问路径
  pathType: Prefix  # 路径类型：Prefix/ImplementationSpecific/Exact
  tls: false  # 是否启用 TLS
  tlsSecretName: ""  # TLS Secret 名称（可选）

路径重写配置

适用于需要将外部访问路径映射到应用内部路径的场景：

ingress:
  enabled: true
  className: nginx
  annotations:
    # 启用正则匹配
    nginx.ingress.kubernetes.io/use-regex: "true"
    # 重写目标路径：将 /newCas/xxx 重写为 /gzeport-sso-web/xxx
    # 注意：/gzeport-sso-web 应替换为实际的 WAR 包部署路径（Context Path）
    nginx.ingress.kubernetes.io/rewrite-target: /gzeport-sso-web/$2
  hostname: gztest.singlewindow.cn
  # Ingress 访问路径，捕获后续路径作为变量 $2
  path: /newCas(/|$)(.*)
  # 使用 ImplementationSpecific 以支持正则
  pathType: ImplementationSpecific
  tls: false

多域名和额外路径配置

ingress:
  enabled: true
  className: nginx
  hostname: app.example.com
  path: /
  pathType: Prefix

  # 额外的主机名配置
  extraHosts:
    - name: api.example.com
      path: /api
      pathType: Prefix

  # 额外的路径配置
  extraPaths:
    - path: /*
      pathType: ImplementationSpecific
      backend:
        service:
          name: ssl-redirect
          port:
            name: use-annotation

  # 自定义规则（支持 Helm 模板）
  extraRules:
    - host: api.example.com
      http:
        paths:
          - path: /v1
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 8080

  # 额外的 TLS 配置
  extraTls:
    - hosts:
      - secure.example.com
      secretName: secure-tls-cert

HPA 自动扩缩容

Chart 会自动适配 Kubernetes 版本，选择合适的 HPA API 版本：
– Kubernetes < 1.23：使用 autoscaling/v2beta1 或 autoscaling/v2beta2
– Kubernetes >= 1.23：使用 autoscaling/v2

autoscaling:
  enabled: true  # 是否启用 HPA，默认 false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

  # 自定义指标（优先级高于上面的 CPU/Memory 配置）
  metrics: []
  # 示例：
  # - type: Resource
  #   resource:
  #     name: cpu
  #     target:
  #       type: Utilization
  #       averageUtilization: 70

  # 自定义扩缩容行为（可选）
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Percent
        value: 50
        periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
      - type: Percent
        value: 100
        periodSeconds: 30
      - type: Pods
        value: 2
        periodSeconds: 30
      selectPolicy: Max

# Kubernetes 版本覆盖（可选，用于 HPA 适配）
kubeVersion: ""

健康检查探针配置

针对 TongWeb 等启动较慢的应用，推荐使用三层探针策略：

probe:
  enabled: true  # 全局探针开关，默认 false

  # 启动探针：专用于处理启动慢的服务
  # 启动期间只有此探针生效，成功后才交由存活和就绪探针接管
  startupProbe:
    enabled: true
    tcpSocket:
      port: http              # 使用容器端口名称，自动引用 appConfig.port
    initialDelaySeconds: 30    # 容器启动后 30s 开始检查
    periodSeconds: 10          # 每 10s 检查一次
    failureThreshold: 30       # 最多允许失败 30 次，总计 30s + (10s * 30) = 330s
    # 也可以使用 httpGet 方式
    # httpGet:
    #   path: /actuator/health
    #   port: http

  # 存活探针：启动探针成功后接手，判断应用是否由于死锁等原因挂掉
  livenessProbe:
    enabled: true
    tcpSocket:
      port: http
    initialDelaySeconds: 10    # 启动探针成功后，只需 10s 即可开始
    periodSeconds: 30
    timeoutSeconds: 10
    failureThreshold: 3

  # 就绪探针：启动探针成功后接手，判断应用是否可对外提供服务
  readinessProbe:
    enabled: true
    tcpSocket:
      port: http
    initialDelaySeconds: 10
    periodSeconds: 20          # 就绪检查稍快一些，以便及时摘除故障节点
    timeoutSeconds: 10
    successThreshold: 1
    failureThreshold: 3

完整配置示例

查看 values-demo.yaml 获取完整的配置示例，该文件包含：
– 完整的镜像配置（包含 registry、repository、tag）
– SkyWalking 监控配置（包含 agent 资源限制）
– 卷挂载配置（时区同步、TongWeb 许可证）
– Service 和 Ingress 配置
– Pod 反亲和性配置
– 所有可用选项的注释说明

示例应用：gzeport-airedo-dm

Chart 打包和发布

打包 Chart

# 语法检查
helm lint ./gzeport-tongweb-1.0.0/

# 打包到当前目录
helm package ./gzeport-tongweb-1.0.0/

# 查看生成的文件
ls -lh gzeport-tongweb-1.0.0.tgz

推送到 Harbor 仓库

# 推送到 Harbor OCI 仓库
helm push gzeport-tongweb-1.0.0.tgz oci://reg-hub.gzeport.com/chartrepo --insecure-skip-tls-verify

# 拉取 Chart
helm pull oci://reg-hub.gzeport.com/chartrepo/gzeport-tongweb --version 1.0.0 --insecure-skip-tls-verify

# 从 OCI 仓库安装
helm install my-app oci://reg-hub.gzeport.com/chartrepo/gzeport-tongweb --version 1.0.0 -f my-values.yaml --insecure-skip-tls-verify

从 Kustomization 迁移

如果你之前使用 Kustomization 部署，迁移步骤：

  1. 复制示例配置 
    cp values-demo.yaml my-app-values.yaml
  2. 更新关键配置
    • 镜像信息：image.registry, image.repository, image.tag
    • 滚动更新策略：strategy
    • 卷挂载：mount.volumeMounts 和 mount.volumes
    • SkyWalking 路径：skywalking.agent.initMountPath 和 mountPath
  3. 测试部署 
    helm install --dry-run --debug my-app ./gzeport-tongweb-1.0.0/ -f my-app-values.yaml
  4. 正式部署 
    helm install my-app ./gzeport-tongweb-1.0.0/ -f my-app-values.yaml -n production

故障排查

查看部署状态

# 查看 Helm 发布状态
helm status my-app -n dev

# 查看当前配置
helm get values my-app -n dev

# 查看完整的渲染清单
helm get manifest my-app -n dev

# 查看 Pod 状态
kubectl get pods -n dev -l app.kubernetes.io/instance=my-app
kubectl describe pod <pod-name> -n dev

查看日志

# 查看应用日志
kubectl logs <pod-name> -n dev

# 查看 init 容器日志
kubectl logs <pod-name> -c skywalking-agent-container -n dev

# 实时查看日志
kubectl logs -f <pod-name> -n dev

调试模板

# 渲染模板并输出
helm template my-app ./gzeport-tongweb-1.0.0/ -f my-values.yaml --debug

# 验证模板语法
helm lint ./gzeport-tongweb-1.0.0/ -f my-values.yaml

# 使用 dry-run 测试
helm install --dry-run --debug my-app ./gzeport-tongweb-1.0.0/ -f my-values.yaml

常见问题

Q: Pod 启动失败，提示 ImagePullBackOff？

A: 检查 image.pullSecrets 配置是否正确，确保 Secret 存在于目标命名空间。

Q: SkyWalking Agent 无法连接到 OAP？

A: 检查 skywalking.collector.backendServices 配置，确保网络可达。

Q: 应用启动时出现 NoSuchMethodError 与 Logback 相关？

A: 这是 SkyWalking Logback 插件与应用 Logback 版本不兼容导致的。检查应用的 Logback 版本：
– 如果是 1.0.x 版本，设置 skywalking.agent.disableLogbackPlugin: true
– 如果是 1.2.x 版本，通常兼容，保持 disableLogbackPlugin: false（默认值）
– 可以通过 kubectl exec 进入容器查看：ls -l /path/to/app/WEB-INF/lib/ | grep logback

Q: 如何控制资源名称？

A: Chart 使用优化的命名逻辑：
– 如果设置了 fullnameOverride，使用该值作为资源名称
– 否则直接使用 Release Name 作为资源名称
– 这避免了重复的 gzeport-tongweb 后缀问题
– 示例：helm install gzeport-sso-web ... 会创建名为 gzeport-sso-web 的资源

Q: 卷挂载失败？

A: 确保 PVC、ConfigMap 等资源在部署前已创建，检查 mount 配置是否正确。

Q: Ingress 无法访问？

A: 检查 ingress.className 和 ingress.annotations 配置，确保 Ingress Controller 正常运行。

Q: Pod 启动很慢，经常被 Kubernetes 重启？

A: 针对 TongWeb 等启动慢的应用，建议启用 startupProbe，并适当调整 failureThreshold 和 periodSeconds，给予足够的启动时间。

Q: 如何查看 SkyWalking Agent 日志？

A:

# 查看 init 容器日志
kubectl logs <pod-name> -c skywalking-agent-container -n dev

# 进入容器查看 agent 日志文件
kubectl exec -it <pod-name> -n dev -- cat /AppHome/logs/skywalking-agent/skywalking-api.log

Q: 多副本部署时，所有 Pod 都调度到同一个节点？

A: 配置 Pod 反亲和性（podAntiAffinity），确保副本分布到不同节点，提高可用性。参考上面的”Pod 亲和性”配置示例。

Q: 如何配置镜像拉取凭证？

A: image.pullSecrets 支持两种格式：
– 字符串格式：pullSecrets: gzeport
– 数组格式：pullSecrets: [{name: gzeport}, {name: another-secret}]

Q: 如何查看 Chart 渲染后的完整清单？

A: 使用 helm get manifest 命令：

helm get manifest my-app -n dev

高级功能

环境变量配置

支持多种方式配置环境变量：

env:
  # 直接设置值
  - name: TZ
    value: "Asia/Shanghai"
  # SkyWalking 采样率配置
  - name: SW_AGENT_SAMPLE_RATE
    value: "0.2"
  # 从 Secret 引用
  - name: SECRET_KEY
    valueFrom:
      secretKeyRef:
        name: my-secret
        key: password

Host Aliases 配置

自定义 Pod 的 /etc/hosts 文件，用于内部域名解析：

hostAliases:
  - ip: "192.168.1.100"
    hostnames:
    - "example.com"
    - "www.example.com"
  - ip: "192.168.1.101"
    hostnames:
    - "api.example.com"

生命周期钩子

配置容器启动和停止时的钩子：

lifecycle:
  # 优雅停机：等待 15 秒让请求处理完成
  preStop:
    exec:
      command: ["/bin/sh", "-c", "sleep 15"]
  # 启动后执行
  postStart:
    exec:
      command: ["/bin/sh", "-c", "echo Hello from the postStart handler"]

安全上下文

securityContext:
  runAsNonRoot: true
  runAsUser: 2888
  fsGroup: 2888

containerSecurityContext:
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL

Pod 亲和性

确保多副本时分布到不同节点，提高可用性：

affinity:
  podAntiAffinity:
    # 优先尝试分布到不同节点（软策略）
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchExpressions:
          - key: app.kubernetes.io/instance
            operator: In
            values:
            - "{{ .Release.Name }}"
        topologyKey: kubernetes.io/hostname

节点选择器和容忍度

# 节点选择器：指定 Pod 调度到特定节点
nodeSelector:
  disktype: ssd
  kubernetes.io/arch: amd64

# 容忍度：允许 Pod 调度到有特定污点的节点
tolerations:
  - key: "node-role.kubernetes.io/master"
    operator: "Exists"
    effect: "NoSchedule"

Pod 注解和标签

# Pod 注解（可用于 Prometheus 监控等）
podAnnotations:
  prometheus.io/scrape: "true"
  prometheus.io/port: "8088"

# Pod 标签（可用于自定义选择器）
podLabels:
  team: backend
  environment: production

ServiceAccount 配置

# 指定 Pod 使用的 ServiceAccount
serviceAccountName: my-service-account

相关资源

源码

关注 阿俊运维公众号或查看：https://mp.weixin.qq.com/s/bqfKVQ00f3E33vscbH5R9Q

tongweb
暂无评论

发送评论 编辑评论 


				

			

						

				

					

						

							

								
							

							
						

					

				

				

					

						

							

								
							

							
						

					

				

				

					

						

							

								
							

							
							
													

					

				

			

			
			

				

					
				

			

				

											

							
							
						

																					

							
							
						

										
					
											
						

	

		
|´・ω・)ノ
ヾ(≧∇≦*)ゝ
(☆ω☆)
（╯‵□′）╯︵┴─┴
￣﹃￣
(/ω＼)
∠( ᐛ 」∠)＿
(๑•̀ㅁ•́ฅ)
→_→
୧(๑•̀⌄•́๑)૭
٩(ˊᗜˋ*)و
(ノ°ο°)ノ
(´இ皿இ｀)
⌇●﹏●⌇
(ฅ´ω`ฅ)
(╯°A°)╯︵○○○
φ(￣∇￣o)
ヾ(´･ ･｀｡)ノ"
( ง ᵒ̌皿ᵒ̌)ง⁼³₌₃
(ó﹏ò｡)
Σ(っ °Д °;)っ
( ,,´･ω･)ﾉ"(´っω･｀｡)
╮(╯▽╰)╭
o(*////▽////*)q
＞﹏＜
( ๑´•ω•) "(ㆆᴗㆆ)
😂
😀
😅
😊
🙂
🙃
😌
😍
😘
😜
😝
😏
😒
🙄
😳
😡
😔
😫
😱
😭
💩
👻
🙌
🖕
👍
👫
👬
👭
🌚
🌝
🙈
💊
😶
🙏
🍦
🍉
😣
Source: github.com/k4yt3x/flowerhd
	

	

		
颜文字
Emoji
小恐龙
花!
	


									

			

			
			
		

	






上一篇