# Server Manager 用户使用教程

这份教程面向日常使用者，按“安装启动 -> 打开项目 -> 配置 -> 创建和管理服务器”的顺序走一遍。

## 1. 安装与启动

### Windows 安装版

1. 获取安装包 `build/output/ServerManager_Setup.exe`。
2. 双击安装，按向导完成安装。
3. 从开始菜单、桌面快捷方式，或安装目录下的 `ServerManager.exe` 启动。

### 源码运行

Windows：

```bat
pip install -r requirements.txt
scripts\run\run.bat gui
```

Linux：

```bash
pip install -r requirements.txt
chmod +x scripts/run/run.sh
./scripts/run/run.sh gui
```

没有桌面环境时可以直接使用命令行：

```bash
./scripts/run/run.sh list
./scripts/run/run.sh --help
```

## 2. 打开服务器项目

启动后在欢迎页点击“打开项目”，选择服务器项目根目录。

正确的项目根目录通常包含这些内容：

- `run` 目录
- `config` 目录
- `rebar3` 或 `rebar3.cmd`
- `apps` 目录

不要选择这些子目录：

- `run`
- `config`
- `.server_manager/config`

首次打开项目后，工具会在项目下准备：

```text
<项目根>/.server_manager/config/
```

其中会包含默认模板和工具配置文件。

## 3. 配置文件说明

项目相关配置都随项目保存，不放在安装目录里。

常用文件：

- `<项目根>/.server_manager/config/default.config`
  默认配置模板，定义创建服务器和生成配置时的默认值。
- `<项目根>/config/project.config`
  项目共享配置，适合放团队共用的数据库、节点、前缀等基础值。
- `<项目根>/.server_manager/config/user.config`
  当前用户配置，由工具设置页保存，优先级最高。
- `<运行目录>/<服务器目录>/config/kv.config`
  单个服务器的差异化配置，创建服务器时生成。

读取优先级从低到高：

```text
default.config < project.config < user.config < 单服 kv.config
```

也就是说：

- 通用默认值放 `default.config`
- 团队共享值放 `config/project.config`
- 自己机器上的路径、数据库、Erlang 路径放 `user.config`
- 某一台服务器独有的端口、库名、节点等放对应的 `kv.config`

## 4. 工具设置

打开“工具设置”页后，重点确认以下区域。

### 项目目录配置

服务器根目录和运行目录只用于查看，不能在这里修改。

如果目录不对，请回到欢迎页或菜单中重新打开正确的项目根目录。

### 启动窗口配置

Windows 下可以选择：

- 自动
- cmd
- PowerShell
- 其他运行 EXE

选择“其他”时，填写终端程序路径即可，工具会自动生成实际启动脚本。

### 数据库配置

填写数据库主机、端口、用户和密码后，点击“测试连接”。

测试成功表示当前工具能连上数据库；测试失败时，检查：

- 主机和端口是否正确
- 数据库账号和密码是否正确
- 当前机器是否能访问数据库网络
- 防火墙或数据库白名单是否放行

### Erlang 与节点配置

填写 Erlang/OTP 安装根目录，例如：

```text
E:\app\erlang\Erlang_OTP_25
```

登录服节点、中心服节点和 Cookie 会用于启动、连接、状态检查等功能。

配置完成后点击“保存配置”，内容会写入：

```text
<项目根>/.server_manager/config/user.config
```

## 5. 创建服务器

进入“创建服务器”页：

1. 选择服务器类型：游戏服、登录服、中心服、跨服服或客户端服。
2. 设置服务器 ID。
3. 确认数据库名、端口、节点、开服时间等字段。
4. 点击“创建服务器”。

创建成功后，工具会在运行目录下生成对应服务器目录，并写入：

```text
<运行目录>/<服务器目录>/config/kv.config
<运行目录>/<服务器目录>/config/sys.config
```

如果同类型同 ID 的服务器已经存在，工具会提示选择其他 ID 或确认覆盖。

## 6. 服务器管理

“服务器管理”页用于查看和操作已创建的服务器。

常用操作：

- 启动服务器
- 快速启动服务器
- 停止服务器
- 连接远程节点
- 查看账号
- 清档

如果节点连接失败，优先检查：

- Cookie 是否一致
- 节点名格式是否正确，例如 `name@ip`
- Erlang 路径是否可用
- 网络和防火墙是否放行

## 7. 日志查看

“日志查看”页可以检索服务器日志。

推荐将 `rg.exe` 放在：

```text
resources/bin/rg.exe
```

打包后工具会优先使用 ripgrep 做日志搜索，速度更快。

## 8. 命令行常用命令

Windows：

```bat
scripts\run\run.bat list
scripts\run\run.bat create --type game --id 1
scripts\run\run.bat start --server ddxq_game_s1
scripts\run\run.bat stop --server ddxq_game_s1
scripts\run\run.bat connect --server ddxq_game_s1
scripts\run\run.bat doctor
```

Linux：

```bash
./scripts/run/run.sh list
./scripts/run/run.sh create --type game --id 1
./scripts/run/run.sh start --server ddxq_game_s1 --background
./scripts/run/run.sh stop --server ddxq_game_s1
./scripts/run/run.sh connect --server ddxq_game_s1
./scripts/run/run.sh doctor
```

查看配置：

```bash
./scripts/run/run.sh config files
./scripts/run/run.sh config show
./scripts/run/run.sh config show --server ddxq_game_s1
```

## 9. 常见问题

### 打开项目后路径不对

通常是打开项目时选错了目录。请重新选择服务器项目根目录，不要选择 `run` 子目录。

### 创建服务器后无法启动

检查：

- `run` 目录是否存在
- 单服 `config/kv.config` 是否生成
- `config/sys.config` 是否生成
- Erlang 路径是否正确
- `rebar3` 或 `rebar3.cmd` 是否可用

### 数据库连接失败

先在“工具设置”页点击“测试连接”。如果失败，按提示检查数据库地址、端口、账号、密码和网络连通性。

### 配置改了但启动结果没变化

确认改的是正确层级：

- 全局默认值改 `default.config`
- 项目共享值改 `config/project.config`
- 当前用户值改 `user.config`
- 单台服务器值改对应服务器的 `kv.config`

单服配置优先级最高，如果 `kv.config` 中已有同名配置，会覆盖上层配置。