server_manager/README.md

# Server Manager

一个跨平台的服务器管理工具，支持 Windows 和 Linux 系统。

- **Windows**: 提供 PyQt6 可视化 GUI 界面
- **Linux**: 提供命令行工具，支持 screen/tmux 后台运行

## 功能特性

### 控制台
- **编译代码**: 编译游戏服务器代码 (`rebar3 as game_server_dev compile`)
- **编译协议**: 生成协议文件 (`rebar3 protobuf compile`)
- **编译Table**: 生成数据表 (`rebar3 cache compile`)
- **编译Tbllog**: 生成日志表 (`rebar3 tbllog compile`)
- **清理编译**: 清理编译产物
- **运行服务器**: 选择并运行服务器
- **快速启动**: 快速启动服务器
- **连接节点**: 远程连接服务器节点
- **Windows 启动窗口**: Windows 下可在工具设置中选择自动、`cmd`、`PowerShell` 或其他运行 EXE。

### 创建服务器
- 创建游戏服务器 (GameServer)
- 创建登录服务器 (LoginServer)
- 创建客户端服务器 (ClientServer)
- 创建中心服务器 (CenterServer)
- 创建跨服服务器 (CrossServer)
- 支持自定义数据库配置
- 支持自定义登录服务器配置

### 服务器管理
- 查看所有已创建的服务器列表
- 启动/快速启动服务器
- 停止服务器
- 远程连接服务器
- 删除服务器

## 打包与发版（维护者）

**推荐流程**：先打**本地测试包**验证，再正式发版。

