# 生产环境部署说明

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

## 先说明一件事

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

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

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

## 部署目标

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

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

## 环境文件组织

### 当前已有环境

| 文件 | 用途 |
| --- | --- |
| `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`，命令形式统一为：

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

生产发布前至少执行：

```bash
make init
make chmod
make code
```

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

```bash
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`

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

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

## profile 编写原则

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

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

然后只改以下内容：

1. `env`
2. `cluster.nats.prefix`
3. `cluster.nats.address`
4. `redis`
5. `mongo`
6. `node`
7. `logger`

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

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

## 节点部署建议

### 单实例节点

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

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

### 多实例节点

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

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

### 启动顺序

建议按依赖顺序启动：

1. Redis、MongoDB、NATS
2. `master`
3. `center`
4. `game`
5. `map`
6. `chat`
7. `record`
8. `gate`
9. `web`
10. `ops`

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

## 启动命令示例

以下示例以 `su.json` 为例：

```bash
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. 发布前检查

```bash
make code
go test ./...
run version
```

重点检查：

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

### 2. 灰度发布

建议：

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

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

- `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`，服务能启动，但数据会写错库，这类问题比启动失败更危险。

## 建议

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

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