开发调试说明

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

调试方式选择

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

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

优先建议：

业务开发先用 dev.json 启动本地 game 节点。
只有在需要验证完整链路时，再切到 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：

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

项目初始化

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

如果需要同步外部配置：

make pull-excel
make pull-proto
make pull-cherry

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

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

核心结论

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

启动命令

在仓库根目录先编译：

make code

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

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

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

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 网络：

docker network create --driver=bridge f1

查看网络：

docker network ls
docker network inspect f1

2. 启动基础依赖

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`

查看状态：

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

3. 启动游戏节点

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`

查看状态与日志：

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

4. 停止环境

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

如需删除网络：

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，通过参数决定环境与节点。

最常用的两个配置如下：

{
    "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 使用仓库根目录

快速排查

查看版本

run version

只编译代码

make code

运行单测

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