whale-town/server

AI Town WebSocket Server

WebSocket 服务器用于 AI Town 多人在线游戏。

功能特性

核心功能

• ✅ WebSocket 连接管理
• ✅ 客户端身份验证
• ✅ 角色创建和管理
• ✅ 实时位置同步
• ✅ 对话消息传递
• ✅ 心跳检测
• ✅ 数据持久化（JSON 文件）
• ✅ 在线/离线状态管理

监控和维护

• ✅ 系统健康监控
• ✅ 自动数据备份
• ✅ 日志管理和分析
• ✅ 维护任务调度
• ✅ Web 管理界面

快速开始

1. 安装依赖

cd server
npm install
# 或
yarn install

2. 运行服务器

开发模式（TypeScript）

npm run dev
# 或
yarn dev

生产模式

# 编译 TypeScript
npm run build
# 或
yarn build

# 运行编译后的代码
npm start
# 或
yarn start

3. 配置

服务器默认运行在端口 8080。

可以通过环境变量修改：

PORT=3000 npm run dev

消息协议

所有消息使用 JSON 格式，包含以下字段：

{
  "type": "message_type",
  "data": {},
  "timestamp": 1234567890
}

客户端 → 服务器

1. 身份验证

{
  "type": "auth_request",
  "data": {
    "username": "player1"
  },
  "timestamp": 1234567890
}

2. 创建角色

{
  "type": "character_create",
  "data": {
    "name": "Hero"
  },
  "timestamp": 1234567890
}

3. 角色移动

{
  "type": "character_move",
  "data": {
    "position": {
      "x": 100.0,
      "y": 200.0
    }
  },
  "timestamp": 1234567890
}

4. 发送对话

{
  "type": "dialogue_send",
  "data": {
    "receiverId": "character_id",
    "message": "Hello!"
  },
  "timestamp": 1234567890
}

5. 心跳

{
  "type": "ping",
  "data": {},
  "timestamp": 1234567890
}

服务器 → 客户端

1. 身份验证响应

{
  "type": "auth_response",
  "data": {
    "success": true,
    "clientId": "uuid"
  },
  "timestamp": 1234567890
}

2. 角色创建响应

{
  "type": "character_create",
  "data": {
    "success": true,
    "character": {
      "id": "uuid",
      "name": "Hero",
      "position": { "x": 1000, "y": 750 },
      "isOnline": true
    }
  },
  "timestamp": 1234567890
}

3. 世界状态

{
  "type": "world_state",
  "data": {
    "characters": [
      {
        "id": "uuid",
        "name": "Hero",
        "position": { "x": 100, "y": 200 },
        "isOnline": true
      }
    ]
  },
  "timestamp": 1234567890
}

4. 角色状态更新

{
  "type": "character_state",
  "data": {
    "characterId": "uuid",
    "name": "Hero",
    "position": { "x": 100, "y": 200 },
    "isOnline": false
  },
  "timestamp": 1234567890
}

5. 角色移动广播

{
  "type": "character_move",
  "data": {
    "characterId": "uuid",
    "position": { "x": 100, "y": 200 }
  },
  "timestamp": 1234567890
}

6. 心跳响应

{
  "type": "pong",
  "data": {},
  "timestamp": 1234567890
}

7. 错误消息

{
  "type": "error",
  "data": {
    "message": "Error description"
  },
  "timestamp": 1234567890
}

数据持久化

角色数据保存在 server/data/characters.json 文件中。

自动保存

• 创建/更新角色时立即保存
• 每 5 分钟自动保存一次
• 服务器关闭时保存

数据格式

[
  {
    "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 编译配置。

监听模式

开发时可以使用监听模式自动重新编译：

npm run watch
# 或
yarn watch

测试

使用 wscat 测试

安装 wscat：

npm install -g wscat

连接到服务器：

wscat -c ws://localhost:8080

发送测试消息：

{"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、连接数等指标
• 备份管理: 创建、恢复、删除数据备份
• 日志分析: 查看和分析服务器日志
• 维护任务: 管理自动维护任务

环境变量

PORT=8080              # WebSocket 服务器端口
ADMIN_PORT=8081        # 管理 API 端口
ADMIN_TOKEN=admin123   # 管理员访问令牌

生产部署

使用 PM2

npm install -g pm2
pm2 start dist/server.js --name ai-town-server
pm2 logs ai-town-server

使用 Docker

FROM node:16
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
EXPOSE 8080 8081
CMD ["npm", "start"]

许可证

MIT