Kezdőlap Felfedezés Súgó
Regisztráció Bejelentkezés
torren
/
s_cherry_e
1
0
Másolás 0
Fájlok Problémák 0 Beolvasztási kérések 0 Wiki
Branch: dev
Branch-ok Tag-ek
s_cherry_e
/
sr
/
docs
/
0003-profile-config.md

0003-profile-config.md 15 KB
Állandó hivatkozás Előzmények Nyers

Profile 配置文件说明

本文档说明 etc/profile/ 目录下各环境配置文件的组织方式、字段含义和修改原则。

目录说明

环境文件

当前仓库存在的顶层 profile 文件：

文件 说明
local.json 本地 Docker 联调环境
dev.json 开发环境
test.json 测试环境
su.json SU 环境
su_dev.json SU 开发联调环境
lgy.json LGY 环境
lgy_dev.json LGY 开发联调环境
dhc.json DHC 环境
dhc_dev.json DHC 开发联调环境
azw.json AZW 环境
lcs.json 现有环境文件

include 文件

etc/profile/include/ 目录用于拆分公共片段，当前可见的公共配置包括：

文件 用途
logger.json 日志模板
dev_cluster.json 开发环境集群配置
dev_data_config.json 开发环境数据配置
dev_mongodb.json 开发环境 MongoDB 配置
dev_redis.json 开发环境 Redis 配置
dev_queue.json 数据库存盘队列配置
dev_session.json 会话配置
dev_genpool.json 全局 ID 池配置
dev_game.json 开发环境节点配置
dev_battle_record.json 战报配置

配置加载方式

节点启动入口在 nodes/main.go，执行流程是：

  1. 读取命令行参数中的 -path
  2. 读取命令行参数中的 -node
  3. 调用 Cherry 的 profile.Init(path, nodeID)
  4. 根据 nodeID 解析节点类型并启动对应节点

实际启动命令：

run -path=./etc/profile/dev.json -node=1

因此 profile 的正确性，直接决定节点能否启动。

整体结构

一个完整 profile 的典型结构如下：

{
    "@desc": "环境描述",
    "include": [],
    "env": "dev",
    "debug": true,
    "print_level": "debug",
    "cluster": {},
    "data_config": {},
    "node": {},
    "db_queue": {},
    "redis": [],
    "mongo": {},
    "rate_limiter": [],
    "sessions": {},
    "gen-pool": {},
    "battle_record": {},
    "logger": {}
}

并不是所有环境都必须把所有字段写满。

例如：

  • su_dev.json 主要通过 include 引入公共片段
  • local.json 与 dev.json 则直接写了完整结构

基础字段

字段 类型 说明
@desc string 环境描述
include array 需要合并的公共配置文件
env string 环境名
debug bool 是否开启调试模式
print_level string 全局日志级别

include

用于配置复用。

示例：

{
    "include": [
        "include/logger.json",
        "include/dev_mongodb.json",
        "include/dev_redis.json"
    ]
}

适用场景：

  • 同一套 Redis、Mongo、logger 被多个环境共用
  • 平台环境只覆盖少量差异字段

cluster

cluster 用于配置服务发现与节点通信。

结构示例

{
    "cluster": {
        "discovery": {
            "mode": "nats"
        },
        "nats": {
            "master_node_id": "master-1",
            "prefix": "test",
            "address": "nats://nats:4222,nats://nats-1:4223,nats://nats-2:4224",
            "reconnect_delay": 1,
            "max_reconnects": 0,
            "request_timeout": 2,
            "user": "",
            "password": "",
            "pool_size": 16,
            "is_stats": false
        }
    }
}

discovery

字段 说明
mode 服务发现模式，当前项目实际主要使用 nats

当前注释里还预留了：

  • default
  • nats
  • etcd

但仓库现有环境基本都是 nats。

nats

字段 说明
master_node_id 主节点 ID，当前固定为 master-1
prefix 环境隔离前缀
address NATS 地址列表，逗号分隔
reconnect_delay 重连等待时间，单位秒
max_reconnects 最大重连次数，0 表示不限
request_timeout 请求超时，单位秒
user 认证用户
password 认证密码
pool_size 连接池大小
is_stats 是否开启统计

修改原则

  • prefix 必须按环境唯一
  • master_node_id 一般不要改
  • address 必须与实际 NATS 集群对应

data_config

用于配置 Excel 导出的游戏数据加载方式。

结构示例

{
    "data_config": {
        "parser": "json",
        "data_source": "file",
        "file": {
            "file_path": "../data/",
            "ext_name": ".json",
            "reload_time": 3000
        },
        "redis": {
            "address": "redis:6379",
            "password": "xxx",
            "db": 0,
            "prefix_key": "data_config",
            "subscribe_key": "data_config_change"
        }
    }
}

