生产环境部署说明

本文档说明当前仓库的环境组织方式、生产环境部署原则、节点部署建议和上线检查项。

先说明一件事

当前仓库 etc/profile/ 目录下不存在 prod.json，现有环境文件是：

test.json
su.json
lgy.json
dhc.json
azw.json
以及对应的 _dev.json

这意味着当前项目的“生产部署”不是统一依赖一个固定 prod.json，而是按平台或环境拆成独立 profile。部署时应以目标环境对应的 profile 为准，而不是假设存在通用 prod.json。

部署目标

生产环境部署需要解决四类问题：

中间件可用，Redis、MongoDB、NATS 先就绪。
profile 与目标环境一一对应，不能混用前缀、库名、Redis ID。
节点按职责拆分启动，尤其 master、gate、game、map、center、web。
上线前完成配置、端口、日志、数据写入和节点发现验证。

环境文件组织

当前已有环境

文件	用途
`test.json`	测试环境
`su.json`	SU 环境
`lgy.json`	LGY 环境
`dhc.json`	DHC 环境
`azw.json`	AZW 环境
`*_dev.json`	对应环境的开发联调版本

环境隔离的关键字段

实际隔离主要依赖以下配置：

字段	作用
`env`	环境名
`cluster.nats.prefix`	集群消息前缀，必须全环境唯一
`redis[].redis_id`	Redis 实例逻辑名
`mongo.*[].db_name`	MongoDB 数据库名
`node.*[].node_id`	节点实例标识

示例：

su.json 使用 prefix: "su"，数据库名形如 su-f1-game
lgy.json 使用 prefix: "lgy"，数据库名形如 lgy-f1-game
azw.json 使用 prefix: "azw"，数据库名形如 azw-f1-game

部署前准备

机器与系统要求

仓库没有提供强制规格表，当前建议按节点职责拆分：

节点	建议
`master`	单独部署，单实例
`center`	单独部署，单实例或主备
`gate`	可多实例，前置负载均衡
`game`	可多实例，按滚服或区服扩容
`map`	可多实例，视地图压力扩容
`web`	可多实例
`chat`	可多实例
`record`	按战报写入压力部署
`ops`	单独控制访问来源

最低前提：

Go 1.24+
MongoDB 7.0+
Redis 可用
NATS 集群可用
服务器时区统一为 Asia/Shanghai

构建产物

仓库实际启动入口是 nodes/main.go，命令形式统一为：

run -path=./etc/profile/<env>.json -node=<node-id>

生产发布前至少执行：

make init
make chmod
make code

如果涉及协议或配置更新，再执行：

make proto
make excel

中间件部署

Redis

用途：

会话存储
全局 ID 生成
部分业务缓存

部署要求：

为目标环境分配独立实例或独立逻辑库
与 profile 内 redis_id 和 address 保持一致
密码必须与环境文件一致

MongoDB

用途：

游戏、中心、地图等持久化数据

当前 profile 使用四组逻辑库：

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

要求：

为每个环境使用独立 db_name
用户名、密码和 URI 必须与 profile 一致
部署前确认账号具有建表、读写权限

NATS

用途：

节点注册
远程调用
集群消息通信

仓库现有配置均默认：

cluster.discovery.mode = nats
cluster.nats.master_node_id = master-1

因此生产环境必须先保证：

master-1 所在节点可启动。
其他节点能访问 NATS。
cluster.nats.prefix 与其他环境不冲突。

profile 编写原则

新增一个生产环境时，建议复制最接近的环境文件，例如：

新平台服复制 su.json / azw.json
新联运环境复制 lgy.json / dhc.json

然后只改以下内容：

env
cluster.nats.prefix
cluster.nats.address
redis
mongo
node
logger

不要直接复用别的环境的：

Redis 库
Mongo 数据库名
NATS prefix
game 节点固定编号

节点部署建议

单实例节点

这些节点通常只部署一个：

节点类型	说明
`master`	服务发现核心节点
`center`	账户与中心服务
`ops`	运维入口，建议严格限制访问

多实例节点

这些节点通常根据压力扩容：

节点类型	说明
`gate`	前置接入，可多实例
`game`	玩家逻辑，可多实例
`map`	沙盘地图，可多实例
`web`	HTTP 服务，可多实例
`chat`	聊天服务，可多实例
`record`	战报与记录，可多实例

启动顺序

建议按依赖顺序启动：

Redis、MongoDB、NATS
master
center
game
map
chat
record
gate
web
ops

gate 和 web 可以放在后面启动，避免外部流量先进入。

启动命令示例

以下示例以 su.json 为例：

run -path=./etc/profile/su.json -node=master-1
run -path=./etc/profile/su.json -node=center-1
run -path=./etc/profile/su.json -node=gate-1
run -path=./etc/profile/su.json -node=web-1
run -path=./etc/profile/su.json -node=ops-1
run -path=./etc/profile/su.json -node=3
run -path=./etc/profile/su.json -node=map-1
run -path=./etc/profile/su.json -node=chat-1
run -path=./etc/profile/su.json -node=record-1

注意：

game 节点有的环境是固定数字，如 3、6
有的环境使用正则 ^\d+$，表示可多开多个 game 实例
center、chat、map 在部分环境中也用正则匹配多实例

发布流程建议

1. 发布前检查

make code
go test ./...
run version

重点检查：

profile 是否引用正确
目标节点 node_id 是否存在
Redis、Mongo、NATS 地址是否可达
日志目录是否可写
etc/data/ 与 internal/data/ 是否已同步

2. 灰度发布

建议：

先启动新版本 master 之外的非入口节点做验证。
确认节点注册成功后，再切换 gate、web。
最后再放量外部流量。

如果是替换式发布，至少保证：

master 不先于依赖中间件下线
gate 切流前，game/map/center 已全部可用

3. 回滚准备

上线前保留：

上一版本二进制
上一版 profile
数据库与 Redis 变更记录
本次构建版本号

如果本次包含协议、配置或数据结构变更，必须先评估是否可逆，不能把回滚建立在“应该没问题”上。

上线核对清单

中间件

Redis 可连接
MongoDB 可连接
NATS 集群正常
master-1 能连通 NATS

配置

env 正确
cluster.nats.prefix 唯一
mongo.db_name 没有串环境
redis_id_list、mongo_id_list 与基础配置可对应
ref_logger 指向存在的 logger 配置

节点

每个启动命令的 -node 与 profile 匹配
gate 和 web 的对外端口未冲突
多实例节点的实例 ID 不重复

数据

etc/data/ 为目标版本
battle_record 存储路径可写
db_queue 参数与环境负载匹配

常见错误

1. 不同环境共用了同一个 NATS prefix

结果：

节点发现串环境
远程调用可能打到错误节点

这是高危配置错误，必须先改 cluster.nats.prefix。

2. `game` 节点编号写错

例如 profile 里写死 node_id = "3"，启动时却用了 -node=1，会直接启动失败。

3. Redis ID 存在，但节点 settings 没引用

redis 配置本身正确不代表节点能用。真正生效的是 __settings__.redis_id_list 里的映射。

4. Mongo 配置正确，但数据库名串环境

例如把 su 环境写成 lgy-f1-game，服务能启动，但数据会写错库，这类问题比启动失败更危险。

建议

如果后续要补齐真正统一的生产部署能力，优先做两件事：

新增标准化 prod.json 或明确的环境模板。
增加 systemd、Supervisor 或容器编排脚本，避免每个节点依赖手工命令启动。

0002-prod-env-deployment.md 8.1 KB Історія Запис