1. `scripts\package\pack_local_test.bat` 或 `python scripts/package/pack_local_test.py` → 产出 `build\output_local\ServerManager_Setup_LOCAL.exe`（不覆盖正式 `build\output\`）。
2. 本地安装测试通过后，再按 **[RELEASE.md](RELEASE.md)** 执行版本号与 `scripts\package\pack_all.bat` / `scripts\package\release.bat` 发版。

**`rg.exe`（可选但推荐）**：将 [ripgrep](https://github.com/BurntSushi/ripgrep/releases) 的 `rg.exe` 放在 `resources\bin\rg.exe`，执行 `scripts\package\build.bat` 时会自动复制进 `src\dist\ServerManager\`，安装后与 `ServerManager.exe` 同目录，日志检索与文件搜索可直接调用。

## 软件安装说明

### Windows 安装包安装（推荐）

1. 从 `build\output` 目录获取安装包：`ServerManager_Setup.exe`
2. 双击运行安装程序，按向导完成安装
3. 安装完成后可从开始菜单或桌面快捷方式启动 Server Manager

### 从源码运行（开发/便携使用）

**Windows：**

1. 确保已安装 Python 3.8+ 和 Erlang/OTP
2. 在 `server_manager` 根目录安装依赖后直接运行：
   ```batch
   pip install -r requirements.txt
   scripts\run\run.bat gui
   ```

**Linux：**

1. 确保已安装 Python 3.8+ 和 Erlang/OTP
2. 在 `server_manager` 根目录安装依赖后运行：
   ```bash
   pip install -r requirements.txt
   chmod +x scripts/run/run.sh
   ./scripts/run/run.sh list    # 命令行
   ./scripts/run/run.sh gui     # 若有桌面环境可启动 GUI
   ```

> **说明**：config 配置是各个项目的配置文件，放在**各个项目的目录下**。工具本身的配置见下方「配置说明」。

## 快速上手（Windows GUI）

Windows 下推荐直接使用图形界面，第一次使用按下面流程即可：

完整使用教程见 [docs/USER_GUIDE.md](docs/USER_GUIDE.md)。

1. 启动工具：
   - 安装版：从开始菜单、桌面快捷方式，或安装目录下的 `ServerManager.exe` 启动。
   - 源码版：在项目根目录执行 `scripts\run\run.bat gui`，或设置 `PYTHONPATH=src` 后执行 `python -m entrypoints`。
2. 打开项目：
   - 在欢迎页点击“打开项目”，或在菜单 `文件 -> 打开项目` 中选择目录。
   - **这里选择的是服务器项目根目录**，例如 `E:\game\server_root`。
   - **不要选择** `run` 目录、`config` 目录、`.server_manager\config` 目录。
3. 首次打开项目时，工具会自动把安装目录（源码运行时为仓库 `resources/config`）里的模板复制到：
   - `<项目根目录>\.server_manager\config\`
4. 打开 `工具设置` 页后，重点确认这 3 个路径：
   - `服务器根目录`：项目根目录本身，例如 `E:\game\server_root`
   - `运行目录`：服务器实例目录，通常为 `<项目根目录>\run`
   - `Erlang 路径`：Erlang/OTP 安装根目录，例如 `E:\app\erlang\Erlang_OTP_25`
5. 配置保存后即可开始使用各功能页：
   - `控制台`：编译代码、快速启动、连接节点、执行常用命令
   - `创建服务器`：按模板创建 game/login/center/cross/client 等服务器
   - `服务器管理`：查看本地/远程服务器、启动、停止、连接
   - `日志查看`：检索和查看日志
   - `工具设置`：维护路径、数据库、节点、Cookie、Erlang 等配置

> Windows 启动窗口说明：可在 `工具设置 -> 启动窗口配置` 选择自动、`cmd`、`PowerShell` 或其他。自动模式仍会优先使用 Windows Terminal（`wt.exe`），未安装时回退到 `cmd`。选择“其他”时只需要配置运行 EXE，工具会为每次启动生成具体的临时启动脚本；MobaXterm 会自动使用 `-newtab "sh <临时脚本>"`，脚本内切换到项目目录并启动 Windows PowerShell 执行真实服务器/连接命令。底层使用环境变量 `SERVER_MANAGER_TERMINAL` 与 `SERVER_MANAGER_TERMINAL_EXE`。

### 选择项目目录的判断方法

如果你不确定“打开项目”该选哪一级目录，可以按下面规则判断：

- 正确的项目根目录通常是 `run`、`config`、`rebar3` 等目录/文件所在的上一级目录。
- 工具打开成功后，会在该目录下生成或读取 `.server_manager\config`。
- 如果你选成了 `run` 目录，后续“运行目录”会变成 `run\run`，这是错误的。

## 安装依赖

### Linux（命令行版本，无需 GUI 依赖）

命令行版本不需要额外依赖，只需 Python 3.8+

```bash
# 可选：如果需要 GUI
pip install PyQt6
```

### Windows

```bash
pip install -r requirements.txt
```

或者直接安装：

```bash
pip install PyQt6
```

## 运行方式

### 打包后主程序直接命令行（Windows / Linux，推荐）

安装或本地打包后的 **`ServerManager.exe`（Windows）**、**`ServerManager`（Linux）** 与源码里的 `entrypoints` 统一入口一致：**无参数启动 GUI；带任意参数则走命令行**（`list`、`create`、`start`、`--help` 等）。

| 场景 | Windows | Linux |
|------|---------|--------|
| 图形界面 | `ServerManager.exe` | `./ServerManager` |
| 命令行 | `ServerManager.exe list` | `./ServerManager list` |
| 帮助 | `ServerManager.exe --help` | `./ServerManager --help` |

- **Windows**：安装目录下的 `ServerManager.exe`，或执行 `scripts\package\build.bat` 后使用 `src\dist\ServerManager\ServerManager.exe`。
- **Linux**：执行 `scripts/package/build_linux.sh` 后使用 `src/dist/ServerManager/ServerManager`；可将该路径加入 `PATH`，或设置环境变量 **`SERVER_MANAGER_MAIN`** 指向该可执行文件。
- **`scripts\run\run.bat` / `scripts/run/run.sh`**：若检测到同目录或 `src/dist/ServerManager/` 下的打包主程序，会自动用它执行（并附带脚本中的 `--root` 服务器根目录），与上面「直接调用」等价、只是多了根目录约定。

### Linux 命令行（推荐）

```bash
# 赋予执行权限
chmod +x scripts/run/run.sh

# 显示帮助
./scripts/run/run.sh

# 列出所有服务器
./scripts/run/run.sh list

# 创建游戏服务器
./scripts/run/run.sh create --type game --id 1

# 启动服务器（当前窗口，默认）
./scripts/run/run.sh start --server ddxq_game_s1

# 启动服务器（后台运行，使用 screen/tmux）
./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 compile
./scripts/run/run.sh compile --target proto

