yldmdocs

kubepocket · app 命名空间下的后端 HTTP 服务

kubepocket 是部署在 app 命名空间的一个后端服务，监听 8080 端口提供 HTTP 接口，依赖 Postgres（经 pgbouncer）与 Redis，启动后注册到 Consul 供网关路由，并集成 Claude API、GitHub OAuth 与 Firebase Cloud Messaging（FCM）推送。它由 yldm-services ApplicationSet 编排，对应 applications/app/kubepocket/ 这一个 kustomize 目录。

部署形态

  • Name
    命名空间
    Description
    app（kustomization namespace: app + namePrefix: app-，资源带 app-kubepocket-* 前缀）
  • Name
    工作负载
    Description
    Deployment，replicas: 2（实际副本数由下方 HPA 在区间内伸缩）
  • Name
    镜像
    Description
    ghcr.io/yldm-tech/kubepocket:2.3.1（tag 由 argocd-image-updater 按 semver 回写 kustomization images:）
  • Name
    调度
    Description
    nodeSelector: workload=app（worker2 / worker4），配 podAntiAffinity（按 app=kubepocket 软反亲和分散到两节点），priorityClassName: production-medium
  • Name
    端口
    Description
    容器端口 8080（name http）
  • Name
    资源
    Description
    requests cpu 50m / memory 64Mi，limits cpu 200m / memory 256Mi
  • Name
    健康探针
    Description
    liveness /health/live、readiness /health/ready、startup /health/live（均 8080）

镜像用 ghcr-secret 拉取（imagePullSecrets）。无 PVC / 持久化存储，所有状态落在外部 Postgres 与 Redis。

配置与依赖

配置来自两个 ConfigMap 与若干环境变量。Deployment 挂载共享的 base-config（/root/configs/base）与本服务的 kubepocket-config（kubepocket.yaml 子路径挂到 /root/configs/services/kubepocket.yaml），并通过 CONFIG_FILE=configs/services/kubepocket.yaml 指向后者。kubepocket-config 里的 kubepocket.yaml 用 ${VAR:default} 占位，运行时由环境变量填充，覆盖 server / jwt / claude / fcm / log / ratelimit / consul 各段。

env 关键项：ENV、ENVIRONMENT、SERVER_MODE=release、SERVER_PORT=8080、SERVER_NAME=kubepocket；Claude 走 CLAUDE_API_KEY（配置默认 model claude-sonnet-4-20250514、max_tokens 4096）；GitHub OAuth 用 GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET，回调 GITHUB_REDIRECT_URI=kubepocket://auth/github/callback；FCM 凭据以 GOOGLE_APPLICATION_CREDENTIALS=/app/secrets/fcm-credentials.json 注入（由 secret 的 FCM_CREDENTIALS 键挂载为文件）。

依赖：

依赖接入方式
PostgreSQLDB_HOST=pgbouncer.postgres.svc.cluster.local，端口 / 库名 / 账号密码来自 secret
RedisREDIS_HOST/PORT/PASSWORD/DB/REDIS_PUBSUB_DB 来自 secret
ConsulCONSUL_ENABLED=true，CONSUL_ADDRESS=consul.consul.svc.cluster.local:8500，并用 downward API 注入 POD_IP 以拼出正确的健康检查 URL

密钥全部走 ExternalSecret kubepocket-secret（ClusterSecretStore vault-backend），生成 secret kubepocket-db-secret，refreshInterval: 1h。remoteRef.key 分布在三处：本服务私有项 yldm/production/kubepocket（claude / jwt / fcm / db** / redis**），共享库凭据 yldm/database（DB_ADMIN_USER / DB_ADMIN_PASSWORD），以及 github/app（GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET）。Deployment 带 reloader.stakater.com/auto: "true"，configmap / secret 变更时自动重启 Pod。

访问与监控

Service kubepocket 为默认 ClusterIP，port 80 → targetPort 8080（name http）。无 Ingress，仅集群内访问 —— 外部流量经 Consul 注册后由网关路由。

NetworkPolicy allow-consul-healthcheck 放行来自 consul 命名空间到 8080 的 Ingress，让 Consul 能做健康检查。

伸缩与可用性：HPA kubepocket-hpa（minReplicas 2 / maxReplicas 5，CPU 目标利用率 70% + 内存 80%）；VPA kubepocket-vpa 为 updateMode: "Off"（仅给建议，区间 cpu 25m–500m / memory 32Mi–512Mi）；PDB kubepocket（maxUnavailable: 1）。

监控侧有 PrometheusRule kubepocket（无 ServiceMonitor），告警组 kubepocket.rules 覆盖：Pod 宕机 / 副本不足、Consul 注册失败或 unhealthy、HTTP 5xx 错误率（warning >3% / critical >10%）、数据库连接错误、p95 延迟 >1s、内存 / CPU 使用率 >85%、以及 Pod 频繁重启。

注意事项

Consul 地址环境变量必须是 CONSUL_ADDRESS 而非 CONSUL_ADDR。deployment.yaml 的注释指出 Viper 把配置键 consul.address 映射为 CONSUL_ADDRESS（点转下划线），用错名字会导致 Consul 注册静默失败 —— Pod 看着正常但服务不在 Consul 里，网关无法路由（对应 KubePocketConsulRegistrationFailed 告警）。

ConfigMap 里 kubepocket.yaml 的 server.mode 写的是 debug，但 Deployment 用 env SERVER_MODE=release 覆盖，运行态为 release。

CLAUDE.md 没有 kubepocket 专属的踩坑段；以上均来自本服务 manifest 与 README 的集群拓扑。

返回 app 服务总览

评论