字段说明

字段 说明
parser 解析器类型，当前使用 json
data_source 数据来源，支持 file 或 redis

file

字段 说明
file_path 数据目录
ext_name 文件扩展名
reload_time 热更新检查间隔，毫秒

redis

字段 说明
address Redis 地址
password Redis 密码
db DB 编号
prefix_key 数据前缀
subscribe_key 配置变更订阅键

现状

当前环境主要还是 file 模式，目录通常是 ../data/。

node

node 是最关键的一段，决定当前 profile 支持哪些节点、每个节点如何匹配以及节点私有配置。

结构示例

{
    "node": {
        "gate": [
            {
                "enable": true,
                "node_id": "gate-1",
                "address": ":30001",
                "__settings__": {
                    "heartbeat": 120,
                    "ref_logger": "debug_file_log",
                    "redis_id_list": {
                        "guid_redis_id": "redis-global",
                        "center_redis_id": "redis-global"
                    }
                }
            }
        ]
    }
}

通用字段

字段 说明
enable 是否启用该实例
node_id 节点 ID，可写固定值，也可写正则
address 对外监听地址，部分节点需要
__settings__ 节点私有设置

node_id 规则

常见写法：

写法 含义
gate-1 固定实例
master-1 固定实例
^\d+$ 匹配任意数字 game 节点
^map-\d+$ 匹配多个 map 节点
^chat-\d+$ 匹配多个 chat 节点

__settings__ 常见字段

字段 说明
ref_logger 引用 logger 中的日志配置名
redis_id_list 当前节点依赖的 Redis 配置映射
mongo_id_list 当前节点依赖的 Mongo 配置映射
heartbeat gate 心跳时间
battle_validation game 是否开启战斗校验
allow_register web 是否允许注册

节点类型

仓库当前支持的节点类型可从 nodes/main.go 看出：

  • master
  • center
  • game
  • gate
  • web
  • ops
  • chat
  • map
  • record

db_queue

db_queue 用于配置 MongoDB 批量落盘策略。

相关代码在 internal/component/db/queue/table_queue_config.go。

结构示例

{
    "db_queue": {
        "save_ticker": 3,
        "save_count": 1000,
        "stop_save_count": 10000,
        "print_save_log": false,
        "tables": []
    }
}

字段说明

字段 说明
save_ticker 定时保存周期，秒
save_count 每次批量保存条数
stop_save_count 节点停止时一次处理条数
print_save_log 是否打印保存日志
tables 针对单表覆盖默认参数

单表覆盖

例如 lgy.json 与 su.json 中，会针对 map_tile、map_res 一类高频表做特殊配置。

示例：

{
    "tables": [
        {
            "name": "map_tile",
            "save_ticker": 120,
            "save_count": 300
        }
    ]
}

redis

redis 用于定义 Redis 实例列表，节点通过 redis_id_list 引用。

结构示例

{
    "redis": [
        {
            "redis_id": "redis-global",
            "address": "redis:6379",
            "password": "xxx",
            "db": 0,
            "pool_size": 64,
            "desc": "全局"
        }
    ]
}

字段说明

字段 说明
redis_id 逻辑 ID
address 地址
password 密码
db Redis DB
pool_size 连接池大小
desc 描述

使用关系

  • 先在 redis 中声明实例
  • 再在 node.*[].__settings__.redis_id_list 中引用
  • 运行时由 Redis 组件读取 redis_id_list

mongo

mongo 用于定义 MongoDB 分组配置，节点通过 mongo_id_list 引用。

结构示例

{
    "mongo": {
        "db_game_group": [
            {
                "enable": true,
                "db_id": "mongo-f1-game",
                "db_name": "f1-game",
                "uri": "mongodb://user:pass@host:27017",
                "timeout": 3000
            }
        ]
    }
}

字段说明

字段 说明
enable 是否启用
db_id 逻辑 ID
db_name 数据库名
uri Mongo 连接串
timeout 超时，毫秒

分组说明

分组 用途
db_game_group game 数据
db_center_group center 数据
db_map_group map 数据

使用关系

  • 先在 mongo 中定义 db_id
  • 再在节点 mongo_id_list 中引用
  • 数据库组件根据 mongo_id_list 取对应实例

rate_limiter

用于限流配置。

结构示例

{
    "rate_limiter": [
        {
            "enable": true,
            "rate_id": "ip_rate",
            "interval": 1,
            "capacity": 60,
            "quantum": 60,
            "clean_ticker_interval": 10,
            "clean_before_minute": 5,
            "error_code": 205
        }
    ]
}

字段说明

