创建新工程
This commit is contained in:
moyin
418
server/README.md
Normal file
418
server/README.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# AI Town WebSocket Server
|
||||
|
||||
WebSocket 服务器用于 AI Town 多人在线游戏。
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 核心功能
|
||||
- ✅ WebSocket 连接管理
|
||||
- ✅ 客户端身份验证
|
||||
- ✅ 角色创建和管理
|
||||
- ✅ 实时位置同步
|
||||
- ✅ 对话消息传递
|
||||
- ✅ 心跳检测
|
||||
- ✅ 数据持久化（JSON 文件）
|
||||
- ✅ 在线/离线状态管理
|
||||
|
||||
### 监控和维护
|
||||
- ✅ 系统健康监控
|
||||
- ✅ 自动数据备份
|
||||
- ✅ 日志管理和分析
|
||||
- ✅ 维护任务调度
|
||||
- ✅ Web 管理界面
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
cd server
|
||||
npm install
|
||||
# 或
|
||||
yarn install
|
||||
```
|
||||
|
||||
### 2. 运行服务器
|
||||
|
||||
#### 开发模式（TypeScript）
|
||||
```bash
|
||||
npm run dev
|
||||
# 或
|
||||
yarn dev
|
||||
```
|
||||
|
||||
#### 生产模式
|
||||
```bash
|
||||
# 编译 TypeScript
|
||||
npm run build
|
||||
# 或
|
||||
yarn build
|
||||
|
||||
# 运行编译后的代码
|
||||
npm start
|
||||
# 或
|
||||
yarn start
|
||||
```
|
||||
|
||||
### 3. 配置
|
||||
|
||||
服务器默认运行在端口 **8080**。
|
||||
|
||||
可以通过环境变量修改：
|
||||
```bash
|
||||
PORT=3000 npm run dev
|
||||
```
|
||||
|
||||
## 消息协议
|
||||
|
||||
所有消息使用 JSON 格式，包含以下字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "message_type",
|
||||
"data": {},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
### 客户端 → 服务器
|
||||
|
||||
#### 1. 身份验证
|
||||
```json
|
||||
{
|
||||
"type": "auth_request",
|
||||
"data": {
|
||||
"username": "player1"
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 创建角色
|
||||
```json
|
||||
{
|
||||
"type": "character_create",
|
||||
"data": {
|
||||
"name": "Hero"
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 角色移动
|
||||
```json
|
||||
{
|
||||
"type": "character_move",
|
||||
"data": {
|
||||
"position": {
|
||||
"x": 100.0,
|
||||
"y": 200.0
|
||||
}
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. 发送对话
|
||||
```json
|
||||
{
|
||||
"type": "dialogue_send",
|
||||
"data": {
|
||||
"receiverId": "character_id",
|
||||
"message": "Hello!"
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. 心跳
|
||||
```json
|
||||
{
|
||||
"type": "ping",
|
||||
"data": {},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
### 服务器 → 客户端
|
||||
|
||||
#### 1. 身份验证响应
|
||||
```json
|
||||
{
|
||||
"type": "auth_response",
|
||||
"data": {
|
||||
"success": true,
|
||||
"clientId": "uuid"
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 角色创建响应
|
||||
```json
|
||||
{
|
||||
"type": "character_create",
|
||||
"data": {
|
||||
"success": true,
|
||||
"character": {
|
||||
"id": "uuid",
|
||||
"name": "Hero",
|
||||
"position": { "x": 1000, "y": 750 },
|
||||
"isOnline": true
|
||||
}
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 世界状态
|
||||
```json
|
||||
{
|
||||
"type": "world_state",
|
||||
"data": {
|
||||
"characters": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Hero",
|
||||
"position": { "x": 100, "y": 200 },
|
||||
"isOnline": true
|
||||
}
|
||||
]
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. 角色状态更新
|
||||
```json
|
||||
{
|
||||
"type": "character_state",
|
||||
"data": {
|
||||
"characterId": "uuid",
|
||||
"name": "Hero",
|
||||
"position": { "x": 100, "y": 200 },
|
||||
"isOnline": false
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 5. 角色移动广播
|
||||
```json
|
||||
{
|
||||
"type": "character_move",
|
||||
"data": {
|
||||
"characterId": "uuid",
|
||||
"position": { "x": 100, "y": 200 }
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 6. 心跳响应
|
||||
```json
|
||||
{
|
||||
"type": "pong",
|
||||
"data": {},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
#### 7. 错误消息
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"data": {
|
||||
"message": "Error description"
|
||||
},
|
||||
"timestamp": 1234567890
|
||||
}
|
||||
```
|
||||
|
||||
## 数据持久化
|
||||
|
||||
角色数据保存在 `server/data/characters.json` 文件中。
|
||||
|
||||
### 自动保存
|
||||
- 创建/更新角色时立即保存
|
||||
- 每 5 分钟自动保存一次
|
||||
- 服务器关闭时保存
|
||||
|
||||
### 数据格式
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "Hero",
|
||||
"ownerId": "client_id",
|
||||
"position": { "x": 1000, "y": 750 },
|
||||
"isOnline": false,
|
||||
"createdAt": 1234567890,
|
||||
"lastSeen": 1234567890
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 心跳机制
|
||||
|
||||
- 客户端应每 30 秒发送一次 `ping` 消息
|
||||
- 服务器每 30 秒检查一次客户端心跳
|
||||
- 如果客户端 60 秒内没有心跳，将被断开连接
|
||||
|
||||
## 开发
|
||||
|
||||
### 项目结构
|
||||
```
|
||||
server/
|
||||
├── src/
|
||||
│ └── server.ts # 主服务器文件
|
||||
├── data/
|
||||
│ └── characters.json # 角色数据（自动生成）
|
||||
├── dist/ # 编译输出（自动生成）
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### TypeScript 配置
|
||||
|
||||
查看 `tsconfig.json` 了解 TypeScript 编译配置。
|
||||
|
||||
### 监听模式
|
||||
|
||||
开发时可以使用监听模式自动重新编译：
|
||||
```bash
|
||||
npm run watch
|
||||
# 或
|
||||
yarn watch
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
### 使用 wscat 测试
|
||||
|
||||
安装 wscat：
|
||||
```bash
|
||||
npm install -g wscat
|
||||
```
|
||||
|
||||
连接到服务器：
|
||||
```bash
|
||||
wscat -c ws://localhost:8080
|
||||
```
|
||||
|
||||
发送测试消息：
|
||||
```json
|
||||
{"type":"auth_request","data":{"username":"test"},"timestamp":1234567890}
|
||||
{"type":"character_create","data":{"name":"TestHero"},"timestamp":1234567890}
|
||||
{"type":"ping","data":{},"timestamp":1234567890}
|
||||
```
|
||||
|
||||
### 使用 Godot 客户端测试
|
||||
|
||||
1. 启动服务器
|
||||
2. 运行 Godot 项目中的 Main.tscn
|
||||
3. 尝试登录和创建角色
|
||||
|
||||
## 日志
|
||||
|
||||
服务器会输出以下日志：
|
||||
|
||||
- `🚀` 服务器启动
|
||||
- `✅` 客户端连接
|
||||
- `❌` 客户端断开/错误
|
||||
- `📨` 接收消息
|
||||
- `🔐` 身份验证
|
||||
- `👤` 角色创建
|
||||
- `💾` 数据保存
|
||||
- `📂` 数据加载
|
||||
- `⏰` 心跳超时
|
||||
- `🛑` 服务器关闭
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Node.js 16+
|
||||
- npm 或 yarn
|
||||
|
||||
## 依赖
|
||||
|
||||
- `ws` - WebSocket 库
|
||||
- `uuid` - UUID 生成
|
||||
- `typescript` - TypeScript 编译器
|
||||
- `ts-node` - TypeScript 运行时
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 端口已被占用
|
||||
|
||||
如果看到 `EADDRINUSE` 错误，说明端口已被占用。
|
||||
|
||||
解决方法：
|
||||
1. 更改端口：`PORT=3000 npm run dev`
|
||||
2. 或关闭占用端口的程序
|
||||
|
||||
### 无法连接
|
||||
|
||||
确保：
|
||||
1. 服务器正在运行
|
||||
2. 防火墙允许端口 8080
|
||||
3. 客户端使用正确的 URL：`ws://localhost:8080`
|
||||
|
||||
### 数据丢失
|
||||
|
||||
数据保存在 `server/data/characters.json`。
|
||||
|
||||
如果数据丢失：
|
||||
1. 检查文件是否存在
|
||||
2. 检查文件权限
|
||||
3. 查看服务器日志中的错误信息
|
||||
|
||||
## 监控和管理
|
||||
|
||||
### Web 管理界面
|
||||
|
||||
服务器启动后，管理界面可通过以下方式访问：
|
||||
- URL: `http://localhost:8081/admin/`
|
||||
- 认证令牌: `admin123`（可通过环境变量 `ADMIN_TOKEN` 修改）
|
||||
|
||||
### 管理功能
|
||||
|
||||
- **系统监控**: 查看内存、CPU、连接数等指标
|
||||
- **备份管理**: 创建、恢复、删除数据备份
|
||||
- **日志分析**: 查看和分析服务器日志
|
||||
- **维护任务**: 管理自动维护任务
|
||||
|
||||
### 环境变量
|
||||
|
||||
```bash
|
||||
PORT=8080 # WebSocket 服务器端口
|
||||
ADMIN_PORT=8081 # 管理 API 端口
|
||||
ADMIN_TOKEN=admin123 # 管理员访问令牌
|
||||
```
|
||||
|
||||
## 生产部署
|
||||
|
||||
### 使用 PM2
|
||||
|
||||
```bash
|
||||
npm install -g pm2
|
||||
pm2 start dist/server.js --name ai-town-server
|
||||
pm2 logs ai-town-server
|
||||
```
|
||||
|
||||
### 使用 Docker
|
||||
|
||||
```dockerfile
|
||||
FROM node:16
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm install
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
EXPOSE 8080 8081
|
||||
CMD ["npm", "start"]
|
||||
```
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user