3-配置管理-仓库使用指南

← 返回首页

🏗️ 架构概览

GitOps模式，配置即代码

Kustomize分层管理
ArgoCD自动部署
多环境差异配置
变更可追溯回滚

⚙️ 实现方法

基础配置+环境补丁

base/：通用配置
overlays/：环境配置
三种补丁方式
声明式管理

🚀 实战部署

Git触发自动部署

修改配置提交
ArgoCD检测变更
自动同步集群
服务滚动更新

🛠️ 运维管理

覆盖日常全场景

版本更新回滚
服务扩缩容
配置热更新
多环境管理

📁 第一步：理解仓库结构

🚀 新手快速上手

记住这个关键路径：overlays/{环境}/kustomization.yaml - 这是每个环境的配置入口！

📍 找到你的环境目录

📝 修改配置文件

🔄 提交到Git仓库

✅ 等待自动部署

gogs-repo/ ├── base/ # 🏠 非OKG老架构Base │ ├── gforge-game/ # 游戏核心服务 │ │ ├── deployment.yaml # K8S部署配置 │ │ ├── service.yaml # 服务暴露配置 │ │ └── kustomization.yaml # Kustomize配置 │ ├── gforge-gateway/ # 网关服务（其他服务类似） │ └── ... # 其他10个服务 │ ├── base-okg/ # 🎮 GameServerSet │ ├── gforge-game/ # 游戏服务器集群 │ │ ├── gameserverset.yaml # OKG游戏服务器配置 │ │ └── kustomization.yaml # Kustomize配置 │ └── ... # 其他OKG服务 │ └── overlays/ # 环境特定配置 ├── dev/ # 开发环境 │ ├── kustomization.yaml # ⭐ 环境配置入口 │ ├── cm.yaml # 业务配置（数据库/Redis） │ ├── deploy-patch-okg.yaml # YAML补丁文件 │ ├── containers-patchs.json # JSON补丁文件 │ └── ingress.yaml # 域名路由配置 │ ├── prod/ # 生产环境（配置类似） ├── banshu/ # 版署环境 └── weixin-ygbyp/ # 微信小游戏

💡 新手提示：记住这个路径 overlays/{环境}/kustomization.yaml，这是每个环境的配置入口！

🎯 第二步：重新认识Kustomize补丁机制

纠正认知：我们讨论的都是Kustomize功能

重要澄清：网上很多教程把YAML/JSON格式误认为不同的补丁工具，实际上所有补丁功能都由Kustomize提供，核心区别是两种不同的机制：

Strategic Merge Patch：智能合并，适合K8s原生资源的常规字段修改
JSON Patch：精确操作，适合复杂场景和数组操作
选择原则：根据修改需求和资源类型选择机制，而非格式

对比维度	Strategic Merge Patch	JSON Patch
应用场景	K8s原生资源常规修改 • Deployment/Service/ConfigMap • 镜像更新、副本调整、标签修改	复杂操作、CRD资源 • 数组精确操作 • GameServerSet等CRD • 删除特定字段
配置复杂度	简单类似原始YAML，直观可读	中等需理解path语法，路径依赖严格
CRD支持	需要Schema 无Schema时降级为简单合并，可能有问题	完全支持不依赖Schema，基于路径操作
数组操作	智能合并(有Schema时) 按name/key字段合并而非替换	精确控制支持add/remove/replace/move等所有操作
错误调试	容易 YAML格式直观，报错清晰	困难路径错误难排查，需要经验
推荐用法	overlays/env/deploy-patch-okg.yaml 常规运维场景首选	overlays/env/containers-patchs.json CRD和复杂场景必备

🔧 Kustomize两种补丁机制实战

核心机制一 Strategic Merge Patch（策略性合并补丁）

📋 机制原理

Kustomize的默认补丁方式
内置K8s原生资源的OpenAPI Schema
智能合并：知道containers列表应该按name字段合并
格式：通常使用YAML，直观易读

🎯 适用场景

K8s原生资源的常规修改
镜像版本更新、副本数调整
标签注解修改、配置字段增加
环境变量覆盖

kustomization.yaml配置方法：

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base/gforge-game
  - ../../base/gforge-gateway

# 新版推荐方式（Kustomize自动识别机制）
patches:
- path: deploy-patch-okg.yaml
  target:
    kind: Deployment
    name: gforge-game

# 旧版方式（仍有效但不推荐）  
# patchesStrategicMerge:
# - deploy-patch-okg.yaml

实战示例：活动期间扩容

文件路径：overlays/prod/deploy-patch-okg.yaml

