# 开发调试说明

本文档说明如何在当前仓库内完成本地开发、联调、单节点调试和 Docker 全套环境调试。

## 调试方式选择

仓库当前有两种常用开发方式：

| 方式 | 适用场景 | 说明 |
| --- | --- | --- |
| dev 环境单节点调试 | 日常功能开发 | 内部已有完整 dev 环境，开发时通常只需要启动本地 `game` 节点 |
| 本机 local 环境全套联调 | 排查节点交互、网关、会话、Docker 问题 | 依赖 `etc/docker/local_db.yaml` 与 `etc/docker/local.yaml` |

优先建议：

1. 业务开发先用 `dev.json` 启动本地 `game` 节点。
2. 只有在需要验证完整链路时，再切到 `local.json` 加 Docker 全套节点。

## 环境要求

### 基础工具

| 工具 | 版本要求 | 用途 |
| --- | --- | --- |
| Go | 1.24+ | 编译与运行 |
| Docker Desktop | 最新稳定版 | 本地 Redis、MongoDB、NATS 与整套 local 节点 |
| protoc | 3.17.3 | 生成协议代码 |
| protoc-gen-go | 1.36.8 | 生成 Go 协议代码 |

### Git 配置

仓库要求关闭 AutoCRLF：

```bash
git config --global core.autocrlf false
git config --global core.safecrlf false
```

## 项目初始化

```bash
git clone <repository-url>
cd f1-server
make init
make chmod
make code
```

如果需要同步外部配置：

```bash
make pull-excel
make pull-proto
make pull-cherry
```

## 方式一：dev 环境单节点调试

这是仓库内最常用的开发方式。

### 核心结论

- 使用配置文件：`etc/profile/dev.json`
- 默认依赖：dev 环境中的 Redis、MongoDB、NATS
- 本地只启动一个 `game` 节点即可
- 启动命令中的 `-node=1` 表示当前实例匹配 `game` 节点配置里的正则 `^\d+$`

### 启动命令

在仓库根目录先编译：

```bash
make code
```

然后进入任意节点目录启动，日常开发通常只启动 `game`：

```bash
cd nodes/game
run -path=../../etc/profile/dev.json -node=1
```

如果需要调试其他节点，可以使用：

```bash
cd nodes/master && run -path=../../etc/profile/dev.json -node=master-1
cd nodes/center && run -path=../../etc/profile/dev.json -node=center-1
cd nodes/gate && run -path=../../etc/profile/dev.json -node=gate-1
cd nodes/web && run -path=../../etc/profile/dev.json -node=web-1
cd nodes/map && run -path=../../etc/profile/dev.json -node=map-1
cd nodes/chat && run -path=../../etc/profile/dev.json -node=chat-1
cd nodes/record && run -path=../../etc/profile/dev.json -node=record-1
```

### dev 环境关键依赖

`dev.json` 当前直接写死了下列连接：

| 组件 | 配置值 |
| --- | --- |
| NATS | `nats://nats:4222,nats://nats-1:4223,nats://nats-2:4224` |
| Redis | `redis:6379` |
| MongoDB | `mongodb://f1user:***@mongodb:27017` |
| 数据目录 | `../data/` |

如果当前机器不在内部网络，`dev.json` 模式无法正常联调。

## 方式二：本机 local 环境全套联调

`local.json` 配合 Docker Compose 可以在本机启动完整环境。

### 1. 创建网络

首次运行前创建 `f1` 网络：

```bash
docker network create --driver=bridge f1
```

查看网络：

```bash
docker network ls
docker network inspect f1
```

### 2. 启动基础依赖

```bash
docker-compose -f etc/docker/local_db.yaml up -d
```

当前 `local_db` 实际启动内容：

| 服务 | 容器名 | 宿主机端口 | 容器内地址 |
| --- | --- | --- | --- |
| Redis | `redis` | `46379` | `redis:6379` |
| MongoDB | `mongodb` | `27017` | `mongodb:27017` |
| NATS | `nats` | `4222`、`8222` | `nats:4222` |
| NATS-1 | `nats-1` | `4223` | `nats-1:4222` |
| NATS-2 | `nats-2` | `4224` | `nats-2:4222` |

