whale-town/server/README.md

# 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