1. 项目概述为什么需要这个“全家桶”最近在折腾一个需要高并发处理用户请求的后台服务核心需求是接收海量HTTP请求进行一些业务逻辑判断比如验签、限流然后读写数据库和缓存最后返回结果。最开始用传统的Nginx 后端应用服务器如Java/Python的架构发现瓶颈很明显每次请求都要穿透到后端网络IO和进程间通信的开销在QPS上去之后成了拖累。后来了解到OpenResty它直接把Lua虚拟机塞进了Nginx让你能在Nginx的各个处理阶段用Lua脚本写业务逻辑这相当于把一部分后端代码“前置”到了网关层性能提升是立竿见影的。但随之而来的就是环境部署的麻烦。OpenResty本身要编译安装还得配Lua的各种第三方库比如操作MySQL和Redis的驱动更别提MySQL和Redis Cluster的搭建了。本地开发环境和测试、生产环境的不一致更是让“在我机器上好好的”这种问题频繁出现。这时候Docker的优势就体现出来了。用Docker把OpenResty Lua MySQL Redis Cluster这整套环境打包成一个可复现、可移植的“全家桶”无论是新同事搭建开发环境还是做CI/CD自动化测试都能做到一键启动环境完全一致。这个项目标题“docker构建openrety lua mysql rediscluster”本质上就是在解决这个痛点。它不是一个简单的软件堆砌而是构建一个高性能、可编排的Web应用后端模拟环境。OpenResty负责高效的网络IO和业务逻辑处理Lua是粘合剂MySQL作为持久化存储Redis Cluster提供高性能的分布式缓存。用Docker来封装则是为了极致的环境一致性和部署效率。2. 整体架构设计与组件选型考量2.1 核心架构图与数据流整个服务的核心数据流可以这样理解用户请求到达OpenResty监听80/443端口。OpenResty的access_by_lua阶段执行Lua脚本进行IP黑名单、请求签名验证等操作。OpenResty的content_by_lua阶段这里是业务逻辑核心。首先Lua脚本会查询Redis Cluster看看数据是否在缓存中。Redis Cluster的分布式特性允许我们部署多个节点缓存容量和吞吐量可以线性增长。如果缓存未命中Cache Miss则Lua脚本通过连接池访问MySQL数据库获取持久化数据。从MySQL获取数据后在返回给用户之前将数据按一定规则写入Redis Cluster供后续请求使用Cache Aside模式。OpenResty响应将处理结果返回给用户。在这个流程中Docker Compose负责将这四个组件OpenResty, Lua环境, MySQL, Redis Cluster组织成一个协同工作的整体。每个组件运行在独立的容器中通过Docker网络进行通信。2.2 关键组件选型与版本确定OpenResty我们选择官方镜像openresty/openresty:1.21.4.1-alpine。Alpine版本镜像体积小安全性相对较高符合容器化最佳实践。1.21.4.1是一个长期支持且稳定的版本。Lua库lua-resty-mysqlOpenResty官方维护的MySQL客户端库非阻塞与Nginx事件模型完美契合。lua-resty-redis-cluster一个支持Redis Cluster的第三方Lua库。这里是个关键点OpenResty自带的lua-resty-redis只支持单节点或主从Redis对Cluster的支持需要这个专门的库。MySQL选择mysql:8.0。相比5.78.0在性能、安全性和JSON支持上都有显著提升。我们以它作为数据源。Redis Cluster选择redis:7-alpine镜像来构建集群。Redis 7在ACL、Function等方面有增强。一个最小的Redis Cluster需要至少3个主节点为了保证高可用我们通常为每个主节点配一个从节点所以至少需要6个容器实例。这里为了演示我们先搭建3主3从的集群。注意在生产环境中MySQL和Redis Cluster通常不会与应用容器部署在同一台宿主机上而是使用独立的云服务或物理机集群。本项目的Docker化主要用于开发、测试和演示环境它提供了与生产环境架构一致但资源消耗可控的本地沙箱。2.3 项目目录结构规划一个清晰的项目结构是成功的一半。在开始写Dockerfile和配置文件之前我们先规划好目录。openresty-lua-docker-example/ ├── docker-compose.yml # 编排所有服务的总纲 ├── nginx/ │ ├── Dockerfile # 定制OpenResty镜像安装Lua依赖 │ ├── nginx.conf # OpenResty主配置文件 │ ├── conf.d/ │ │ └── default.conf # 具体的HTTP服务配置 │ └── lua/ # 存放所有Lua脚本 │ ├── app.lua # 主要业务逻辑脚本 │ ├── mysql.lua # MySQL操作封装 │ └── redis_cluster.lua # Redis Cluster操作封装 ├── mysql/ │ ├── init.sql # 数据库初始化脚本建表、插入基础数据 │ └── my.cnf # MySQL自定义配置可选 └── redis-cluster/ ├── redis-node-1/ │ └── redis.conf # 节点1配置 ├── redis-node-2/ │ └── redis.conf # 节点2配置 └── ... (共6个节点目录) # 其余节点配置这个结构将配置、脚本和数据分离一目了然。3. 核心组件配置与Docker化实战3.1 构建定制的OpenResty镜像官方的OpenResty镜像不包含我们需要的lua-resty-redis-cluster库所以需要自定义Dockerfile来安装。nginx/Dockerfile:# 基于官方Alpine镜像 FROM openresty/openresty:1.21.4.1-alpine # 安装Git和必要的编译工具用于下载和安装LuaRocks及第三方库 RUN apk add --no-cache git gcc libc-dev make # 安装LuaRocksOpenResty Alpine镜像默认不包含 RUN wget https://luarocks.org/releases/luarocks-3.9.2.tar.gz \ tar -xzf luarocks-3.9.2.tar.gz \ cd luarocks-3.9.2 \ ./configure --with-lua/usr/local/openresty/luajit \ --lua-suffixjit \ --with-lua-include/usr/local/openresty/luajit/include/luajit-2.1 \ make make install \ cd .. rm -rf luarocks-3.9.2* # 使用LuaRocks安装 lua-resty-redis-cluster # 注意这里指定了--server参数因为默认源可能访问慢或不稳定 RUN luarocks install lua-resty-redis-cluster --serverhttps://luarocks.cn # 清理缓存减小镜像体积 RUN apk del git gcc libc-dev make \ rm -rf /var/cache/apk/* # 将本地的Lua脚本和配置文件拷贝到镜像中 COPY ./lua /usr/local/openresty/nginx/lua/ COPY nginx.conf /usr/local/openresty/nginx/conf/nginx.conf COPY ./conf.d /etc/nginx/conf.d/ # 暴露80端口 EXPOSE 80 # 启动OpenResty CMD [/usr/local/openresty/bin/openresty, -g, daemon off;]关键点解析为什么用Alpine镜像体积小最终镜像约100MB安全补丁更新快。但它的musl libc与标准glibc略有差异极少数二进制依赖可能有问题对于我们只运行OpenResty和Lua来说完全够用。安装编译工具链Alpine基础镜像很精简需要手动安装gcc,make等来编译LuaRocks。安装完成后立即删除这些工具是构建小镜像的常见技巧。LuaRocks配置--with-lua参数必须指向OpenResty自带的LuaJIT路径确保安装的库与当前OpenResty环境兼容。使用国内源--serverhttps://luarocks.cn能显著加速在中国大陆的下载速度避免因网络问题导致构建失败。3.2 配置OpenResty与Lua脚本nginx/nginx.conf(核心配置简化版):worker_processes auto; # 自动根据CPU核心数设置工作进程 events { worker_connections 1024; # 每个工作进程的最大连接数 } http { include mime.types; default_type application/json; # 默认返回JSON格式 # 启用Lua代码缓存生产环境必须开启否则每次请求都加载脚本性能极差 lua_code_cache on; # 初始化阶段加载Lua模块 init_by_lua_block { -- 预加载全局模块避免在请求阶段重复加载 require resty.core redis_cluster require resty.rediscluster mysql require resty.mysql } # 配置上游服务器本例中未使用但保留结构 upstream backend { # 这里可以配置其他后端服务 } # 包含具体的server配置 include /etc/nginx/conf.d/*.conf; }nginx/conf.d/default.conf:server { listen 80; server_name localhost; location /api/data { # 设置响应头 default_type application/json; charset utf-8; # 所有业务逻辑都在这个Lua脚本中处理 content_by_lua_file /usr/local/openresty/nginx/lua/app.lua; } # 一个健康检查端点 location /health { access_by_lua_block { ngx.say({status: UP}) } } }核心Lua脚本nginx/lua/app.lua:-- 获取请求参数 local args ngx.req.get_uri_args() local id args.id if not id or id then ngx.status ngx.HTTP_BAD_REQUEST ngx.say({error: missing parameter: id}) ngx.exit(ngx.HTTP_BAD_REQUEST) end -- 1. 先尝试从Redis Cluster获取缓存 local cache_data get_from_redis_cluster(id) if cache_data then ngx.say(cache_data) return -- 缓存命中直接返回 end -- 2. 缓存未命中查询MySQL local db_data get_from_mysql(id) if not db_data then ngx.status ngx.HTTP_NOT_FOUND ngx.say({error: data not found}) ngx.exit(ngx.HTTP_NOT_FOUND) end -- 3. 将数据库结果写入Redis Cluster设置过期时间如60秒 set_to_redis_cluster(id, db_data, 60) -- 4. 返回数据给用户 ngx.say(db_data) -- 下面是封装的函数实际会放在单独的模块文件中这里为演示写在一起 function get_from_redis_cluster(key) local red_c redis_cluster:new({ name my_redis_cluster, serv_list { {ip redis-node-1, port 6379}, {ip redis-node-2, port 6379}, {ip redis-node-3, port 6379}, {ip redis-node-4, port 6379}, {ip redis-node-5, port 6379}, {ip redis-node-6, port 6379}, }, keepalive_timeout 60000, -- 连接池保活时间 keepalive_cons 1000, -- 连接池大小 connection_timout 1000, -- 连接超时(ms) max_redirection 5, -- 最大重定向次数Cluster节点跳转 }) local res, err red_c:get(key) if not res then ngx.log(ngx.ERR, failed to get key from redis cluster: , err) return nil end -- 将连接放回连接池 local ok, err red_c:set_keepalive() if not ok then ngx.log(ngx.ERR, failed to set keepalive: , err) end return res end function get_from_mysql(id) local db, err mysql:new() if not db then ngx.log(ngx.ERR, failed to instantiate mysql: , err) return nil end db:set_timeout(1000) -- 1秒超时 local ok, err, errno, sqlstate db:connect({ host mysql, -- Docker Compose中的服务名 port 3306, database test_db, user root, password your_strong_password_here, }) if not ok then ngx.log(ngx.ERR, failed to connect to mysql: , err, : , errno, , sqlstate) return nil end -- 使用参数化查询防止SQL注入 local sql SELECT id, name, value FROM test_table WHERE id ? local res, err, errno, sqlstate db:query(sql, {id}) if not res then ngx.log(ngx.ERR, bad result: , err, : , errno, , sqlstate) return nil end -- 将结果转换为JSON字符串这里简化处理实际可使用cjson库 local ok, err db:set_keepalive(10000, 100) -- 放入连接池 if not ok then ngx.log(ngx.ERR, failed to set keepalive: , err) end if #res 0 then return nil end -- 假设我们有一个简单的序列化函数实际应用中应使用cjson return string.format({id:%d,name:%s,value:%s}, res[1].id, res[1].name, res[1].value) end function set_to_redis_cluster(key, value, exptime) -- 类似get_from_redis_cluster调用red_c:set(key, value)和red_c:expire(key, exptime) -- 此处省略具体实现 end实操心得在Lua脚本中连接数据库和Redis一定要使用连接池set_keepalive。如果不使用连接池每次请求都新建TCP连接性能会急剧下降。keepalive_cons参数控制连接池大小需要根据实际并发量调整。3.3 配置MySQL与数据初始化docker-compose.yml中MySQL部分:services: mysql: image: mysql:8.0 container_name: my-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: your_strong_password_here MYSQL_DATABASE: test_db MYSQL_USER: app_user MYSQL_PASSWORD: app_user_password ports: - 3306:3306 volumes: - mysql_data:/var/lib/mysql - ./mysql/init.sql:/docker-entrypoint-initdb.d/init.sql # 初始化脚本挂载 networks: - app-network volumes: mysql_data:mysql/init.sql:-- 创建应用专用的数据库和用户虽然环境变量已创建这里确保权限 CREATE DATABASE IF NOT EXISTS test_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE test_db; -- 创建一个简单的测试表 CREATE TABLE IF NOT EXISTS test_table ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255) NOT NULL, value TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB; -- 插入一些测试数据 INSERT INTO test_table (name, value) VALUES (item_1, This is the first value.), (item_2, This is the second value.), (item_3, This is the third value.);关键点解析数据持久化通过volumes将容器内的/var/lib/mysql目录挂载到名为mysql_data的Docker卷上。这样即使容器被删除数据也不会丢失。初始化脚本将SQL文件挂载到/docker-entrypoint-initdb.d/目录下MySQL容器在首次启动时会自动执行该目录下的所有.sql、.sh文件。这是初始化数据库表结构和基础数据的标准做法。网络所有服务都加入同一个自定义的Docker网络app-network这样容器间可以通过服务名如mysql、redis-node-1直接通信无需知道IP地址。3.4 搭建Redis Cluster集群这是最复杂的一步。Redis Cluster的Docker化需要启动多个容器并手动或通过脚本将它们组成集群。docker-compose.yml中Redis Cluster部分:services: redis-node-1: image: redis:7-alpine container_name: redis-node-1 command: redis-server /usr/local/etc/redis/redis.conf --cluster-enabled yes --cluster-config-file nodes-1.conf --cluster-node-timeout 5000 ports: - 7001:6379 volumes: - ./redis-cluster/redis-node-1/redis.conf:/usr/local/etc/redis/redis.conf - redis-data-1:/data networks: - app-network redis-node-2: image: redis:7-alpine container_name: redis-node-2 command: redis-server /usr/local/etc/redis/redis.conf --cluster-enabled yes --cluster-config-file nodes-2.conf --cluster-node-timeout 5000 ports: - 7002:6379 volumes: - ./redis-cluster/redis-node-2/redis.conf:/usr/local/etc/redis/redis.conf - redis-data-2:/data networks: - app-network # ... 定义 redis-node-3 到 redis-node-6端口映射依次为7003-7006 volumes: redis-data-1: redis-data-2: # ... 定义 redis-data-3 到 redis-data-6redis-cluster/redis-node-1/redis.conf(基础配置):port 6379 bind 0.0.0.0 protected-mode no daemonize no appendonly yes cluster-require-full-coverage no关键点解析集群启动参数--cluster-enabled yes启用集群模式。--cluster-config-file nodes-1.conf集群节点自动生成的配置文件记录了集群状态。--cluster-node-timeout 5000节点超时时间毫秒。端口映射将每个节点的容器内6379端口映射到宿主机的不同端口7001-7006方便我们使用宿主机上的redis-cli进行管理。数据持久化使用appendonly yes开启AOF持久化并将数据目录/data挂载到独立的Docker卷确保数据安全。3.5 使用Docker Compose编排一切最终的docker-compose.yml将上述所有服务整合在一起。docker-compose.yml(完整版):version: 3.8 services: openresty: build: ./nginx # 使用当前目录下nginx文件夹中的Dockerfile构建 container_name: my-openresty restart: unless-stopped ports: - 8080:80 # 宿主机8080映射到容器80 depends_on: - mysql - redis-node-1 - redis-node-2 - redis-node-3 - redis-node-4 - redis-node-5 - redis-node-6 networks: - app-network mysql: image: mysql:8.0 container_name: my-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: your_strong_password_here MYSQL_DATABASE: test_db ports: - 3306:3306 volumes: - mysql_data:/var/lib/mysql - ./mysql/init.sql:/docker-entrypoint-initdb.d/init.sql networks: - app-network # Redis Cluster Nodes (3主3从) redis-node-1: image: redis:7-alpine container_name: redis-node-1 command: redis-server /usr/local/etc/redis/redis.conf --cluster-enabled yes --cluster-config-file nodes-1.conf --cluster-node-timeout 5000 ports: - 7001:6379 volumes: - ./redis-cluster/redis-node-1/redis.conf:/usr/local/etc/redis/redis.conf - redis-data-1:/data networks: - app-network redis-node-2: image: redis:7-alpine container_name: redis-node-2 command: redis-server /usr/local/etc/redis/redis.conf --cluster-enabled yes --cluster-config-file nodes-2.conf --cluster-node-timeout 5000 ports: - 7002:6379 volumes: - ./redis-cluster/redis-node-2/redis.conf:/usr/local/etc/redis/redis.conf - redis-data-2:/data networks: - app-network # ... 定义 redis-node-3, redis-node-4, redis-node-5, redis-node-6 # 配置类似注意修改container_name、ports映射和volumes路径 networks: app-network: driver: bridge volumes: mysql_data: redis-data-1: redis-data-2: redis-data-3: redis-data-4: redis-data-5: redis-data-6:4. 集群初始化、操作与问题排查4.1 启动服务与初始化Redis Cluster启动所有容器docker-compose up -d这将会构建OpenResty镜像并启动MySQL和所有6个Redis节点容器。初始化Redis Cluster 所有Redis节点容器启动后它们还是独立的实例需要手动将它们组成一个集群。# 进入任意一个Redis节点容器 docker exec -it redis-node-1 sh # 在容器内执行集群创建命令 # 格式redis-cli --cluster create node1-ip:port node2-ip:port ... --cluster-replicas 1 # 注意在Docker网络内使用容器名和容器内端口6379 redis-cli --cluster create \ redis-node-1:6379 \ redis-node-2:6379 \ redis-node-3:6379 \ redis-node-4:6379 \ redis-node-5:6379 \ redis-node-6:6379 \ --cluster-replicas 1执行后redis-cli会给出一个主从分配方案例如1、2、3为主节点4是1的从5是2的从6是3的从输入yes确认即可。验证集群状态# 在容器内连接任意节点查看集群信息 redis-cli -c -h redis-node-1 -p 6379 cluster nodes你会看到一个包含所有节点ID、角色master/slave、槽位slot分配信息的列表。4.2 测试完整链路测试MySQL连接docker exec -it my-mysql mysql -uroot -p # 输入密码后执行 USE test_db; SELECT * FROM test_table;测试OpenResty接口 使用curl或浏览器访问http://localhost:8080/api/data?id1。第一次请求会触发get_from_mysql从数据库查询id1的数据然后写入Redis并返回JSON。第二次请求会命中Redis缓存直接返回响应时间会快很多。4.3 常见问题与排查技巧实录问题1OpenResty启动失败报错lua-resty-redis-cluster模块找不到。排查检查nginx/Dockerfile中luarocks install步骤是否成功。可以进入构建中的容器或最终运行的容器查看。docker exec -it my-openresty sh # 进入容器后 luarocks list | grep redis-cluster解决确保网络通畅可以尝试更换LuaRocks源。或者将lua-resty-redis-cluster的源码直接下载到./nginx/lua/目录在Lua脚本中用package.path直接引用避免在Dockerfile中编译安装。问题2Lua脚本连接MySQL或Redis Cluster超时。排查检查OpenResty容器是否能ping通mysql和redis-node-1等服务名。docker exec -it my-openresty sh ping mysql检查MySQL和Redis容器的日志看是否有错误。docker logs my-mysql docker logs redis-node-1在Lua脚本中增加错误日志输出检查具体的错误信息。解决确认所有服务都在同一个Docker网络app-network中。检查Lua脚本中的连接参数主机名、端口、密码是否正确。调整连接超时参数set_timeout,connection_timeout。问题3向Redis Cluster写入数据时报错MOVED或ASK。原因这是Redis Cluster的正常行为。客户端请求的key根据CRC16算法被分配到了其他节点节点会返回MOVED错误并告知正确节点。排查lua-resty-redis-cluster库应该能自动处理这些重定向。如果频繁出现检查库的max_redirection参数是否设置过小或者集群状态是否正常是否有节点宕机槽位分配是否完整。redis-cli -c -h redis-node-1 -p 6379 cluster info | grep cluster_slots_assigned # 输出应为cluster_slots_assigned:16384问题4Docker Desktop启动失败提示“Virtualization support wasnt detected”。背景这是Windows/macOS上运行Docker Desktop的常见问题。解决步骤BIOS/UEFI设置重启电脑进入BIOS/UEFI设置确保Intel VT-x或AMD-V虚拟化技术已启用。Windows功能针对Windows打开“控制面板” - “程序” - “启用或关闭Windows功能”。确保“Hyper-V”和“Windows虚拟机监控程序平台”已勾选启用。如果之前未启用启用后需要重启。WSL 2推荐方案安装并启用WSL 2适用于Linux的Windows子系统然后在Docker Desktop设置中将后端引擎改为WSL 2这通常比传统Hyper-V更稳定。杀毒软件/安全软件暂时禁用第三方杀毒软件有时它们会干扰虚拟化功能。问题5Lua脚本性能不佳QPS上不去。排查方向连接池确保MySQL和Redis连接都正确使用了set_keepalive。Lua代码缓存检查nginx.conf中lua_code_cache是否设置为on生产环境必须为on。OpenResty配置调整worker_processes通常等于CPU核心数和worker_connections。系统限制检查宿主机和容器的资源限制CPU、内存使用docker stats查看。日志级别将ngx.log的级别从ERR调整为更高级别如WARN或INFO避免频繁写磁盘影响性能。通过以上步骤一个基于Docker的OpenResty Lua MySQL Redis Cluster开发环境就搭建并调试完毕了。这个环境完美复现了生产架构的核心部分让你能在本地进行全链路的功能开发和性能测试。
1. 项目概述为什么需要这个“全家桶”最近在折腾一个需要高并发处理用户请求的后台服务核心需求是接收海量HTTP请求进行一些业务逻辑判断比如验签、限流然后读写数据库和缓存最后返回结果。最开始用传统的Nginx 后端应用服务器如Java/Python的架构发现瓶颈很明显每次请求都要穿透到后端网络IO和进程间通信的开销在QPS上去之后成了拖累。后来了解到OpenResty它直接把Lua虚拟机塞进了Nginx让你能在Nginx的各个处理阶段用Lua脚本写业务逻辑这相当于把一部分后端代码“前置”到了网关层性能提升是立竿见影的。但随之而来的就是环境部署的麻烦。OpenResty本身要编译安装还得配Lua的各种第三方库比如操作MySQL和Redis的驱动更别提MySQL和Redis Cluster的搭建了。本地开发环境和测试、生产环境的不一致更是让“在我机器上好好的”这种问题频繁出现。这时候Docker的优势就体现出来了。用Docker把OpenResty Lua MySQL Redis Cluster这整套环境打包成一个可复现、可移植的“全家桶”无论是新同事搭建开发环境还是做CI/CD自动化测试都能做到一键启动环境完全一致。这个项目标题“docker构建openrety lua mysql rediscluster”本质上就是在解决这个痛点。它不是一个简单的软件堆砌而是构建一个高性能、可编排的Web应用后端模拟环境。OpenResty负责高效的网络IO和业务逻辑处理Lua是粘合剂MySQL作为持久化存储Redis Cluster提供高性能的分布式缓存。用Docker来封装则是为了极致的环境一致性和部署效率。2. 整体架构设计与组件选型考量2.1 核心架构图与数据流整个服务的核心数据流可以这样理解用户请求到达OpenResty监听80/443端口。OpenResty的access_by_lua阶段执行Lua脚本进行IP黑名单、请求签名验证等操作。OpenResty的content_by_lua阶段这里是业务逻辑核心。首先Lua脚本会查询Redis Cluster看看数据是否在缓存中。Redis Cluster的分布式特性允许我们部署多个节点缓存容量和吞吐量可以线性增长。如果缓存未命中Cache Miss则Lua脚本通过连接池访问MySQL数据库获取持久化数据。从MySQL获取数据后在返回给用户之前将数据按一定规则写入Redis Cluster供后续请求使用Cache Aside模式。OpenResty响应将处理结果返回给用户。在这个流程中Docker Compose负责将这四个组件OpenResty, Lua环境, MySQL, Redis Cluster组织成一个协同工作的整体。每个组件运行在独立的容器中通过Docker网络进行通信。2.2 关键组件选型与版本确定OpenResty我们选择官方镜像openresty/openresty:1.21.4.1-alpine。Alpine版本镜像体积小安全性相对较高符合容器化最佳实践。1.21.4.1是一个长期支持且稳定的版本。Lua库lua-resty-mysqlOpenResty官方维护的MySQL客户端库非阻塞与Nginx事件模型完美契合。lua-resty-redis-cluster一个支持Redis Cluster的第三方Lua库。这里是个关键点OpenResty自带的lua-resty-redis只支持单节点或主从Redis对Cluster的支持需要这个专门的库。MySQL选择mysql:8.0。相比5.78.0在性能、安全性和JSON支持上都有显著提升。我们以它作为数据源。Redis Cluster选择redis:7-alpine镜像来构建集群。Redis 7在ACL、Function等方面有增强。一个最小的Redis Cluster需要至少3个主节点为了保证高可用我们通常为每个主节点配一个从节点所以至少需要6个容器实例。这里为了演示我们先搭建3主3从的集群。注意在生产环境中MySQL和Redis Cluster通常不会与应用容器部署在同一台宿主机上而是使用独立的云服务或物理机集群。本项目的Docker化主要用于开发、测试和演示环境它提供了与生产环境架构一致但资源消耗可控的本地沙箱。2.3 项目目录结构规划一个清晰的项目结构是成功的一半。在开始写Dockerfile和配置文件之前我们先规划好目录。openresty-lua-docker-example/ ├── docker-compose.yml # 编排所有服务的总纲 ├── nginx/ │ ├── Dockerfile # 定制OpenResty镜像安装Lua依赖 │ ├── nginx.conf # OpenResty主配置文件 │ ├── conf.d/ │ │ └── default.conf # 具体的HTTP服务配置 │ └── lua/ # 存放所有Lua脚本 │ ├── app.lua # 主要业务逻辑脚本 │ ├── mysql.lua # MySQL操作封装 │ └── redis_cluster.lua # Redis Cluster操作封装 ├── mysql/ │ ├── init.sql # 数据库初始化脚本建表、插入基础数据 │ └── my.cnf # MySQL自定义配置可选 └── redis-cluster/ ├── redis-node-1/ │ └── redis.conf # 节点1配置 ├── redis-node-2/ │ └── redis.conf # 节点2配置 └── ... (共6个节点目录) # 其余节点配置这个结构将配置、脚本和数据分离一目了然。3. 核心组件配置与Docker化实战3.1 构建定制的OpenResty镜像官方的OpenResty镜像不包含我们需要的lua-resty-redis-cluster库所以需要自定义Dockerfile来安装。nginx/Dockerfile:# 基于官方Alpine镜像 FROM openresty/openresty:1.21.4.1-alpine # 安装Git和必要的编译工具用于下载和安装LuaRocks及第三方库 RUN apk add --no-cache git gcc libc-dev make # 安装LuaRocksOpenResty Alpine镜像默认不包含 RUN wget https://luarocks.org/releases/luarocks-3.9.2.tar.gz \ tar -xzf luarocks-3.9.2.tar.gz \ cd luarocks-3.9.2 \ ./configure --with-lua/usr/local/openresty/luajit \ --lua-suffixjit \ --with-lua-include/usr/local/openresty/luajit/include/luajit-2.1 \ make make install \ cd .. rm -rf luarocks-3.9.2* # 使用LuaRocks安装 lua-resty-redis-cluster # 注意这里指定了--server参数因为默认源可能访问慢或不稳定 RUN luarocks install lua-resty-redis-cluster --serverhttps://luarocks.cn # 清理缓存减小镜像体积 RUN apk del git gcc libc-dev make \ rm -rf /var/cache/apk/* # 将本地的Lua脚本和配置文件拷贝到镜像中 COPY ./lua /usr/local/openresty/nginx/lua/ COPY nginx.conf /usr/local/openresty/nginx/conf/nginx.conf COPY ./conf.d /etc/nginx/conf.d/ # 暴露80端口 EXPOSE 80 # 启动OpenResty CMD [/usr/local/openresty/bin/openresty, -g, daemon off;]关键点解析为什么用Alpine镜像体积小最终镜像约100MB安全补丁更新快。但它的musl libc与标准glibc略有差异极少数二进制依赖可能有问题对于我们只运行OpenResty和Lua来说完全够用。安装编译工具链Alpine基础镜像很精简需要手动安装gcc,make等来编译LuaRocks。安装完成后立即删除这些工具是构建小镜像的常见技巧。LuaRocks配置--with-lua参数必须指向OpenResty自带的LuaJIT路径确保安装的库与当前OpenResty环境兼容。使用国内源--serverhttps://luarocks.cn能显著加速在中国大陆的下载速度避免因网络问题导致构建失败。3.2 配置OpenResty与Lua脚本nginx/nginx.conf(核心配置简化版):worker_processes auto; # 自动根据CPU核心数设置工作进程 events { worker_connections 1024; # 每个工作进程的最大连接数 } http { include mime.types; default_type application/json; # 默认返回JSON格式 # 启用Lua代码缓存生产环境必须开启否则每次请求都加载脚本性能极差 lua_code_cache on; # 初始化阶段加载Lua模块 init_by_lua_block { -- 预加载全局模块避免在请求阶段重复加载 require resty.core redis_cluster require resty.rediscluster mysql require resty.mysql } # 配置上游服务器本例中未使用但保留结构 upstream backend { # 这里可以配置其他后端服务 } # 包含具体的server配置 include /etc/nginx/conf.d/*.conf; }nginx/conf.d/default.conf:server { listen 80; server_name localhost; location /api/data { # 设置响应头 default_type application/json; charset utf-8; # 所有业务逻辑都在这个Lua脚本中处理 content_by_lua_file /usr/local/openresty/nginx/lua/app.lua; } # 一个健康检查端点 location /health { access_by_lua_block { ngx.say({status: UP}) } } }核心Lua脚本nginx/lua/app.lua:-- 获取请求参数 local args ngx.req.get_uri_args() local id args.id if not id or id then ngx.status ngx.HTTP_BAD_REQUEST ngx.say({error: missing parameter: id}) ngx.exit(ngx.HTTP_BAD_REQUEST) end -- 1. 先尝试从Redis Cluster获取缓存 local cache_data get_from_redis_cluster(id) if cache_data then ngx.say(cache_data) return -- 缓存命中直接返回 end -- 2. 缓存未命中查询MySQL local db_data get_from_mysql(id) if not db_data then ngx.status ngx.HTTP_NOT_FOUND ngx.say({error: data not found}) ngx.exit(ngx.HTTP_NOT_FOUND) end -- 3. 将数据库结果写入Redis Cluster设置过期时间如60秒 set_to_redis_cluster(id, db_data, 60) -- 4. 返回数据给用户 ngx.say(db_data) -- 下面是封装的函数实际会放在单独的模块文件中这里为演示写在一起 function get_from_redis_cluster(key) local red_c redis_cluster:new({ name my_redis_cluster, serv_list { {ip redis-node-1, port 6379}, {ip redis-node-2, port 6379}, {ip redis-node-3, port 6379}, {ip redis-node-4, port 6379}, {ip redis-node-5, port 6379}, {ip redis-node-6, port 6379}, }, keepalive_timeout 60000, -- 连接池保活时间 keepalive_cons 1000, -- 连接池大小 connection_timout 1000, -- 连接超时(ms) max_redirection 5, -- 最大重定向次数Cluster节点跳转 }) local res, err red_c:get(key) if not res then ngx.log(ngx.ERR, failed to get key from redis cluster: , err) return nil end -- 将连接放回连接池 local ok, err red_c:set_keepalive() if not ok then ngx.log(ngx.ERR, failed to set keepalive: , err) end return res end function get_from_mysql(id) local db, err mysql:new() if not db then ngx.log(ngx.ERR, failed to instantiate mysql: , err) return nil end db:set_timeout(1000) -- 1秒超时 local ok, err, errno, sqlstate db:connect({ host mysql, -- Docker Compose中的服务名 port 3306, database test_db, user root, password your_strong_password_here, }) if not ok then ngx.log(ngx.ERR, failed to connect to mysql: , err, : , errno, , sqlstate) return nil end -- 使用参数化查询防止SQL注入 local sql SELECT id, name, value FROM test_table WHERE id ? local res, err, errno, sqlstate db:query(sql, {id}) if not res then ngx.log(ngx.ERR, bad result: , err, : , errno, , sqlstate) return nil end -- 将结果转换为JSON字符串这里简化处理实际可使用cjson库 local ok, err db:set_keepalive(10000, 100) -- 放入连接池 if not ok then ngx.log(ngx.ERR, failed to set keepalive: , err) end if #res 0 then return nil end -- 假设我们有一个简单的序列化函数实际应用中应使用cjson return string.format({id:%d,name:%s,value:%s}, res[1].id, res[1].name, res[1].value) end function set_to_redis_cluster(key, value, exptime) -- 类似get_from_redis_cluster调用red_c:set(key, value)和red_c:expire(key, exptime) -- 此处省略具体实现 end实操心得在Lua脚本中连接数据库和Redis一定要使用连接池set_keepalive。如果不使用连接池每次请求都新建TCP连接性能会急剧下降。keepalive_cons参数控制连接池大小需要根据实际并发量调整。3.3 配置MySQL与数据初始化docker-compose.yml中MySQL部分:services: mysql: image: mysql:8.0 container_name: my-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: your_strong_password_here MYSQL_DATABASE: test_db MYSQL_USER: app_user MYSQL_PASSWORD: app_user_password ports: - 3306:3306 volumes: - mysql_data:/var/lib/mysql - ./mysql/init.sql:/docker-entrypoint-initdb.d/init.sql # 初始化脚本挂载 networks: - app-network volumes: mysql_data:mysql/init.sql:-- 创建应用专用的数据库和用户虽然环境变量已创建这里确保权限 CREATE DATABASE IF NOT EXISTS test_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE test_db; -- 创建一个简单的测试表 CREATE TABLE IF NOT EXISTS test_table ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255) NOT NULL, value TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) ENGINEInnoDB; -- 插入一些测试数据 INSERT INTO test_table (name, value) VALUES (item_1, This is the first value.), (item_2, This is the second value.), (item_3, This is the third value.);关键点解析数据持久化通过volumes将容器内的/var/lib/mysql目录挂载到名为mysql_data的Docker卷上。这样即使容器被删除数据也不会丢失。初始化脚本将SQL文件挂载到/docker-entrypoint-initdb.d/目录下MySQL容器在首次启动时会自动执行该目录下的所有.sql、.sh文件。这是初始化数据库表结构和基础数据的标准做法。网络所有服务都加入同一个自定义的Docker网络app-network这样容器间可以通过服务名如mysql、redis-node-1直接通信无需知道IP地址。3.4 搭建Redis Cluster集群这是最复杂的一步。Redis Cluster的Docker化需要启动多个容器并手动或通过脚本将它们组成集群。docker-compose.yml中Redis Cluster部分:services: redis-node-1: image: redis:7-alpine container_name: redis-node-1 command: redis-server /usr/local/etc/redis/redis.conf --cluster-enabled yes --cluster-config-file nodes-1.conf --cluster-node-timeout 5000 ports: - 7001:6379 volumes: - ./redis-cluster/redis-node-1/redis.conf:/usr/local/etc/redis/redis.conf - redis-data-1:/data networks: - app-network redis-node-2: image: redis:7-alpine container_name: redis-node-2 command: redis-server /usr/local/etc/redis/redis.conf --cluster-enabled yes --cluster-config-file nodes-2.conf --cluster-node-timeout 5000 ports: - 7002:6379 volumes: - ./redis-cluster/redis-node-2/redis.conf:/usr/local/etc/redis/redis.conf - redis-data-2:/data networks: - app-network # ... 定义 redis-node-3 到 redis-node-6端口映射依次为7003-7006 volumes: redis-data-1: redis-data-2: # ... 定义 redis-data-3 到 redis-data-6redis-cluster/redis-node-1/redis.conf(基础配置):port 6379 bind 0.0.0.0 protected-mode no daemonize no appendonly yes cluster-require-full-coverage no关键点解析集群启动参数--cluster-enabled yes启用集群模式。--cluster-config-file nodes-1.conf集群节点自动生成的配置文件记录了集群状态。--cluster-node-timeout 5000节点超时时间毫秒。端口映射将每个节点的容器内6379端口映射到宿主机的不同端口7001-7006方便我们使用宿主机上的redis-cli进行管理。数据持久化使用appendonly yes开启AOF持久化并将数据目录/data挂载到独立的Docker卷确保数据安全。3.5 使用Docker Compose编排一切最终的docker-compose.yml将上述所有服务整合在一起。docker-compose.yml(完整版):version: 3.8 services: openresty: build: ./nginx # 使用当前目录下nginx文件夹中的Dockerfile构建 container_name: my-openresty restart: unless-stopped ports: - 8080:80 # 宿主机8080映射到容器80 depends_on: - mysql - redis-node-1 - redis-node-2 - redis-node-3 - redis-node-4 - redis-node-5 - redis-node-6 networks: - app-network mysql: image: mysql:8.0 container_name: my-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: your_strong_password_here MYSQL_DATABASE: test_db ports: - 3306:3306 volumes: - mysql_data:/var/lib/mysql - ./mysql/init.sql:/docker-entrypoint-initdb.d/init.sql networks: - app-network # Redis Cluster Nodes (3主3从) redis-node-1: image: redis:7-alpine container_name: redis-node-1 command: redis-server /usr/local/etc/redis/redis.conf --cluster-enabled yes --cluster-config-file nodes-1.conf --cluster-node-timeout 5000 ports: - 7001:6379 volumes: - ./redis-cluster/redis-node-1/redis.conf:/usr/local/etc/redis/redis.conf - redis-data-1:/data networks: - app-network redis-node-2: image: redis:7-alpine container_name: redis-node-2 command: redis-server /usr/local/etc/redis/redis.conf --cluster-enabled yes --cluster-config-file nodes-2.conf --cluster-node-timeout 5000 ports: - 7002:6379 volumes: - ./redis-cluster/redis-node-2/redis.conf:/usr/local/etc/redis/redis.conf - redis-data-2:/data networks: - app-network # ... 定义 redis-node-3, redis-node-4, redis-node-5, redis-node-6 # 配置类似注意修改container_name、ports映射和volumes路径 networks: app-network: driver: bridge volumes: mysql_data: redis-data-1: redis-data-2: redis-data-3: redis-data-4: redis-data-5: redis-data-6:4. 集群初始化、操作与问题排查4.1 启动服务与初始化Redis Cluster启动所有容器docker-compose up -d这将会构建OpenResty镜像并启动MySQL和所有6个Redis节点容器。初始化Redis Cluster 所有Redis节点容器启动后它们还是独立的实例需要手动将它们组成一个集群。# 进入任意一个Redis节点容器 docker exec -it redis-node-1 sh # 在容器内执行集群创建命令 # 格式redis-cli --cluster create node1-ip:port node2-ip:port ... --cluster-replicas 1 # 注意在Docker网络内使用容器名和容器内端口6379 redis-cli --cluster create \ redis-node-1:6379 \ redis-node-2:6379 \ redis-node-3:6379 \ redis-node-4:6379 \ redis-node-5:6379 \ redis-node-6:6379 \ --cluster-replicas 1执行后redis-cli会给出一个主从分配方案例如1、2、3为主节点4是1的从5是2的从6是3的从输入yes确认即可。验证集群状态# 在容器内连接任意节点查看集群信息 redis-cli -c -h redis-node-1 -p 6379 cluster nodes你会看到一个包含所有节点ID、角色master/slave、槽位slot分配信息的列表。4.2 测试完整链路测试MySQL连接docker exec -it my-mysql mysql -uroot -p # 输入密码后执行 USE test_db; SELECT * FROM test_table;测试OpenResty接口 使用curl或浏览器访问http://localhost:8080/api/data?id1。第一次请求会触发get_from_mysql从数据库查询id1的数据然后写入Redis并返回JSON。第二次请求会命中Redis缓存直接返回响应时间会快很多。4.3 常见问题与排查技巧实录问题1OpenResty启动失败报错lua-resty-redis-cluster模块找不到。排查检查nginx/Dockerfile中luarocks install步骤是否成功。可以进入构建中的容器或最终运行的容器查看。docker exec -it my-openresty sh # 进入容器后 luarocks list | grep redis-cluster解决确保网络通畅可以尝试更换LuaRocks源。或者将lua-resty-redis-cluster的源码直接下载到./nginx/lua/目录在Lua脚本中用package.path直接引用避免在Dockerfile中编译安装。问题2Lua脚本连接MySQL或Redis Cluster超时。排查检查OpenResty容器是否能ping通mysql和redis-node-1等服务名。docker exec -it my-openresty sh ping mysql检查MySQL和Redis容器的日志看是否有错误。docker logs my-mysql docker logs redis-node-1在Lua脚本中增加错误日志输出检查具体的错误信息。解决确认所有服务都在同一个Docker网络app-network中。检查Lua脚本中的连接参数主机名、端口、密码是否正确。调整连接超时参数set_timeout,connection_timeout。问题3向Redis Cluster写入数据时报错MOVED或ASK。原因这是Redis Cluster的正常行为。客户端请求的key根据CRC16算法被分配到了其他节点节点会返回MOVED错误并告知正确节点。排查lua-resty-redis-cluster库应该能自动处理这些重定向。如果频繁出现检查库的max_redirection参数是否设置过小或者集群状态是否正常是否有节点宕机槽位分配是否完整。redis-cli -c -h redis-node-1 -p 6379 cluster info | grep cluster_slots_assigned # 输出应为cluster_slots_assigned:16384问题4Docker Desktop启动失败提示“Virtualization support wasnt detected”。背景这是Windows/macOS上运行Docker Desktop的常见问题。解决步骤BIOS/UEFI设置重启电脑进入BIOS/UEFI设置确保Intel VT-x或AMD-V虚拟化技术已启用。Windows功能针对Windows打开“控制面板” - “程序” - “启用或关闭Windows功能”。确保“Hyper-V”和“Windows虚拟机监控程序平台”已勾选启用。如果之前未启用启用后需要重启。WSL 2推荐方案安装并启用WSL 2适用于Linux的Windows子系统然后在Docker Desktop设置中将后端引擎改为WSL 2这通常比传统Hyper-V更稳定。杀毒软件/安全软件暂时禁用第三方杀毒软件有时它们会干扰虚拟化功能。问题5Lua脚本性能不佳QPS上不去。排查方向连接池确保MySQL和Redis连接都正确使用了set_keepalive。Lua代码缓存检查nginx.conf中lua_code_cache是否设置为on生产环境必须为on。OpenResty配置调整worker_processes通常等于CPU核心数和worker_connections。系统限制检查宿主机和容器的资源限制CPU、内存使用docker stats查看。日志级别将ngx.log的级别从ERR调整为更高级别如WARN或INFO避免频繁写磁盘影响性能。通过以上步骤一个基于Docker的OpenResty Lua MySQL Redis Cluster开发环境就搭建并调试完毕了。这个环境完美复现了生产架构的核心部分让你能在本地进行全链路的功能开发和性能测试。
)