# 自动化/诊断命令
./scripts/run/run.sh info --json
./scripts/run/run.sh status --json
./scripts/run/run.sh config show --server ddxq_game_s1
./scripts/run/run.sh logs search ddxq_game_s1 error
./scripts/run/run.sh command start ddxq_game_s1
./scripts/run/run.sh doctor
```

或者直接使用新的 Python 模块入口：

```bash
PYTHONPATH=src python3 -m entrypoints.cli list
PYTHONPATH=src python3 -m entrypoints.cli create --type game --id 1
PYTHONPATH=src python3 -m entrypoints.cli start --server ddxq_game_s1
```

### Linux GUI（需要桌面环境）

```bash
./scripts/run/run.sh gui
# 或
PYTHONPATH=src python3 -m entrypoints
```

### Windows 命令行

```batch
:: 显示帮助
scripts\run\run.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 start --server ddxq_game_s1 --background

:: 启动 GUI 界面
scripts\run\run.bat gui

:: 自动化/诊断命令
scripts\run\run.bat info --json
scripts\run\run.bat status --json
scripts\run\run.bat config show --server ddxq_game_s1
scripts\run\run.bat logs search ddxq_game_s1 error
scripts\run\run.bat command start ddxq_game_s1
scripts\run\run.bat doctor
```

### Windows GUI

在项目根目录运行 `scripts\run\run.bat gui` 或直接：

```bash
set PYTHONPATH=src
python -m entrypoints
```

### MCP 服务

本项目内置 MCP stdio 服务，供支持 MCP 的大模型客户端直接调用服务器管理能力：

```batch
set PYTHONPATH=src
python -m entrypoints.cli --root E:\game\server_root mcp
```

客户端配置示例见 [MCP.md](MCP.md)。服务会暴露 `server_manager_*` 工具，包括服务器列表、状态检查、读取配置、创建服务器、启动/停止、重新生成配置、编译、搜索/读取日志。

### 打包成可执行文件

**Windows：**

```batch
scripts\package\build.bat           # 标准打包，产出 src\dist\ServerManager\ServerManager.exe
scripts\package\build_portable.bat  # 便携版打包
```

**Linux：**

```bash
chmod +x scripts/package/build_linux.sh
./scripts/package/build_linux.sh    # 产出 src/dist/ServerManager/ServerManager
```

## 命令行工具参数

```
用法: python -m entrypoints.cli <命令> [参数]

命令:
  list                    列出所有服务器
  create                  创建服务器
  start                   启动服务器
  stop                    停止服务器
  connect                 连接到服务器
  compile                 编译代码
  regen                   重新生成 sys.config
  info                    显示项目路径、版本和工具信息
  status                  检查服务器节点在线状态
  config                  查看/修改项目或服务器配置
  logs                    列出、读取或检索服务器日志
  command                 只生成并打印启动/停止/连接命令
  ids                     查看已有服务器 ID 和下一个可用 ID
  doctor                  检查目录、配置模板和外部工具可用性
  migrate                 手动执行项目配置迁移
  mcp                     启动 MCP stdio 服务

create 参数:
  --type, -t              服务器类型 (game/login/center/cross/client)
  --id, -i                服务器ID
  --prefix, -p            服务器前缀 (默认: ddxq)
  --db-host               数据库地址
  --db-port               数据库端口
  --db-user               数据库用户
  --db-pass               数据库密码
  --tcp-port              TCP端口
  --http-port             HTTP端口
  --login-node            登录节点
  --center-node           中心节点
  --overwrite             覆盖已存在的服务器

start 参数:
  --server, -s            服务器目录名
  --quick, -q             快速启动（不使用 rebar3）
  --background, -b        后台运行（打开新窗口）

stop 参数:
  --server, -s            服务器名称

connect 参数:
  --server, -s            服务器名称
  --ip                    目标IP

compile 参数:
  --target, -t            编译目标 (all/code/proto/table/tbllog)

自动化输出:
  --json                  支持 list/info/status/config/logs/command/ids/doctor/migrate/regen --all

常用新增命令:
  status [server ...] [--ip IP] [--strict]
  config path|files|init|show|get|set|unset
  logs list|read|search
  command start|stop|connect
  ids --type game|login|center|cross|client
  regen --all
```

## 版本与自动更新（version.json）

用于自动更新检测的 `version.json` 需包含以下字段（客户端更新服务读取 `download_url` 作为安装包下载地址）：

| 字段 | 说明 |
|------|------|
| `version` | 当前发布版本号，如 `"1.0.1"` |
| `download_url` | 安装包下载地址（见下方格式） |
| `full_installer_url` | 完整安装包下载地址，建议与 `download_url` 保持一致 |
| `release_notes` | 更新说明，支持 `\n` 换行 |

**download_url 填写规则（走本项目后端下载接口）：**

- 格式：`http://<后端地址>:3000/api/download?path=server_manager/<路径>/<安装包文件名>.exe`
- 路径 `path` 相对于本仓库的 `backend/storage` 目录。
- 安装包固定文件名为 `ServerManager_Setup.exe`（不带版本号），path 为：`server_manager/build/output/ServerManager_Setup.exe`。