字段 说明
enable 是否启用
rate_id 限流器 ID
interval 加令牌周期
capacity 桶容量
quantum 每次补充数量
clean_ticker_interval 清理周期
clean_before_minute 清理多久未使用的数据
error_code 触发限流时返回码

sessions

用于会话系统的 Redis 配置。

相关代码在 internal/sessions/actor.go。

结构示例

{
    "sessions": {
        "redis_id": "redis-global"
    }
}

字段说明

字段 说明
redis_id 会话系统使用的 Redis 实例 ID

gen-pool

用于全局 ID 生成池配置。

相关代码在 internal/gen_pool/actor.go。

结构示例

{
    "gen-pool": {
        "redis_id": "redis-global"
    }
}

字段说明

字段 说明
redis_id ID 池使用的 Redis 实例 ID

battle_record

用于战报记录存储配置。

相关代码：

  • nodes/record/mode_file.go
  • nodes/record/mode_cloud.go

结构示例

{
    "battle_record": {
        "enable": true,
        "mode": "file",
        "file": {
            "suffixKey": ".bin",
            "succeedPathKey": "../battle_record/succeed",
            "failedPathKey": "../battle_record/failed"
        },
        "cloud": {
            "url": "",
            "secretKey": ""
        }
    }
}

字段说明

字段 说明
enable 是否启用
mode 存储方式，file 或 cloud

file

字段 说明
suffixKey 后缀名
succeedPathKey 成功目录
failedPathKey 失败目录

cloud

字段 说明
url 上传地址
secretKey 上传鉴权

logger

用于定义日志模板，节点通过 ref_logger 引用。

结构示例

{
    "logger": {
        "debug_file_log": {
            "level": "debug",
            "stack_level": "error",
            "enable_write_file": true,
            "enable_console": false,
            "max_age": 7,
            "time_format": "15:04:05.000",
            "print_caller": true,
            "rotation_time": 86400,
            "file_link_path": "logs/%nodeid.log",
            "file_path_format": "logs/%nodeid_%Y%m%d%H%M.log"
        }
    }
}

当前常用日志模板

从 include/logger.json 看，常见模板有：

  • debug_console_log
  • debug_file_log
  • debug_log
  • info_console_log
  • info_file_log
  • info_log

字段说明

字段 说明
level 日志级别
stack_level 触发堆栈打印的级别
enable_write_file 是否写文件
enable_console 是否输出控制台
max_age 保留天数
time_format 时间格式
print_caller 是否打印调用位置
rotation_time 滚动周期，秒
file_link_path 当前日志软链路径
file_path_format 日志文件命名格式

不同环境的典型差异

local.json

  • 本地 Docker 联调
  • Redis 地址是 redis:6379
  • Mongo 库名是 local-f1-*
  • 日志默认写文件

dev.json

  • 开发环境
  • Redis、Mongo、NATS 指向开发环境地址
  • game 节点通常使用数字 ID

*_dev.json

  • 通过 include 复用公共配置
  • 一般只覆盖少量差异，如 env、cluster.nats.pool_size

平台环境文件

例如 su.json、lgy.json、azw.json：

  • 通过不同 env 区分平台
  • 通过不同 cluster.nats.prefix 做集群隔离
  • 通过不同 db_name 做数据库隔离
  • game 节点编号可能固定，也可能允许多实例

修改建议

新增环境

建议流程：

  1. 复制最接近的现有环境文件
  2. 修改 env
  3. 修改 cluster.nats.prefix
  4. 修改 Redis 与 Mongo 地址、密码、库名
  5. 修改节点 node_id 与端口
  6. 启动单节点验证

修改已有环境

优先检查四个高风险字段：

  1. cluster.nats.prefix
  2. mongo.*.db_name
  3. node.*[].node_id
  4. node.*[].__settings__.redis_id_list / mongo_id_list

不建议直接改的内容

  • master_node_id
  • 节点类型名称
  • 已上线环境的 db_name
  • 已上线环境的 game 节点 ID 规则

启动示例

run -path=./etc/profile/local.json -node=gate-1
run -path=./etc/profile/dev.json -node=1
run -path=./etc/profile/su.json -node=master-1
run -path=./etc/profile/lgy.json -node=web-1

常见错误

1. -node 与 node_id 不匹配

例如 profile 里写的是 node_id: "web-1"，启动却用了 -node=web。

2. 只改了 redis，没改 redis_id_list

节点最终使用哪个 Redis，不是看你定义了多少个 redis，而是看节点 settings 引用了哪个 ID。

3. include 引入了公共配置，但顶层又被错误覆盖

这种问题最容易出现在 *_dev.json。改动前先确认最终覆盖顺序。

4. NATS prefix 与其他环境重复

节点会串环境，这是最危险的配置错误之一。