查看状态：

```bash
docker-compose -f etc/docker/local_db.yaml ps
```

### 3. 启动游戏节点

```bash
docker-compose -f etc/docker/local.yaml up -d
```

当前 `local.yaml` 实际启动的节点：

| 节点 | 容器名 | 对外端口 |
| --- | --- | --- |
| master | `f1-master-1` | 无 |
| center | `f1-center-1` | 无 |
| game | `f1-game-1` | 无 |
| map | `f1-map-1` | 无 |
| chat | `f1-chat-1` | 无 |
| record | `f1-record-1` | 无 |
| gate | `f1-gate-1` | `30001` |
| web | `f1-web-1` | `18080 -> 80` |
| ops | `f1-ops-1` | `18081` |

查看状态与日志：

```bash
docker-compose -f etc/docker/local.yaml ps
docker logs -f f1-game-1
docker logs -f f1-gate-1
```

### 4. 停止环境

```bash
docker-compose -f etc/docker/local.yaml down
docker-compose -f etc/docker/local_db.yaml down
```

如需删除网络：

```bash
docker network rm f1
```

## local profile 关键参数

`etc/profile/local.json` 的实际特征如下：

| 配置项 | 当前值 | 说明 |
| --- | --- | --- |
| `env` | `local` | 本地私服环境 |
| `cluster.discovery.mode` | `nats` | 节点发现依赖 NATS |
| `cluster.nats.prefix` | `test` | local 环境也使用 `test` 集群前缀 |
| `redis[0].address` | `redis:6379` | Docker 内部地址 |
| `mongo.*.db_name` | `local-f1-*` | 本地数据库名带 `local-` 前缀 |
| `logger.debug_file_log.enable_console` | `false` | 默认主要写文件 |

## IDE 调试

### VSCode

可直接调试 `nodes/main.go`，通过参数决定环境与节点。

最常用的两个配置如下：

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "dev-game-1",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "${workspaceFolder}/nodes/main.go",
            "args": [
                "run",
                "-path=${workspaceFolder}/etc/profile/dev.json",
                "-node=1"
            ],
            "console": "integratedTerminal"
        },
        {
            "name": "local-gate-1",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            "program": "${workspaceFolder}/nodes/main.go",
            "args": [
                "run",
                "-path=${workspaceFolder}/etc/profile/local.json",
                "-node=gate-1"
            ],
            "console": "integratedTerminal"
        }
    ]
}
```

### GoLand

`Run/Debug Configurations` 中新增 `Go Build` 或 `Go Application`：

- Run kind 选择 package/file 均可
- 入口文件使用 `nodes/main.go`
- Program arguments 使用 `run -path=... -node=...`
- Working directory 使用仓库根目录

## 快速排查

### 查看版本

```bash
run version
```

### 只编译代码

```bash
make code
```

### 运行单测

```bash
go test ./...
go test ./internal/algorithm/astar/
go test -run TestAstar ./internal/algorithm/astar/
```

## 常见问题

### 1. `run` 启动失败，提示节点不匹配

优先检查：

- `-node` 是否命中 profile 中的 `node_id`
- `game` 节点通常是数字，如 `1`、`3`、`6`
- `gate`、`web`、`master` 等节点通常是固定字符串

### 2. 本地已启动 Docker，但节点仍连不上 Redis 或 MongoDB

优先检查：

```bash
docker-compose -f etc/docker/local_db.yaml ps
docker ps
docker network inspect f1
```

然后确认 `local.json` 中使用的是容器内部地址 `redis:6379`、`mongodb:27017`，不是宿主机地址。

### 3. 端口冲突

本地默认暴露端口：

- `30001`：gate
- `18080`：web
- `18081`：ops
- `46379`：Redis
- `27017`：MongoDB
- `4222/4223/4224`：NATS
- `8222`：NATS 监控

如端口冲突，修改对应的 Docker Compose 映射端口。

### 4. 为什么日常开发不建议启动全套节点

因为仓库已经约定：

- 开发期默认依赖现成 dev 环境
- 本地仅启动 `game` 节点即可进入业务开发
- 全套 local 环境更适合排查网关、会话同步、节点互调和容器问题