**示例：**

- 本机/内网测试：`http://127.0.0.1:3000/api/download?path=server_manager/build/output/ServerManager_Setup.exe`
- 内网其他机器访问：`http://172.18.180.94:3000/api/download?path=server_manager/build/output/ServerManager_Setup.exe`
- 使用域名：`http://your-domain.com:3000/api/download?path=server_manager/build/output/ServerManager_Setup.exe`

发布新版本时：打包会覆盖生成 `ServerManager_Setup.exe` → 修改 `version.json` 的 `version`、`release_notes` 即可；`download_url` / `full_installer_url` 始终指向 `ServerManager_Setup.exe`。

结构调整后的发布要求：

- 正式发布统一使用 `server_manager/build/output/version.json` 和 `server_manager/build/output/ServerManager_Setup.exe`。
- 本次目录结构和文件名变化较大，必须走完整安装包更新；不要给旧版本生成只替换 `ServerManager.exe` 的增量补丁，否则旧安装目录里的依赖文件不会一起更新。
- `scripts\package\release.bat` 默认生成全量更新 manifest，产物只输出到 `build/output`。

## 配置说明

- **打开项目时选择的目录**：应当是服务器项目根目录，不是 `run`、`config` 或 `.server_manager\config` 子目录。
- **项目级工具配置目录**：`<项目根目录>\.server_manager\config\`
  - `default.config`：默认配置模板，首次打开项目时自动复制到这里
  - `user.config`：工具保存的路径、数据库、节点、Erlang 等用户覆盖配置
  - `<项目根>\config\project.config`：项目共享配置，优先级低于 `user.config`、高于 `default.config`
- **运行目录**：通常为 `<项目根目录>\run`，里面是各个服务器实例目录。
- **单服配置文件**：通常位于 `<运行目录>\<服务器目录>\config\kv.config`。
- **模板来源**：
  - 安装版运行时：读取 `ServerManager.exe` 同级的 `config\`
  - 源码运行时：读取仓库根目录的 `resources\config\`

首次运行时，程序会自动在当前项目下准备 `.server_manager\config`；如果自动创建失败，请先检查安装目录或仓库 `resources\config` 下是否存在完整模板，至少要包含 `default.config`。

## 文件结构

```
tools/server_manager/
├── build/                  # 打包产物：output、output_local
├── resources/              # version/config/icon/bin 等资源
├── scripts/                # 打包、更新、工具脚本
├── src/                    # MVC 拆分后的源码
│   ├── controllers/
│   ├── entrypoints/
│   ├── mcp/
│   ├── models/
│   ├── services/
│   ├── util/
│   └── views/
├── requirements.txt
└── version.json
```
（`README.md` 位于仓库根目录。）

## 系统要求

### Linux
- Python 3.8+
- Erlang/OTP
- (可选) screen 或 tmux（用于后台运行服务器）

### Windows
- Windows 10/11
- Python 3.8+
- Erlang/OTP
- PyQt6（GUI 界面）

## Linux 后台运行说明

在 Linux 下启动服务器时，工具会自动检测并使用以下方式：

1. **screen**（优先）: 如果安装了 screen，会创建一个 screen 会话
   ```bash
   # 查看会话
   screen -ls
   # 连接会话
   screen -r ddxq_game_s1
   # 分离会话: Ctrl+A, D
   ```

2. **tmux**: 如果没有 screen 但有 tmux
   ```bash
   # 查看会话
   tmux ls
   # 连接会话
   tmux attach -t ddxq_game_s1
   ```

3. **后台进程**: 如果都没有，直接在后台启动

## 注意事项

1. 首次使用请先确认配置文件中的目录路径正确
2. 创建服务器前请确保数据库配置正确
3. 远程连接需要服务器正在运行
4. 删除服务器操作不可恢复，请谨慎操作
5. Linux 下建议安装 screen 或 tmux 以便管理后台服务器

## 版本历史

- v1.1: 添加 Linux 命令行支持，跨平台兼容
- v1.0: 初始版本，Windows GUI 整合所有批处理脚本功能