# luaCloud

**Repository Path**: wolfyang888/lua-cloud

## Basic Information

- **Project Name**: luaCloud
- **Description**: lua写的微服务
- **Primary Language**: Lua
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-09
- **Last Updated**: 2026-05-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lua-Cloud 微服务框架

## 📋 目录结构
- `master/` - Master服务目录
  - `master.lua` - Master管理进程
  - `masterClient.lua` - Master客户端
- `worker/` - Worker服务目录
  - `event_worker.lua` - Worker工作进程
  - `standalone_worker.lua` - 独立Worker启动脚本
- `monitor/` - 监控服务目录
- `configCenter/` - 配置中心目录
- `eventWorkClient.lua` - Worker客户端
- `UnifiedClient.lua` - 统一客户端

## 🚀 快速开始

### 启动Master
```bash
lua master.lua
```

### 启动独立Worker（分布式部署）
```bash
lua worker/standalone_worker.lua --master-ip 192.168.1.100 --services '["payment"]' --port 9500
```

## 👁️ 新增：实时监控功能

现在您可以使用内置的监控程序实时查看系统状态！

### 启动监控程序
```bash
# 基本用法
lua start_monitor.lua

# 指定Master地址和端口
lua start_monitor.lua --master-ip 192.168.1.100 --master-port 10000

# 自定义检查间隔（毫秒）
lua start_monitor.lua --interval 3000
```

### 监控功能特性
- ✅ **Master健康状态**：实时显示Master连接状态和响应情况
- 📊 **服务实例统计**：显示每个服务类型的Worker实例数量
- 🔧 **Worker详细状态**：区分本地和远程Worker，显示IP、端口、服务类型
- 💓 **心跳监控**：对远程Worker进行心跳检测，自动标记失效实例
- 🔄 **自动重连**：网络中断后自动重连Master
- 🎨 **实时刷新**：每秒自动刷新显示，提供直观的可视化界面

### 监控界面示例
```
================================================================================
🚀 Lua-Cloud 微服务监控面板
================================================================================
Master 状态: ✅ healthy (127.0.0.1:10000)
最后检查时间: 2026-01-09 15:12:25
--------------------------------------------------------------------------------
📊 服务实例统计:
  ✅ generic             : 2 个实例
  ✅ payment             : 1 个实例
--------------------------------------------------------------------------------
🔧 Worker 详细状态:
  🏠 本地 Workers:
    ✅ local_1            127.0.0.1:9001 [generic]
    ✅ local_2            127.0.0.1:9002 [generic]
  ☁️  远程 Workers:
    ✅ worker_payment_001 192.168.1.101:9500 [payment]
      💓 最后心跳: 15:12:20
================================================================================
🔄 自动刷新中... (按 Ctrl+C 退出)
```

### Master控制命令
```bash
# 扩容本地Workers
echo '{"type":"cmd","name":"scale","value":5}' | nc 127.0.0.1 10000

# 查看所有服务
echo '{"type":"cmd","name":"list_services"}' | nc 127.0.0.1 10000

# 查看所有Workers
echo '{"type":"cmd","name":"get_workers"}' | nc 127.0.0.1 10000
```

### 使用统一客户端
```lua
local client = UnifiedClient:new{master_ip="127.0.0.1"}
client:connect_to_master()
client:call_service("payment", "process_payment", {amount=100}, function(result)
    print("支付结果:", result)
end)
```

## 🧪 测试

运行测试脚本来验证功能：
```bash
# 测试监控程序
lua test_monitor.lua

# 测试统一客户端
lua test_unified_client.lua
```

## 📝 配置说明

修改 `config.lua` 文件来调整系统配置：
- `master_ip` / `master_port`: Master地址和端口
- `worker_num`: 本地Worker数量（仅managed模式）
- `worker_mode`: "managed" 或 "standalone"
- `worker_service_types`: Worker提供的服务类型

## 📡 通信协议

### Master 与 Client 通信报文格式

#### 注册请求 (Register Request)
```json
{
  "type": "register",
  "worker_id": "test_worker_1",
  "ip": "0.0.0.0",
  "port": 9001,
  "worker_name": "add",
  "service_types": "math"
}
```

#### 注册响应 (Register Response)
```json
{
  "ok": true,
  "type": "register",
  "service_types": "math",
  "worker_id": "test_worker_1"
}
```

#### 心跳请求 (Heartbeat Request)
```json
{
  "type": "heartbeat",
  "worker_id": "test_worker_1"
}
```

#### 心跳响应 (Heartbeat Response)
```json
{
  "ok": true,
  "type": "heartbeat"
}
```

#### 注销请求 (Unregister Request)
```json
{
  "type": "unregister",
  "worker_id": "test_worker_1"
}
```

#### 注销响应 (Unregister Response)
```json
{
  "ok": true,
  "type": "unregister",
  "worker_id": "test_worker_1"
}
```

### 服务信息查询报文格式

#### 查询服务统计 (List Services Request)
```json
{
  "type": "cmd",
  "name": "list_services"
}
```

#### 服务统计响应 (List Services Response)
```json
{
  "ok": true,
  "type": "cmd",
  "name": "list_services",
  "services": {
    "math": 1
  }
}
```

#### 查询 Worker 信息 (Get Workers Request)
```json
{
  "type": "cmd",
  "name": "get_workers"
}
```

#### Worker 信息响应 (Get Workers Response)
```json
{
  "ok": true,
  "type": "cmd",
  "name": "get_workers",
  "workers": [
    {
      "id": "test_worker_1",
      "ip": "0.0.0.0",
      "port": 9001,
      "service_types": "math",
      "type": "remote",
      "last_heartbeat": 1234567890123
    }
  ]
}
```