# overlays/prod/deploy-patch-okg.yaml
# Strategic Merge会智能合并以下配置
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gforge-game
spec:
  replicas: 10  # 从3扩容到10
  template:
    spec:
      containers:
      - name: game-server  # 按name匹配容器，智能合并
        resources:
          requests:
            cpu: "2"      # 只覆盖这些字段，其他保持不变
            memory: "4Gi"
          limits:
            cpu: "4"
            memory: "8Gi"
        env:
        - name: LOG_LEVEL
          value: "info"   # 覆盖或新增环境变量
---
# 同时处理多个资源
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gforge-gateway
spec:
  replicas: 5  # 网关也要扩容

💡 Strategic Merge优势：你只需要写出想要修改的字段，Kustomize会智能地与base配置合并，无需担心覆盖其他配置。

核心机制二 JSON Patch（精确路径补丁）

📋 机制原理

基于明确路径(path)和操作类型(op)
支持操作：add/remove/replace/copy/move/test
格式：JSON，路径依赖严格
不依赖资源Schema，纯路径操作

🎯 适用场景

数组元素的精确操作
Strategic Merge无法满足的复杂需求
关键场景：为CRD资源打补丁
删除特定字段或配置

kustomization.yaml配置方法：

# overlays/prod/kustomization.yaml
patches:
- path: containers-patchs.json
  target:
    kind: GameServerSet
    name: gforge-.*  # 支持正则匹配

实战示例：精确修改GameServerSet

文件路径：overlays/prod/containers-patchs.json

# overlays/prod/containers-patchs.json
[
  {
    "op": "test",  # 先测试确保路径正确
    "path": "/spec/template/spec/containers/0/name",
    "value": "game-server"
  },
  {
    "op": "replace",
    "path": "/spec/template/spec/containers/0/env/2/value",
    "value": "notice"  # 修改第3个环境变量的值
  },
  {
    "op": "add",
    "path": "/spec/template/spec/containers/0/env/-",
    "value": {
      "name": "ENABLE_PROFILING",
      "value": "true"  # 在数组末尾添加新环境变量
    }
  },
  {
    "op": "replace",
    "path": "/spec/replicas",
    "value": 5  # 修改副本数
  },
  {
    "op": "remove",
    "path": "/spec/template/spec/containers/0/env/1"  # 删除第2个环境变量
  }
]

⚠️ JSON Patch注意事项：
• 路径必须精确匹配，建议先用 kubectl get -o json 查看完整结构
• 使用 test 操作验证路径正确性
• 数组索引从0开始，/- 表示数组末尾

特殊场景为CRD打补丁的挑战与策略

🚨 核心问题：Schema缺失导致的预期外行为

为什么Strategic Merge对K8s原生资源"智能"？
因为Kustomize内置了K8s原生资源的OpenAPI Schema，知道containers列表应该按name字段智能合并。

CRD的问题：
Kustomize默认不认识GameServerSet等CRD结构，无Schema时会降级为简单JSON Merge，可能产生非预期行为。

实际影响示例：

# 期望：只修改第一个容器的镜像，保留其他容器
# 实际：Strategic Merge可能替换整个containers列表

# base-okg/gforge-game/gameserverset.yaml（原始配置）
spec:
  template:
    spec:
      containers:
      - name: game-server
        image: old-image:v1.0
      - name: sidecar
        image: sidecar:v1.0

# overlays/prod/deploy-patch-okg.yaml（补丁）
spec:
  template:
    spec:
      containers:
      - name: game-server
        image: new-image:v2.0  # 只想改这个

# 结果：sidecar容器可能被删除！

解决方案对比：

方案一：提供Schema（高级）

# kustomization.yaml
openapi:
  path: https://raw.githubusercontent.com/openkruise/kruise/master/config/crd/bases/apps.kruise.io_gameserversets.yaml

适合团队标准化
需要维护Schema地址
网络依赖

方案二：使用JSON Patch（推荐）

[
  {
    "op": "replace",
    "path": "/spec/template/spec/containers/0/image",
    "value": "new-image:v2.0"
  }
]

稳定可靠，不依赖Schema
精确控制
路径明确，便于调试

💡 最佳实践建议：
• CRD补丁优先选择JSON Patch
• 路径构建前先用 kubectl get gameserverset -o json 查看结构
• 使用 test 操作验证路径正确性
• 复杂补丁可以拆分为多个简单操作

🛠️ 实用工具和技巧

路径构建辅助

# 查看完整资源结构
kubectl get gameserverset gforge-game -o json | jq '.'

