# zlua

**Repository Path**: xyruler/zlua

## Basic Information

- **Project Name**: zlua
- **Description**: ZLUA 是一个基于 C+LuaJIT 实现的 Linux 服务端框架，提供高性能、高稳定性和可扩展性开发底座。它采用事件驱动模式、主从工作线程架构，结合了 C 语言的高性能和 Lua 语言的灵活性，让开发者能够快速构建高效的服务端应用，如游戏服务器、Web 服务器、API 网关等。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-15
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Lua, C语言, LuaJIT, 同步编程

## README

# ZLUA 

<div align="center">

![ZLUA Logo](https://img.shields.io/badge/ZLUA-Framework-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-Linux-lightgrey)
![LuaJIT](https://img.shields.io/badge/powered%20by-LuaJIT-red)

**高性能 Linux 服务端框架，基于 C+LuaJIT 实现**

</div>

## 📋 目录

- [简介](#简介)
- [特性](#特性)
- [快速开始](#快速开始)
  - [环境要求](#环境要求)
  - [安装步骤](#安装步骤)
  - [运行](#运行)
- [架构](#架构)
- [文档](#文档)
- [开发计划](#开发计划)
- [贡献](#贡献)
- [许可证](#许可证)

## 简介

ZLUA 是一个基于 C+LuaJIT 实现的 Linux 服务端框架，旨在提供高性能、稳定性和可扩展性。它采用事件驱动模式、主从工作线程架构，适合构建高并发网络应用，如游戏服务器、Web 服务器、API 网关等。

ZLUA 结合了 C 语言的高性能和 Lua 语言的灵活性，让开发者能够快速构建高效的服务端应用。

## ✨ 特性

### 高性能

- **基于LuaJIT**：性能接近 C 语言，JIT 编译带来的性能优势
- **事件驱动**：使用 epoll 事件驱动，高效处理并发连接

### 扩展性

- **C/Lua 混合编程**：高度灵活，兼具性能与开发效率
- **兼容 OpenResty 生态**：可直接使用 lua-resty-* 库
- **热更新支持**：支持线程级别的热更新，无需停机维护

### 📥 安装步骤

### 安装步骤

1. 克隆代码库

```bash
git clone https://intranet-gitlib.laiyouxi.com:1443/support/zlua.git
cd zlua
```

2. 安装依赖

```bash
# Ubuntu/Debian
sudo apt-get install -y build-essential cmake libssl-dev automake autoconf libtool m4 perl

# CentOS/RHEL
sudo yum install -y gcc gcc-c++ make cmake openssl-devel automake autoconf libtool m4 perl
```

3. 编译

```bash
# 编译
make all [options]

options:
  WITH_ALL=1  # 使用所有库 - 包含 WITH_PROTOBUF, WITH_SQLITE3, WITH_SQLITE3_STATIC, WITH_UTF8, WITH_OPENSSL_LUALIB
  WITH_SQLITE3=1  # 使用sqlite3 动态链接，需安装sqlite3库
  WITH_SQLITE3_STATIC=1  # 直接编译sqlite3源码，会增加执行程序包大小约7M
  WITH_PROTOBUF=1  # 使用 protobuf 库
  WITH_UTF8=1  # 使用 utf8 库
  WITH_OPENSSL_LUALIB=1  # 使用 openssl-lualib 库
  WITH_CLUSTER=1  # 使用 cluster 库 包含WITH_PROTOBUF
  WITH_XDB=1  # 使用 xdb 库

# 安装
sudo make install

# 发布项目时，可选择直接将项目代码打包到执行文件中
make all PROJCET=myproject PROJECT_DIR=./myproject TARGET=myproject
```

### 运行

```bash
# 运行
# worker_dir 为工作目录，默认为当前目录，main.lua 为入口脚本
zlua -p worker_dir main

# 如果发布项目时已将项目打包到执行文件中，则可直接运行
./myproject

# 可以指定工作目录，默认使用当前目录，使用工作目录后，可以通过更新工作目录中的脚本进行热更新
./myproject -p worker_dir


# 启动时，可注入环境变量, 在脚本中使用 sys.get_env("WORKER_PATH") 获取
WORKER_PATH=./worker_dir ./myproject

# 优雅退出
zlua -p worker_dir -s quit
或
kill -15 <pid>

# 热重载
zlua -p worker_dir -s reload
或
kill -1 <pid>

#强制退出
zlua -p worker_dir -s stop
或
kill -9 <pid>
```

## 🏗️ 架构

ZLUA 采用主从工作线程架构:

1. **主线程**：负责管理工作线程的生命周期
2. **工作线程**：处理实际业务逻辑

核心组件:

- **事件循环**：基于 epoll 的事件驱动模型
- **网络库**：高性能的 TCP/UDP 实现
- **定时器**：精确的定时器实现
- **共享内存**：高效的共享内存实现
- **共享信号量**：高效的共享信号量实现
- **共享通道**：高效的共享通道实现

## 📝 文档与示例

### 文档

- [API](API.md)
- [API 参考](doc/api-reference.md)

### 示例

请查看 `examples` 目录获取更多示例。

## 🗓️ 开发计划

- [ ] 添加更多数据库驱动
- [ ] 改进日志系统
- [ ] 添加性能监控工具
- [ ] 构建更完善的测试框架

## 👥 贡献

欢迎提交 PR 和 Issue 来帮助改进 ZLUA！

<div align="center">
<p>
  <a href="#zlua">↑ 返回顶部 ↑</a>
</p>

<p>
  <sub>感谢使用 ZLUA！如有问题，欢迎提出 issue 或通过邮件联系我们</sub>
</p>
</div>