## 架构特性

- **服务注册与发现**: Worker启动后自动向Master注册
- **健康检查**: Master定期检查Worker心跳，自动移除失效节点
- **动态扩缩容**: 支持按服务类型进行扩缩容
- **跨机器部署**: Worker可以部署在不同机器上
- **向后兼容**: 保持原有的本地spawn模式
- **实时监控**: 内置监控程序，提供可视化系统状态展示

## 使用示例

### 注册自定义服务方法
```lua
local worker = EventWorker.new("0.0.0.0", 9500, {
    worker_id = "my_custom_worker",
    service_types = {"custom_service"}
})

worker:register("my_method", function(params)
    -- 处理业务逻辑
    return { result = "success" }
end)

worker:start()
```

现在您的Lua-Cloud框架具备了完整的微服务监控能力！🎉

# lua-cloud - 高性能Lua微服务框架

## 特性

- ⚡ **高性能异步I/O** - 基于luv/libuv实现
- 🔄 **服务注册与发现** - 自动注册、心跳检测
- 📈 **动态扩缩容** - 支持命令行动态调整
- 🌐 **跨机器部署** - 支持分布式Worker管理
- 👁️ **实时监控** - 内置可视化监控界面
- 🧵 **全协程处理** - 所有消息类型都在协程中处理
- 📊 **协程池优化** - 支持自定义协程池大小

## 架构

```
Master (master/master.lua) ←TCP→ [Worker (worker/event_worker.lua)]
↑                             ↑
Client ←UnifiedClient→ Master/Monitor
Monitor (monitor.lua) ←TCP→ Master
```

## 快速开始

### 启动Master

```bash
# 基础启动
lua master.lua

# 自定义协程池大小启动
lua master/start_master.lua --coroutine-pool-size 30
```

### 启动Worker

```bash
# 本地托管模式
lua master.lua

# 独立部署模式
lua worker/standalone_worker.lua --master-ip 192.168.1.100 --services '["payment"]' --port 9500
```

### 启动监控

```bash
lua start_monitor.lua
```

## 配置选项

### Master配置参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `bind_ip` | string | "127.0.0.1" | Master监听IP |
| `control_port` | number | 10000 | 控制端口 |
| `worker_num` | number | 3 | 本地Worker数量 |
| `coroutine_pool_size` | number | 20 | 协程池大小 |
| `configCenterHost` | string | nil | 配置中心主机 |
| `configCenterPort` | number | nil | 配置中心端口 |

### 协程池配置指南

协程池大小直接影响系统并发处理能力和内存占用：

```lua
-- 小型应用 (开发测试)
local master = Master:new({
    coroutine_pool_size = 5  -- 5个协程
})

-- 中型应用 (一般生产)
local master = Master:new({
    coroutine_pool_size = 20  -- 20个协程
})

-- 大型应用 (高并发生产)
local master = Master:new({
    coroutine_pool_size = 50  -- 50个协程
})
```

**选择建议：**
- 开发测试: 5-10个协程
- 小型应用: 10-20个协程
- 中型应用: 20-30个协程
- 大型应用: 30-50个协程
- 超高并发: 50+个协程

## 协程处理机制

### 全协程处理架构

所有消息类型都在协程池中处理，包括：

1. **CMD命令消息** - scale、list_services、get_workers等
2. **注册消息** - Worker注册到Master
3. **心跳消息** - Worker健康状态汇报
4. **注销消息** - Worker主动注销
5. **配置相关** - 配置中心交互消息

```lua
-- 启动日志示例
[Master] started, listening on 127.0.0.1:10000
[Master] 改进协程池模式已启用
[Master] 协程池大小: 20
[Master] 当前运行协程数: 0
[Master] 空闲协程数: 20
```

### 协程处理优势

- **非阻塞处理** - 避免单个耗时操作阻塞整个服务
- **资源复用** - 协程可复用，减少创建销毁开销
- **并发控制** - 通过池大小限制并发数量
- **负载均衡** - 任务队列机制平衡处理负载

## API参考

### Master命令

通过TCP连接发送JSON命令：

```json
{
  "type": "cmd",
  "name": "scale",
  "value": 5,
  "id": "unique_request_id"
}
```

支持的命令：
- `scale` - 调整Worker数量
- `list_services` - 列出所有服务
- `get_workers` - 获取Worker列表
- `shutdown` - 关闭Master

### 消息类型

所有消息类型都支持在协程中处理：

```json
// 注册消息
{
  "type": "register",
  "worker_id": "worker_1",
  "service_types": ["payment"],
  "id": "reg_1"
}

// 心跳消息
{
  "type": "heartbeat",
  "worker_id": "worker_1",
  "timestamp": 1234567890,
  "id": "hb_1"
}

// 注销消息
{
  "type": "unregister",
  "worker_id": "worker_1",
  "reason": "shutdown",
  "id": "unreg_1"
}
```

## 性能优化

### 协程池调优

1. **监控协程池状态**：
```bash
# 启动后观察日志
[Master] 改进协程池模式已启用
[Master] 协程池大小: 20
[Master] 当前运行协程数: 0
[Master] 空闲协程数: 20
```

2. **根据负载调整大小**：
   - 负载较轻：减少协程池大小节省内存
   - 负载较重：增加协程池大小提升并发能力

3. **避免过度配置**：
   - 协程过多会增加GC压力
   - 建议根据实际QPS需求配置

## 故障排除

常见问题及解决方案...

## 贡献指南

欢迎提交Issue和Pull Request！

## 许可证

MIT License