# 验证补丁效果（不实际应用）
kustomize build overlays/dev --dry-run

常见错误排查

Strategic Merge意外替换列表：检查是否缺少Schema
JSON Patch路径错误：使用test操作验证
补丁不生效：检查target匹配条件

路径语法速查

/spec/replicas          # 简单字段
/spec/template/spec/containers/0  # 数组第一个元素
/spec/template/spec/containers/-  # 数组末尾添加
~1 表示 /                # 路径转义
~0 表示 ~                # 路径转义

🎮 第三步：游戏运维常见场景实战

新版本发布流程

触发时机：游戏版本更新、功能发布、紧急修复

新手操作指南

获取新版本镜像标签（从CI/CD系统或镜像仓库）
修改 kustomization.yaml 中的 images.newTag
提交到Git仓库，写明版本更新说明
观察ArgoCD同步状态，确认部署成功
验证服务运行状态，检查日志和监控

活动期间扩容

触发时机：大型活动、版本首发、玩家高峰期

# 1. 评估需要扩容的服务
# 2. 修改 deploy-patch-okg.yaml
spec:
  replicas: 10  # 根据预估负载设置
  
# 3. 同时调整资源限制
resources:
  requests:
    cpu: "2"
    memory: "4Gi"
    
# 4. 考虑相关服务联动扩容（网关、数据库连接池等）

数据库切换

触发时机：数据库迁移、主从切换、性能优化

# 修改 cm.yaml 中的数据库配置
db:
  login:
    host: <ip1>  # 新数据库地址
    port: 3306
    poolsize: 20       # 可能需要调整连接池
    
# 注意事项：
# 1. 先在开发环境验证
# 2. 确保新数据库数据同步完成
# 3. 考虑灰度切换方案

操作建议：
• 先在 dev 环境验证配置正确性
• 生产环境操作前做好配置备份
• 关注平台上的部署状态和服务健康检查

🏷️ 环境配置差异对比

开发环境 (dev) DEV

debug true

loglevelname debug

replicas 1

autosync true

基础配置 base-okg/

生产环境 (prod) PROD

debug false

loglevelname notice

replicas 3-5

autosync false

基础配置 base/

版署环境 (banshu) SPECIAL

合规配置版署要求

功能限制特殊配置

基础配置 base/

配置选择原则：
• 开发环境使用 base-okg/ (GameServerSet) 便于调试
• 生产环境使用 base/ (标准Deployment) 保证稳定性
• 特殊环境根据业务需求选择合适的基础配置

📋 游戏服务组件架构

Gateway
网关服务

Center
中心服务

Recharge
充值服务

Game
游戏核心

Rank
排行榜

Common
通用服务

FSync
帧同步

服务通信说明：
• Center 与其他服务通过内部RPC通信
• Center 中心服务负责服务发现和协调，可能引起单点故障
• Login 服务设计层面是无状态，允许自由伸缩
• Game 能伸不能缩，所有组件涉及存档、讲究开停顺序，详见接口文档
• 社交类服务（Chat/Friend/Guild）独立部署，按需扩展

🔧 常用操作速查

调整副本数：
修改 deploy-patch-okg.yaml 中的 replicas

更新版本：
修改 kustomization.yaml 中的 images.newTag

业务配置：
修改 cm.yaml 中的数据库、Redis配置

域名配置：
修改 ingress.yaml 中的路由规则

🎮 游戏业务git配置管理指南

🏗️ 架构概览

⚙️ 实现方法

🚀 实战部署

🛠️ 运维管理

🚀 新手快速上手

🎯 第二步：重新认识Kustomize补丁机制

纠正认知：我们讨论的都是Kustomize功能

🔧 Kustomize两种补丁机制实战

核心机制一 Strategic Merge Patch（策略性合并补丁）

📋 机制原理

🎯 适用场景

kustomization.yaml配置方法：

实战示例：活动期间扩容

核心机制二 JSON Patch（精确路径补丁）

📋 机制原理

🎯 适用场景

kustomization.yaml配置方法：

实战示例：精确修改GameServerSet

特殊场景 为CRD打补丁的挑战与策略

实际影响示例：

解决方案对比：

方案一：提供Schema（高级）

方案二：使用JSON Patch（推荐）

🛠️ 实用工具和技巧

路径构建辅助

常见错误排查

路径语法速查

新版本发布流程

新手操作指南

活动期间扩容

数据库切换

开发环境 (dev) DEV

生产环境 (prod) PROD

版署环境 (banshu) SPECIAL

🔧 常用操作速查

特殊场景为CRD打补丁的挑战与策略