柴少的官方网站

Jenkins基础补充(五)

Thu, 05 Feb 2026 17:56:56 +0800

#距离jenkins系统文章已经过去了N多年,jenkins版本及使用方法已经发生了很大改变,这里借这篇文章回顾一下基础知识,起到承上启下的作用,基础牢固者可略过

一、Scaling Jenkins(扩展Jenkins)

官网文档：https://www.jenkins.io/doc/book/scaling/

1.1 jenkins目录结构

#之前没有讲jenkins的目录结构,这里就以当前最新版2.541.1举例

#先介绍文件

config.xml #Jenkins全局核心配置文件,包含Jenkins运行的基础配置:端口、工作目录、安全策略、全局工具配置、代理设置等,修改后重启Jenkins生效
hudson.model.UpdateCenter.xml #插件更新中心配置,定义Jenkins插件下载的源地址默认官方源
hudson.plugins.emailext.ExtendedEmailPublisher.xml #扩展邮件插件(Email Ext)全局配置,配置邮件发送的全局参数
hudson.plugins.git.GitTool.xml #Git工具的全局配置
identity.key.enc #身份加密密钥,Jenkins用于加密身份信息(如账号密码、远程服务器密钥)的核心文件
jenkins.install.InstallUtil.lastExecVersion #Jenkins最后执行的版本标识
jenkins.install.UpgradeWizard.state #升级向导状态文件,避免重复触发升级流程
jenkins.model.JenkinsLocationConfiguration.xml #Jenkins位置配置,定义Jenkins的访问地址、节点通信等的基础地址配置
jenkins.telemetry.Correlator.xml #Jenkins遥测配置,记录Jenkins的遥测标识，用于向官方上报基础运行数据
nodeMonitors.xml #节点监控配置,用于节点健康检查
org.jenkinsci.plugins.workflow.flow.FlowExecutionList.xml #流水线执行列表配置,记录Pipeline的运行实例状态、执行记录关联信息，用于流水线历史查询、断点续跑
queue.xml #任务队列配置,记录Jenkins等待执行的任务队列(如触发了多个Job但执行器不足时的排队信息)，重启Jenkins后队列不会丢失
secret.key #Jenkins核心加密密钥,用于加密所有敏感数据(如密码、令牌、私钥),是Jenkins安全的核心文件,丢失后所有加密数据将无法解密
secret.key.not-so-secret #辅助加密密钥(非敏感),配合secret.key使用的轻量密钥，无敏感信息，仅做加密补充

#然后再介绍下目录

caches #Jenkins缓存目录,存储插件、更新中心、依赖包的下载缓存，减少重复下载；可手动删除，重启Jenkins后会重新生成，不影响核心功能
jobs #所有Job(任务)的核心存储目录,每个Job对应一个子目录,子目录内包含：
     #1.config.xml:该Job的专属配置(构建步骤、触发器、源码地址等)；
     #2.builds:该Job的所有构建历史(按构建号命名，包含日志、产物、报告）；
     #3.nextBuildNumber: 当前构建到的BuildId
logs #Jenkins系统日志目录,存储Jenkins的运行日志、节点通信日志、插件日志 
plugins #插件安装目录, 核心目录,每个已安装的插件对应一个子目录(插件名+版本)，子目录内包含插件的jar包、配置文件、依赖；
secrets #敏感信息存储目录,存储Jenkins的所有敏感数据
updates #插件更新缓存目录,存储插件更新中心的索引、插件版本列表、更新包缓存，配合UpdateCenter.xml使用，用于插件的检查更新、一键安装   
userContent #Jenkins自定义静态资源目录、可存放自定义的静态文件(如图片、HTML、报告模板)，通过JenkinsURL/userContent/[文件名]可直接访问
users #Jenkins用户信息目录,每个用户对应一个子目录（以用户ID 命名），子目录内包含config.xml（用户信息：昵称、邮箱、权限、加密后的密码）
war #Jenkins WAR包解压目录,包含核心前端页面、后端类文件、默认配置；不可随意修改，修改后可能导致 Jenkins 启动失败
workspace #Job默认工作空间目录,每个Job的构建会在workspace/[Job名]下拉取源码、执行构建命令、生成中间产物

1.2 Glossary(词汇表)

基本词组：

Agent #代理,执行任务的节点
Artifact #这次构建任务，最后产出的"成品文件"
Build #构建,作业单次执行的结果
Cloud #Cloud(动态代理节点)就是让Jenkins能"自动创建、用完就删"的代理节点
Controller #jenkins主节点也就是服务主控节点本身
Core #jenkins的应用程序
Downstream #下游,被当前任务自动触发的任务
Executor #执行数,一个节点能同时执行任务的数量
Fingerprint #指纹,给Jar/文件生成唯一指纹(唯一哈希值)，用来追踪：这个文件是哪次构建生成的、被哪些任务用过。
Folder #用来给Jenkins任务分类、放一起的文件夹
Item # Jenkins里点[新建任务]出来的所有东西，全都叫Item
Jenkins URL #用户访问的jenkins应用程序的主url
Job #Jenkins里真正用来跑构建、打包、部署的任务
Kubernetes #就是你理解的K8S
Label #给节点打"标签/分组标记"，用来分配任务跑在哪个节点上面
LTS #长期稳定版
Node #能被Jenkins用来跑任务的机器，都叫Node。
Project #一个被废弃的术语,与job同义
Pipeline #用代码写的自动化部署流程
Plugin #插件,功能扩展包
Publisher #构建跑完之后，才执行的操作
Resource Root URL #专门放静态文件的"副域名"
Release #版本上线
Stage #阶段,pipeline流程里面的每个阶段
Step #步骤,上面阶段里面的每一小步操作
Trigger #自动启动任务的开关,满足某个条件，Jenkins自己跑Job
Update Center #更新中心
Upstream #上游任务,触发当前任务的前一个任务
View #视图,自定义的任务列表
Workspace #工作区,Job运行时,代码拉下来、打包、生成jar所在的那个文件夹

二、Pipeline学习

官网文档：https://www.jenkins.io/doc/book/pipeline/
#这里主要是跟着官方文档的结构学习一下Pipeline

2.1 Pipeline介绍

什么是Pipeline？

Jenkins本质上是一个支持多种自动化模式的自动化引擎。Pipeline为Jenkins添加了一组强大的自动化工具，支持从简单的持续集成到全面的CD管道的用例。通过对一系列相关任务进行建模，用户可以利用Pipeline的许多功能：

code(代码)：管道在代码中实现，通常签入源代码管理，使团队能够编辑、审查和迭代他们的交付管道。
Durable(持久)：管道可以在Jenkins控制器的计划内和计划外重启中生存。
Pausable(可暂停)：管道可以选择停止并等待人工输入或批准，然后再继续运行管道。
Versatile(多功能)：管道支持复杂的现实CD需求，包括分叉/连接、循环和并行执行工作的能力。
Extensible(可扩展)：Pipeline插件支持对其DSL(写代码定义任务)的自定义扩展，以及与其他插件集成的多种选项。

声明式管道定义

在声明性管道语法中，管道块定义了整个管道中完成的所有工作。先来一个最简单的例子：

pipeline {
    agent any //必须：指定执行任务的节点（any 表示任意可用节点）
    stages { // 必须：定义流水线的所有阶段
        stage('Build'){ // 至少一个stage
            steps{ // 必须：该阶段要执行的具体操作
                echo "This is Build" // 执行命令（如shell、git等）,这里不能为空不然任务会报错
            }
        }
        stage('Test'){
            steps{
                echo "This is Test"
            }
        }
        stage('Deploy'){
            steps{
                echo "This is Deploy"
            }
        }
    }
}

#上面就是一个简单的声明式流水线的例子,是一种结构化、易读、面向声明式编程的DSL语法,核心是"声明要做什么"。只需要按照固定的语法结构定义流水线的目标（比如 “拉代码→编译→测试→部署”），Jenkins 会自动处理底层执行逻辑。

声明式管道内置的结构化关键字：

pipeline：顶层容器，包裹所有声明式逻辑（必须）
agent：指定流水线执行的节点
stages：所有阶段的容器，至少包含一个 stage（必须）
stage：单个阶段（如 “拉代码”“测试”），每个 stage 对应一个业务步骤
steps：单个阶段的具体操作（如执行 shell 命令、调用 maven）
when：条件判断：仅当满足条件时执行该 stage（如仅 main 分支部署）
parameters：定义流水线运行时的参数（如分支名、版本号）
post：后置操作：流水线 / 阶段结束后执行（如成功通知、失败发邮件）
environment：定义环境变量（如 ENV_NAME = 'prod'）

脚本式管道定义

脚本式管道是基于 Groovy 语言的全功能编程脚本，语法更灵活，更像传统的编程方式，适合需要复杂逻辑控,关注"如何做"。先来一个简单的例子:

node('linux'){
    stage('拉取代码'){
        echo '开始从Git仓库拉取代码...'
        checkout([
            $class: 'GitSCM', //指定Pipeline使用Jenkins Git插件(GitSCM类)来处理Git仓库的代码拉取；
            branches: [[name: '*/main']], // 你的分支
            userRemoteConfigs: [[
                url: 'git@git.test.com:apache/seatunnel-web.git', // SSH格式URL
                credentialsId: '5b6bbc50-3c8d-4912-8f92-9eee90d0fa0c' //对应SSH私钥的凭证ID,注意如果指定的node节点有git权限这里可以不加
            ]],
            gitTool: 'Default' //GitSCM的参数：指定Jenkins配置的Git工具
        ])
        echo '代码拉取完成！'
    }
    
    stage('编译构建') {
        echo '开始执行Maven编译...'
        try {
            // 加载环境变量后执行mvn
            sh '''
                source /etc/profile
                export PATH=$PATH
                mvn -v  # 先验证Maven版本
                mvn clean package -DskipTests
            '''
            echo '编译构建成功！'
        } catch (Exception e) {
            echo "编译失败: ${e.getMessage()}"
            error('构建终止，编译失败！')
        }
    }
}

2.2 Blue Ocean介绍

#官方文档：https://www.jenkins.io/doc/book/blueocean/ #不过看官方文档这个插件不再功能更新了

Blue Ocean是Jenkins 的现代化可视化界面插件，专为Pipeline流水线设计，核心是让CI/CD流程更直观、易用、协作友好。

#插件安装就不介绍了,就是插件搜索Blue Ocean然后安装下就行,下面是安装后,去job任务点击Blue Ocean之后跳转界面效果：

#左上角的天气是健康图标：

太阳: 超过80%的运行成功
太阳有乌云： 61% to 80%的任务运行成功
多云：41% to 60%的任务运行成功
下雨：21% to 40%的任务运行成功
风暴：少于21%的任务运行成功

#中间位置点击运行就是开始执行此任务
#下面的状态是执行任务的状态列表信息,其中左边的状态图标分别对应：

转圈：进行中
绿色：通过
黄色：不稳定
红色：失败
灰色：已中止

#然后我们点击一个最近执行的任务就会跳入到详情页：

#点击那个动作那个动作的圆圈变大,当前界面就显示的哪个动作的日志哦,现在是编译构建圆圈大所以显示的这个动作的日志

2.3 Stage View(完整阶段视图)介绍

#还是插件选择：Stage View
#这个插件的作用是：直观展示流水线执行流程、快速定位构建失败位置、查看阶段耗时、多分支/多次构建对比、直接进入阶段日志

测试环境按需动态加载(三)

Thu, 15 Jan 2026 14:38:32 +0800

#紧接上文:https://blog.51niux.com/?id=329 我们已经手工创建网关文件并将入口流量进行按需路由

一、自动创建网关配置文件

#比如现在我们在web管理平台页面新增一个网关域名,或者是又新增了一个location,又或者是location改变了后端集群(比如集群合并了),那么都需要触发一个web接口去新增或者修改线下和沙箱网关的域名,这时候就需要提供一个web接口进行传参调用了。

1.1 创建模版文件

# cat /opt/web/pod_consul/template/gateway_service.conf #可见模版文件中只需要替换一个域名就可以了

server {
    listen 80;
    listen 443 ssl;
    server_name Domain_Name;

    # 强制HTTPS时开启
    if ($scheme != "https") {
        return 301 https://$host$request_uri;
    }

    #关于SSL部分的内容请参照前面的配置

    # 指定 dnsmasq 的地址 127.0.0.1，优先解析 hosts 里的域名
    resolver 127.0.0.1 valid=10s ipv6=off;
    resolver_timeout 5s;

    include /opt/soft/nginx/conf.d/location/Domain_Name/*.location.conf;

    access_log /opt/log/nginx/Domain_Name/Domain_Name_access.log main;
    error_log /opt/log/nginx/Domain_Name/Domain_Name_error.log error;
}

# cat /opt/web/pod_consul/template/gateway_location.conf #驼峰式的变量就是需要替换的,值就来自于咱们前面插入的那些数据

location / {
    # ===== 固定配置（直接写死）=====
    set $demand_number "ReqId";  # 初始化默认值
    set $trace_tag "ReqId";
    set $client_ip "";  # 核心：初始化自定义变量client_ip
    set $proxy_env "Env_Name";               # 环境（固定：offline/mirror）
    set $stable_domain "ModuleName-Env_Name-ReqId.test.com";  # stable后端域名（固定）
    set $module_name "ModuleName";  # 模块名（固定）
    set $cache_expire 60;   

    # 执行核心业务逻辑（Lua会写入专属日志）
    access_by_lua_file /opt/soft/nginx/conf.d/lua/ip_demand_query.lua;

    # 域名拼接（直接使用Nginx固定变量）
    if ($demand_number = "stable") {
        set $proxy_domain $stable_domain;
    }
    if ($demand_number != "stable") {
        set $proxy_domain "$module_name-$proxy_env-$trace_tag.test.com";
    }

    # 代理转发
    proxy_pass https://$proxy_domain$request_uri;

    proxy_set_header Host $proxy_domain;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_next_upstream http_502  error timeout invalid_header;
    proxy_set_header X-Forwarded-Proto  $scheme;

    # 基础代理配置
    proxy_connect_timeout 5s;
    proxy_send_timeout 5s;
    proxy_read_timeout 5s;
}

1.2 基于域名的网关域名修改

博文来自：www.51niux.com

#pip install django djangorestframework pymysql paramiko

#cd /opt/web/pod_consul/ && django-admin startproject gateway_api

# vim pod_consul/settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # 新增以下内容
    'rest_framework',
    'nginx_conf_app',
    'gateway_api',
]

# vi pod_consul/urls.py

urlpatterns = [
    ......
    # 挂载应用路由，前缀为 /gateway/
    path('gateway/',include('gateway_api.urls')),
]

# vi gateway_api/urls.py

from django.urls import path
from .views import GatewayConfigGenerateView

urlpatterns = [
    # 接口访问路径：http://域名/gateway/generate-config/
    path('generate-config/', GatewayConfigGenerateView.as_view(), name='generate_gateway_config'),
]

#vi gateway_api/views.py

# -*- coding: utf-8 -*-
import os
import re
import paramiko
import pymysql
import logging
import logging.handlers
from datetime import datetime
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status

# ==================== 本地配置（根据实际环境修改） ====================
TEMPLATE_DIR = "/opt/web/pod_consul/template"  # 模板文件目录（干净的模板，无rewrite）
LOCAL_TEMP_DIR = "/opt/web/temp"               # 本地临时目录
LOG_DIR = "/opt/web/pod_consul/logs"           # 日志目录
LOG_FILE = os.path.join(LOG_DIR, "gateway_api.log")
# 自动创建目录
for dir_path in [LOCAL_TEMP_DIR, LOG_DIR]:
    if not os.path.exists(dir_path):
        os.makedirs(dir_path)

# ==================== 日志配置 ====================
logger = logging.getLogger("gateway_api")
logger.setLevel(logging.DEBUG)
if not logger.handlers:
    # 日志格式：时间 + 级别 + 内容
    handler = logging.handlers.RotatingFileHandler(
        LOG_FILE, maxBytes=50*1024*1024, backupCount=5, encoding="utf-8"
    )
    formatter = logging.Formatter("%(asctime)s %(levelname)s %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
    handler.setFormatter(formatter)
    logger.addHandler(handler)

# ==================== 数据库配置（根据实际环境修改） ====================
DB_CONFIG = {
    "host": "192.168.1.101",
    "port": 3306,
    "user": "route",
    "password": "route123456",
    "database": "route",
    "charset": "utf8mb4"
}

# ==================== 远端Nginx服务器配置（根据实际环境修改） ====================
REMOTE_NGINX_SERVERS = [
    {
        "name": "nginx-server-1",
        "host": "192.168.1.102",       # 远端Nginx服务器IP
        "port": 22,                    # SSH端口
        "username": "root",            # SSH登录用户名
        "key_filename": "~/.ssh/id_rsa",# 本地SSH私钥路径（优先用密钥，也可替换为password）
        # "password": "your_ssh_password", # 若不用密钥，取消注释并填写密码
        "remote_service_dir": "/opt/soft/nginx/conf.d",  # 远端service.conf存放目录
        "remote_location_root": "/opt/soft/nginx/conf.d/location",  # 远端location目录根路径
        "nginx_reload_cmd": "/opt/soft/nginx/sbin/nginx -s reload"  # Nginx重载命令
    }
]

# ==================== 核心工具函数 ====================
def is_valid_rewrite_rule(rule):
    """
    校验rewrite规则是否有效：
    1. 非None
    2. 非字符串"NULL"（大小写不敏感）
    3. 去除空格后非空
    """
    if rule is None or (isinstance(rule, str) and rule.strip().upper() == "NULL"):
        return False
    if not isinstance(rule, str) or not rule.strip():
        return False
    return True

def ensure_remote_dir_exists(sftp, remote_dir):
    """
    确保远端目录存在（SFTP方式创建，比SSH命令更可靠，且能立即生效）
    :param sftp: paramiko的SFTP客户端对象
    :param remote_dir: 远端目录路径
    """
    try:
        # 尝试列出目录，判断是否存在
        sftp.listdir(remote_dir)
        logger.info(f"远端目录【{remote_dir}】已存在")
    except IOError:
        # 目录不存在，递归创建（mkdir -p 效果）
        # 拆分目录层级
        dir_parts = remote_dir.split('/')
        current_path = ""
        for part in dir_parts:
            if not part:
                current_path += "/"
                continue
            current_path += part + "/"
            try:
                sftp.stat(current_path)
            except IOError:
                sftp.mkdir(current_path)
                logger.info(f"创建远端目录：{current_path}")
        logger.info(f"远端目录【{remote_dir}】创建成功")

class GatewayConfigGenerateView(APIView):
    """
    核心功能：生成线下/沙箱网关的Nginx配置，仅当rewrite_rule有效时才添加rewrite行
    传参：domain_name（线下网关域名）
    """
    def post(self, request):
        # 记录请求日志
        logger.info(f"接收到配置生成请求，参数：{request.data}")
        
        # 1. 基础参数验证
        domain_name = request.data.get("domain_name")
        if not domain_name or not isinstance(domain_name, str) or len(domain_name) > 255:
            logger.error(f"参数错误：线下网关域名无效，传入值：{domain_name}")
            return Response({
                "code": 400,
                "msg": "线下网关域名不能为空，且长度不能超过255个字符",
                "data": None
            }, status=status.HTTP_400_BAD_REQUEST)
        
        try:
            # 2. 数据库查询（获取线下网关+location+沙箱网关信息）
            db_conn = pymysql.connect(**DB_CONFIG)
            cursor = db_conn.cursor(pymysql.cursors.DictCursor)
            
            # 查询线下网关关联的location信息
            offline_sql = """
                SELECT 
                    o.id AS offline_gateway_id,
                    o.domain_name AS offline_domain,
                    l.location_path,
                    l.module_name,
                    l.cluster_name,
                    l.rewrite_rule
                FROM offline_gateway o
                JOIN offline_location l ON o.id = l.offline_gateway_id
                WHERE o.domain_name = %s
                ORDER BY l.location_path;
            """
            cursor.execute(offline_sql, (domain_name,))
            offline_location_list = cursor.fetchall()
            
            # 无location配置直接返回
            if not offline_location_list:
                logger.warning(f"未查询到线下网关【{domain_name}】关联的location配置")
                cursor.close()
                db_conn.close()
                return Response({
                    "code": 404,
                    "msg": f"未查询到线下网关【{domain_name}】关联的location配置",
                    "data": None
                }, status=status.HTTP_404_NOT_FOUND)
            
            # 查询关联的沙箱网关
            mirror_sql = """
                SELECT domain_name AS mirror_domain
                FROM mirror_gateway
                WHERE offline_gateway_id = %s;
            """
            cursor.execute(mirror_sql, (offline_location_list[0]["offline_gateway_id"],))
            mirror_gateway_list = cursor.fetchall()
            
            # 关闭数据库连接
            cursor.close()
            db_conn.close()
            logger.info(f"数据库查询完成：线下location数量={len(offline_location_list)}，沙箱网关数量={len(mirror_gateway_list)}")
            
            # 3. 整理需要生成配置的域名列表（线下+沙箱）
            domain_list = []
            # 添加线下网关
            domain_list.append({
                "domain": offline_location_list[0]["offline_domain"],
                "domain_type": "offline",
                "location_list": offline_location_list
            })
            # 添加沙箱网关
            for mirror in mirror_gateway_list:
                domain_list.append({
                    "domain": mirror["mirror_domain"],
                    "domain_type": "mirror",
                    "location_list": offline_location_list
                })
            
            # 4. 生成配置文件并上传到远端Nginx服务器
            upload_results = []
            for server in REMOTE_NGINX_SERVERS:
                server_result = {
                    "server_name": server["name"],
                    "server_host": server["host"],
                    "status": "success",
                    "msg": "",
                    "data": {}
                }
                
                try:
                    logger.info(f"开始处理远端服务器：{server['name']}（{server['host']}）")
                    
                    # 建立SSH连接
                    ssh = paramiko.SSHClient()
                    ssh.set_missing_host_key_policy(paramiko.AutoAddPolicy())
                    ssh_connect_kwargs = {
                        "hostname": server["host"],
                        "port": server["port"],
                        "username": server["username"]
                    }
                    if "key_filename" in server and server["key_filename"]:
                        ssh_connect_kwargs["key_filename"] = os.path.expanduser(server["key_filename"])
                    elif "password" in server and server["password"]:
                        ssh_connect_kwargs["password"] = server["password"]
                    ssh.connect(**ssh_connect_kwargs)
                    sftp = ssh.open_sftp()
                    logger.info(f"成功连接远端服务器：{server['host']}")
                    
                    # 遍历每个域名生成配置
                    for domain_item in domain_list:
                        current_domain = domain_item["domain"]
                        domain_type = domain_item["domain_type"]
                        location_list = domain_item["location_list"]
                        
                        server_result["data"][current_domain] = {
                            "service_conf": "",
                            "location_dir": "",
                            "location_files": []
                        }
                        logger.info(f"开始生成域名【{current_domain}】的配置文件")
                        
                        # ========== 生成service.conf文件 ==========
                        service_template_path = os.path.join(TEMPLATE_DIR, "gateway_service.conf")
                        with open(service_template_path, "r", encoding="utf-8") as f:
                            service_content = f.read()
                        service_content = service_content.replace("Domain_Name", current_domain)
                        local_service_file = os.path.join(LOCAL_TEMP_DIR, f"{current_domain}.conf")
                        with open(local_service_file, "w", encoding="utf-8") as f:
                            f.write(service_content)
                        remote_service_file = os.path.join(server["remote_service_dir"], f"{current_domain}.conf")
                        sftp.put(local_service_file, remote_service_file)
                        os.remove(local_service_file)
                        server_result["data"][current_domain]["service_conf"] = remote_service_file
                        logger.info(f"成功上传service文件：{remote_service_file}")
                        
                        # ========== 生成location.conf文件 ==========
                        # 远端location目录
                        remote_location_dir = os.path.join(server["remote_location_root"], current_domain)
                        # 用SFTP方式确保目录存在（立即生效，无时序问题）
                        ensure_remote_dir_exists(sftp, remote_location_dir)
                        server_result["data"][current_domain]["location_dir"] = remote_location_dir
                        
                        # 按集群名分组location
                        cluster_loc_map = {}
                        for loc in location_list:
                            cluster_name = loc["cluster_name"]
                            if cluster_name not in cluster_loc_map:
                                cluster_loc_map[cluster_name] = []
                            cluster_loc_map[cluster_name].append(loc)
                        
                        # 遍历每个集群生成带序号的location文件
                        for cluster_name, locs in cluster_loc_map.items():
                            for idx, loc in enumerate(locs, 1):
                                # 读取模板并替换变量
                                location_template_path = os.path.join(TEMPLATE_DIR, "gateway_location.conf")
                                with open(location_template_path, "r", encoding="utf-8") as f:
                                    location_content = f.read()
                                
                                location_content = location_content.replace("ReqId", "stable")
                                location_content = location_content.replace("Env_Name", domain_type)
                                location_content = location_content.replace("ModuleName", loc["module_name"])
                                
                                # ========== 非/路径改为正则匹配（location ~） ==========
                                loc_path = loc["location_path"]
                                if loc_path != "/":
                                    # 替换为正则匹配形式：location ~ 路径 {
                                    # 注意：正则中的/无需转义，常规路径直接拼接即可
                                    location_content = re.sub(
                                        r"location / {", 
                                        f"location ~ {loc_path} {{",  # 关键：添加~符号，改为正则匹配
                                        location_content
                                    )
                                    logger.info(f"【{current_domain}】的location【{loc_path}】设置正则匹配形式：location ~ {loc_path} {{")
                                # 路径为/时，保留原普通匹配形式
                                else:
                                    logger.info(f"【{current_domain}】的location【{loc_path}】保留普通匹配形式：location / {{")
                                
                                # ========== rewrite规则插入到access_by_lua_file上方 ==========
                                rewrite_rule = loc["rewrite_rule"]
                                is_rewrite_valid = is_valid_rewrite_rule(rewrite_rule)
                                if is_rewrite_valid:
                                    clean_rule = rewrite_rule.strip()
                                    rewrite_line = f"    rewrite {clean_rule} break;\n"
                                    # 找到access_by_lua_file的位置，在其上方插入rewrite
                                    lua_file_pos = location_content.find("    access_by_lua_file")
                                    if lua_file_pos != -1:
                                        location_content = location_content[:lua_file_pos] + rewrite_line + location_content[lua_file_pos:]
                                        logger.info(f"【{current_domain}】的location【{loc['location_path']}】添加rewrite规则到access_by_lua_file上方：{clean_rule}")
                                        
                                        # ========== 仅当有有效rewrite时，替换proxy_pass ==========
                                        location_content = re.sub(
                                            r"proxy_pass https://\$proxy_domain\$request_uri;",
                                            "proxy_pass https://$proxy_domain$uri?$args;",
                                            location_content
                                        )
                                        logger.info(f"【{current_domain}】的location【{loc['location_path']}】更新proxy_pass为：proxy_pass https://$proxy_domain$uri?$args;")
                                    else:
                                        # 若模板中无access_by_lua_file，仍插入到proxy_pass上方
                                        proxy_pass_pos = location_content.find("    proxy_pass")
                                        if proxy_pass_pos != -1:
                                            location_content = location_content[:proxy_pass_pos] + rewrite_line + location_content[proxy_pass_pos:]
                                            logger.warning(f"模板中未找到access_by_lua_file，为【{current_domain}】的location【{loc['location_path']}】添加rewrite规则到proxy_pass上方：{clean_rule}")
                                            
                                            # ==========仅当有有效rewrite时，替换proxy_pass ==========
                                            location_content = re.sub(
                                                r"proxy_pass https://\$proxy_domain\$request_uri;",
                                                "proxy_pass https://$proxy_domain$uri?$args;",
                                                location_content
                                            )
                                            logger.info(f"【{current_domain}】的location【{loc['location_path']}】更新proxy_pass为：proxy_pass https://$proxy_domain$uri?$args;")
                                else:
                                    logger.info(f"【{current_domain}】的location【{loc['location_path']}】rewrite规则无效（值：{rewrite_rule}），保留原始proxy_pass格式")
                                
                                # 生成文件并上传
                                loc_filename = f"{cluster_name}-{idx:02d}.location.conf"
                                local_loc_file = os.path.join(LOCAL_TEMP_DIR, loc_filename)
                                with open(local_loc_file, "w", encoding="utf-8") as f:
                                    f.write(location_content)
                                
                                # 远端文件路径
                                remote_loc_file = os.path.join(remote_location_dir, loc_filename)
                                # 上传文件（添加异常捕获，确保上传失败能记录日志）
                                try:
                                    sftp.put(local_loc_file, remote_loc_file)
                                    logger.info(f"成功上传location文件：{remote_loc_file}")
                                except Exception as upload_err:
                                    logger.error(f"上传location文件【{remote_loc_file}】失败：{str(upload_err)}")
                                    raise upload_err  # 抛出异常，让外层捕获
                                
                                # 删除本地临时文件
                                os.remove(local_loc_file)
                                
                                # 记录文件信息
                                server_result["data"][current_domain]["location_files"].append({
                                    "filename": loc_filename,
                                    "remote_path": remote_loc_file,
                                    "location_path": loc["location_path"],
                                    "rewrite_rule": rewrite_rule,
                                    "is_rewrite_valid": is_rewrite_valid,
                                    "location_match_type": "regex" if loc_path != "/" else "normal",  # 标记匹配类型
                                    "proxy_pass_format": "https://$proxy_domain$uri?$args;" if is_rewrite_valid else "https://$proxy_domain$request_uri;"  # 新增：标记proxy_pass格式
                                })
                    
                    # ========== 重载Nginx配置 ==========
                    logger.info(f"执行Nginx重载命令：{server['nginx_reload_cmd']}")
                    stdin, stdout, stderr = ssh.exec_command(server["nginx_reload_cmd"])
                    reload_stderr = stderr.read().decode().strip()
                    if reload_stderr:
                        server_result["msg"] = f"Nginx重载警告：{reload_stderr}"
                        logger.warning(f"服务器【{server['host']}】Nginx重载警告：{reload_stderr}")
                    
                    # 关闭连接
                    sftp.close()
                    ssh.close()
                    logger.info(f"完成远端服务器【{server['host']}】的配置生成和上传")
                
                except Exception as e:
                    server_result["status"] = "failed"
                    server_result["msg"] = str(e)
                    logger.error(f"处理远端服务器【{server['host']}】失败：{str(e)}", exc_info=True)
                
                upload_results.append(server_result)
            
            # 返回结果
            logger.info(f"配置生成请求处理完成，线下网关域名：{domain_name}")
            return Response({
                "code": 200,
                "msg": "配置生成并上传完成",
                "data": {
                    "offline_domain": domain_name,
                    "mirror_domains": [m["mirror_domain"] for m in mirror_gateway_list],
                    "upload_results": upload_results
                }
            }, status=status.HTTP_200_OK)
        
        except pymysql.MySQLError as e:
            logger.error(f"数据库操作失败：{str(e)}", exc_info=True)
            return Response({
                "code": 500,
                "msg": f"数据库操作失败：{str(e)}",
                "data": None
            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
        
        except Exception as e:
            logger.error(f"配置生成失败：{str(e)}", exc_info=True)
            return Response({
                "code": 500,
                "msg": f"配置生成失败：{str(e)}",
                "data": None
            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)

#nohup python3 manage.py runserver 0.0.0.0:8000 &

博文来自：www.51niux.com

1.3 调用下接口检查创建的文件

# curl -X POST http://127.0.0.1:8000/gateway/generate-config/ -H "Content-Type: application/json" -d '{"domain_name": "zhongtai.test.com"}'

# curl -X POST http://127.0.0.1:8000/gateway/generate-config/ -H "Content-Type: application/json" -d '{"domain_name": "houtai.test.com"}'

#可以去网关域名服务器查看一下conf.d下面是不是已经创建了线下和沙箱域名,然后location下面的域名下面是不是location文件也有了,然后要注意的是我的location文件都是集群名-01.location.conf,集群名-02.location.conf依次类推的形式,并且location /对应的集群必须是集群名-01.location.conf的命名形式,为啥要多加一个01/02依次累加呢,因为了兼顾一个集群可能会存在于多个location下面。

#然后你可以访问网关域名查看一下不同的location路径是不是到了指定集群下面,包括rewrite配置,可以看一个产生的location文件

# cat /opt/soft/nginx/conf.d/location/houtai.test.com/集群名-02.location.conf

location ~ /api/token/ {
    # ===== 固定配置（直接写死）=====
    set $demand_number "stable";  # 初始化默认值
    set $trace_tag "stable";
    set $client_ip "";  # 核心：初始化自定义变量client_ip
    set $proxy_env "offline";               # 环境（固定：offline/mirror）
    set $stable_domain "模块名-offline-stable.test.com";  # stable后端域名（固定）
    set $module_name "模块名";  # 模块名（固定）
    set $cache_expire 60;   

    # 执行核心业务逻辑（Lua会写入专属日志）
    rewrite /api/(.*) /api/auth/$1 break;
    access_by_lua_file /opt/soft/nginx/conf.d/lua/ip_demand_query.lua;

    # 域名拼接（直接使用Nginx固定变量）
    if ($demand_number = "stable") {
        set $proxy_domain $stable_domain;
    }
    if ($demand_number != "stable") {
        set $proxy_domain "$module_name-$proxy_env-$trace_tag.test.com";
    }

    # 代理转发
    proxy_pass https://$proxy_domain$uri?$args;

    proxy_set_header Host $proxy_domain;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_next_upstream http_502  error timeout invalid_header;
    proxy_set_header X-Forwarded-Proto  $scheme;

    # 基础代理配置
    proxy_connect_timeout 5s;
    proxy_send_timeout 5s;
    proxy_read_timeout 5s;
}

#这里注意一下$request_uri和$uri的区别：

$request_uri:原始请求的完整路径 + 参数（不含锚点 #），只读、永不改变
$uri:Nginx 内部处理后的路径部分（无参数）

我们以https://houtai.test.com/api/token/dasdsada?a=123&b=456 请求举例:

$request_uri: 从网关nginx到后端nginx接收到的请求都是GET /api/token/dasdsada?a=123&b=456 #rewrite并没有生效参数也传递了

$uri: 网关是/api/token/dasdsada?a=123&b=456 后端Nginx是/api/auth/token/dasdsada #可以看到rewrite生效但是参数无法传递

$uri?$args：网关是/api/token/dasdsada?a=123&b=456 后端nginx是/api/auth/token/dasdsada?a=123&b=456 #可以看到rewrite生效参数也传递了

1.4 测试一下trace_tag是否实现了透传

#我们采用一个简单的方式,直接修改nginx的日志格式：

# ===== 自定义日志格式（包含常用Header + 核心变量）=====
    log_format custom_format '$remote_addr [$time_local] "$request" '
                            '$status $body_bytes_sent "$http_referer" '
                            '"$http_user_agent" "$http_x_real_ip" "$http_x_forwarded_for" '  # 客户端IP相关Header
                            '"$http_host"  "$http_trace_tag" '   # 自定义业务Header（按需改）
                            '$request_uri $uri $args';     # 路径/参数变量（排查rewrite用）

#然后让我们测试的网关域名和后端nginx域名都引用这个日志格式,然后开始浏览器访问请求看日志输出：
#https://houtai.test.com/api/auth/token/dasdsada?a=123&b=456 #有rewrite的域名

# tail -f /opt/log/nginx/houtai.test.com/houtai.test.com_access.log

"houtai.test.com"  "35184" /api/token/dasdsada?a=123&b=456 /api/auth/token/dasdsada a=123&b=456

# tail -f /opt/log/nginx/http-develop-offline-stable.test.com/http-develop-offline-stable.test.com_access.log #估计没创建35184的需求后端让其走稳定

"http-develop-offline-stable.test.com"  "35184" /api/auth/token/dasdsada?a=123&b=456 /api/auth/token/dasdsada a=123&b=456

#从上面可以看到trace_tag这个自定义变量是往后透传的,虽然请求的是stable域名,但是trace_tag还是需求号,这样交给后端集群后还是tag染色的

#https://houtai.test.com/api/service/dadsada #再来一个没有rewrite的域名

# tail -f /opt/log/nginx/houtai.test.com/houtai.test.com_access.log

"houtai.test.com"  "35184" /api/service/dadsada /api/service/dadsada -

# tail -f /opt/log/nginx/http-develop-offline-stable.test.com/http-develop-offline-stable.test.com_access.log

"http-develop-offline-stable.test.com"  "35184" /api/service/dadsada /api/service/dadsada -

#重点说一下,可以看到trace_tag已经可以传递下去了,其实也可以再优化一下,比如你的需求环境和稳定环境有所区分,需求环境的location会赋值一个trace_tag的默认值,lua脚本做个判断如果是稳定环境再往header里面写trace_tag,如果是需求环境就直接用自己配置文件中固定好的trace_tag,这样能保证不会因为程序错误导致trace_tag赋值错了,因为既然都到需求环境的域名了,这trace_tag肯定就是需求号了。

#好了到此,我们按需环境从网关流量入口到后端域名创建以及与容器相关联就介绍完毕了,当然这只是一个大体的流程,细节点还需要自己完善,怎么跟平台结合使用还需要结合实际场景来,比如需求环境销毁后如何及时的清理consul和nginx中的无效配置文件。

测试环境按需动态加载(二)

Wed, 31 Dec 2025 14:39:54 +0800

#紧接上文:www.51niux.com/?id=326 前面以及介绍了pod生命周期在consul中的操作,nginx后端跟consul的关联以及相关的表创建,下面进入到第二部分流量侧操作

一、初始化集群域名的创建

#前面我们已经首先介绍了集群pod在nginx的配置文件中如何存在可以让域名通过consul获取到pod的信息进而调用到pod集群的http接口。

1.1 创建模版文件

# ls /opt/web/pod_consul/template

location.conf  location_upstream_demand.conf  location_upstream_stable.conf  service.conf

# cat /opt/web/pod_consul/template/service.conf

include /opt/soft/nginx/conf.d/location/Domain_Name/*.location_upstream.conf;

server {
    listen 80;
    listen 443 ssl;
    server_name Domain_Name;
    
    # 强制HTTPS时开启
    if ($scheme != "https") {
        return 301 https://$host$request_uri;
    }
  
    ssl_certificate      certification/test.com.pem;
    ssl_certificate_key  certification/test.com.key;
    ssl_session_cache shared:SSL:10m; ## size suggest: 10m,50m
    ssl_session_timeout  1d; # time suggest: 10m,1d
    ssl_prefer_server_ciphers on;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS';
    
    include /opt/soft/nginx/conf.d/cors;
    server_tokens off;
    charset utf-8;

    include /opt/soft/nginx/conf.d/location/Domain_Name/*.location.conf;

    access_log /opt/log/nginx/Domain_Name/Domain_Name_access.log main;
    error_log /opt/log/nginx/Domain_Name/Domain_Name_error.log error;

}

# cat /opt/web/pod_consul/template/location.conf

location / {
    proxy_next_upstream http_502  error timeout invalid_header;
    proxy_pass http://Domain_Name_pool;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto  $scheme;
}

# cat /opt/web/pod_consul/template/location_upstream_demand.conf

upstream Domain_Name_pool {
  server 127.0.0.1:11111 down;
  upsync 192.168.1.101:8500/v1/kv/upstreams/Env_Name/demand/Req_Id/Cluster_Name upsync_timeout=5s upsync_interval=500ms upsync_type=consul strong_dependency=off;
  upsync_dump_path /data/nginxconf/upstream/Cluster_Name-Env_Name-Req_Id.conf;
  include /data/nginxconf/upstream/Cluster_Name-Env_Name-Req_Id.conf;
}

# cat /opt/web/pod_consul/template/location_upstream_stable.conf #稳定环境和需求环境kv路径不一样所以upstream模版是两个不同文件

upstream Domain_Name_pool {
  server 127.0.0.1:11111 down;
  upsync 192.168.1.101:8500/v1/kv/upstreams/Env_Name/stable/Cluster_Name upsync_timeout=5s upsync_interval=500ms upsync_type=consul strong_dependency=off;
  upsync_dump_path /data/nginxconf/upstream/Cluster_Name-Env_Name-Req_Id.conf;
  include /data/nginxconf/upstream/Cluster_Name-Env_Name-Req_Id.conf;
}

#好了模版文件创建完了,下一步就可以写程序,根据接口传参然后把修改好后的文件发送到对端nginx机器了

#cat /opt/soft/nginx/conf.d/cors #在目标nginx机器上面创建的允许跨域访问的文件

    ##跨域配置
    set $cors_origin "";
    set $cors_cred   "";
    set $cors_header "";
    set $cors_method "";
    if ($http_origin ~* 'https?://([^/]*\.test\.com|[^/]*\.test\.cn)$'){
            set $cors_origin $http_origin;
            set $cors_cred   true;
            set $cors_header $http_access_control_request_headers;
            set $cors_method $http_access_control_request_method;
    }
    
    add_header Access-Control-Allow-Origin      $cors_origin;
    add_header Access-Control-Allow-Credentials $cors_cred;
    add_header Access-Control-Allow-Headers     $cors_header;
    add_header Access-Control-Allow-Methods     $cors_method;
    add_header Access-Control-Max-Age           86400;
    if ($request_method = 'OPTIONS') {
        return 204;
    }

1.2 编写接口程序

#调用接口创建域名那步操作就不介绍了,你可以自建dns服务也可以调用公共dns服务接口进行域名维护,或者除网关外的内网域名全部更新网关机器的hosts文件,只有公网域名才会去公网dns服务创建,这都看各自的需求了

#下面程序的大概意思就是,当你发布页面进行集群初始化的时候,会触发nginx模版文件的创建

# cat /opt/web/pod_consul/nginx_conf_app/views.py

# -*- coding: utf-8 -*-
import os
import shutil
import paramiko
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from rest_framework.exceptions import ValidationError

# ==================== 本地配置（务必修改） ====================
TEMPLATE_DIR = "/opt/web/pod_consul/template"  # 模板文件目录（service/location等）
LOCAL_TEMP_DIR = "/opt/web/temp"   # 本地临时生成目录

# ==================== 远端服务器配置（务必修改） ====================
REMOTE_NGINX_SERVERS = [
    {
        "name": "nginx-server-1",
        "host": "192.168.1.102",       # 远端IP
        "port": 22,
        "username": "root",            # SSH用户名
        "key_filename": "~/.ssh/id_rsa",# 本地私钥路径
        # 远端Nginx目录（绝对路径）
        "remote_service_dir": "/opt/soft/nginx/conf.d",
        "remote_location_root": "/opt/soft/nginx/conf.d/location",
        "remote_upstream_dir": "/data/nginxconf/upstream",
        "nginx_reload_cmd": "/opt/soft/nginx/sbin/nginx -s reload"
    }
]

# 允许的环境值
ALLOWED_CLUSTER_ENV = {"offline", "mirror"}
ALLOWED_DEMAND_ENV = {"demand", "stable"}

def replace_file_content(file_path, replace_map):
    """替换文件内容"""
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()
        for old, new in replace_map.items():
            content = content.replace(old, new)
        with open(file_path, 'w', encoding='utf-8') as f:
            f.write(content)
        return True, "替换成功"
    except Exception as e:
        return False, f"替换失败: {str(e)}"

def exec_ssh_command(ssh_client, command):
    """执行SSH命令并返回结果"""
    try:
        stdin, stdout, stderr = ssh_client.exec_command(command, timeout=10)
        exit_code = stdout.channel.recv_exit_status()
        return {
            "success": exit_code == 0,
            "stdout": stdout.read().decode('utf-8').strip(),
            "stderr": stderr.read().decode('utf-8').strip(),
            "exit_code": exit_code
        }
    except Exception as e:
        return {
            "success": False,
            "stdout": "",
            "stderr": f"命令执行异常: {str(e)}",
            "exit_code": -1
        }

class GenerateNginxConfView(APIView):
    def post(self, request):
        # 1. 参数校验
        params = ["module_name", "cluster_name", "cluster_env", "demand_env", "req_id"]
        data = {k: request.data.get(k) for k in params}
        if not all(data.values()):
            return Response({
                "code": 400,
                "msg": f"缺少参数: {[k for k, v in data.items() if not v]}"
            }, status=400)
        
        if data["cluster_env"] not in ALLOWED_CLUSTER_ENV or data["demand_env"] not in ALLOWED_DEMAND_ENV:
            return Response({
                "code": 400,
                "msg": f"cluster_env只能是{ALLOWED_CLUSTER_ENV}，demand_env只能是{ALLOWED_DEMAND_ENV}"
            }, status=400)
            
        # 2. 基础变量
        domain = f"{data['module_name']}-{data['cluster_env']}-{data['req_id']}.test.com"
        upstream_file = f"{data['cluster_name']}-{data['cluster_env']}-{data['req_id']}.conf"
        result = {
            "code": 200,
            "msg": "操作成功",
            "data": {
                "domain": domain,
                "servers": []
            }
        }
        
        # 3. 本地生成配置文件
        try:
            # 创建本地临时目录
            os.makedirs(LOCAL_TEMP_DIR, exist_ok=True)
            local_files = {}

            # 3.1 生成service.conf
            service_local = os.path.join(LOCAL_TEMP_DIR, f"{domain}.conf")
            shutil.copy(os.path.join(TEMPLATE_DIR, "service.conf"), service_local)
            replace_file_content(service_local, {"Domain_Name": domain})
            local_files["service"] = service_local

            # 3.2 生成location.conf
            location_dir = os.path.join(LOCAL_TEMP_DIR, domain)
            os.makedirs(location_dir, exist_ok=True)
            location_local = os.path.join(location_dir, f"{domain}.location.conf")
            shutil.copy(os.path.join(TEMPLATE_DIR, "location.conf"), location_local)
            replace_file_content(location_local, {"Domain_Name": domain})
            local_files["location"] = location_local

            # 3.3 生成location_upstream.conf
            upstream_local = os.path.join(location_dir, f"{domain}.location_upstream.conf")
            shutil.copy(os.path.join(TEMPLATE_DIR, f"location_upstream_{data['demand_env']}.conf"), upstream_local)
            replace_file_content(upstream_local, {
                "Domain_Name": domain,
                "Env_Name": data["cluster_env"],
                "Req_Id": data["req_id"],
                "Cluster_Name": data["cluster_name"]
            })
            local_files["upstream_conf"] = upstream_local

        except Exception as e:
            return Response({
                "code": 500,
                "msg": f"本地生成文件失败: {str(e)}"
            }, status=500)

        # 4. 处理远端服务器
        for server in REMOTE_NGINX_SERVERS:
            server_log = []
            server_success = True
            ssh_client = None

            try:
                # 4.1 建立SSH连接
                ssh_client = paramiko.SSHClient()
                ssh_client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
                ssh_client.connect(
                    hostname=server["host"],
                    port=server["port"],
                    username=server["username"],
                    key_filename=os.path.expanduser(server["key_filename"]),
                    timeout=15
                )
                server_log.append(f"SSH连接成功: {server['host']}")

                # 4.2 创建远端目录（核心修复：用SSH命令创建，确保目录存在）
                # 创建service目录（一般已存在，兜底）
                cmd = f"mkdir -p {server['remote_service_dir']}"
                res = exec_ssh_command(ssh_client, cmd)
                if not res["success"]:
                    raise Exception(f"创建service目录失败: {res['stderr']}")
                
                # 创建location域名目录（关键！之前失败的核心）
                remote_location_dir = os.path.join(server["remote_location_root"], domain)
                cmd = f"mkdir -p {remote_location_dir}"
                res = exec_ssh_command(ssh_client, cmd)
                if not res["success"]:
                    raise Exception(f"创建location目录失败: {res['stderr']}")
                server_log.append(f"创建远端目录: {remote_location_dir}")

                # 创建upstream目录
                cmd = f"mkdir -p {server['remote_upstream_dir']}"
                res = exec_ssh_command(ssh_client, cmd)
                if not res["success"]:
                    raise Exception(f"创建upstream目录失败: {res['stderr']}")

                # 4.3 上传文件（SFTP，目录已确保存在）
                sftp = ssh_client.open_sftp()

                # 上传service.conf
                remote_service = os.path.join(server["remote_service_dir"], f"{domain}.conf")
                sftp.put(local_files["service"], remote_service)
                server_log.append(f"上传service.conf: {remote_service}")

                # 上传location.conf（核心修复：指定正确的远端路径）
                remote_location = os.path.join(remote_location_dir, f"{domain}.location.conf")
                sftp.put(local_files["location"], remote_location)
                server_log.append(f"上传location.conf: {remote_location}")

                # 上传location_upstream.conf
                remote_upstream_conf = os.path.join(remote_location_dir, f"{domain}.location_upstream.conf")
                sftp.put(local_files["upstream_conf"], remote_upstream_conf)
                server_log.append(f"上传location_upstream.conf: {remote_upstream_conf}")
                sftp.close()

                # 4.4 创建upstream空文件
                cmd = f"touch {os.path.join(server['remote_upstream_dir'], upstream_file)}"
                res = exec_ssh_command(ssh_client, cmd)
                if not res["success"]:
                    raise Exception(f"创建upstream空文件失败: {res['stderr']}")
                server_log.append(f"创建upstream空文件: {os.path.join(server['remote_upstream_dir'], upstream_file)}")

                # 4.5 重启Nginx
                cmd = server["nginx_reload_cmd"]
                res = exec_ssh_command(ssh_client, cmd)
                if not res["success"]:
                    server_log.append(f"Nginx重启警告: {res['stderr']}")
                else:
                    server_log.append("Nginx重启成功")

            except Exception as e:
                server_success = False
                server_log.append(f"执行失败: {str(e)}")
                result["code"] = 500
                result["msg"] = "部分服务器执行失败"
            finally:
                if ssh_client:
                    ssh_client.close()
                    server_log.append("SSH连接关闭")

            # 记录单服务器结果
            result["data"]["servers"].append({
                "name": server["name"],
                "host": server["host"],
                "success": server_success,
                "log": server_log
            })

        return Response(result, status=result["code"])

1.3 调用接口创建配置文件

# curl -X POST http://localhost:8000/nginx_conf_app/api/generate_nginx_conf/ -H "Content-Type: application/json" -d '{

"module_name": "模块名",

"cluster_name": "集群名",

"cluster_env": "offline",

"demand_env": "stable",

"req_id": "stable"

# curl -X POST http://localhost:8000/nginx_conf_app/api/generate_nginx_conf/ -H "Content-Type: application/json" -d '{

"module_name": "模块名",

"cluster_name": "集群名",

"cluster_env": "offline",

"demand_env": "demand",

"req_id": "35184"

#这样就会创建server.conf域名文件,location文件以及upstream文件,并且在nginx -s reload的时候还会创建本地缓存文件,可以自行配置域名浏览器访问看是否到了后端对应的pod服务,这里不就截图测试结果了。

#通过上面的程序我们在发布页面测试环境初始化阶段就将集群以及对应的域名和nginx配置好了,这些域名呢都是默认location / 逻辑很简单就是将集群通过域名映射出去了而已,如果是多location的域名怎么办呢？-那就靠网关域名来进行转发了(现在一般网站都在搞前后端分离,大部分后端域名都是location /对应的一个集群,然后具体的入口控制在了前端域名那里),当然肯定还有一些后端域名存在多location的情况,这就通过网关进行路由了,毕竟搞了按需这种方式就是重度依赖网关域名的转发。

博文来自：www.51niux.com

二、网关域名的操作

2.1.网关域名数据插入

#接着上章节的表数据,我们先插入一些新的数据用于测试

MariaDB [route]> insert into offline_gateway (domain_name,network_type,applicant) values ('houtai.test.com','intranet','guliu');
MariaDB [route]> insert into offline_location (offline_gateway_id,module_name,cluster_name,location_path,rewrite_rule,applicant) values (4,'模块名','集群名','/','NULL','guliu');
MariaDB [route]> insert into offline_location (offline_gateway_id,module_name,cluster_name,location_path,rewrite_rule,applicant) values (4,'模块名','集群名','/api/(path|service)/','NULL','guliu');
MariaDB [route]> insert into offline_location (offline_gateway_id,module_name,cluster_name,location_path,rewrite_rule,applicant) values (4,'模块名','集群名','/api/token/','/api/(.*) /api/auth/$1','guliu');
MariaDB [route]> insert into mirror_gateway (domain_name,offline_gateway_id,network_type,applicant) values ('houtai-mirror.test.com',4,'intranet','guliu');
MariaDB [route]> insert into on_demand (source_ip,demand_number,user) values ('192.168.1.135',35184,'test01');

#这样我们创建了一个新的测试网关,也让集群跟网关域名的location关联上了,也让沙箱网关域名跟测试域名网关关联上了,关联的意义就是获取location与集群的对应信息

2.2 编写网关调用的lua脚本

# vi /opt/soft/nginx/main-conf/nginx.conf #这里创建一个需求号缓存就是避免频繁的访问mysql(访问mysql获取的结果缓存1分钟)

lua_package_path "/opt/soft/package/lua-resty-redis-0.29/lib/?.lua;/usr/local/lua_core/lib/lua/?.lua;;";
# 仅保留IP-reqid缓存字典（1分钟过期）
lua_shared_dict ip_reqid_cache 100m;

#mkdir /opt/soft/nginx/conf.d/lua/logs/

# vi /opt/soft/nginx/conf.d/lua/ip_demand_query.lua

-- 1. 初始化IP-reqid缓存
local ip_reqid_cache = ngx.shared.ip_reqid_cache

-- 2. Lua专属日志文件配置（单独写入，不混Nginx日志）
local lua_log_path = "/opt/soft/nginx/conf.d/lua/logs/gateway_proxy.log"
-- 日志格式化函数（带时间、级别、内容）
local function lua_log(level, content)
    local time_str = os.date("%Y-%m-%d %H:%M:%S")
    local log_str = string.format("[%s] [%s] %s\n", time_str, level, content)
    -- 追加写入日志文件（权限需确保nginx用户可写）
    local f, err = io.open(lua_log_path, "a")
    if f then
        f:write(log_str)
        f:close()
    else
        -- 兜底：写入Nginx错误日志
        ngx.log(ngx.ERR, "Lua日志写入失败：", err, " 内容：", log_str)
    end
end

-- 补全string.trim函数（Lua原生无trim，解决reqid带空格问题）
if not string.trim then
    function string.trim(s)
        return (s:gsub("^%s+", ""):gsub("%s+$", ""))
    end
end

-- 3. 从Nginx配置中获取固定变量（用于拼接转发域名和日志）
local gateway_domain = ngx.var.server_name        -- 网关域名（Nginx的server_name）
local proxy_env = ngx.var.proxy_env              -- 环境变量（offline/mirror）
local stable_domain = ngx.var.stable_domain      -- stable兜底域名
local module_name = ngx.var.module_name          -- 模块名
local request_uri = ngx.var.request_uri          -- 转发的location（请求路径）

-- 4. 初始化Nginx变量（供转发/头信息使用）
ngx.var.client_ip = ""
ngx.var.trace_tag = ""
ngx.var.demand_number = "stable"

-- 5. MySQL配置（保持原有配置）
local mysql_config = {
    host = "192.168.1.101",
    port = 3306,
    database = "route",
    user = "route",
    password = "route123456",
    timeout = 1000,
    pool_size = 100,
    pool_idle_time = 10000
}

-- 6. 防SQL注入函数（转义IP中的特殊字符）
local function escape_sql_str(str)
    if not str then
        return "''"
    end
    -- 转义单引号（SQL注入核心风险点）
    str = string.gsub(str, "'", "''")
    -- 仅保留IP合法字符（数字+点），进一步防护
    str = string.gsub(str, "[^0-9%.]", "")
    return "'" .. str .. "'"
end

-- 7. 工具函数：获取客户端真实IP
local function get_client_ip()
    local x_real_ip = ngx.req.get_headers()["X-Real-IP"]
    local x_forwarded_for = ngx.req.get_headers()["X-Forwarded-For"]
    if x_forwarded_for then
        local ip_list = string.gmatch(x_forwarded_for, "([^,]+)")
        x_forwarded_for = ip_list() and string.trim(ip_list()) or nil
    end
    local client_ip = x_real_ip or x_forwarded_for or ngx.var.remote_addr
    ngx.var.client_ip = client_ip
    -- 记录网关域名、客户端IP、请求路径
    lua_log("INFO", "基础信息 | 网关域名：" .. gateway_domain .. " | 客户端IP：" .. client_ip .. " | 转发Location：" .. request_uri)
    return client_ip
end

-- 8. 工具函数：reqid合法性校验（长度+逐字符判断，避开正则兼容问题）
local function validate_reqid(reqid)
    -- 第一步：先trim去空格
    local trimmed_reqid = string.trim(reqid or "")
    lua_log("INFO", "reqid校验 | 原始reqid：[" .. tostring(reqid) .. "] | 去空格后：[" .. trimmed_reqid .. "]")
    
    -- 第二步：空值判断
    if trimmed_reqid == "" then
        lua_log("WARN", "reqid校验 | reqid为空，强制转为stable")
        return "stable"
    end

    -- 第三步：校验规则（长度=5 + 逐字符判断是否为数字，替代正则）
    local is_stable = (trimmed_reqid == "stable")
    local is_5digit = false

    -- 判断是否是5位长度 + 每个字符都是数字（0-9）
    if string.len(trimmed_reqid) == 5 then
        local all_digit = true
        for i = 1, 5 do
            local c = string.sub(trimmed_reqid, i, i)
            if not (c >= "0" and c <= "9") then
                all_digit = false
                break
            end
        end
        is_5digit = all_digit
        -- 调试日志：打印逐字符校验结果
        lua_log("DEBUG", "reqid校验 | 5位长度：" .. tostring(string.len(trimmed_reqid)==5) .. " | 全数字：" .. tostring(all_digit))
    end

    if is_stable or is_5digit then
        lua_log("INFO", "reqid校验 | reqid合法：" .. trimmed_reqid)
        return trimmed_reqid
    else
        lua_log("WARN", "reqid校验 | reqid非法(" .. trimmed_reqid .. ")，强制转为stable（规则：仅支持5位纯数字或stable）")
        return "stable"
    end
end

-- 9. 工具函数：查询MySQL获取原始reqid
local function query_db_reqid(client_ip)
    lua_log("INFO", "DB查询 | 缓存未命中，查询MySQL：IP=" .. client_ip)
    local db, err = require("resty.mysql"):new()
    if not db then
        local err_msg = "DB错误 | 创建MySQL连接失败：" .. (err or "未知错误")
        lua_log("ERROR", err_msg)
        return nil
    end

    db:set_timeout(mysql_config.timeout)

    -- 连接数据库
    local ok, err, errno = db:connect({
        host = mysql_config.host,
        port = mysql_config.port,
        database = mysql_config.database,
        user = mysql_config.user,
        password = mysql_config.password
    })

    if not ok then
        local err_msg = "DB错误 | 连接MySQL失败：" .. (err or "未知错误") .. " errno=" .. (errno or "nil")
        lua_log("ERROR", err_msg)
        return nil
    end

    -- 替换?占位符，手动拼接SQL并做防注入处理
    local escaped_ip = escape_sql_str(client_ip)
    local sql = string.format("SELECT demand_number FROM on_demand WHERE source_ip = %s LIMIT 1", escaped_ip)
    lua_log("INFO", "DB查询 | 执行SQL：" .. sql)

    local res, err = db:query(sql)

    -- 放回连接池
    local ok, err_pool = db:set_keepalive(mysql_config.pool_idle_time, mysql_config.pool_size)
    if not ok then
        lua_log("WARN", "DB警告 | MySQL连接放回池失败：" .. (err_pool or "未知错误"))
    end

    -- 处理结果
    if err then
        local err_msg = "DB错误 | 查询MySQL失败：" .. (err or "未知错误")
        lua_log("ERROR", err_msg)
        return nil
    end

    local db_reqid = nil
    if res and #res > 0 then
        db_reqid = res[1].demand_number
        lua_log("INFO", "DB结果 | IP=" .. client_ip .. " reqid=" .. tostring(db_reqid))
    else
        lua_log("INFO", "DB结果 | MySQL未查到IP(" .. client_ip .. ")的reqid")
    end
    return db_reqid
end

-- 10. DNS解析校验函数（判断域名是否可解析）
local function is_domain_resolvable(domain, timeout)
    -- 默认超时时间100ms，避免阻塞请求
    local dns_timeout = timeout or 100
    -- 使用ngx.socket.tcp进行DNS解析（纯Nginx+Lua环境兼容）
    local sock = ngx.socket.tcp()
    sock:settimeout(dns_timeout)
    -- 尝试连接域名的80端口（仅检测解析，不实际建立连接）
    local ok, err = sock:connect(domain, 80)
    if ok then
        sock:close()
        return true
    else
        -- 常见解析失败错误：host not found、timeout
        lua_log("WARN", "DNS解析 | 域名[" .. domain .. "]不可访问：" .. err)
        sock:close()
        return false
    end
end

-- 11. 工具函数：计算最终转发域名（DNS校验+兜底逻辑）
local function get_final_proxy_domain(final_reqid)
    local target_domain
    -- 拼接目标域名
    if final_reqid == "stable" then
        target_domain = stable_domain
        lua_log("INFO", "转发域名 | 直接使用stable兜底域名：" .. target_domain)
        ngx.var.proxy_domain = target_domain
        return target_domain
    else
        target_domain = module_name .. "-" .. proxy_env .. "-" .. final_reqid .. ".test.com"
        lua_log("INFO", "转发域名 | 拼接目标域名：" .. target_domain)
    end

    -- 校验目标域名是否可解析，不可解析则切换到stable
    if is_domain_resolvable(target_domain) then
        lua_log("INFO", "转发域名 | 域名[" .. target_domain .. "]可解析，正常转发")
        ngx.var.proxy_domain = target_domain
        return target_domain
    else
        lua_log("WARN", "转发域名 | 域名[" .. target_domain .. "]不可解析，切换到stable兜底域名")
        ngx.var.proxy_domain = stable_domain
        return stable_domain
    end
end

-- 12. 主逻辑：缓存查询 + DB兜底（仅60秒缓存）
local function get_reqid()
    local client_ip = get_client_ip()
    local cache_expire = tonumber(ngx.var.cache_expire) or 60

    -- 先查缓存
    local reqid = ip_reqid_cache:get(client_ip)
    if reqid then
        lua_log("INFO", "缓存命中 | IP=" .. client_ip .. " reqid=" .. reqid)
        return validate_reqid(reqid)
    end

    -- 缓存未命中：查DB
    local db_reqid = query_db_reqid(client_ip)
    -- 无论是否查到，都缓存60秒（避免频繁查库）
    local cache_val = db_reqid or "NULL"
    local ok, err = ip_reqid_cache:set(client_ip, cache_val, cache_expire)
    if not ok then
        lua_log("ERROR", "缓存错误 | 缓存设置失败：IP=" .. client_ip .. " 错误=" .. (err or "未知错误"))
    else
        lua_log("INFO", "缓存设置 | IP=" .. client_ip .. " 值=" .. cache_val .. " 过期时间=" .. cache_expire .. "秒")
    end

    -- 校验并返回
    return validate_reqid(db_reqid or "stable")
end

-- 13. 主执行逻辑
local function main()
    lua_log("INFO", "===== 新请求开始 =====")
    local final_reqid = get_reqid()
    ngx.var.trace_tag = final_reqid
    ngx.var.demand_number = final_reqid

    -- 计算并记录最终转发域名（含DNS校验+兜底）
    local final_proxy_domain = get_final_proxy_domain(final_reqid)

    -- 设置Trace-Tag请求头（非空才设）
    if final_reqid ~= "" then
        ngx.req.set_header("Trace-Tag", final_reqid)
        lua_log("INFO", "请求头 | 设置Trace-Tag：" .. final_reqid)
    end

    -- 全链路信息汇总日志
    lua_log("INFO", "请求完成 | 网关域名：" .. gateway_domain .. 
        " | 客户端IP：" .. ngx.var.client_ip .. 
        " | 转发Location：" .. request_uri .. 
        " | 最终trace_tag：" .. final_reqid .. 
        " | 最终转发域名：" .. final_proxy_domain)
    lua_log("INFO", "===== 请求结束 =====\n")
end

-- 执行主逻辑（捕获异常，写入Lua日志）
local ok, err = pcall(main)
if not ok then
    lua_log("FATAL", "Lua执行异常：" .. err)
    -- 异常时强制使用stable
    ngx.var.trace_tag = "stable"
    ngx.var.demand_number = "stable"
    ngx.var.proxy_domain = stable_domain
    -- 异常时也记录基础信息，方便排查
    lua_log("ERROR", "异常兜底 | 网关域名：" .. gateway_domain .. " | 客户端IP：" .. ngx.var.client_ip .. " | 强制使用stable转发")
end

博文来自：www.51niux.com

#vi /opt/soft/nginx/conf.d/lua/clear_ip_cache.lua #这个脚本的作用就是把ip对应的需求号从缓存中清理掉方便及时重新获取

-- 1. 初始化缓存和响应参数
local ip_reqid_cache = ngx.shared.ip_reqid_cache
local resp_code = 200
local resp_msg = "操作成功"
local resp_ip = ""
local resp_old_val = "NULL"

-- 2. Lua专属日志文件配置
local lua_log_path = "/opt/soft/nginx/conf.d/lua/logs/lua_cache_api.log"
local function lua_log(level, content)
    local time_str = os.date("%Y-%m-%d %H:%M:%S")
    local log_str = string.format("[%s] [%s] %s\n", time_str, level, content)
    local f, err = io.open(lua_log_path, "a")
    if f then
        f:write(log_str)
        f:close()
    else
        ngx.log(ngx.ERR, "Lua接口日志写入失败：", err, " 内容：", log_str)
    end
end

-- 3. 解析POST参数（获取要清理的IP）
local function get_post_ip()
    ngx.req.read_body()
    local post_data = ngx.req.get_post_args()
    local target_ip = post_data.ip or post_data.target_ip or ""
    lua_log("INFO", "接收清理请求：参数IP=" .. target_ip)

    -- 简单IP格式校验
    local is_valid_ip = string.match(target_ip, "^%d+%.%d+%.%d+%.%d+$")
    if not is_valid_ip or target_ip == "" then
        local err_msg = "参数错误：IP格式非法或为空（接收值：" .. target_ip .. "）"
        lua_log("WARN", err_msg)
        resp_code = 400
        resp_msg = err_msg
        return nil
    end

    resp_ip = target_ip
    lua_log("INFO", "IP格式校验通过：" .. target_ip)
    return target_ip
end

-- 4. 清理缓存核心逻辑
local function clear_cache(target_ip)
    if not target_ip then
        return false
    end

    -- 查询原缓存值
    local old_val = ip_reqid_cache:get(target_ip)
    resp_old_val = old_val or "NULL" 
    lua_log("INFO", "清理前缓存值：IP=" .. target_ip .. " 值=" .. resp_old_val)

    -- 删除缓存
    local ok, err = ip_reqid_cache:delete(target_ip)
    if not ok then
        local err_msg = "缓存清理失败：IP=" .. target_ip .. " 错误=" .. (err or "未知错误")
        lua_log("ERROR", err_msg)
        resp_code = 500
        resp_msg = err_msg
        return false
    end

    -- 记录操作日志
    local success_msg = "缓存清理成功：IP=" .. target_ip .. " 原缓存值=" .. resp_old_val
    lua_log("INFO", success_msg)
    return true
end

-- 5. 纯Lua拼接JSON字符串（核心：无cjson依赖）
local function build_json()
    local json_str = string.format(
        '{"code":%d,"msg":"%s","data":{"ip":"%s","old_cache_value":"%s"}}',
        resp_code,
        ngx.escape_uri(resp_msg):gsub("%%22", "\\\""),  -- 转义双引号
        resp_ip,
        resp_old_val
    )
    -- 还原URI编码，仅保留JSON需要的转义
    json_str = ngx.unescape_uri(json_str)
    return json_str
end

-- 6. 主执行逻辑（捕获异常）
local function main()
    lua_log("INFO", "===== 缓存清理接口请求开始 =====")
    local target_ip = get_post_ip()
    clear_cache(target_ip)

    -- 构建并返回JSON响应（纯Lua拼接）
    local res_json = build_json()
    ngx.header["Content-Type"] = "application/json"
    ngx.say(res_json)
    
    lua_log("INFO", "接口响应：" .. res_json)
    lua_log("INFO", "===== 缓存清理接口请求结束 =====\n")
end

-- 执行并捕获异常
local ok, err = pcall(main)
if not ok then
    local err_msg = "接口执行异常：" .. err
    lua_log("FATAL", err_msg)
    -- 异常时返回错误JSON
    local err_json = string.format('{"code":500,"msg":"%s","data":{}}', err_msg)
    ngx.header["Content-Type"] = "application/json"
    ngx.say(err_json)
end

# vim /opt/soft/nginx/conf.d/cache-api.test.com.conf #配置上后nginx reload一下

server {
    listen 80;
    server_name cache-api.test.com;  # 接口专属域名

    location /clear_ip_cache {
        # IP白名单（仅内网可访问）
        allow 127.0.0.1;
        allow 192.168.1.0/24;
        deny all;

        # 仅允许POST请求
        if ($request_method != POST) {
            return 405 "Method Not Allowed";
        }

        # 执行缓存清理逻辑（Lua写入专属日志）
        content_by_lua_file /opt/soft/nginx/conf.d/lua/clear_ip_cache.lua;
        add_header Content-Type application/json;
    }

    access_log /opt/log/nginx/cache-api.test.com/cache-api.test.com_access.log main;
    error_log /opt/log/nginx/cache-api.test.com/cache-api.test.com_error.log error;
}

# curl -X POST "http://cache-api.test.com/clear_ip_cache" -d "ip=192.168.1.101" #可以清理测试一下,看下接口是否正常

{"code":200,"msg":"操作成功","data":{"ip":"192.168.1.101","old_cache_value":"NULL"}}

# yum install dnsmasq -y

# vim /etc/dnsmasq.conf

listen-address=127.0.0.1

# systemctl start dnsmasq #Nginx的resolver不支持直接读取/etc/hosts，必须通过DNS服务中转

# vi /opt/soft/nginx/conf.d/zhongtai.test.com.conf

server {
    listen 80;
    listen 443 ssl;
    server_name zhongtai.test.com;
    #ssl配置引用上面的nginx的配置这里就不粘贴占用篇幅了

    server_tokens off;
    charset utf-8;

    #指定dnsmasq的地址127.0.0.1，优先解析hosts里的域名,valid=10s是域名解析缓存时间，避免频繁解析，可根据需要调整（如60或者300s）；
    #这个valid有一点是注意的,这是nginx缓存域名的时间,不管是正确还是错误的缓存,都要等缓存过期后重新解析,如果你域名变更不频繁可以调大缓存时间
    resolver 127.0.0.1:53 valid=10s ipv6=off;
    #默认等待时间,如果只依赖于本地hosts解析可以设置成如500ms,如果是本地hosts+dns服务这里可以设置的大一点,nginx有缓存也不会频繁的域名解析
    resolver_timeout 5s;

    include /opt/soft/nginx/conf.d/location/zhongtai.test.com/*.location.conf;

    access_log /opt/log/nginx/zhongtai.test.com/zhongtai.test.com_access.log main;
    error_log /opt/log/nginx/zhongtai.test.com/zhongtai.test.com_error.log error;
}

博文来自：www.51niux.com

# vi /opt/soft/nginx/conf.d/location/zhongtai.test.com/zhongtai.test.com.location.conf #配置好后nginx reload一下

location / {
    # ===== 固定配置（直接写死）=====
    set $demand_number "stable";  # 初始化默认值
    set $trace_tag "stable";
    set $client_ip "";  # 核心：初始化自定义变量client_ip
    set $proxy_env "offline";               # 环境（固定：offline/mirror）
    set $stable_domain "模块名-offline-stable.test.com";  # stable后端域名（固定）
    set $module_name "模块名";  # 模块名（固定）
    set $cache_expire 60;   

    # 执行核心业务逻辑（Lua会写入专属日志）
    access_by_lua_file /opt/soft/nginx/conf.d/lua/ip_demand_query.lua;

    # 域名拼接（直接使用Nginx固定变量）
    if ($demand_number = "stable") {
        set $proxy_domain $stable_domain;
    }
    if ($demand_number != "stable") {
        set $proxy_domain "$module_name-$proxy_env-$trace_tag";
    }

    # 代理转发
    proxy_pass https://$proxy_domain$request_uri;

    # ===== Trace-Tag传递：仅非空时设置 =====
    proxy_set_header Host $proxy_domain;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_next_upstream http_502  error timeout invalid_header;
    proxy_set_header X-Forwarded-Proto  $scheme;

    # 基础代理配置
    proxy_connect_timeout 5s;
    proxy_send_timeout 5s;
    proxy_read_timeout 5s;
}

#然后就可以浏览器访问zhongtai.test.com做测试了,主要测试三种场景:
1. ip指向的需求有对应的模块域名(比如正好是我们要测试的变更模块)
2. ip指向的需求没有对应的模块域名(比如请求域名不是我们变更的模块自然就不会再需求里面了,会不会走到stable环境)

3. 来源IP压根就不存在于任何需求中或者绑定了stable环境,请求是否走到stable的域名

可以观察对应域名的访问日志来观测路由请求是否符合需求。

# tail -f /opt/soft/nginx/conf.d/lua/logs/gateway_proxy.log #比如网关完整的路由记录便于排查问题

[INFO] ===== 新请求开始 =====
[INFO] 基础信息 | 网关域名：zhongtai.test.com | 客户端IP：192.168.1.135 | 转发Location：/dasdsadsa/dadasdas/
[INFO] DB查询 | 缓存未命中，查询MySQL：IP=192.168.1.135
[INFO] DB查询 | 执行SQL：SELECT demand_number FROM on_demand WHERE source_ip = 192.168.1.135' LIMIT 1
[INFO] DB结果 | IP=192.168.1.135 reqid=35184
[INFO] 缓存设置 | IP=192.168.1.135 值=35184 过期时间=60秒
[INFO] reqid校验 | 原始reqid：[35184] | 去空格后：[35184]
[DEBUG] reqid校验 | 5位长度：true | 全数字：true
[INFO] reqid校验 | reqid合法：35184
[INFO] 转发域名 | 最终转发到：http_develop-offline-35184.test.com 
[INFO] 请求头 | 设置Trace-Tag：35184
[INFO] 请求完成 | 网关域名：zhongtai.test.com  | 客户端IP：192.168.1.135 | 转发Location：/dasdsadsa/dadasdas/ | 最终trace_tag：35184 | 转发域名：http_develop-offline-35184.test.com 
[INFO] ===== 请求结束 =====

SeaTunnel搭建部署

Mon, 01 Dec 2025 17:36:01 +0800

SeaTunnel原名Waterdrop(水滴),2021年10月更名为SeaTunnel,2021年12月9日加入Apache孵化,2023年6月1日毕业成为Apache顶级项目。

SeaTunnel是一个非常易用、超高性能的分布式数据集成平台,支持实时海量数据同步。

具体介绍请看官网文档：https://seatunnel.apache.org/zh-CN/docs/2.3.12/about

一、SeaTunnel-2.3.12部署

1.1 二进制包环境部署

安装Java (Java 8 或 11，其他高于Java 8的版本理论上也可以工作) 以及设置 JAVA_HOME。

安装二进制包

官网下载地址：https://seatunnel.apache.org/download/

#export version="2.3.12" #通过终端下载一下

#wget "https://archive.apache.org/dist/seatunnel/${version}/apache-seatunnel-${version}-bin.tar.gz"

#tar -xzvf "apache-seatunnel-${version}-bin.tar.gz"

下载连接器插件

#从2.2.0-beta版本开始，二进制包不再默认提供连接器依赖，因此在第一次使用时，需要执行以下命令来安装连接器：(当然，也可以从Apache Maven Repository 手动下载连接器:https://repo.maven.apache.org/maven2/org/apache/seatunnel/，然后将其移动至connectors/目录下，如果是2.3.5之前则需要放入connectors/seatunnel目录下)。

# sh bin/install-plugin.sh 2.3.12 #下载指定版本的连接器,然后就开始疯狂报错了

#通常情况下，你不需要所有的连接器插件。你可以通过配置config/plugin_config来指定所需的插件,

可以在${SEATUNNEL_HOME}/connectors/plugins-mapping.properties下找到所有支持的连接器和相应的plugin_config配置名称。

#下面我通过maven的方式解决上面的下载连接器报错,当然可能稍微麻烦一点,安装maven这步不再介绍

# vim ~/.m2/settings.xml

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <mirrors>
    <!-- 阿里云公共仓库 -->
    <mirror>
      <id>aliyunmaven</id>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>
      <mirrorOf>*</mirrorOf> <!-- 所有请求都走阿里云仓库 -->
    </mirror>
  </mirrors>
</settings>

# vim /opt/soft/apache-seatunnel-2.3.12/bin/install-plugin.sh #改成使用mvn

#${SEATUNNEL_HOME}/mvnw dependency:get -Dtransitive=false -DgroupId=org.apache.seatunnel -DartifactId=${line} -Dversion=${version} -Ddest=${SEATUNNEL_HOME}/connectors
mvn dependency:get -Dtransitive=false -DgroupId=org.apache.seatunnel -DartifactId=${line} -Dversion=${version} -Ddest=${SEATUNNEL_HOME}/connectors

# sh bin/install-plugin.sh 2.3.12 #然后再次下载连接器

#上图表示下载连接器成功

# rsync -avz ~/.m2/repository/org/apache/seatunnel/ /opt/soft/apache-seatunnel-2.3.12/connectors/ >/dev/null #手工将这些连接器移到指定目录

验证一下从mysql查询数据

#确认连接器connector-jdbc、connector-doris在${SEATUNNEL_HOME}/connectors/目录下即可

#需要去https://repo1.maven.org/maven2/mysql/mysql-connector-java/下载jdbc driver jar package 驱动，并放置在 ${SEATUNNEL_HOME}/lib/目录下

# cd /opt/soft/apache-seatunnel-2.3.12/lib/

# wget https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.30/mysql-connector-java-8.0.30.jar

# cd /opt/soft/apache-seatunnel-2.3.12

# mkdir job

#基本配置结构：https://seatunnel.apache.org/zh-CN/docs/2.3.12/concept/config/

# vim /opt/soft/apache-seatunnel-2.3.12/job/st.conf

env {
  parallelism = 2
  job.mode = "BATCH"
}

source {
  #SeaTunnel插件名称区分大小写，必须严格写为Jdbc(首字母大写)，如果写成小写jdbc或全大写JDBC，也会导致插件找不到
  Jdbc {
    url = "jdbc:mysql://192.168.1.110:3306/seatunnel?useSSL=false&serverTimezone=UTC"
    driver = "com.mysql.cj.jdbc.Driver"
    connection_check_timeout_sec = 100
    username = "seatunnel"
    password = "seatunnel"
    # 保持在 MySQL 中拼接的逻辑
    query = "SELECT CONCAT('id=',id,', type=',type,', role_name=',role_name,', description=',description,', create_time=',create_time,', update_time=',update_time) AS readable_output FROM seatunnel.role"
    fetch_size = 1000
    schema {
      fields {
        readable_output = "VARCHAR"
      }
    }
    # 添加 table 配置，统一 tableId 为简短名称
    table = "role"
  }
}

sink {
  Console {
    print-header = false
    encoding = "UTF-8"
    fields = ["readable_output"]
    # 2.3.12 版本特有的简化输出配置
    format = "simple"
  }
}

# cd /opt/soft/apache-seatunnel-2.3.12

# ./bin/seatunnel.sh --config ./job/st.conf -m local #跑一下我们的读取mysql的任务,输出下面的报错信息

ERROR [o.a.s.c.s.SeaTunnel           ] [main] - Exception StackTrace:org.apache.seatunnel.core.starter.exception.CommandExecuteException: SeaTunnel job executed failed
	at org.apache.seatunnel.core.starter.seatunnel.command.ClientExecuteCommand.execute(ClientExecuteCommand.java:228)
	at org.apache.seatunnel.core.starter.SeaTunnel.run(SeaTunnel.java:40)
	at org.apache.seatunnel.core.starter.seatunnel.SeaTunnelClient.main(SeaTunnelClient.java:40)
Caused by: org.apache.seatunnel.api.table.factory.FactoryException: ErrorCode:[API-06], ErrorDescription:[Factory initialize failed] - Unable to create a source for identifier 'Jdbc'.

#哎呀竟然报错了,啥原因我们解决一下

#SeaTunnel 作业配置中使用了 Jdbc 作为数据源（source），但当前 SeaTunnel 环境中没有安装或配置 Jdbc 源插件
#SeaTunnel 2.x+版本的插件默认存放路径：$SEATUNNEL_HOME/plugins，检查是否存在 source 目录下的seatunnel-source-jdbc文件夹

#mkdir /opt/soft/apache-seatunnel-2.3.12/plugins/source && cd /opt/soft/apache-seatunnel-2.3.12/plugins/source

#wget https://repo1.maven.org/maven2/org/apache/seatunnel/connector-jdbc/2.3.12/connector-jdbc-2.3.12.jar

# cd /opt/soft/apache-seatunnel-2.3.12

# ./bin/seatunnel.sh --config ./job/st.conf -m local #再次执行读取mysql打印到屏幕的任务,从输出结果可以看到读取了2行输出了2行

......
INFO  [.a.s.c.s.c.s.ConsoleSinkWriter] [st-multi-table-sink-writer-1] - subtaskIndex=0  rowIndex=1:  SeaTunnelRow#tableId=default.default.default SeaTunnelRow#kind=INSERT : id=1, type=0, role_name=ADMIN_ROLE, description=Admin User
INFO  [.a.s.c.s.c.s.ConsoleSinkWriter] [st-multi-table-sink-writer-1] - subtaskIndex=0  rowIndex=2:  SeaTunnelRow#tableId=default.default.default SeaTunnelRow#kind=INSERT : id=2, type=1, role_name=NORMAL_ROLE, description=Normal User
......
Job Statistic Information
***********************************************
......
Total Time(s)             :                   3
Total Read Count          :                   2
Total Write Count         :                   2
Total Failed Count        :                   0
***********************************************

#可以看到输出了两行内容,但是还有元数据信息并非标准输出,这是因为在2.3.12版本中，Console Sink无法完全去除元数据前缀，但通过配置优化可以简化它；核心的 “字段名 = 值" 数据已经正确输出，这部分是有效的；若需要完全干净的输出，可以将结果输出到文件再查看。

1.2 源码包安装

# mvn -version #首先mvn先安装一下

Apache Maven 3.9.11

# vim ~/.m2/settings.xml #增加华为镜像源,不然会有编译报错,因为有两个包是华为云maven仓库专属

<settings>
    <mirrors>
        <!-- 保留阿里云镜像 -->
        <mirror>
            <id>aliyunmaven</id>
            <mirrorOf>central</mirrorOf>
            <url>https://maven.aliyun.com/repository/public</url>
        </mirror>
        <!-- 添加华为云镜像 -->
        <mirror>
            <id>huaweicloud-maven</id>
            <mirrorOf>huaweicloud</mirrorOf>
            <url>https://repo.huaweicloud.com/repository/maven/</url>
        </mirror>
    </mirrors>
    <profiles>
        <profile>
            <id>huaweicloud</id>
            <repositories>
                <repository>
                    <id>huaweicloud-maven</id>
                    <url>https://repo.huaweicloud.com/repository/maven/</url>
                    <releases><enabled>true</enabled></releases>
                    <snapshots><enabled>false</enabled></snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>huaweicloud</activeProfile>
    </activeProfiles>
</settings>

# wget https://dlcdn.apache.org/seatunnel/2.3.12/apache-seatunnel-2.3.12-src.tar.gz

# tar xf apache-seatunnel-2.3.12-src.tar.gz

# cd apache-seatunnel-2.3.12-src

# mvn clean install -DskipTests -Dskip.spotless=true

#上面那个阿里云源的配置记得配置上啊，如果一开始执行就报错的话可以执行mvn spotless:apply修复一下

#到上面这个界面就表示编译成功了

# cp seatunnel-dist/target/apache-seatunnel-2.3.12-bin.tar.gz /opt/soft/

# cd /opt/soft

# tar xf apache-seatunnel-2.3.12-bin.tar.gz

# cd apache-seatunnel-2.3.12 #源码构建所有的连接器插件和一些必要的依赖都包含在二进制包中。可以直接使用连接器插件，而无需单独安装它们。

# 可以用我们上面的mysql驱动器的测试命令测试一下,没有任何报错

# sh bin/seatunnel-cluster.sh start --daemon #后台启动下服务

博文来自：www.51niux.com

二、apache-seatunnel-web部署

2.1 mysql5.7安装

#apache-seatunnel-web需要mysql5.7+,这里也记录一下编译过程吧

#cd /opt/soft

# wget https://github.com/Kitware/CMake/releases/download/v3.31.10/cmake-3.31.10.tar.gz

# tar xf cmake-3.31.10.tar.gz

# cd cmake-3.31.10

# ./bootstrap

# gmake && gmake install

# /usr/local/bin/cmake -version

cmake version 3.31.10

# cd /opt/soft

# wget https://archives.boost.io/release/1.59.0/source/boost_1_59_0.tar.gz

# tar xf boost_1_59_0.tar.gz

# wget https://dev.mysql.com/get/Downloads/MySQL-5.7/mysql-5.7.44.tar.gz

# tar xf mysql-5.7.44.tar.gz

# cd mysql-5.7.44

# /usr/local/bin/cmake -DCMAKE_INSTALL_PREFIX=/opt/soft/mysql -DMYSQL_DATADIR=/opt/soft/mysql/data -DSYSCONFDIR=/etc -DWITH_INNOBASE_STORAGE_ENGINE=1 -DWITH_PARTITION_STORAGE_ENGINE=1 -DWITH_FEDERATED_STORAGE_ENGINE=1 -DWITH_BLACKHOLE_STORAGE_ENGINE=1 -DWITH_MYISAM_STORAGE_ENGINE=1 -DENABLED_LOCAL_INFILE=1 -DENABLE_DTRACE=0 -DDEFAULT_CHARSET=utf8mb4 -DDEFAULT_COLLATION=utf8mb4_general_ci -DWITH_EMBEDDED_SERVER=1 -DDOWNLOAD_BOOST=1 -DFORCE_INSOURCE_BUILD=1 -DWITHOUT_PARTITION_STORAGE_ENGINE=0 -DCMAKE_C_COMPILER=/usr/bin/gcc -DCMAKE_CXX_COMPILER=/usr/bin/g++ -DWITH_BOOST=/opt/soft/boost_1_59_0 -DDOWNLOAD_BOOST=0

# make -j 4

# make install

# useradd mysql -s /sbin/nologin -M

# cp support-files/mysql.server /etc/init.d/mysqld

# chmod +x /etc/init.d/mysqld

# mkdir /opt/soft/mysql/data

# chown mysql:mysql /opt/soft/mysql/data

# mkdir /opt/soft/mysql/log

# chown mysql:mysql /opt/soft/mysql/log

# /opt/soft/mysql/bin/mysqld --initialize --user=mysql --basedir=/opt/soft/mysql --datadir=/opt/soft/mysql/data

# vim /etc/my.cnf

[client]
port=3306
socket=/tmp/mysql.sock
default-character-set=utf8mb4
[mysqld]
server-id=1
log-bin=mysql-bin
binlog-format=ROW
#skip-grant-tables
port=3306
user=mysql
max_connections=200
socket=/tmp/mysql.sock
basedir=/opt/soft/mysql
datadir=/opt/soft/mysql/data
pid-file=/opt/soft/mysql/log/mysql.pid
character-set-client-handshake=FALSE
character-set-server=utf8mb4
collation-server=utf8mb4_bin
init_connect='SET NAMES utf8mb4'
default-storage-engine=INNODB
log_error=/opt/soft/mysql/log/mysql-error.log
slow_query_log_file=/opt/soft/mysql/log/mysql-slow.log
expire_logs_days=3
[mysqldump]
quick
max_allowed_packet=16M

#touch /opt/soft/mysql/log/mysql-error.log

#chown mysql:mysql /opt/soft/mysql/log/mysql-error.log

#/etc/init.d/mysqld start

2.2 二进制包安装

# wget https://dlcdn.apache.org/seatunnel/seatunnel-web/1.0.2/apache-seatunnel-web-1.0.2-bin.tar.gz

# tar xf apache-seatunnel-web-1.0.2-bin.tar.gz

# vim conf/application.yml

datasource下面的数据库信息修改成实际的.jwt下面的secretKey要填一个比如mysecretkeyforseatunnelweb2025111

# cp /opt/soft/apache-seatunnel-2.3.8/config/hazelcast-client.yaml /opt/soft/apache-seatunnel-web-1.0.2/conf/

# cp /opt/soft/apache-seatunnel-2.3.8/connectors/plugin-mapping.properties /opt/soft/apache-seatunnel-web-1.0.2/conf/

# vim script/seatunnel_server_env.sh #修改成实际的数据库信息

# sh /opt/soft/apache-seatunnel-web-1.0.2/script/init_sql.sh #进行数据库表的初始化,需要的mysql版本是5.7+

# cd /opt/soft/apache-seatunnel-web-1.0.2/libs/ && wget https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.30/mysql-connector-java-8.0.30.jar #不做这步操作的话启动日志会报数据库连接器报错:Caused by: java.lang.IllegalStateException: Cannot load driver class: com.mysql.cj.jdbc.Driver

# cd /opt/soft/apache-seatunnel-web-1.0.2

# vim bin/seatunnel-backend-daemon.sh #加一条环境变量,不然启动报错找不到seatunnel

set -
SEATUNNEL_HOME=/opt/soft/apache-seatunnel-2.3.8

# sh bin/seatunnel-backend-daemon.sh start

#we端口为8801,访问下web页面发现有一个报错

查看下报错日志,大概意思是少了datasource：

ERROR [tr:,sp:] [qtp546936087-21] [GlobalExceptionHandler.logError():78] - No supported data source found
org.apache.seatunnel.datasource.exception.DataSourceSDKException: No supported data source found
	at org.apache.seatunnel.datasource.AbstractDataSourceClient.<init>(AbstractDataSourceClient.java:107)
	at org.apache.seatunnel.datasource.DataSourceClient.<init>(DataSourceClient.java:26)
	at org.apache.seatunnel.app.thirdparty.datasource.DataSourceClientFactory.getDataSourceClient(DataSourceClientFactory.java:32)
	at org.apache.seatunnel.app.service.impl.DatasourceServiceImpl.queryAllDatasourcesGroupByType(DatasourceServiceImpl.java:478)
	at org.apache.seatunnel.app.controller.SeatunnelDatasourceController.getSupportDatasources(SeatunnelDatasourceController.java:302)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
......

又两种方法解决上面的报错：
第一种手工方式:
# mkdir datasource

# cd datasource

# https://repo.maven.apache.org/maven2/org/apache/seatunnel/ #去这里把对应版本的jar包手工下载下来

第二种方式就是用脚本：

# vim bin/download_datasource.sh #还是那个mvnw命令那个ssl证书报错我没有解决所以换成mvn的方式了

    #"$SEATUNNEL_WEB_HOME"/mvnw dependency:get -DgroupId=org.apache.seatunnel -DartifactId="$i" -Dversion="$version" -Ddest="$DATASOURCE_DIR" 
    mvn dependency:get -DgroupId=org.apache.seatunnel -DartifactId="$i" -Dversion="$version" -Ddest="$DATASOURCE_DIR"

# sh bin/download_datasource.sh 1.0.2 #搞不懂web-1.0.2脚本里面的version=1.0.0,要么修改脚本变量要么传参

# for num in `find ~/.m2/repository/org/apache/seatunnel/|grep datasource|grep '.jar$'|grep "1.0.2"`;do rsync -avz $num datasource/;done

做了上述操作后,我们重启下apache-seatunnel-web-1.0.2服务再来查看下页面：

#从上面的截图可以看到数据源页面不再报错了,当然也可以再查下日志没有异常报错了。

2.3 源码包安装

#如果有条件的话还是建议进行源码包安装,安装出来的插件都比较全,比二进制包各种报错然后花精力解决要好

#https://github.com/apache/seatunnel-web #git地址

#官网给出的版本对应表,保险期间还是用2.3.8吧,我看web的libs目录下面关于seatunnel的都是2.3.8的

#wget https://downloads.apache.org/seatunnel/seatunnel-web/1.0.2/apache-seatunnel-web-1.0.2-src.tar.gz

#tar xf apache-seatunnel-web-1.0.2-src.tar.gz

#cd apache-seatunnel-web-1.0.2-src

# vim build.sh

  #/bin/sh $WORKDIR/mvnw clean package -DskipTests -Pci
  mvn clean package -DskipTests -Pci

#mvn spotless:apply

# sh build.sh code #正常没有报错的话二进制包就打包了

# cp seatunnel-web-dist/target/apache-seatunnel-web-1.0.2.tar.gz /opt/soft/

# cd /opt/soft/

# tar xf apache-seatunnel-web-1.0.2.tar.gz

# vim conf/application.yml

datasource下面的数据库信息修改成实际的.jwt下面的secretKey要填一个比如mysecretkeyforseatunnelweb2025111

# cp /opt/soft/apache-seatunnel-2.3.8/config/hazelcast-client.yaml /opt/soft/apache-seatunnel-web-1.0.2/conf/

# cp /opt/soft/apache-seatunnel-2.3.8/connectors/plugin-mapping.properties /opt/soft/apache-seatunnel-web-1.0.2/conf/

# vim script/seatunnel_server_env.sh #修改成实际的数据库信息

# sh /opt/soft/apache-seatunnel-web-1.0.2/script/init_sql.sh #进行数据库表的初始化

# vim bin/seatunnel-backend-daemon.sh #加一条环境变量,不然启动报错找不到seatunnel

set -
SEATUNNEL_HOME=/opt/soft/apache-seatunnel-2.3.8

# sh bin/seatunnel-backend-daemon.sh start

博文来自：www.51niux.com

三、数据库表同步的一些简单示例

#现在基础环境搭建完毕了,现在让我们来一些简单的数据同步

3.1 命令行单表同步

#先来一个最简单的示例，从A库同步完整表到B库

# vim job/test.conf

# 定义运行时环境
env {
  parallelism = 4
  job.mode = "BATCH"
}
source{
    Jdbc {
        url = "jdbc:mysql://192.168.1.110:3306/seatunnel?serverTimezone=GMT%2b8&useUnicode=true&characterEncoding=UTF-8&rewriteBatchedStatements=true"
        driver = "com.mysql.cj.jdbc.Driver"
        connection_check_timeout_sec = 100
        username = "seatunnel"
        password = "seatunnel"
        query = "select * from role"
    }
}

transform {
    # 如果您想了解更多关于如何配置 SeaTunnel 的信息，并查看完整的转换插件列表，
    # 请访问 https://seatunnel.apache.org/docs/transform-v2/sql
}

sink {
    jdbc {
        url = "jdbc:mysql://192.168.1.111:3306/seatunnel_bak?useUnicode=true&characterEncoding=UTF-8&rewriteBatchedStatements=true"
        driver = "com.mysql.cj.jdbc.Driver"
        username = "seatunnel"
        password = "seatunnel"
        database = "seatunnel_bak" 
        table = "role"
        generate_sink_sql = true  #自动生成插入语句
        batch_insert = true  # 开启批量插入（提升性能）
        batch_size = 1000    # 批量大小（可选，默认500）
        }
    #如果你想了解更多关于如何配置seatunnel的信息，并查看完整的sink插件列表，
    #请前往https://seatunnel.apache.org/docs/connector-v2/sink
}

#特别注意目标数据库是要存在的,不然数据同步不过去会有报错提示：Caused by: java.sql.SQLSyntaxErrorException: Unknown database 'seatunnel_bak'

# ./bin/seatunnel.sh --config ./job/test.conf -m local

#从上图的数据库插入情况来看,也可以看出来我们只要库存在,表就能自动创建并自动插入数据

第一点:仅同步数据不同步表结构

好了,那么有一个问题,如果再执行一遍这个脚本会怎么样呢？

#从上图可以看出同样的数据重复insert插入了,明明源表id是主键啊,但是sink表没有这个主键的设置才会这样。Seatunnel JDBC Sink 的核心特性 ——Seatunnel 仅负责 “数据同步”，不负责 “表结构同步 / 创建”，包括主键、索引、字段类型、约束等表结构信息，都不会自动同步 / 创建，这是导致主键未同步的根本原因。就用推荐方法提前手工创建目标表。

#这时候你执行脚本第一遍可以,第二遍就会报错:

Caused by: java.sql.SQLIntegrityConstraintViolationException: Duplicate entry '1' for key 'PRIMARY'

#直接说结论不贴图片了,一旦设置了主键,只要主键冲突,后面的insert插入也就不会再执行,也就是说这种同步操作适用于新表的全量同步

第二点:绕过主键冲突报错,实现增删改效果

#vim job/test.conf #注意不仅是追加插入数据哦可自行测试效果

# 定义运行时环境
env {
  parallelism = 4
  job.mode = "BATCH"
}

source {
    Jdbc {
        url = "jdbc:mysql://192.168.1.110:3306/seatunnel?serverTimezone=GMT%2b8&useUnicode=true&characterEncoding=UTF-8&rewriteBatchedStatements=true"
        driver = "com.mysql.cj.jdbc.Driver"
        connection_check_timeout_sec = 100
        username = "seatunnel"
        password = "seatunnel"
        query = "select * from role"
    }
}

transform {
    # 无需转换
}

sink {
    jdbc {
        url = "jdbc:mysql://192.168.1.111:3306/seatunnel?useUnicode=true&characterEncoding=UTF-8&rewriteBatchedStatements=true"
        driver = "com.mysql.cj.jdbc.Driver"
        username = "seatunnel"
        password = "seatunnel"
        database = "seatunnel" 
        table = "role"
        
        # 核心：主键冲突时跳过，不报错
        skip_on_conflict = true
        # 指定主键字段（需与目标表主键一致）
        primary_keys = ["id"]
        
        # 保留批量插入提升性能
        generate_sink_sql = true
        batch_insert = true
        batch_size = 1000
        
        # 可选：开启错误重试（进一步避免偶发报错）
        max_retries = 3
    }
}

#剩下的多表,指定字段同步就不写示例了,网上一查就查到了

博文来自：www.51niux.com

四、Mysql CDC模式

#前面介绍的都是命令行模式,如果你不需要实时数据同步可以采用上面那种定时任务的方式,但是如果想要类似于主从数据同步那种方式就要用到CDC模式了

#MySQL CDC连接器允许从MySQL数据库读取快照数据和增量数据。

4.1 创建mysql用户

#在源库创建有指定权限的用户

mysql> CREATE USER 'source-cdc'@'%' IDENTIFIED BY 'source-cdc';
mysql> GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'source-cdc'@'%' IDENTIFIED BY 'source-cdc';
#SELECT是查询权限、RELOAD重载/刷新权限(允许执行FLUSH类命令如FLUSH PRIVILEGES、FLUSH BINARY LOGS，CDC 需刷新binlog元信息)
#SHOW DATABASES是查询数据库列表权限,REPLICATION SLAVE是复制从库权限(允许用户模拟MySQL从库，读取主库的binlog,CDC核心获取数据变更日志)
#REPLICATION CLIENT是复制客户端权限,允许执行SHOW MASTER STATUS/SHOW SLAVE STATUS，获取binlog位点(文件名+偏移量)，CDC 需定位同步起点。    
mysql> FLUSH PRIVILEGES;

4.2 启动mysql的binlog

mysql> show variables where variable_name in ('log_bin', 'binlog_format', 'binlog_row_image', 'gtid_mode', 'enforce_gtid_consistency');

+--------------------------+----------------+
| Variable_name            | Value          |
+--------------------------+----------------+
| binlog_format            | ROW            |
| binlog_row_image         | FULL           |
| enforce_gtid_consistency | ON             |
| gtid_mode                | ON             |
| log_bin                  | ON             |
+--------------------------+----------------+
5 rows in set (0.00 sec)

#如果与上述结果不一致，请使用以下属性配置MySQL服务器配置文件（$MYDateTimeHOME/MySQL.cnf），如下表所示：

server-id         = 223344
log_bin           = mysql-bin
expire_logs_days  = 10
binlog_format     = row
# mysql 5.6+ requires binlog_row_image to be set to FULL
binlog_row_image  = FULL

# enable gtid mode
# mysql 5.6+ requires gtid_mode to be set to ON
gtid_mode = on
enforce_gtid_consistency = on

#上面只是官方的实例,server-id没必要一致啊

# /etc/init.d/mysqld restart

4.3 记录下相关参数

#官方文档：https://seatunnel.apache.org/zh-CN/docs/2.3.12/connector-v2/source/MySQL-CDC

下载相关依赖包,不然会启动报错：

# ls plugins/*.jar #有下面三个jar包就行

plugins/connector-cdc-base-2.3.12.jar  plugins/connector-cdc-mysql-2.3.12.jar  plugins/connector-jdbc-2.3.12.jar

先来一个-m local方式的数据同步：

#vim job/cdc_test.conf

env {
  #本地模式仅支持单并行度
  parallelism = 1
  #流式同步模式（CDC必需）
  job.mode = "STREAMING"
  #检查点间隔
  checkpoint.interval = 10000
}

source {
  MySQL-CDC {
    url = "jdbc:mysql://192.168.1.110:3306/seatunnel?useSSL=false&allowPublicKeyRetrieval=true"
    #CDC同步账号（需有binlog读取权限）
    username = "source-cdc"
    password = "source-cdc"
    table-names = ["seatunnel.role"]
    #唯一server-id（避免与MySQL自身server-id冲突）
    server-id = 5401
    #启动模式：先全量同步，再增量同步
    startup.mode = "initial"
    #可选：指定binlog起始位置（避免找不到binlog，需替换为你的实际值）
    #先执行 show master status; 获取File和Position后填写
    startup.specific.offset.file = "mysql-bin.000001"
    startup.specific.offset.pos = 4
  }
}

sink {
  jdbc {
    url = "jdbc:mysql://192.168.1.111:3306/seatunnel?useSSL=false"
    driver = "com.mysql.cj.jdbc.Driver"
    username = "seatunnel"
    password = "seatunnel"
    #自动生成写入SQL
    generate_sink_sql = true
    database = "seatunnel"
    #目标表名
    table = "role"
    # 键字段（保障更新/删除同步）
    primary_keys = ["id"]
    #关闭XA事务（2.3.12本地模式XA有Bug）
    is_exactly_once = false
    #关闭批量写入（避免静默失败）
    batch_size = 1
    #开启调试日志，排查错误的时候使用
    #log.enabled = true
    #log.level = "DEBUG"
    #retry_times = 3
    #retry_interval = 1000
  }
}

# ./bin/seatunnel.sh --config job/cdc_test.conf -m local #这是一个常驻进程了就不是一次性的了,但是是前台启动,可以放到后台并将输入写入到一个日志文件

#如果目的库跟源库数据不一致,只在第一次启动的时候会把目标库的数据更新过来,这个进程常态的可以实现源库数据往目标库的插入和删除和update动作触发同步。

#注意这种方式用# bin/seatunnel.sh --list是查不到在运行任务的,只有使用集群模式才可以

再来2.3.12版本的cdc调用集群方式表同步：

#这就需要#bin/seatunnel-cluster.sh start --daemon 启动服务并确保5801端口是启动的

#vim job/cluster_cdc_job.conf

env {
  #集群并行度
  execution.parallelism = 2                
  job.mode = "STREAMING"
  checkpoint.interval = 10000
  #Engine集群配置
  seatunnel.engine.job.mode = "cluster"
  seatunnel.engine.server.address = "127.0.0.1:5801"
  seatunnel.engine.job.heartbeat.interval = 30000
  #自定义Job Name（支持中文/英文，建议包含业务+表名）
  job.name = "MySQL_CDC_同步_seatunnel_role表"
  #任务失败自动重启（避免变成CANCELED）
  seatunnel.engine.job.restart.count = 3
  seatunnel.engine.job.restart.interval = 5000
  #任务超时时间（避免长时间卡壳）
  seatunnel.engine.job.timeout = 3600000
}

source {
  MySQL-CDC {
    url = "jdbc:mysql://192.168.1.110:3306/seatunnel?useSSL=false&allowPublicKeyRetrieval=true"
    username = "source-cdc"
    password = "source-cdc"
    #数组格式表名（集群模式不支持单字符串）
    table-names = ["seatunnel.role"]
    #集群内唯一（避免与其他节点冲突）
    server-id = 5401
    #首次启动全量+后续增量同步                       
    startup.mode = "initial"               
    #集群模式优化：增大binlog读取缓存
    debezium.connector.properties.max.queue.size = 8192
    debezium.connector.properties.max.batch.size = 2048
  }
}

sink {
  jdbc {
    url = "jdbc:mysql://192.168.1.111:3306/seatunnel?useSSL=false"
    driver = "com.mysql.cj.jdbc.Driver"
    username = "seatunnel"
    password = "seatunnel"
    generate_sink_sql = true
    database = "seatunnel"
    table = "role"
    primary_keys = ["id"]
    #集群模式关闭XA（避免分布式事务问题）
    is_exactly_once = false
    #集群模式恢复批量（提升性能）                
    batch_size = 50
    #批量刷新间隔                        
    batch_flush_interval = 1000            
    #集群模式重试
    retry_times = 5
    retry_interval = 2000
    #全字段同步
    upsert_all_fields = true
    #连接池（集群模式避免连接耗尽）
    connection_pool {
      type = "hikari"
      hikaricp {
        maximum-pool-size = 10
        minimum-idle = 2
        connection-timeout = 30000
      }
    }
  }
}

# ./bin/seatunnel.sh --config job/cluster_cdc_job.conf -m cluster #使用集群模式启动服务,一样首次启动的时候会把目标库的数据更新到跟源库表一致

# bin/seatunnel.sh --list #查看再运行的

再来2.3.8版本的cdc调用集群方式表同步：

# vim job/cluster_cdc_job.conf

env {
  #并行度
  execution.parallelism = 2
  #流模式（CDC必须用STREAMING）
  job.mode = "STREAMING"
  #检查点间隔
  checkpoint.interval = 10000
  #集群模式相关
  seatunnel.engine.job.mode = "cluster"
  seatunnel.engine.server.address = "127.0.0.1:5801"
  seatunnel.engine.job.heartbeat.interval = 30000
  #任务名称
  job.name = "MySQL_CDC_同步_seatunnel_role表"
  #失败重启配置
  seatunnel.engine.job.restart.count = 3
  seatunnel.engine.job.restart.interval = 5000
  seatunnel.engine.job.timeout = 3600000
  #基础配置（避免类加载冲突）
  job.type = "STREAM"
  checkpoint.storage = "MEMORY"
}

source {
  MySQL-CDC {
    base-url = "jdbc:mysql://192.168.1.110:3306/seatunnel?serverTimezone=Asia/Shanghai&useSSL=false"
    username = "source-cdc"
    password = "source-cdc"
    database-name = "seatunnel"
    table-names = ["seatunnel.role"]
    #server-id必须唯一（避免和其他CDC任务冲突，建议范围5000-65535）
    server-id = 5401
    #启动模式：initial（全量+增量）、latest-offset（仅增量）
    startup.mode = "initial"
    #时区
    server-time-zone = "Asia/Shanghai"
    #binlog消费性能配置
    max.queue.size = 8192
    max.batch.size = 2048
    #批量读取超时
    poll.interval.ms = 1000
    
  }
}

sink {
  jdbc {
    url = "jdbc:mysql://192.168.1.111:3306/seatunnel"
    driver = "com.mysql.cj.jdbc.Driver"
    user = "seatunnel"
    password = "seatunnel"
    generate_sink_sql = true
    database = seatunnel
    table = role
    primary_keys = ["id"]
  }
}

# ./bin/seatunnel.sh --cluster seatunnel --config job/cluster_cdc_job.conf #注意--cluster seatunnel 就是对应hazelcast.yaml中的cluster-name

4.4 零星记录

取消任务：

#2.3.8的版本不行应该是有BUG不能取消掉停止的任务需要重启seatunnel集群清空内存中的任务才行

正常的操作来说(命令和api中没有直接delete的操作命令)：

history-job-expire-minutes: 1440 #配置文件里面有多久清理掉停止任务的参数,单位是分钟,想调小这个回收时间就把时间调小点
#然后你把任务手工停止或者,# bin/seatunnel.sh -can jobid 把任务变成CANCELED状态,然后到了时间seatunnel就会把任务回收掉了

重新恢复任务：

#2.3.8和2.3.12关于checkpoint的位置不一样,以2.3.12为例:/tmp/seatunnel/checkpoint_snapshot #如果任务正常启动的话,这里会有id号的目录

#如果你的任务非正常停掉了,你正常启动任务的话就是一个全新jobid就跟之前记录的内容关联不上了,你如果想还启原来的jobid跟之前的断点续传文件关联式：
#sh bin/seatunnel.sh --config job/cdc_test.conf -r 之前的jobid

启动任务：

#前面介绍启动作业的方式都是前台启动,这样你ps进程的话会看到除了sea以外还有其他进程,如果启动的作业太多就会有好多进程,这样显然不太好

# sh bin/seatunnel.sh --config job/cdc_test.conf --async #这个 --async 参数可以让作业在后台运行，当作业提交后，客户端会退出。这样ps进程的时候就只有seatunnel本身的集群服务进程了,就不会再有额外的作业进程了

指定作业名称：

# sh bin/seatunnel.sh --config job/cdc_test.conf --async -n myjob #-n 或 --name 参数可以指定作业的名称,配置文件里面定义了名称也会被这个名称覆盖

#官网中文文档讲的很清楚,详细的可参照官网文档,集群的模式啊监控啊之类的可以看官方文档: https://seatunnel.apache.org/zh-CN/docs/2.3.12/seatunnel-engine/about

测试环境按需动态加载(一)

Mon, 18 Aug 2025 17:43:12 +0800

总算到了最后一步了哈,前面又是consul又是lua的,就是为了实现本文要讲的内容

#紧接上文,我们consul的使用已经总结的差不多了,但是是不是感觉没有展现一个实际的场景来把consul结合起来使其作用更大化呢?
我下面描述一个具体的场景：一般我们会有一套稳定环境,但是会有N多套测试需求环境,而且这是一个动态变化的过程,这里我们需求用需求号代替,比如今天测试一个集群的功能创建了一个2001的需求,后天又创建了一个2002的需求,那么正常来说你访问网站是不是就变成了aaa-2001.xxx.com/aaa-2002.xxx.com,这就带来一个问题测试起来太繁琐了(每次测试你都要更换URL),现在很多都是app测试了,app更换域名还是挺麻烦的。还有一个问题现在很多都是微服务架构,就是你是不是要1比1的部署测试环境,不然你的测试流程很可能走不下去。
那么我们怎么解决上述问题呢,一方面让测试更便捷另一方面让成本更低,我们可以试想一下:先提供一个web平台用户可以选择自己要访问哪个环境,然后nginx+lua成为网关,一个固定域名基于来源来判断要访问哪个环境并路由,然后后端是nginx+consul将请求转发到执行的需求环境容器,然后需求号再作为tag一直透传下去,有对应的需求就将请求交给对应的需求容器,没有对应的需求容器就将请求交给稳定环境是不是就解决了我们上面提到的问题,好了大体思路有了我们去实现它。

一、容器在consul中的管理

1.1 容器在consul中存在结构？

#容器一般怎么命名呢,肯定是有一个固有的结构对吧,而且我们会把容器的一些信息写入到k8s的yaml文件中的label,比如下面：

spec:
  template:
    metadata:
      labels:
        app: 模块名-2001
        env_type: offline
        reqid: "2001"
        k8scluster: offline_k8s01
        clustername: 集群名
        modulename: 模块名

#这样我们在consul中去创建kv的原始信息就有了,那么我们是扁平的创建还是目录层级的创建呢？

下面看一下完整的示例：

# curl http://127.0.0.1:8500/v1/kv/upstreams/?keys #可以看到如果采用目录层级的形式的话会比较直观,层层目录递进最后直到最后ip:端口形成的key

[
    "upstreams/",
    "upstreams/dianshang_http_develop-mirror-stable/",
    "upstreams/dianshang_http_develop-mirror-stable/192.168.1.187:30660",
    "upstreams/dianshang_tcp_develop-mirror-stable/",
    "upstreams/dianshang_tcp_develop-mirror-stable/192.168.1.252:30660",
    "upstreams/mirror/",
    "upstreams/mirror/stable/",
    "upstreams/offline/",
    "upstreams/offline/demand/",
    "upstreams/offline/demand/22384/",
    "upstreams/offline/demand/22384/dianshang_http_develop/",
    "upstreams/offline/demand/22384/dianshang_http_develop/192.168.1.187:30660",
    "upstreams/offline/demand/22384/dianshang_tcp_develop/",
    "upstreams/offline/demand/22384/dianshang_tcp_develop/192.168.1.252:30660",
    "upstreams/offline/demand/25568/dianshang_http_develop/192.168.1.187:3066",
    "upstreams/offline/stable/",
    "upstreams/offline/stable/dianshang_http_develop/",
    "upstreams/offline/stable/dianshang_http_develop/192.168.1.187:30660",
    "upstreams/offline/stable/dianshang_tcp_develop/",
    "upstreams/offline/stable/dianshang_tcp_develop/192.168.1.252:30660"
]

#选择哪种影响都有限就在程序上面做判断就可以了,但是我倾向于第二种一方面比较直观另一方面删除需求的时候也比较方便,比如我现在要删除25568需求(需求已释放)

# curl --request DELETE http://127.0.0.1:8500/v1/kv/upstreams/offline/demand/25568 #执行此命令就行

# curl -X PUT -d '{"weight":1, "max_fails":2, "fail_timeout":10}' http://127.0.0.1:8500/v1/kv/upstreams/offline/demand/25568/dianshang_http_develop/192.168.1.187:3066 #这是一个创建需求kv的操作

#一般测试环境容器就起一个pod,这既节省成本管理起来也比较简单,理论上每个需求集群下面只应该有一个pod，pod发生启动关闭无非两个事件,一个就是重启,一个就是副本更新启动新的关闭旧的,所以一旦接收到这个需求集群的启动上报就直接PUT更新就可以了,更新的肯定是最新的podip。

1.2 容器重启/关闭发送信息

#仔细思考一下,如果只启动一个pod节点的话,我们还需要关闭事件吗,我们只需要delete/put这2个动作就行了,因为每个需求集群下面只有一个podip:端口存在(因为目录下面是追加而不是覆盖,所以添加新IP:端口的key前需要将目录下面清空)。

好了那么我们假设我们有一个web接口负责接收pod启动和关闭时候的上报,那么我们如何触发这个动作呢

第一种方法钩子触发：

在yaml文件中的spec:的containers:下面定义(我pod_name和pod_ip分别用了两种取值的方式哦)

env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        apiVersion: v1
        fieldPath: metadata.name
  - name: POD_IP
    valueFrom:
      fieldRef:
        fieldPath: status.podIP
  - name: PATH
    value: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/soft/java/bin"
lifecycle:
  postStart:
    exec:   
      command:
        - "/bin/sh"
        - "-c"  
        - 'curl -i -X POST -H "Content-type:application/json" -d "{\"clustername\":\"dianshang_http_develop\",\"modulename\":\"http-develop\",\"env_type\":\"offline\",\"reqid\":\"25568\",\
"pod_name\":\"`hostname`\",\"pod_ip\":\"$POD_IP\",\"port\":\"30553\"}" http://lua.test.com/docker/report/start/'
  preStop:
    exec:   
      command:
        - "/bin/sh"
        - "-c"  
        - 'curl -i -X POST -H "Content-type:application/json" -d "{\"clustername\":\"dianshang_http_develop\",\"modulename\":\"http-develop\",\"env_type\":\"offline\",\"reqid\":\"25568\",\
"pod_name\":\"`hostname`\",\"pod_ip\":\"$POD_IP\",\"port\":\"30553\"}" http://lua.test.com/docker/report/stop/'

题外话：你说我想一个钩子发给多个接口怎么办(确实有这个需求啊,监控平台可能也想要这个事件呢),以关闭钩子举例：

preStop:
  exec:
    command:  
      - "/bin/sh" 
      - "-c"    
      - 'curl -i -X POST -H "Content-type:application/json" -d "{\"clustername\":\"dianshang_http_develop\",\"pod_ip\":\"`ifconfig |grep -v 127.0.0.1|grep -o inet.*[nB]|grep -o [0-9].*[0-9
]`\"}" http://watcher.test.com/pod/stop ; curl -d "docker_name=`hostname`&action_state=Stop" http://report.test.com/docker/hook_report/'

#通过;就可以实现各取所需,各接口要自己的信息了,这个;的作用是执行多个命令而且;后面的命令是不受;前面命令成功与否的状态影响的。

第二种方法启动触发：

在yaml文件命令哪里是启动脚本并传参,让脚本去做一些必要的操作并拉起服务,当然这种方式就是只能启动上报了

command: ["/bin/sh"]
args: ["/root/init.sh", "集群名", "offline", "服务类型","镜像版本","监听端口","模块名","stable/也可以是需求号"]

#然后把上面的启动的curl命令就可以放到这个/root/init.sh脚本中了,脚本都不陌生了啊。

#题外话,这种脚本的方式在启动容器的时候有很大的作用,比如我们如何实现一个镜像多环境使用呢,就是通过在镜像中埋一个脚本的形式,默认打的是线上的配置,这样什么都不用动服务直接启免去了改动风险,因为线上和测试环境是资源隔离的也不用担心测试环境调用到了线上因为服务压根就启动不起来。然后脚本判断如果是测试环境,就再拉一个脚本所有的操作都在这个脚本中操作(有好处的,比如你要修改点东西正常流程的话是需要重新打一个镜像,但是这样只需要重启一下容器就可以重新拉一下脚本就可以做最新的处理了),然后检测到是测试或者沙箱环境,就把对应的配置文件包拉下来替换配置文件目录然后启动服务就行了。

#但是我们线上环境要的是稳定,不能每次都拉一个新脚本吧如果拉取失败我容器岂不是启动不起来了,所以在管理平台做一个开关,启动的时候做个判断,如果发现接口返回的状态码是要进行更新,就去拉取脚本并执行这个新脚本直至再次发版这个开关就会自动关闭了。(这个功能很适合大批量的操作,比如在我们批量更新log4j之类的漏洞的时候很好用,只需要批量重启容器就可以完成漏洞修复,一些大批量的修复只需要运维重启就可以了,不需要重新构建镜像大批量的发版了)。

博文来自：www.51niux.com

1.3 web接口接上报并处理

# vim /opt/web/pod_consul/docker/urls.py

from django.urls import path,include
from . import views
urlpatterns = [
        path('index/',views.index),
        path('report/start/',views.StartView.as_view(),name='start_report'),
        path('report/stop/',views.StopView.as_view(),name='stop_report'),
]

# cat /opt/web/pod_consul/docker/views.py #下面是一个简单的接收上报维护consul的接口demo

# ~*~ coding: utf-8 ~*~
"""
容器上报管理系统的视图层代码
负责处理容器启动/停止的上报请求，并与Consul服务进行交互
"""
import sys
import json
from typing import Dict, Any, Optional  # 导入类型提示工具，增强代码可读性和IDE支持
import requests  # 用于发送HTTP请求到Consul服务
from django.http import JsonResponse, HttpResponse  # Django的HTTP响应处理类
from django.views import View  # Django基础视图类
from django.conf import settings  # 用于获取Django项目配置

# 从Django配置中获取Consul服务地址，若未配置则使用默认值
# 这样的设计使得Consul地址可通过配置文件修改，无需改动代码
CONSUL_URL = getattr(settings, 'CONSUL_URL', 'http://127.0.0.1:8500/v1/kv')

# 定义对外暴露的视图类，控制导入时的可见性
__all__ = ['StartView', 'StopView', 'index']

def index(request) -> HttpResponse:
    """
    系统根路径视图函数
    Args:
        request: Django请求对象
    Returns:
        HttpResponse: 返回简单的HTML响应
    """
    return HttpResponse('<h2>docker</h2>')

class ConsulClient:
    """
    Consul服务交互客户端类
    封装了与Consul API的所有交互操作，职责单一，便于维护和测试
    """
    @staticmethod
    def _construct_base_url(env_type: str, reqid: str, clustername: str) -> str:
        """
        构建Consul操作的基础URL路径
        根据环境类型(env_type)和请求ID(reqid)决定不同的存储路径，
        稳定版本(stable)和需求版本(demand)使用不同的目录结构
        Args:
            env_type: 环境类型(如prod/test等)
            reqid: 请求ID，用于区分不同的部署需求
            clustername: 集群名称
        Returns:
            str: 构建好的基础URL
        """
        if reqid == "stable":
            return f"{CONSUL_URL}/upstreams/{env_type}/stable/{clustername}"
        return f"{CONSUL_URL}/upstreams/{env_type}/demand/{reqid}/{clustername}"
    
    @staticmethod
    def _construct_full_url(env_type: str, reqid: str, clustername: str, pod_ip: str, port: str) -> str:
        """
        构建包含完整服务信息的Consul URL路径
        在基础URL的基础上添加Pod的IP和端口，形成唯一标识服务实例的路径
        Args:
            env_type: 环境类型
            reqid: 请求ID
            clustername: 集群名称
            pod_ip: 容器/Pod的IP地址
            port: 服务端口
        Returns:
            str: 完整的Consul操作URL
        """
        base_url = ConsulClient._construct_base_url(env_type, reqid, clustername)
        return f"{base_url}/{pod_ip}:{port}"
    
    @staticmethod
    def clear_existing_entries(env_type: str, reqid: str, clustername: str) -> Optional[requests.Response]:
        """
        清除Consul中指定集群的现有条目
        在新服务上线时，先清除该集群的旧有记录，避免无效服务信息残留
        Args:
            env_type: 环境类型
            reqid: 请求ID
            clustername: 集群名称
        Returns:
            Optional[requests.Response]: Consul API的响应对象，失败时返回None
        """
        # 构建清除操作的URL，recurse参数表示递归删除该路径下的所有条目
        clear_url = f"{ConsulClient._construct_base_url(env_type, reqid, clustername)}?recurse"
        try:
            # 发送DELETE请求清除现有记录
            response = requests.delete(clear_url)
            # 检查HTTP响应状态码，非2xx状态会抛出异常
            response.raise_for_status()
            return response
        except requests.exceptions.RequestException as e:
            # 捕获所有HTTP请求相关异常并记录
            print(f"清除Consul条目时出错: {str(e)}")
            return None
    
    @staticmethod
    def update_service_entry(env_type: str, reqid: str, clustername: str, pod_ip: str, port: str) -> Optional[requests.Response]:
        """
        在Consul中更新服务实例信息
        当容器启动时，将其服务信息(IP、端口、权重等)注册到Consul
        Args:
            env_type: 环境类型
            reqid: 请求ID
            clustername: 集群名称
            pod_ip: 容器/Pod的IP地址
            port: 服务端口
        Returns:
            Optional[requests.Response]: Consul API的响应对象，失败时返回None
        """
        # 构建更新操作的URL
        update_url = ConsulClient._construct_full_url(env_type, reqid, clustername, pod_ip, port)
        # 服务配置数据，包含负载均衡相关参数
        service_data = json.dumps({
            "weight": 1,           # 服务权重，用于负载均衡
            "max_fails": 3,        # 最大失败次数，超过后标记服务不可用
            "fail_timeout": 1      # 失败超时时间(秒)
        })
        try:
            # 发送PUT请求更新服务信息
            response = requests.put(update_url, data=service_data)
            response.raise_for_status()  # 检查HTTP响应状态
            return response
        except requests.exceptions.RequestException as e:
            print(f"更新Consul条目时出错: {str(e)}")
            return None
    
    @staticmethod
    def remove_service_entry(env_type: str, reqid: str, clustername: str, pod_ip: str, port: str) -> Optional[requests.Response]:
        """
        从Consul中移除服务实例信息
        当容器停止时，从Consul中删除其服务信息，避免流量被路由到已停止的服务
        Args:
            env_type: 环境类型
            reqid: 请求ID
            clustername: 集群名称
            pod_ip: 容器/Pod的IP地址
            port: 服务端口
        Returns:
            Optional[requests.Response]: Consul API的响应对象，失败时返回None
        """
        # 构建删除操作的URL
        delete_url = ConsulClient._construct_full_url(env_type, reqid, clustername, pod_ip, port)
        try:
            # 发送DELETE请求移除服务信息
            response = requests.delete(delete_url)
            response.raise_for_status()  # 检查HTTP响应状态
            return response
        except requests.exceptions.RequestException as e:
            print(f"移除Consul条目时出错: {str(e)}")
            return None

class BaseContainerView(View):
    """
    容器操作的基础视图类
    封装了StartView和StopView的共同功能，减少代码重复，
    遵循DRY(Don't Repeat Yourself)原则
    """
    def _parse_request_data(self, request) -> Dict[str, str]:
        """
        解析并验证请求中的JSON数据
        提取请求中的容器信息字段，并为缺失的字段提供默认值(空字符串)
        Args:
            request: Django请求对象
        Returns:
            Dict[str, str]: 解析后的容器信息字典
        Raises:
            json.JSONDecodeError: 当请求数据不是有效的JSON格式时抛出
        """
        try:
            # 解析请求体中的JSON数据
            data = json.loads(request.body)
            # 提取所需字段，使用get方法确保即使字段缺失也不会报错
            return {
                'clustername': data.get('clustername', ''),  # 集群名称
                'modulename': data.get('modulename', ''),    # 模块名称
                'port': data.get('port', ''),                # 服务端口
                'pod_ip': data.get('pod_ip', ''),            # Pod/容器IP
                'reqid': data.get('reqid', ''),              # 请求ID
                'env_type': data.get('env_type', ''),        # 环境类型
                'pod_name': data.get('pod_name', '')         # Pod/容器名称
            }
        except json.JSONDecodeError:
            # 记录解析错误信息便于调试
            print("错误：POST数据不是有效的JSON格式")
            print("原始数据：", request.body)
            raise  # 重新抛出异常，由调用方处理响应
    
    def get(self, request) -> HttpResponse:
        """
        处理GET请求
        提供简单的欢迎信息，告知客户端应使用POST方法上报容器信息
        Args:
            request: Django请求对象
        Returns:
            HttpResponse: 包含欢迎信息的响应
        """
        return HttpResponse(
            "欢迎使用容器上报管理系统，请进行容器信息的上报",
            content_type="application/json;charset=utf-8"
        )

class StartView(BaseContainerView):
    """
    处理容器启动上报的视图类
    当容器启动时，接收其信息并更新到Consul服务发现系统
    """
    def post(self, request) -> JsonResponse:
        """
        处理容器启动的POST请求
        解析请求数据，记录容器启动信息，并更新Consul中的服务注册信息
        Args:
            request: Django请求对象，包含容器启动信息
        Returns:
            JsonResponse: 包含处理结果的JSON响应
        """
        try:
            # 解析请求数据
            data = self._parse_request_data(request)
            # 打印容器启动信息，用于日志记录和调试
            print(
                f"容器启动上报: {data['clustername']}, "
                f"{data['modulename']}, {data['port']}, {data['pod_ip']}, "
                f"{data['reqid']}, {data['env_type']}, {data['pod_name']}"
            )
            # 清除该集群的现有条目
            clear_response = ConsulClient.clear_existing_entries(
                data['env_type'], data['reqid'], data['clustername']
            )
            # 检查清除操作是否成功
            if clear_response is None:
                return JsonResponse(
                    {'status': 'error', 'message': '清除现有条目失败'},
                    status=500  # 500表示服务器内部错误
                )
            # 更新服务条目，注册新的容器信息
            update_response = ConsulClient.update_service_entry(
                data['env_type'], data['reqid'], data['clustername'],
                data['pod_ip'], data['port']
            )
            # 检查更新操作是否成功
            if update_response is None:
                return JsonResponse(
                    {'status': 'error', 'message': '更新服务条目失败'},
                    status=500
                )
            # 所有操作成功完成
            return JsonResponse({'status': 'success', 'message': '数据已接收并处理'})
        except json.JSONDecodeError:
            # 处理JSON解析错误
            return JsonResponse(
                {'status': 'error', 'message': '无效的JSON数据'},
                status=400  # 400表示请求参数错误
            )
        except Exception as e:
            # 捕获所有未预料到的异常，避免服务崩溃
            print(f"StartView中发生未预期错误: {str(e)}")
            return JsonResponse(
                {'status': 'error', 'message': '发生未预期的错误'},
                status=500
            )

class StopView(BaseContainerView):
    """
    处理容器停止上报的视图类
    当容器停止时，接收其信息并从Consul服务发现系统中移除该服务
    """
    def post(self, request) -> JsonResponse:
        """
        处理容器停止的POST请求
        解析请求数据，记录容器停止信息，并从Consul中移除该服务信息
        Args:
            request: Django请求对象，包含容器停止信息
        Returns:
            JsonResponse: 包含处理结果的JSON响应
        """
        try:
            # 解析请求数据
            data = self._parse_request_data(request)
            # 打印容器停止信息，用于日志记录和调试
            print(
                f"容器关闭上报: {data['clustername']}, "
                f"{data['modulename']}, {data['port']}, {data['pod_ip']}, "
                f"{data['reqid']}, {data['env_type']}, {data['pod_name']}"
            )
            # 从Consul中移除服务条目
            response = ConsulClient.remove_service_entry(
                data['env_type'], data['reqid'], data['clustername'],
                data['pod_ip'], data['port']
            )
            # 检查移除操作是否成功
            if response is None:
                return JsonResponse(
                    {'status': 'error', 'message': '移除服务条目失败'},
                    status=500
                )
            # 操作成功完成
            return JsonResponse({'status': 'success', 'message': '数据已接收并处理'})
        except json.JSONDecodeError:
            # 处理JSON解析错误
            return JsonResponse(
                {'status': 'error', 'message': '无效的JSON数据'},
                status=400
            )
        except Exception as e:
            # 捕获所有未预料到的异常
            print(f"StopView中发生未预期错误: {str(e)}")
            return JsonResponse(
                {'status': 'error', 'message': '发生未预期的错误'},
                status=500
            )

#然后你找一个你的需求容器把上报信息接口添加到yaml文件中然后apply一下,然后等容器完整重启后,delete pod一下可以看看consul中得信息是否发生变化

容器关闭上报: 上报信息
10:42:10] "POST /docker/report/stop/ HTTP/1.1" 200 84
容器启动上报: 
10:42:20] "POST /docker/report/start/ HTTP/1.1" 200 84

#从接口的输出可以看出来单个Pod发生delete事件的时候是先触发关闭钩子再触发新容器的启动钩子

#我们的demo代码中已经在启动接口中增加了清空整个目录的操作,所以使用上面提到的第二种方法只启动上报已经可以实现我们需要的效果,但是接口只能实现一次是吧,如果失败了呢你不能把所有的pod都重启一遍然后让重新上报吧,所以最好还要有一个兜底的功能。

#那么这个兜底功能如何实现呢,我说个最简单的方法：
首先我们需要拿到各个环境在consul中的信息,比如需求环境：
# curl http://127.0.0.1:8500/v1/kv/upstreams/offline/demand/?keys|grep 192.168 #这样环境/需求号/集群名称/集群的IP:端口我们都能得到了

    "upstreams/offline/demand/22384/dianshang_http_develop/192.168.1.187:30660",
    "upstreams/offline/demand/22384/dianshang_tcp_develop/192.168.1.252:30660",
    "upstreams/offline/demand/25568/dianshang_http_develop/192.168.1.187:3066"

# kubectl get pods -n demand -o wide #这样当前需求环境运行的集群/需求以及对应的podip我们就拿到了,然后写个程序跟consul中的信息每分钟一核准不就行了

博文来自：www.51niux.com

二、nginx使用Consul转发请求

2.1 需求域名配置

https://blog.51niux.com/?id=322 这个文章中的内容就用上了哦

# vim /opt/soft/nginx/conf.d/集群名-docker-25298.test.com.conf

include /opt/soft/nginx/conf.d/location/集群名-docker-25298.test.com/*.location_upstream.conf;
server {
    ......
    include /opt/soft/nginx/conf.d/location/集群名-docker-25298.test.com/*.location.conf;
}

#注意了,为什么需要两个include,为什么把upstream.conf引用放到http区域呢而不是单纯的include一个*.conf？因为你要都放到server{}区域是要有下面得报错的:

nginx: [emerg] "upstream" directive is not allowed here in /opt/soft/nginx/conf.d/location/模块名-docker-25298.test.com/模块名-docker-25298.test.com.location_upstream.conf:1
nginx: configuration file /opt/soft/nginx/main-conf/nginx.conf test failed

# vim /opt/soft/nginx/conf.d/location/集群名-docker-25298.test.com/集群名-docker-25298.test.com.location.conf

    location / {
        proxy_next_upstream http_502  error timeout invalid_header;
        proxy_pass http://集群名-docker-25298_pool;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto  $scheme;
    }

# vim /opt/soft/nginx/conf.d/location/集群名-docker-25298.test.com/集群名-docker-25298.test.com.location_upstream.conf

upstream 集群名-docker-25298_pool {
  server 127.0.0.1:11111 down;
  upsync 127.0.0.1:8500/v1/kv/upstreams/offline/demand/25298/集群名 upsync_timeout=5s upsync_interval=500ms upsync_type=consul strong_dependency=off;
  upsync_dump_path /data/nginxconf/location/集群名-offline-25298.conf;
  include /data/nginxconf/location/集群名-offline-25298*.conf;
}

# /opt/soft/nginx/sbin/nginx -s reload #可以自行用测试域名访问一下看看请求是不是到了consul里面存储的后端IP:端口,可以的这里就不粘贴测试结果了

#上面只是一个location是吧,但是生产环境中我们有时候一个域名有多个location,这怎么实现呢,其实道理是相同的,一般默认我们都是所有的请求都给location /,但是如果你有其他location呢,你这里就依次类推在比如/opt/soft/nginx/conf.d/location/集群名-docker-25298.test.com/下面创建关于其他的location.conf和upstream.conf文件就可以了。好的那么第二个问题来了,我怎么知道这个域名在创建需求的时候需要额外创建其他的location呢?这就设计到mysql存储数据了,通常呢我们一般有一个模版域名,比如stable域名,我们新增的lcation都通过web页面这上面创建location对应的集群,比如点击添加最少需要(域名/模块名|集群名/location)这三个信息,然后也可以在域名的右侧点击查看可以看到(模块名/集群名/后端端口号/location/申请人/申请时间)这些大体的信息

#这样就可以实现给一个域名添加除/以外的其他指定的location,这些location就可以作用到nginx的配置文件中了,你的请求也就会被location路由了。

#我们参照上面的例子再做一个stable环境的,要实现一个网关域名转发:1.如果来源IP绑定了需求就优先走需求域名,如果没有需求域名就走稳定环境域名但是是需求的tag

2.2 网关数据表创建

#先创建一个mysql表记录来源IP和需求号的对应关系(当然你可以丰富表字段比如user-agent、添加人、需求描述、添加时间、是否生效等)：

CREATE TABLE `on_demand` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '自增序号',
  `source_ip` varchar(45) NOT NULL COMMENT '用户来源IP（如 192.168.1.131）',
  `demand_number` varchar(50) NOT NULL COMMENT '需求号（stable/25228）',
  `user` varchar(50) NOT NULL COMMENT '操作用户',  -- 新增user字段，补充合理注释
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',  -- 增加默认值更实用
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_source_ip` (`source_ip`),  -- -- 添加唯一约束，确保一个来源IP只能对应一个需求编号
  KEY `idx_ip_demand` (`source_ip`,`demand_number`)  -- 联合索引，提升查询效率
) ENGINE=InnoDB AUTO_INCREMENT=6 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='IP与环境映射表';

#然后再创建一下网关表,我们这样涉及,现有一个线下环境的网关表,线下网关绑定location,沙箱网关跟稳定网关做关联,这样location就保持一致了

CREATE TABLE `offline_gateway` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `domain_name` varchar(255) NOT NULL COMMENT '线下网关域名（如 offline.user.test.com）',
  `network_type` varchar(10) NOT NULL COMMENT '网络类型（intranet-内网/extranet-外网）',
  `applicant` varchar(50) NOT NULL COMMENT '申请人（创建者）',
  `create_time` datetime NOT NULL DEFAULT current_timestamp() COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp() COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_offline_domain` (`domain_name`) COMMENT '线下域名唯一，避免重复'
) ENGINE=InnoDB AUTO_INCREMENT=4 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='线下网关模板表（存储线下网关基础信息，作为沙箱的配置来源）';

CREATE TABLE `offline_location` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `offline_gateway_id` bigint(20) NOT NULL COMMENT '关联的线下网关ID',
  `module_name` varchar(100) NOT NULL COMMENT '所属模块',
  `cluster_name` varchar(255) NOT NULL COMMENT '对应的集群名称（如 http_user_service）',
  `location_path` varchar(255) NOT NULL COMMENT 'location路径（如 /user/login）',
  `rewrite_rule` varchar(500) DEFAULT NULL COMMENT '重写规则（如 /user/login/(.*) /auth/$1）',
  `applicant` varchar(50) NOT NULL COMMENT '申请人（创建者）',
  `create_time` datetime NOT NULL DEFAULT current_timestamp() COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp() COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_offline_loc` (`offline_gateway_id`,`location_path`),
  CONSTRAINT `offline_location_ibfk_1` FOREIGN KEY (`offline_gateway_id`) REFERENCES `offline_gateway` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB AUTO_INCREMENT=8 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='线下网关的location配置表（沙箱网关直接复用此配置）';

CREATE TABLE `mirror_gateway` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `domain_name` varchar(255) NOT NULL COMMENT '沙箱网关域名（如 mirror1.user.test.com）',
  `offline_gateway_id` bigint(20) NOT NULL COMMENT '绑定的线下网关ID（1个沙箱仅绑定1个线下）',
  `network_type` varchar(10) NOT NULL COMMENT '网络类型（通常与线下一致）',
  `applicant` varchar(50) NOT NULL COMMENT '申请人（创建者）',
  `create_time` datetime NOT NULL DEFAULT current_timestamp() COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp() COMMENT '更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_mirror_domain` (`domain_name`),
  UNIQUE KEY `uk_mirror_offline` (`domain_name`,`offline_gateway_id`),
  KEY `offline_gateway_id` (`offline_gateway_id`),
  CONSTRAINT `mirror_gateway_ibfk_1` FOREIGN KEY (`offline_gateway_id`) REFERENCES `offline_gateway` (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=6 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='沙箱网关表（与线下网关映射，1个沙箱绑定1个线下，1个线下可绑定多个沙箱）';

#下面我们插入一些测试数据查看一下效果：
> select * from offline_gateway;

> select * from offline_location;

> select * from mirror_gateway;

#可以看到我们的表结构大概就是这样的,让测试网关去关联location对应的集群,我们要环境一致嘛,所以沙箱环境就以测试网关信息由模版就可以了,那么沙箱环境怎么知道自己关联了哪些location呢？

> SELECT m.domain_name AS 沙箱域名, o.domain_name AS 线下域名, l.location_path, l.cluster_name, l.rewrite_rule FROM mirror_gateway m JOIN offline_gateway o ON m.offline_gateway_id = o.id JOIN offline_location l ON o.id = l.offline_gateway_id WHERE m.domain_name = 'user-mirror-1.test.com';

> SELECT m.domain_name AS 沙箱域名, o.domain_name AS 线下域名, l.location_path, l.cluster_name, l.rewrite_rule, l.module_name, m.network_type FROM mirror_gateway m JOIN offline_gateway o ON m.offline_gateway_id = o.id JOIN offline_location l ON o.id = l.offline_gateway_id ORDER BY m.domain_name, l.location_path; #这是查询所有沙箱域名跟线下域名对应的location关系的sql语句

> SELECT o.domain_name AS 线下域名, l.location_path AS location路径, l.module_name AS 模块名称, l.cluster_name AS 集群名称, l.rewrite_rule AS 重写规则, l.applicant AS 配置申请人, l.create_time AS 配置创建时间 FROM offline_gateway o JOIN offline_location l ON o.id = l.offline_gateway_id WHERE o.domain_name = 'user-offline.test.com' ORDER BY l.location_path; #单个线下网关域名对应的location信息

> SELECT o.domain_name AS 线下域名, l.location_path AS location路径, l.module_name AS 模块名称, l.cluster_name AS 集群名称, l.rewrite_rule AS 重写规则 FROM offline_gateway o JOIN offline_location l ON o.id = l.offline_gateway_id ORDER BY o.domain_name, l.location_path; #所有的location信息

> SELECT o.domain_name AS 线下域名, l.location_path AS location路径, l.cluster_name AS 集群名称, GROUP_CONCAT(DISTINCT m.domain_name) AS 关联的沙箱域名 FROM offline_location l JOIN offline_gateway o ON l.offline_gateway_id = o.id LEFT JOIN mirror_gateway m ON o.id = m.offline_gateway_id WHERE l.cluster_name = 'http_order_service' GROUP BY o.domain_name, l.location_path, l.cluster_name ORDER BY o.domain_name, l.location_path; #查询单个模块集群

> SELECT l.cluster_name AS 集群名称, GROUP_CONCAT(DISTINCT o.domain_name ORDER BY o.domain_name) AS 关联的线下域名, GROUP_CONCAT(DISTINCT CONCAT(o.domain_name, ':', l.location_path) ORDER BY o.domain_name, l.location_path) AS 线下域名与location路径, GROUP_CONCAT(DISTINCT m.domain_name ORDER BY m.domain_name) AS 关联的沙箱域名 FROM offline_location l JOIN offline_gateway o ON l.offline_gateway_id = o.id LEFT JOIN mirror_gateway m ON o.id = m.offline_gateway_id GROUP BY l.cluster_name ORDER BY l.cluster_name;

#上面的sql语句是查询所有的集群关联的线下域名以及location信息

#好了通过上面的sql语句基本可以满足我们需求了,包括程序去创建nginx的配置文件和平台的查询操作,当然配置文件的更新比如增删改,就变为平台操作触发式的了

博文来自：www.51niux.com

2.3 需求域名数据表创建

#这个需求域名就是各种需求域名创建时候的记录信息,主要是为了web平台关联展示用的

CREATE TABLE `environment_domain` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `domain_name` varchar(255) NOT NULL COMMENT '域名全称',
  `module_name` varchar(100) NOT NULL COMMENT '模块名称',
  `cluster_name` varchar(255) NOT NULL COMMENT '集群名称',
  `environment` varchar(20) NOT NULL COMMENT '环境标识（offline/mirror）',
  `requirement_id` varchar(50) DEFAULT NULL COMMENT '需求编号（用于批量下线）',
  `env_type` varchar(20) NOT NULL COMMENT '环境类型：stable-稳定环境，demand-需求环境',
  `network_type` varchar(10) NOT NULL COMMENT '网络类型：intranet-内网，extranet-外网',
  `description` varchar(500) DEFAULT NULL COMMENT '域名描述',
  `applicant` varchar(50) NOT NULL COMMENT '申请人（创建者）',
  `create_time` datetime NOT NULL DEFAULT current_timestamp(),
  `update_time` datetime NOT NULL DEFAULT current_timestamp() ON UPDATE current_timestamp(),
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_domain_name` (`domain_name`),
  KEY `idx_requirement_id` (`requirement_id`) COMMENT '用于需求下线时批量查询',
  KEY `idx_domain_applicant` (`applicant`) COMMENT '用于按申请人查询域名'
) ENGINE=InnoDB AUTO_INCREMENT=13 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='需求环境域名表（含申请人信息）';

> select domain_name,module_name,cluster_name,environment,requirement_id,env_type,network_type from environment_domain order by environment,env_type desc; #可以看下示例数据

#可以看到域名的命名规格就是:模块名-环境-需求.域名后缀,我们默认的需求环境当然是内网类型了啊,因为请求主要依赖于网关转发吗,但是也难免会有某个集群的域名需要进行三方联调,那么我们直接把网关域名开成公网访问显然是不合适的(因为网关域名作为内网测试入口一旦公网就是基本走稳定环境了),当然细节层面还是要基于现状来的,这套主要是为了自动化的按需需求,有些满足不了的需求可以手工创建一个域名随着需求生命周期维护。

Nginx结合Lua实现弹窗二次验证(三)

Fri, 18 Jul 2025 16:44:06 +0800

承接上文,上文我们只显示了基于用户秘钥字符串的生成和白名单的功能,也算对二次认证有了个初步的了解,下面我们来一个完整的示例。

下面我们通过每一个程序文件的介绍来深入理解我们需要实现什么功能,如何去实现的。

一、二次验证代码介绍

1.1 config.lua

这个配置文件是认证系统的核心配置，负责定义数据库连接、认证策略、Redis 配置、会话管理等关键参数。

#vi /usr/local/nginx/conf/auth/config.lua

local _M = {
    db = {
        host = "127.0.0.1",
        port = 3306,
        database = "auth_db",
        user = "auth",
        password = "auth123",
        max_packet_size = 1024 * 1024,
        max_idle_timeout = 30000,  -- 连接池空闲超时时间
        pool_size = 100,           -- 连接池大小
    },

    -- 白名单配置
    whitelist = {
        file = "/usr/local/nginx/conf/auth/ip_whitelist.txt",
        reload_interval = 86400,  -- 24小时重新加载
    },
    
    -- 认证配置
    auth = {
        max_attempts = 3,          -- 最大尝试次数
        ban_time = 1200,           -- 封禁时间(秒)：20分钟
        attempt_ttl = 300,         -- 尝试计数有效期(秒)：5分钟
        code_length = 6,           -- 验证码长度
        secret_length = 32,        -- 秘钥长度
	    totp_time_step = 30,       -- TOTP时间步长(秒)：30秒
        default_secret_key = "604264e9fd0315c5cbe873106db78d7051d739894095867c4c2a9cbc05bfdf86",  -- 全局默认密钥
    },
    
    -- Redis配置
    redis = {
        host = "127.0.0.1",
        port = 6379,
        password = nil,
        timeout = 1000,            -- 连接超时(ms)
        keepalive = 10000,         -- 连接池保持时间(ms)
        pool_size = 100,            -- 连接池大小
        user_secret_ttl = 3600,    -- 用户秘钥缓存时间(秒)：1小时
    },
    
    -- 会话配置
    session = {
        cookie_name = "auth_session",
        cookie_domain = ".test.com",
        cookie_path = "/",
        cookie_secure = false,
        cookie_http_only = true,
        expire_time = 86400,       -- 会话有效期(秒)：1天
        cross_domain = false,  -- 设置为true如果是跨域应用
        local_cache_offset = 10,  -- 本地缓存比Redis提前过期的秒数
    },

    -- 全局免认证URL
    skip_auth_global = {
        ["/health"] = true,
        ["/metrics"] = true,
        ["/static/"] = true,
        ["/favicon.ico"] = true,
    },

    -- 域名级免认证URL
    skip_auth_domain = {
        ["lua.test.com"] = {
            ["/auth/login"] = true,
            ["/auth/logout"] = true,
        },
        ["api.test.com"] = {
            ["/public/"] = true,
        }
    },
    
    -- 模板路径
    templates = {
        auth_popup = "/usr/local/nginx/conf/auth/templates/auth_popup.html",
    },
    
    -- 日志配置
    log = {
        level = "info",  -- 全局日志级别
        access_file = "/opt/log/nginx/auth_access.log",  -- 正常访问日志
        error_file = "/opt/log/nginx/auth_error.log"     -- 错误日志
    }
}

return _M

#通过配置文件我们可以看到我们做了一个灵活的设置,那就是我们可能指定就算启用了这个lua文件,但是有些域名可能有很多location,有些location是不需要认证的,这就是域名级别的路径白名单,我们也有一些全局的,比如favicon.ico浏览器小图标,这就是全局的白名单。

#前面我们的前端页面是写到lua文件中的,现在呢我们将lua前端文件从lua代码中剥离了出来放到了templates目录下面,更规范修改更灵活。

#然后呢我们是希望认证日志跟nginx本身的日志文件区分开,默认都写到了error.log里面,我们是想成功/失败的认证日志记录到我们指定日志文件便于排查。

1.2 log_utils.lua

这是一个日志工具模块文件,为了规范的记录系统日志。亮点介绍：

上下文适配：避免非请求阶段调用请求阶段API导致的错误
安全健壮：通过pcall捕获所有可能的异常，确保日志操作不影响主流程
格式统一：标准化日志内容，便于后续分析和监控
配置驱动：日志路径、级别通过config.lua统一管理,便于维护

# vi /usr/local/nginx/conf/auth/log_utils.lua

-- 1.模块初始化与依赖引入
local config = require("config")  --引入全局配置(日志路径、级别等）
-- 为啥要local ngx = ngx这种呢?主要是性能优化：减少全局变量查找开销/代码健壮性：避免全局变量污染/代码可读性：明确依赖关系
-- Lua访问局部变量的速度远快于全局变量(约快30%)。对于高频调用的模块(如ngx、os)，通过定义局部变量可以显著提升性能。
local ngx = ngx  --Nginx Lua 模块(提供请求上下文信息)
local os = os  --操作系统模块(获取时间戳）
local io = io  --输入输出模块(文件操作)

local _M = {} --定义模块对象,用于导出函数

-- 2.上下文判断：区分请求/非请求阶段
-- Nginx运行阶段分为请求阶段(处理HTTP请求)和非请求阶段(如启动、配置加载)，两者可调用的API不同(例如ngx.var仅在请求阶段可用)
-- 判断是否处于请求上下文
local function is_request_context()
    -- 尝试访问ngx.var.request_id(仅请求阶段存在),失败则为非请求阶段,pcall捕获可能的错误
    local success, _ = pcall(function()
        return ngx.var.request_id  -- 尝试访问请求ID，非请求阶段会报错
    end)
    return success
end

-- 3.安全获取客户端IP
-- 获取客户端IP,客户端IP可能来自X-Forwarded-For(代理场景)、X-Real-IP或直接连接的remote_addr,需兼容非请求阶段
local function get_client_ip_safe()
    if not is_request_context() then
        return "N/A"  --非请求阶段无客户端IP,返回默认值
    end
    
    -- 仅在请求上下文时调用 ngx.req.get_headers()
    local headers = ngx.req.get_headers()
    local client_ip = headers["X-Forwarded-For"] or  --优先取代理传递的IP
                      headers["X-Real-IP"] or --次优先取真实IP
                      ngx.var.remote_addr or "unknown" --最后取直接连接IP   
    
    --处理 X-Forwarded-For多IP场景(格式:"ip1, ip2, ..."，取第一个)
    if type(client_ip) == "string" and string.find(client_ip, ",") then
        client_ip = string.sub(client_ip, 1, string.find(client_ip, ",") - 1)
    end
    
    return client_ip
end

-- 4.安全获取请求 ID
-- 请求ID(request_id)Nginx为每个请求生成的唯一标识,用于追踪请求链路,仅在请求阶段可用。
local function get_request_id_safe()
    if not is_request_context() then
        return "N/A" 
    end
    return ngx.var.request_id or "unknown"  --返回请求ID，默认"unknown"
end

-- 5.日志格式化:统一日志格式
-- 格式化日志:确保包含时间戳、级别、客户端 IP、请求 ID、具体信息，便于日志分析工具解析。
local function format_log(level, message)
    local client_ip = get_client_ip_safe()
    local timestamp = os.date("%Y-%m-%d %H:%M:%S") -- 时间戳(年-月-日 时:分:秒)
    local request_id = get_request_id_safe()
    
    -- 拼接日志字符串：[时间] [级别] [IP] [请求ID] 信息
    return string.format("[%s] [%s] [%s] [%s] %s",
        timestamp,
        level,
        client_ip,
        request_id,
        tostring(message)  -- 确保message是字符串类型
    )
end

-- 安全格式化日志（纯非请求阶段专用）
local function format_log_safe(level, message)
    local timestamp = os.date("%Y-%m-%d %H:%M:%S")
    return string.format("[%s] [%s] [N/A] [N/A] %s",
        timestamp,
        level,
        tostring(message)  -- 确保message是字符串类型
    )
end

-- 6.日志写入:安全操作文件
-- 负责将格式化后的日志写入配置文件指定的路径,包含错误处理(如文件无法打开时降级打印到控制台)
local function write_log(file_path, message)
    -- 参数校验
    if type(file_path) ~= "string" or file_path == "" then
        print("[LOG_ERROR] 日志文件路径不能为空")
        return false
    end
    
    -- 尝试打开日志文件("a"表示追加模式)
    local file, err = io.open(file_path, "a")
    if not file then
        print("[LOG_ERROR] 无法打开日志文件: " .. file_path .. ", 错误: " .. (err or "未知错误"))
        print("[FALLBACK] " .. message)
        return false
    end
    
    -- 安全写入日志(使用pcall捕获写入过程中的错误)
    local ok, write_err = pcall(function()
        file:write(message .. "\n")  -- 写入日志并换行
        file:flush()  -- 强制刷新到磁盘(避免缓存导致日志丢失)
    end)
    file:close()  -- 无论成功与否都关闭文件
    
    -- 处理写入错误
    if not ok then
        print("[LOG_ERROR] 写入日志失败: " .. (write_err or "未知错误"))
        return false
    end
    
    return true -- 写入成功
end

-- 7. 日志级别控制:按配置输出
-- 根据config.log.level控制不同级别的日志是否输出，避免冗余日志。

-- 调试日志(自动适配上下文)
function _M.debug(message)
    -- 要注意~=在lua中是不等于的比较运算符,跟其他语音中的!=类似
    if config.log.level ~= "debug" then
        return false  -- 日志级别不匹配,不输出
    end
    -- 根据上下文选择日志格式,写入访问日志文件
    local log_msg = is_request_context() 
        and format_log("DEBUG", message) 
        or format_log_safe("DEBUG", message)
    return write_log(config.log.access_file, log_msg)
end

-- 信息日志(自动适配上下文)
function _M.info(message)
    if config.log.level ~= "debug" and config.log.level ~= "info" then
        return false
    end
    local log_msg = is_request_context() 
        and format_log("INFO", message) 
        or format_log_safe("INFO", message)
    return write_log(config.log.access_file, log_msg)
end

-- 警告日志(自动适配上下文)
function _M.warn(message)
    local log_msg = is_request_context() 
        and format_log("WARN", message) 
        or format_log_safe("WARN", message)
    return write_log(config.log.error_file, log_msg)
end

-- 错误日志(自动适配上下文)
function _M.error(message)
    local log_msg = is_request_context() 
        and format_log("ERROR", message) 
        or format_log_safe("ERROR", message)
    return write_log(config.log.error_file, log_msg)
end

-- 8. 兼容旧版本：提供安全日志方法
-- 为兼容可能存在的旧代码调用,保留info_safe和error_safe别名。
function _M.info_safe(message)
    return _M.info(message) -- 等同于 info 方法
end

function _M.error_safe(message)
    return _M.error(message) -- 等同于 error 方法
end

return _M  -- 导出模块,供其他脚本通过require("log_utils")调用

1.3 db_utils.lua

该文件是数据库操作模块，基于 resty.mysql 库封装了MySQL数据库的常用操作，主要用于认证系统中用户信息、会话数据的存储与查询。其核心功能包括：

1.安全连接MySQL数据库并管理连接池
2.提供防SQL注入的查询方法
3.初始化数据库表结构(用户表、会话表)
4.封装用户密钥查询等业务相关的数据库操作

# vi /usr/local/nginx/conf/auth/db_utils.lua #这个文件不多做介绍了,前面有介绍

-- 1.模块依赖与初始化
local mysql = require("resty.mysql")
local config = require("config").db
local log = require("log_utils")  -- 使用新的日志模块

local _M = {}

-- 2. 数据库连接管理
-- 连接数据库并设置超时，使用连接池减少频繁创建连接的开销
function _M.connect()
    local db, err = mysql:new()
    if not db then
        log.error("创建MySQL实例失败: " .. err)
        return nil, "创建MySQL实例失败: " .. err
    end
    
    -- 设置超时
    db:set_timeout(1000)  -- 1秒超时
    
    -- 连接数据库
    local ok, err, errno, sqlstate = db:connect({
        host = config.host,
        port = config.port,
        database = config.database,
        user = config.user,
        password = config.password,
        max_packet_size = config.max_packet_size
    })
    
    if not ok then
        local error_msg = string.format("连接数据库失败: %s, 错误码: %d, SQL状态: %s", err, errno, sqlstate)
        log.error(error_msg)
        return nil, error_msg
    end
    
    log.info("数据库连接成功")
    return db
end

-- 3.安全执行SQL查询
-- 执行SQL语句并自动将连接放回连接池，避免连接泄漏。
function _M.execute_query(sql)
    log.info("执行SQL查询: " .. sql)
    local db, err = _M.connect()
    if not db then
        log.error("获取数据库连接失败: " .. err)
        return nil, err
    end
    
    local res, err, errno, sqlstate = db:query(sql)
    
    -- 将连接放回连接池
    db:set_keepalive(config.max_idle_timeout, config.pool_size)
    
    if not res then
        local error_msg = string.format("执行SQL失败: %s, 错误码: %d, SQL状态: %s", err, errno, sqlstate)
        log.error(error_msg)
        return nil, error_msg
    end
    
    return res
end

-- 4.防SQL注入：字符串转义
-- 对用户输入的字符串进行转义(如单引号替换为双引号)，避免恶意SQL注入。
function _M.escape_literal(str)
    if str == nil then
        return "NULL"
    end
    
    -- 示例:若用户输入user' OR '1'='1，转义后变为 'user'' OR ''1''=''1',避免注入攻击。
    if type(str) == "boolean" then
        return str and "1" or "0"
    end
    
    if type(str) == "number" then
        return tostring(str)
    end
    
    str = tostring(str)
    str = string.gsub(str, "\\", "\\\\")
    str = string.gsub(str, "'", "''")
    return "'" .. str .. "'"
end

-- 5.数据库表初始化
-- 创建users(用户表)和sessions(会话表)，确保系统启动时表结构存在。
function _M.init_tables()
    log.info("开始初始化数据库表")
    
    -- 创建用户表
    local create_users_sql = [[
        CREATE TABLE IF NOT EXISTS users (
            id INT AUTO_INCREMENT PRIMARY KEY, -- 用户名(唯一)
            username VARCHAR(50) UNIQUE NOT NULL,
            otp_secret VARCHAR(32) NOT NULL,
            login_attempts INT DEFAULT 0,
            last_attempt_time DATETIME,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP
        )
    ]]
    
    local res, err = _M.execute_query(create_users_sql)
    if not res then
        log.error("创建用户表失败: " .. err)
        return false, "创建用户表失败: " .. err
    end
    
    log.info("用户表创建成功")
    
    -- 创建会话表
    local create_sessions_sql = [[
        CREATE TABLE IF NOT EXISTS sessions (
            session_id VARCHAR(64) PRIMARY KEY, -- 会话ID(唯一)
            user_id INT NOT NULL,
            expires_at DATETIME NOT NULL,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
            FOREIGN KEY (user_id) REFERENCES users(id) -- 外键关联用户表
        )
    ]]
    
    local res, err = _M.execute_query(create_sessions_sql)
    if not res then
        log.error("创建会话表失败: " .. err)
        return false, "创建会话表失败: " .. err
    end
    
    log.info("会话表创建成功")
    return true
end

-- 6.业务方法:获取用户密钥
-- 查询指定用户名对应的OTP密钥(用于TOTP验证码验证）
function _M.get_user_secret(username)
    log.info("开始获取用户秘钥: " .. username)
    
    -- 安全转义用户名
    local escaped_username = _M.escape_literal(username)
    
    -- 构建SQL查询
    local sql = string.format([[
        SELECT otp_secret FROM users WHERE username = %s]], escaped_username)  -- 使用转义后的用户名

    -- 执行查询
    local res, err = _M.execute_query(sql)
    
    -- 记录查询错误
    if err then
        log.error("查询用户秘钥失败: " .. err)
        return nil
    end
    
    -- 处理结果(用户不存在则返回 nil)
    if not res or #res == 0 then
        log.info("用户不存在，用户名: " .. username)
        return nil
    end
    
    -- 返回用户密钥
    log.info("成功获取用户秘钥: " .. username)
    return res[1]["otp_secret"]  -- 取第一条结果的otp_secret字段
end

return _M

博文来自：www.51niux.com

1.4 修改Nginx增加共享内存和白名单初始化

# vi /usr/local/nginx/conf/nginx.conf

    #gzip  on;
    # 共享内存定义
    lua_shared_dict ip_whitelist_cache 5m;
    lua_shared_dict session_cache 100m;
    # 定义一个自定义变量用于存储自定义标识（内存中）
    lua_shared_dict custom_request_id 10m;
    # Lua模块路径
    lua_package_path "/usr/local/lua_core/lib/lua/?.lua;/usr/local/nginx/conf/auth/?.lua;;";
    # 白名单初始化（修正：移除直接执行的初始化，改为显式调用）
    init_by_lua_file /usr/local/nginx/conf/auth/init_by_lua.lua;

    # worker进程初始化（修正：使用完整的init_worker.lua文件）
    init_worker_by_lua_file /usr/local/nginx/conf/auth/init_worker.lua;

1.5 redis_utils.lua

# vi /usr/local/nginx/conf/auth/redis_utils.lua

-- 第一部分: 基础工具与连接管理
-- 1.1.模块依赖与初始化
local redis = require("resty.redis")  -- 引入 OpenResty Redis 客户端
local config = require("config")      -- 引入全局配置（包含 Redis 连接信息等）
local log = require("log_utils")      -- 引入日志工具

local _M = {}  -- 定义模块表，用于导出公共方法
-- 1.2.安全日志处理函数
-- 作用：处理空值，统一显示为 [空值]/通过正则替换非数字、字母、标点和空格的字符为?,避免日志被特殊字符破坏
local function safe_log_value(value)
    if not value or value == "" then
        return "[空值]"
    end
    -- 过滤不可见字符（如控制字符），防止日志格式混乱
    -- ^在字符类中表示"取反",%w表示字母和数字,%p表示标点符号,这就是匹配除了字母、数字、标点符号和空格之外的所有字符替换为?
    return tostring(value):gsub("[^%w%p ]", "?")
end
-- 1.3.Redis连接管理函数
local function connect()
    local red = redis:new()  -- 创建 Redis 客户端实例
    red:set_timeout(config.redis.timeout or 1000)  -- 设置超时时间（默认1秒）
    
    -- 连接 Redis 服务器（使用配置的 host 和 port，默认本地 127.0.0.1:6379）
    local ok, err = red:connect(
        config.redis.host or "127.0.0.1",
        config.redis.port or 6379
    )
    
    -- 连接失败处理
    if not ok then
        log.error(
            "[Redis连接] 失败，" ..
            "host: [" .. safe_log_value(config.redis.host) .. "], " ..
            "port: [" .. safe_log_value(config.redis.port) .. "], " ..
            "error: [" .. safe_log_value(err) .. "]"
        )
        return nil, err
    end
    
    -- 选择数据库（默认0号库）
    local db = config.redis.db or 0
    local ok, err = red:select(db)
    if not ok then
        log.error(
            "[Redis操作] 选择数据库失败，" ..
            "db: [" .. safe_log_value(db) .. "], " ..
            "error: [" .. safe_log_value(err) .. "]"
        )
        red:close()  -- 失败时关闭连接释放资源
        return nil, err
    end
    
    log.info(
        "[Redis连接] 成功，" ..
        "host: [" .. safe_log_value(config.redis.host) .. "], " ..
        "port: [" .. safe_log_value(config.redis.port) .. "], " ..
        "db: [" .. safe_log_value(db) .. "]"
    )
    
    return red, nil
end

-- 第二部分：用户会话管理
-- 2.1.会话查询（多级缓存机制）
-- 设计点：多级缓存(本地缓存+Redis减少网络开销)/数据双重检验，防止脏数据污染/域名隔离(通过cookie_domain区分不同域名的会话)
-- 从配置中获取会话相关参数（默认空表避免 nil 错误）
local session_conf = config.session or {}
function _M.get_user_session(session_id)
    if not session_id or session_id == "" then
        log.info("[会话查询] session_id为空")
        return nil
    end
    
    -- 构建缓存键（格式：session:域名:session_id，支持多域名隔离）
    local cache_key = "session:" .. (session_conf.cookie_domain or "") .. ":" .. session_id
    
    -- 第一步：检查本地缓存（ngx.shared.session_cache，内存级缓存）
    local username = ngx.shared.session_cache and ngx.shared.session_cache:get(cache_key)
    if username then
        -- 获取剩余有效期，便于监控缓存状态
        local remaining_time = ngx.shared.session_cache:ttl(cache_key)
        log.info(
            "[会话查询] 命中本地缓存，" ..
            "session_id: [" .. safe_log_value(session_id) .. "], " ..
            "username: [" .. safe_log_value(username) .. "], " ..
            "剩余有效期: " .. remaining_time .. "秒"
        )
        
        -- 数据有效性校验：防止缓存脏数据（如非字符串类型或包含非法标识）
        if type(username) ~= "string" or string.find(username, "userdata:") then
            log.warn("[会话查询] 本地缓存数据无效，已删除")
            ngx.shared.session_cache:delete(cache_key)
            return nil
        end
        
        return username  -- 本地缓存命中直接返回
    end
    
    -- 第二步：本地缓存未命中，查询 Redis
    log.info("[会话查询] 本地缓存未命中，查询Redis")
    local red, err = connect()
    if not red then
        log.error("[会话查询] Redis连接失败：" .. err)
        return nil
    end
    
    -- 从 Redis 获取会话数据
    local username, redis_err = red:get(cache_key)
    red:close()  -- 及时关闭连接释放资源
    
    -- 处理 Redis 查询错误
    if redis_err then
        log.error("[会话查询] Redis查询失败：" .. redis_err)
        return nil
    end
    
    -- 第三步：验证 Redis 数据并同步到本地缓存
    if username and username ~= "" then
        -- 校验数据格式（同本地缓存逻辑）
        if type(username) ~= "string" or string.find(username, "userdata:") then
            log.warn("[会话查询] Redis数据无效，已删除")
            red:del(cache_key)  -- 清理脏数据
            return nil
        end
        
        -- 同步到本地缓存（默认有效期300秒，可通过配置修改）
        if ngx.shared.session_cache then
            ngx.shared.session_cache:set(cache_key, username, session_conf.cache_time or 300)
            log.info("[本地缓存-写入] 成功")
        end
        
        return username
    else
        log.info("[会话查询] Redis未命中")
        return nil
    end
end
-- 2.2.会话创建（双向同步机制）
function _M.create_user_session(session_id, username, expire_seconds)
    -- 参数校验：必填参数缺失直接返回失败
    if not session_id or not username or not expire_seconds then
        log.error("[会话创建] 参数缺失")
        return false
    end
    
    -- 数据格式校验：拒绝无效用户名
    if type(username) ~= "string" or string.find(username, "userdata:") then
        log.error("[会话创建] 用户名格式无效，拒绝创建")
        return false
    end
    
    local cache_key = "session:" .. (session_conf.cookie_domain or "") .. ":" .. session_id
    
    -- 第一步：写入 Redis（带过期时间）
    local red, err = connect()
    if not red then
        log.error("[会话创建] Redis连接失败：" .. err)
        return false
    end
    
    -- 使用 setex 原子操作：同时设置值和过期时间
    local ok, set_err = red:setex(cache_key, expire_seconds, username)
    red:close()
    
    if not ok then
        log.error("[会话创建] Redis写入失败：" .. set_err)
        return false
    end
    
    -- 第二步：同步到本地缓存（有效期更短，避免与 Redis 数据不一致）
    if ngx.shared.session_cache then
        local local_cache_time = math.min(expire_seconds, session_conf.cache_time or 300)
        ngx.shared.session_cache:set(cache_key, username, local_cache_time)
        log.info("[会话创建] 本地缓存同步成功，有效期：" .. local_cache_time .. "秒")
    end
    
    log.info("[会话创建] 成功，有效期：" .. expire_seconds .. "秒")
    return true
end
-- 2.3. 本地缓存专用查询函数
function _M.get_session_from_cache(session_id)
    if not session_id or session_id == "" then
        return nil
    end
    
    local cache_key = "session:" .. (session_conf.cookie_domain or "") .. ":" .. session_id
    local username = ngx.shared.session_cache and ngx.shared.session_cache:get(cache_key)
    
    if username then
        -- 同 get_user_session 的数据校验逻辑
        local remaining_time = ngx.shared.session_cache:ttl(cache_key)
        log.info("[本地缓存-读取] 命中，剩余有效期：" .. remaining_time .. "秒")
        
        if type(username) ~= "string" or string.find(username, "userdata:") then
            log.warn("[本地缓存-读取] 数据无效，已删除")
            ngx.shared.session_cache:delete(cache_key)
            return nil
        end
        
        return username
    else
        log.info("[本地缓存-读取] 未命中")
        return nil
    end
end

-- 第三部分：TOTP 密钥管理
-- 3.1.获取用户 TOTP 密钥
function _M.get_user_secret(username)
    if not username or username == "" then
        log.error("[获取密钥] 用户名为空")
        return nil, "username_empty"
    end
    
    local key = "user_secret:" .. username  -- 密钥存储键格式：user_secret:用户名
    local red, err = connect()
    
    if not red then
        log.error("[获取密钥] Redis连接失败")
        return nil, "redis_connect_failed"
    end
    
    -- 从 Redis 获取密钥
    local secret, redis_err = red:get(key)
    red:close()
    
    if redis_err then
        log.error("[获取密钥] Redis查询失败：" .. redis_err)
        return nil, "redis_query_failed"
    end
    
    -- 明确区分"用户不存在"和"查询成功但无数据"
    if secret == nil then
        log.info("[获取密钥] 用户不存在：" .. username)
        return nil, "user_not_found"
    end
    
    log.info("[获取密钥] 成功：" .. username)
    return secret, nil
end
-- 3.2.设置用户TOTP密钥
function _M.set_user_secret(username, secret)
    if not username or not secret then
        log.error("[设置密钥] 参数缺失")
        return false
    end
    
    local key = "user_secret:" .. username
    local red, err = connect()
    
    if not red then
        log.error("[设置密钥] Redis连接失败")
        return false
    end
    
    -- 长期存储（1年有效期），适合TOTP密钥的持久化需求
    local ok, redis_err = red:setex(key, 365 * 24 * 3600, secret)
    red:close()
    
    if not ok then
        log.error("[设置密钥] Redis写入失败：" .. redis_err)
        return false
    end
    
    log.info("[设置密钥] 成功：" .. username)
    return true
end

-- 第四部分：认证安全控制
-- 4.1.认证尝试次数记录与自动封禁
local auth_conf = config.auth or {}  -- 认证配置（最大尝试次数、封禁时间等）

function _M.record_attempt(username)
    if not username or username == "" then
        log.error("[记录尝试] 用户名为空")
        return nil
    end
    
    local key = "auth_attempts:" .. username  -- 尝试次数存储键
    local max_attempts = auth_conf.max_attempts or 5  -- 默认最大5次尝试
    local ban_time = auth_conf.ban_time or 1200  -- 默认封禁20分钟（1200秒）
    
    local red, err = connect()
    if not red then
        log.error("[记录尝试] Redis连接失败")
        return nil
    end
    
    -- 先检查用户是否已被封禁
    local is_banned, redis_err = red:get("user_banned:" .. username)
    if redis_err then
        log.error("[记录尝试] 检查封禁状态失败：" .. redis_err)
        red:close()
        return nil
    end
    
    if is_banned and is_banned == "1" then
        log.warn("[记录尝试] 用户已被封禁：" .. username)
        red:close()
        return 0  -- 已封禁返回0
    end
    
    -- 自增尝试次数（原子操作，支持并发场景）
    local attempts, redis_err = red:incr(key)
    if redis_err then
        log.error("[记录尝试] 自增失败：" .. redis_err)
        red:close()
        return nil
    end
    
    -- 首次记录时设置过期时间（与封禁时间一致）
    if attempts == 1 then
        red:expire(key, ban_time)
    end
    
    -- 达到最大尝试次数时自动封禁
    if attempts >= max_attempts then
        red:setex("user_banned:" .. username, ban_time, "1")  -- 封禁标记
        log.warn("[记录尝试] 达到最大次数，已封禁：" .. username)
        red:close()
        return 0
    end
    
    log.info(
        "[记录尝试] 成功，剩余次数：" .. (max_attempts - attempts) ..
        "，用户：" .. username
    )
    red:close()
    return max_attempts - attempts  -- 返回剩余尝试次数
end
-- 4.2.辅助封禁管理函数
-- 重置认证尝试次数（如登录成功后调用）
function _M.reset_attempts(username)
    if not username or username == "" then
        log.error("[重置尝试] 用户名为空")
        return false
    end
    
    local key = "auth_attempts:" .. username
    local red, err = connect()
    
    if not red then
        log.error("[重置尝试] Redis连接失败")
        return false
    end
    
    -- 删除尝试次数记录和封禁标记
    red:del(key)
    red:del("user_banned:" .. username)
    red:close()
    
    log.info("[重置尝试] 成功：" .. username)
    return true
end

-- 检查用户是否被封禁
function _M.is_user_banned(username)
    if not username or username == "" then
        log.error("[检查封禁] 用户名为空")
        return false
    end
    
    local key = "user_banned:" .. username
    local red, err = connect()
    
    if not red then
        log.error("[检查封禁] Redis连接失败")
        return false
    end
    
    local is_banned = red:get(key)
    red:close()
    
    log.info("[检查封禁] " .. (is_banned and "已封禁" or "未封禁") .. "：" .. username)
    return is_banned and is_banned == "1"  -- 明确返回布尔值
end

-- 手动封禁用户（支持自定义封禁时间）
function _M.ban_user(username, ban_time)
    if not username or username == "" then
        log.error("[封禁用户] 用户名为空")
        return false
    end
    
    -- 封禁时间默认使用配置的ban_time（20分钟），支持自定义
    ban_time = ban_time or (auth_conf.ban_time or 1200)
    local key = "user_banned:" .. username  -- 封禁标记存储键
    local red, err = connect()
    
    if not red then
        log.error(
            "[封禁用户] Redis连接失败，" ..
            "username: [" .. safe_log_value(username) .. "], " ..
            "error: [" .. safe_log_value(err) .. "]"
        )
        return false
    end
    
    -- 写入封禁标记（值为"1"，带过期时间）
    local ok, redis_err = red:setex(key, ban_time, "1")
    red:close()
    
    if not ok then
        log.error(
            "[封禁用户] Redis操作失败，" ..
            "username: [" .. safe_log_value(username) .. "], " ..
            "error: [" .. safe_log_value(redis_err) .. "]"
        )
        return false
    end
    
    log.info(
        "[封禁用户] 成功，" ..
        "username: [" .. safe_log_value(username) .. "], " ..
        "封禁时间: [" .. safe_log_value(ban_time) .. "秒]"
    )
    return true
end

-- 第五部分:无效会话清理
function _M.clean_invalid_sessions()
    -- 连接Redis
    local red, err = connect()
    if not red then
        log.error("[清理无效会话] Redis连接失败")
        return false
    end
    
    local cursor = "0"  -- 游标初始值（用于SCAN命令分页）
    local deleted = 0   -- 记录删除的无效会话数
    local processed = 0 -- 记录处理的总会话数
    
    log.info("[清理无效会话] 开始扫描会话数据...")
    
    -- 循环扫描所有会话键（使用SCAN避免阻塞Redis）
    --  repeat...until是一种循环结构，类似于其他语言中的 do...while 循环。它的特点是先执行循环体，再判断条件，因此循环体至少会执行一次
    repeat
        -- 扫描匹配"session:*"的键，每次返回部分结果
        -- 安全扫描：使用SCAN命令替代KEYS，避免一次性扫描大量键导致Redis阻塞
        local res, err = red:scan(cursor, "MATCH", "session:*")
        if not res then
            log.error("[清理无效会话] Redis扫描失败：" .. safe_log_value(err))
            break
        end
        
        cursor = res[1]  -- 更新游标（用于下一次扫描）
        local keys = res[2]  -- 当前批次的键列表
        processed = processed + #keys  -- 累计处理数
        
        -- 检查每个会话键的值是否有效
        for _, key in ipairs(keys) do
            local username, err = red:get(key)
            -- 无效判定：非字符串类型或包含"userdata:"（脏数据标识）
            if username and (type(username) ~= "string" or string.find(username, "userdata:")) then
                red:del(key)  -- 删除无效会话
                deleted = deleted + 1
                log.info("[清理无效会话] 已删除无效会话: " .. key)
            end
        end
    until cursor == "0"  -- 游标为0表示扫描完成
    
    red:close()
    log.info(
        "[清理无效会话] 完成，" ..
        "共处理 " .. processed .. " 个会话，" ..
        "删除 " .. deleted .. " 个无效会话"
    )
    return true
end
        
return _M  -- 导出模块表，供其他脚本调用

1.6 totp_utils.lua

# vi /usr/local/nginx/conf/auth/totp_utils.lua

#该文件是TOTP(时间同步验证码)工具模块，基于RFC6238标准实现了TOTP验证码的生成与验证功能。TOTP 广泛用于双因素认证(2FA)，其核心原理是通过密钥和当前时间生成短期有效的验证码。

-- 1.模块初始化与常量定义
local bit32 = require("bit")  -- 位操作库（用于哈希计算）
local log = require("log_utils")  -- 日志工具

local _M = {}  -- 模块对象

-- Base32 字符集（遵循 RFC 4648 标准）
-- 包含大写字母、小写字母（用于兼容）和数字 2-7
local BASE32_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz234567"
local BASE32_UPPER = string.upper(BASE32_CHARS)  -- 大写字符集（用于解码基准）
local BASE32_LOWER = string.lower(BASE32_CHARS)  -- 小写字符集（用于兼容）
local BASE32_PAD = "="  -- Base32 填充符

-- 2. Base32解码(TOTP 密钥解码)
-- TOTP密钥通常以Base32编码存储(如JBSWY3DPEHPK3PXP),需解码为原始字节才能用于加密。
function _M.base32_decode(base32_str, allow_lowercase)
    -- 参数校验：必须为字符串
    if type(base32_str) ~= "string" then
        log.error("base32_decode: 非法参数类型，期望字符串")
        return nil, "INVALID_PARAM_TYPE"
    end
    
    -- 清理输入：移除空格和填充符（=）
    local cleaned = base32_str:gsub("%s+", ""):gsub(BASE32_PAD, "")
    
    -- 空输入处理
    if #cleaned == 0 then
        log.error("base32_decode: 空输入字符串")
        return nil, "EMPTY_INPUT"
    end
    
    -- 非法字符校验
    local valid_chars = allow_lowercase and BASE32_CHARS or BASE32_UPPER  -- 允许小写时放宽校验
    for i = 1, #cleaned do
        local char = cleaned:sub(i, i)
        if valid_chars:find(char, 1, true) == nil then  -- 精确匹配字符
            log.error("base32_decode: 发现非法字符 '", char, "'")
            return nil, "INVALID_CHAR"
        end
    end
    
    -- 其实避免麻烦正式环境就直接字母生成的时候就全大写字母就好了,就没有转义兼容方面的问题了
    -- 统一转为大写（确保解码逻辑一致）
    cleaned = string.upper(cleaned)
    
    -- 解码核心逻辑：将 Base32 字符转为字节流
    local result = {}  -- 存储解码后的字节
    local bits = 0     -- 累计位数（Base32 每字符 5 位）
    local value = 0    -- 累计数值（用于拼接字节）
    
    for i = 1, #cleaned do
        local char = cleaned:sub(i, i)
        local pos = BASE32_UPPER:find(char, 1, true)  -- 查找字符在大写集的位置（1-32）
        if not pos then
            log.error("base32_decode: 字符集查找失败")
            return nil, "CHARSET_LOOKUP_FAILED"
        end
        local val = pos - 1  -- 转为 0-31 的数值
        
        -- 累计 5 位，凑满 8 位则生成一个字节
        value = (value * 32) + val  -- 左移 5 位，加上新值
        bits = bits + 5
        
        -- 当累计位数 >=8 时，提取一个字节
        while bits >= 8 do
            local byte = math.floor(value / (2 ^ (bits - 8)))  -- 取高 8 位
            table.insert(result, string.char(byte))
            value = value % (2 ^ (bits - 8))  -- 保留剩余位数
            bits = bits - 8
        end
    end
    
    -- 处理剩余不足 8 位的情况（补 0 凑整）
    if bits > 0 then
        local byte = math.floor(value / (2 ^ (8 - bits)))  -- 补 0 后取 8 位
        table.insert(result, string.char(byte))
    end
    
    return table.concat(result), nil  -- 返回解码后的字节字符串
end

-- 3. SHA-1哈希算法(TOTP 加密基础)
-- SHA-1用于生成消息摘要，是HMAC-SHA1的基础。
-- 左旋转函数（SHA-1 核心操作）
local function rotl32(n, b)
    b = b % 32  -- 旋转位数取模（防止溢出）
    -- 左旋转 b 位，溢出部分补到右侧
    return bit32.band(bit32.lshift(n, b), 0xFFFFFFFF) + bit32.rshift(n, 32 - b)
end

-- 消息填充（SHA-1 要求消息长度为 512 位的倍数）
local function pad_message(message)
    local length_bits = #message * 8  -- 消息长度（位）
    if length_bits > 0x7FFFFFFFFFFFFFFF then  -- 超过 64 位表示范围
        error("Message too long for SHA-1 padding")
    end
    
    -- 步骤1：添加 0x80 标记
    local padded = message .. string.char(0x80)
    -- 步骤2：补 0 直到长度 ≡ 448 mod 512（留出 64 位存长度）
    while (#padded * 8) % 512 ~= 448 do
        padded = padded .. string.char(0x00)
    end    
    -- 步骤3：添加 64 位长度（大端序）
    local length_bytes = {}
    for i = 7, 0, -1 do  -- 从高位到低位
        local byte_val = bit32.band(math.floor(length_bits / (256 ^ i)), 0xFF)
        table.insert(length_bytes, string.char(byte_val))
    end    
    return padded .. table.concat(length_bytes)
end

-- 将 64 字节消息块转为 16 个 32 位字（SHA-1 处理单位）
local function words_from_block(block)
    local words = {}
    for j = 1, 16 do  -- 64字节 = 16 * 4字节
        local start = (j - 1) * 4 + 1
        local end_pos = start + 3
        -- 按大端序拼接 4 字节为 32 位字
        local byte1, byte2, byte3, byte4 = block:byte(start, end_pos)
        byte2 = byte2 or 0  -- 处理不足 4 字节的情况
        byte3 = byte3 or 0
        byte4 = byte4 or 0
        
        words[j] = bit32.bor(
            bit32.lshift(byte1, 24),  -- 最高位字节
            bit32.lshift(byte2, 16),
            bit32.lshift(byte3, 8),
            byte4  -- 最低位字节
        )
    end
    return words
end

-- SHA-1 哈希函数
function _M.sha1(message)
    -- 初始化哈希值（FIPS 180-4 标准）
    local H0 = 0x67452301
    local H1 = 0xEFCDAB89
    local H2 = 0x98BADCFE
    local H3 = 0x10325476
    local H4 = 0xC3D2E1F0

    -- 消息填充
    local padded = pad_message(message)

    -- 分块处理（每块 512 位 = 64 字节）
    for i = 1, #padded, 64 do
        local block = padded:sub(i, i + 63)  -- 取 64 字节块
        local words = words_from_block(block)  -- 转为 16 个 32 位字
        
        -- 扩展为 80 个 32 位字
        for t = 17, 80 do
            -- 第 t 个字 = 前 t-3、t-8、t-14、t-16 个字异或后左旋转 1 位
            local word = bit32.bxor(words[t - 3], words[t - 8], words[t - 14], words[t - 16])
            words[t] = rotl32(word, 1)
        end
        
        -- 主循环：更新哈希值
        local A, B, C, D, E = H0, H1, H2, H3, H4  -- 临时变量
        
        for t = 1, 80 do
            local temp, f, k  -- f 为函数，k 为常量（分 4 轮）
            local t_idx = t - 1  -- 0-79
            
            if t_idx < 20 then  -- 第 1 轮（0-19）
                f = bit32.bor(bit32.band(B, C), bit32.band(bit32.bnot(B), D))
                k = 0x5A827999
            elseif t_idx < 40 then  -- 第 2 轮（20-39）
                f = bit32.bxor(B, C, D)
                k = 0x6ED9EBA1
            elseif t_idx < 60 then  -- 第 3 轮（40-59）
                f = bit32.bor(bit32.band(B, C), bit32.band(B, D), bit32.band(C, D))
                k = 0x8F1BBCDC
            else  -- 第 4 轮（60-79）
                f = bit32.bxor(B, C, D)
                k = 0xCA62C1D6
            end
            
            -- 核心计算：A = (A 左旋 5 位) + f + E + 第 t 个字 + k
            temp = bit32.band(rotl32(A, 5) + f + E + words[t] + k, 0xFFFFFFFF)  -- 限制为 32 位
            
            -- 寄存器移位
            E = D
            D = C
            C = rotl32(B, 30)  -- B 左旋 30 位
            B = A
            A = temp
        end
        
        -- 累加哈希值（更新全局哈希值）
        H0 = bit32.band(H0 + A, 0xFFFFFFFF)
        H1 = bit32.band(H1 + B, 0xFFFFFFFF)
        H2 = bit32.band(H2 + C, 0xFFFFFFFF)
        H3 = bit32.band(H3 + D, 0xFFFFFFFF)
        H4 = bit32.band(H4 + E, 0xFFFFFFFF)
    end
    
    -- 转换哈希值为字节字符串（每个哈希值 4 字节，共 20 字节）
    local hash_bytes = {}
    for i, h in ipairs({H0, H1, H2, H3, H4}) do
        for j = 3, 0, -1 do  -- 大端序
            local byte_val = bit32.band(bit32.rshift(h, j * 8), 0xFF)
            table.insert(hash_bytes, string.char(byte_val))
        end
    end   
    return table.concat(hash_bytes)
end

-- 4.HMAC-SHA1算法(TOTP核心)
-- HMAC是基于哈希的消息认证码,TOTP通过HMAC-SHA1(密钥，时间步)生成验证码。
function _M.hmac_sha1(key, data)
    -- 参数校验
    if type(key) ~= "string" or type(data) ~= "string" then
        log.error("hmac_sha1: 非法参数类型")
        return nil, "INVALID_PARAM_TYPE"
    end
    
    -- 处理密钥：若长度 >64 字节，先用 SHA-1 压缩为 20 字节
    if #key > 64 then
        key = _M.sha1(key)
    end
    
    -- 填充密钥到 64 字节（HMAC 要求）
    key = key .. string.rep("\0", 64 - #key)  -- 不足部分补 0
    
    -- 生成内键（与 0x36 异或）和外键（与 0x5C 异或）
    local inner_key = {}
    local outer_key = {}
    for i = 1, 64 do
        local byte_val = key:byte(i)
        table.insert(inner_key, string.char(bit32.bxor(byte_val, 0x36)))  -- 内键异或 0x36
        table.insert(outer_key, string.char(bit32.bxor(byte_val, 0x5C)))  -- 外键异或 0x5C
    end    
    local inner_key_str = table.concat(inner_key)
    local outer_key_str = table.concat(outer_key)
    
    -- 计算 HMAC 值：HMAC = SHA1(外键 + SHA1(内键 + 数据))
    local inner_hash = _M.sha1(inner_key_str .. data)
    if not inner_hash then
        return nil, "INNER_HASH_FAILED"
    end
    
    local outer_hash = _M.sha1(outer_key_str .. inner_hash)
    return outer_hash, nil
end

-- 5.TOTP 验证码生成与验证
-- 5.1生成TOTP验证码
function _M.generate_totp(base32_secret, time_step, digits, allow_lowercase)
    -- 参数默认值
    time_step = time_step or 30  -- 时间步长（默认30秒）
    digits = digits or 6         -- 验证码位数（默认6位）
    allow_lowercase = allow_lowercase or true  -- 允许小写密钥
    
    -- 参数校验
    if type(base32_secret) ~= "string" or base32_secret == "" then
        log.error("generate_totp: 非法密钥")
        return nil, "INVALID_SECRET"
    end
    if time_step <= 0 or digits < 6 or digits > 8 then
        log.error("generate_totp: 非法参数范围")
        return nil, "INVALID_PARAMS"
    end
    
    -- 解码 Base32 密钥
    local secret, err = _M.base32_decode(base32_secret, allow_lowercase)
    if not secret then
        log.error("generate_totp: 密钥解码失败")
        return nil, err
    end
    
    -- 计算当前时间步（counter = 当前时间 / 时间步长，取整数）
    local current_time = os.time()
    local counter = math.floor(current_time / time_step)
    
    -- 将 counter 转为 8 字节大端序（TOTP 要求）
    local counter_bytes = {}
    for i = 7, 0, -1 do  -- 从高位到低位
        local byte_val = bit32.band(math.floor(counter / (256 ^ i)), 0xFF)
        counter_bytes[#counter_bytes + 1] = string.char(byte_val)
    end
    local counter_str = table.concat(counter_bytes)
    
    -- 计算 HMAC-SHA1(密钥, counter)
    local hash, err = _M.hmac_sha1(secret, counter_str)
    if not hash then
        log.error("generate_totp: HMAC 计算失败")
        return nil, err
    end
    
    -- 动态截断（DT，取哈希值的一部分生成数字）
    local offset = bit32.band(hash:byte(20), 0x0F)  -- 取第20字节的低4位作为偏移量
    
    -- 从偏移量开始取 4 字节，最高位设为 0（避免符号问题）
    local binary_code = 0
    for i = 1, 4 do
        local byte_val = hash:byte(offset + i)
        binary_code = bit32.bor(binary_code, bit32.lshift(byte_val, (4 - i) * 8))
    end
    binary_code = bit32.band (binary_code, 0x7FFFFFFF) -- 清除最高位，确保为正数

    -- 计算验证码（取模 10^digits，不足位数补 0）
    local otp = binary_code % (10 ^ digits)
    return string.format ("%0" .. digits .. "d", otp), nil
end

-- 5.2验证TOTP验证码* 
-- 支持时间窗口容错（默认前后各1个时间步，共3个窗口），解决网络延迟导致的验证失败问题。  
function _M.verify_totp(base32_secret, code, time_step, digits, window, allow_lowercase)
    -- 参数默认值
    time_step = time_step or 30
    digits = digits or 6
    window = window or 1  -- 时间窗口（默认±1个时间步）
    allow_lowercase = allow_lowercase or true
    
    -- 验证码格式校验（必须为数字）
    if type(code) ~= "string" or not code:match("^%d+$") then
        log.error("verify_totp: 验证码格式非法")
        return false, "INVALID_CODE_FORMAT"
    end
    
    -- 计算当前时间步
    local current_time = os.time()
    local current_counter = math.floor(current_time / time_step)
    
    -- 验证时间窗口内的所有可能时间步（如 window=1 则验证 current_counter-1、current_counter、current_counter+1）
    for i = -window, window do
        local counter_try = current_counter + i
        
        -- 生成对应时间步的验证码
        local otp, err = _M.generate_totp(base32_secret, time_step, digits, allow_lowercase)
        if not otp then
            log.error("verify_totp: 生成验证码失败")
            return false, err
        end
        
        -- 安全比较验证码（防止时序攻击）
        if _M.safe_compare(otp, code) then
            log.info("verify_totp: 验证成功，时间步=", counter_try)
            return true, "VALID", counter_try
        end
    end
    
    log.info("verify_totp: 所有时间窗口验证失败")
    return false, "INVALID", current_counter
end
-- 6.安全辅助函数
-- 6.1安全比较(防止时序攻击)
-- 普通字符串比较（如 ==）可能因比较时长泄露字符串差异信息，安全比较确保无论匹配与否，耗时一致。
function _M.safe_compare(a, b)
    if #a ~= #b then  -- 长度不同直接返回 false
        return false
    end
    
    local result = 0
    -- 逐字节比较，累计差异（即使中途发现差异，仍会比较完所有字节）
    for i = 1, #a do
        result = result + (string.byte(a, i) ~= string.byte(b, i) and 1 or 0)
    end
    return result == 0  -- 无差异则返回 true
end
-- 6.2生成Base32密钥(用于初始化用户TOTP密钥)
function _M.generate_secret(length, use_lowercase)
    length = length or 16  -- 密钥长度（默认16字节，128位）
    use_lowercase = use_lowercase or true  -- 生成小写密钥（兼容常见工具）
    
    -- 生成随机字节（优先使用 Nginx 共享内存的随机源）
    local bytes = ngx.shared.random and ngx.shared.random:bytes(length, true)
    if not bytes then
        -- 备选方案：使用 math.random（安全性较低，适合测试）
        bytes = ""
        for i = 1, length do
            bytes = bytes .. string.char(math.random(0, 255))
        end
    end
    
    -- 编码为 Base32
    local encoded, err = _M.base32_encode(bytes, use_lowercase)
    if not encoded then
        error("生成密钥失败: " .. (err or "未知错误"))
    end
    
    return encoded
end
-- 6.3Base32编码(用于生成密钥)
function _M.base32_encode(input, use_lowercase)
    if not input or #input == 0 then
        return nil, "EMPTY_INPUT"
    end
    
    -- 转换输入为字节数组
    local bytes = {}
    for i = 1, #input do
        bytes[i] = string.byte(input, i)
    end
    
    -- 计算输出长度（每5字节输入对应8字节Base32输出）
    local len = #bytes
    local rem = len % 5
    local out_len = ((len - rem) / 5) * 8
    if rem > 0 then
        out_len = out_len + 8  -- 不足5字节的部分也按8字符处理
    end
    
    -- 编码核心逻辑
    local output = ""
    -- 按5字节块处理
    for i = 0, len - 5, 5 do
        local chunk = {}
        for j = 0, 4 do  -- 取5字节
            if i + j < len then
                chunk[j + 1] = bytes[i + j + 1]
            else
                chunk[j + 1] = 0  -- 补0
            end
        end
        
        -- 将5字节（40位）拆分为8个5位值
        local value = bit32.bor(
            bit32.lshift(chunk[1], 32),  -- 第1字节左移32位
            bit32.lshift(chunk[2], 24),
            bit32.lshift(chunk[3], 16),
            bit32.lshift(chunk[4], 8),
            chunk[5]
        )
        
        -- 提取8个5位值，映射到Base32字符
        for j = 0, 7 do
            local idx = bit32.band(bit32.rshift(value, (7 - j) * 5), 0x1F) + 1  -- 1-32
            local char = string.sub(BASE32_UPPER, idx, idx)
            -- 转为小写（如果需要）
            if use_lowercase and idx <= 26 then  -- 字母部分（A-Z）转为小写
                char = string.lower(char)
            end
            output = output .. char
        end
    end
    
    -- 添加填充符（=）确保输出长度为8的倍数
    if rem > 0 then
        output = output .. string.rep(BASE32_PAD, 8 - ((len * 8) % 40) / 5)
    end
    
    return output, nil
end
-- 6. 模块导出
return _M

博文来自：www.51niux.com

1.7 ip_utils.lua

#该文件是IP地址校验工具模块，主要用于检查客户端IP是否在预定义的白名单中。支持两种匹配模式(精确匹配:直接判断IP是否存在于白名单/CIDR匹配:判断IP是否属于某个网段(如192.168.1.0/24))

# vi /usr/local/nginx/conf/auth/ip_utils.lua

-- 1. 模块初始化与依赖
local whitelist_cache = ngx.shared.ip_whitelist_cache  -- Nginx 共享内存缓存
local log = require("log_utils")  -- 日志工具
local bit = require("bit")  -- 位操作库（用于 CIDR 计算）

local _M = {}  -- 模块对象

-- 主校验函数:检查IP是否在白名单
function _M.check_ip_whitelist(ip)
    -- 高效缓存机制,使用Nginx共享内存缓存白名单，避免重复读取配置
    -- 检查白名单是否已初始化（缓存中应有 "initialized" 标记）
    if not whitelist_cache:get("initialized") then
        log.error("白名单未初始化")
        return false
    end
    
    -- 步骤1：精确匹配
    -- 先精确匹配再CIDR匹配，减少不必要的计算
    if whitelist_cache:get("entry:" .. ip) then
        log.debug("IP在白名单中（精确匹配）: " .. ip)
        return true
    end
    
    -- 步骤2：CIDR匹配（遍历所有 CIDR 格式的白名单条目）
    -- 批量获取缓存键(get_keys)，提升CIDR匹配效率
    local keys = whitelist_cache:get_keys(1000)  -- 获取缓存中的前1000个键
    for _, key in ipairs(keys) do
        if key:find("entry:", 1, true) == 1 then  -- 只处理以 "entry:" 开头的键
            local cidr = key:sub(7)  -- 提取实际的 IP/CIDR
            if cidr:find("/") and _M.ip_in_cidr(ip, cidr) then  -- 检查是否为 CIDR 格式并调用匹配函数
                log.debug("IP在白名单中（CIDR匹配）: " .. ip .. " in " .. cidr)
                return true
            end
        end
    end
    
    -- 未匹配任何白名单条目
    return false
end

-- 3.CIDR 匹配核心函数
-- 判断一个IP是否属于某个CIDR网段(如192.168.1.0/24)
function _M.ip_in_cidr(ip, cidr)
    -- 解析输入IP为四个十进制数（如 "192.168.1.1" → {192, 168, 1, 1}）
    local ip_octets = {}
    for octet in ip:gmatch("%d+") do
        table.insert(ip_octets, tonumber(octet))
    end
    if #ip_octets ~= 4 then return false end  -- 非合法IPv4地址
    
    -- 将IP转换为32位整数（用于位运算）
    local function ip_to_int(octets)
        return octets[1] * 256^3 + octets[2] * 256^2 + octets[3] * 256 + octets[4]
    end
    local ip_int = ip_to_int(ip_octets)
    
    -- 解析CIDR格式（如 "192.168.1.0/24" → base_ip="192.168.1.0", mask=24）
    local base_ip, mask = cidr:match("^([%d.]+)/(%d+)$")
    if not base_ip then
        return ip == cidr  -- 非CIDR格式（如纯IP），直接精确匹配
    end
    
    -- 解析基础IP（CIDR中的网络地址部分）
    local base_octets = {}
    for octet in base_ip:gmatch("%d+") do
        table.insert(base_octets, tonumber(octet))
    end
    if #base_octets ~= 4 then return false end  -- 非合法IPv4地址
    
    local base_int = ip_to_int(base_octets)
    mask = tonumber(mask)  -- CIDR掩码位数（如24）    
    -- 通过位运算(bit.band、bit.lshift)实现高效网段匹配 
    -- 计算32位掩码（如 /24 → 255.255.255.0 → 0xFFFFFF00）
    local mask_int = mask == 0 and 0 or bit.lshift(0xFFFFFFFF, 32 - mask)
    
    -- 判断IP是否在CIDR网段内：
    -- 1. 将IP和基础IP分别与掩码做AND运算
    -- 2. 比较结果是否相同（相同则表示在同一网段）
    return bit.band(ip_int, mask_int) == bit.band(base_int, mask_int)
end

return _M

1.8 init_whitelist.lua

#该文件是IP白名单加载模块，负责从配置文件读取IP白名单规则，并将其加载到Nginx共享内存中

# vi /usr/local/nginx/conf/auth/init_whitelist.lua

local config = require("config")  -- 全局配置模块（包含白名单文件路径）
local whitelist_cache = ngx.shared.ip_whitelist_cache  -- Nginx共享内存
local log = require("log_utils")  -- 日志工具
local ip_utils = require("ip_utils")  -- IP处理工具（此处未直接使用，但可能用于验证）

local _M = {}  -- 模块对象
-- 2. 白名单加载函数
function _M.load_whitelist() 
    log.info("加载IP白名单...")
    
    -- 步骤1：打开白名单文件
    local file, err = io.open(config.whitelist.file, "r")
    if not file then 
        log.error("无法打开白名单文件: " .. err)
        return false
    end
    
    -- 步骤2：清空现有缓存（避免旧规则残留）
    whitelist_cache:flush_all()
    
    -- 步骤3：逐行读取文件并加载到缓存
    local count = 0  -- 记录加载的规则数量
    for line in file:lines() do 
        line = line:gsub("^%s+", ""):gsub("%s+$", "")  -- 去除首尾空格
        
        -- 跳过空行和注释（以#开头的行）
        if line ~= "" and not line:find("^#") then 
            -- 将IP/CIDR存入缓存，键格式为 "entry:IP/CIDR"，值为true
            -- 共享内存高效存储：支持多进程共享/每条规则以entry:IP/CIDR为键，避免键冲突并便于后续查询
            whitelist_cache:set("entry:" .. line, true)
            count = count + 1
        end
    end
    
    file:close()  -- 关闭文件
    
    -- 步骤4：存储元数据（标记初始化状态和统计信息）
    whitelist_cache:set("initialized", true)  -- 标记白名单已初始化
    whitelist_cache:set("last_loaded", ngx.time())  -- 记录加载时间戳,便于监控配置更新频率
    whitelist_cache:set("count", count)  -- 记录规则总数,用于运行时校验
            
    log.info("白名单加载完成，共 " .. count .. " 条记录")
    return true
end

return _M

# echo "127.0.0.1" >> /usr/local/nginx/conf/auth/ip_whitelist.txt #创建一个白名单文件防止启动报错

1.9 init_by_lua.lua

#该文件是Nginx启动时的初始化脚本，其核心功能是在Nginx启动阶段加载IP白名单配置到共享内存，并标记初始化状态，为后续请求的 IP 校验做准备。

# vi /usr/local/nginx/conf/auth/init_by_lua.lua

-- 加载白名单初始化模块
-- 模块化设计:引入独立模块，将白名单加载逻辑与初始化入口分离，提高可维护性。
local init_whitelist = require("init_whitelist")

-- 执行白名单加载，返回布尔值表示成功/失败
local success = init_whitelist.load_whitelist()

-- 根据加载结果设置状态并记录日志
if not success then
    ngx.log(ngx.ERR, "白名单初始化失败，系统将拒绝所有请求")
    -- 设置初始化标记为 false（关键！后续请求校验会拒绝所有IP）
    -- 共享内存缓存:使用ngx.shared.ip_whitelist_cache存储白名单数据，这是Nginx进程间共享的内存区域，所有工作进程均可访问。
    ngx.shared.ip_whitelist_cache:set("initialized", false)
else
    ngx.log(ngx.INFO, "白名单初始化成功")
end

1.10 init_worker.lua

#该文件是 Nginx 工作进程初始化脚本，其核心功能是：在每个Nginx 工作进程启动时执行初始化任务、实现IP白名单的定时自动刷新机制、通过分布式锁保证多进程

#该脚本与 init_by_lua.lua 互补，前者负责全局初始化，后者负责工作进程级别的初始化和定时任务

# vi /usr/local/nginx/conf/auth/init_worker.lua

local config = require("config")  -- 全局配置
local whitelist_cache = ngx.shared.ip_whitelist_cache  -- 共享内存缓存
local log = require("log_utils")  -- 日志工具
local MAX_RETRIES = 3  -- 最大重试次数

-- 2.安全加载模块工具函数
-- 作用：使用 pcall 安全加载 Lua 模块，捕获并记录加载异常，避免因模块缺失导致进程崩溃。
local function safe_require(module_name)
    local status, result = pcall(require, module_name)
    if not status then
        log.error("模块加载失败: " .. module_name .. ", 错误: " .. result)
        return nil
    end
    return result
end

-- 3.白名单重载函数
-- 核心逻辑：检查是否达到配置的刷新间隔、通过共享内存锁(reload_lock)实现分布式锁机制、仅获取锁的进程执行白名单刷新，避免多进程重复操作
local function reload_whitelist()
    local init_whitelist = safe_require("init_whitelist")
    if not init_whitelist then
        return false
    end
    
    local now = ngx.time()  -- 当前时间戳
    local last_load_time = whitelist_cache:get("last_loaded") or 0  -- 上次加载时间
    
    -- 判断是否达到刷新间隔（配置中定义，如 300 秒）
    if now - last_load_time >= config.whitelist.reload_interval then
        -- 亮点1:分布式锁机制：通过whitelist_cache:add("reload_lock")实现跨进程同步使用、锁有效期(30秒)防止死锁
        local ok, err = whitelist_cache:add("reload_lock", true, 30)
        if ok then
            log.info("工作进程 " .. ngx.worker.pid() .. " 重新加载白名单")
            local success = init_whitelist.load_whitelist()  -- 调用实际加载函数
            whitelist_cache:delete("reload_lock")  -- 释放锁
            return success
        elseif err ~= "exists" then
            log.error("获取白名单加载锁失败: " .. err)
        end
    end
    
    return true  -- 时间未到或锁被占用，视为成功
end

-- 4.定时器初始化函数
-- 关键点：使用ngx.timer.every创建周期性定时器\配置刷新间隔动态调整、处理premature标志，避免定时器提前终止时的异常
local function init_timers()
    -- 亮点2：定时自动刷新：基于ngx.timer.every的非阻塞定时器，不影响正常请求处理、刷新间隔可配置，支持动态调整
    local ok, err = ngx.timer.every(config.whitelist.reload_interval, function(premature)
        if premature then return end  -- 定时器提前终止时退出
        reload_whitelist()  -- 执行白名单刷新
    end)
    
    if not ok then
        log.error("创建白名单定时任务失败: " .. err)
        return false
    end
    
    log.info("白名单定时任务创建成功，间隔: " .. config.whitelist.reload_interval .. " 秒")
    return true
end

-- 5.工作进程初始化主函数
-- 重试机制：首次加载白名单失败时自动重试(最多3次)、每次重试间隔0.5秒,提高初始化成功率
local function init_worker()
    log.info("工作进程初始化开始 (PID: " .. ngx.worker.pid() .. ")")
    
    -- 首次加载白名单（带重试机制）
    local retries = 0
    local success = false
    while retries < MAX_RETRIES and not success do
        success = reload_whitelist()
        retries = retries + 1
        if not success then 
            ngx.sleep(0.5)  -- 失败时等待 0.5 秒后重试
        end
    end
    
    if not success then
        log.error("白名单首次加载失败，尝试次数: " .. MAX_RETRIES)
    end
    
    -- 初始化定时器
    init_timers()
    
    log.info("工作进程初始化完成 (PID: " .. ngx.worker.pid() .. ")")
end

-- 6.安全执行初始化
local status, err = pcall(init_worker)
if not status then
    log.error("工作进程初始化异常: " .. err)
end

1.11 auth.lua

#该文件是认证网关核心模块，负责对客户端请求进行多层级认证(IP 白名单、会话验证、TOTP 验证码），并实现免认证URL控制、会话管理、安全防护等功能。作为 Nginx 请求处理链路的关键环节，它决定请求是否被允许访问后端服务。

# vi /usr/local/nginx/conf/auth/auth.lua

-- 第一部分:模块依赖与初始化
local config = require("config")  -- 全局配置（含免认证规则、会话设置等）
local redis_utils = require("redis_utils")  -- Redis操作工具（会话存储、用户状态）
local db_utils = require("db_utils")  -- 数据库工具（用户密钥查询）
local ip_utils = require("ip_utils")  -- IP白名单校验工具
local totp_utils = require("totp_utils")  -- TOTP验证码生成与验证
local log = require("log_utils")  -- 日志工具

-- 第二部分:基础工具函数
-- 2.1. 安全日志处理
local function safe_log_value(value)
    if not value or value == "" then
        return "[空值]"  -- 明确标记空值，避免日志显示空白
    end
    -- 过滤不可见字符（如控制字符、特殊符号），防止日志格式混乱
    return tostring(value):gsub("[^%w%p ]", "?")
end
-- 2.2.免认证URL检查
-- 2.2.1 免认证规则匹配逻辑
local function is_skip_auth(url, skip_rules)
    -- 精确匹配（URL完全一致）
    if skip_rules[url] then
        return true
    end
    -- 前缀匹配（规则以"/"结尾时，匹配所有以此为前缀的URL）
    for pattern, _ in pairs(skip_rules) do
        if string.sub(pattern, -1) == "/" and string.sub(url, 1, #pattern) == pattern then
            return true
        end
    end
    return false
end

-- 2.2.2 免认证检查入口
local function check_skip_auth()
    local current_url = ngx.var.uri  -- 当前请求URL
    local current_host = ngx.var.host  -- 当前请求域名
    local log_prefix = "[免认证检查] "

    -- 检查全局免认证URL（所有域名生效）
    if config.skip_auth_global and type(config.skip_auth_global) == "table" then
        if is_skip_auth(current_url, config.skip_auth_global) then
            log.info(log_prefix .. "全局免认证URL，允许访问（url: " .. safe_log_value(current_url) .. "）")
            return true
        end
    end

    -- 检查域名级免认证URL（仅当前域名生效）
    if config.skip_auth_domain and type(config.skip_auth_domain) == "table" then
        local domain_rules = config.skip_auth_domain[current_host]
        if domain_rules and type(domain_rules) == "table" then
            if is_skip_auth(current_url, domain_rules) then
                log.info(log_prefix .. "域名级免认证URL，允许访问（host: " .. safe_log_value(current_host) .. ", url: " .. safe_log_value(current_url) .. "）")
                return true
            end
        end
    end

    return false  -- 需要认证
end
-- 2.3. 客户端 IP 获取
local function get_client_ip()
    local ip = ngx.var.remote_addr  -- 直接客户端IP
    local xff = ngx.var.http_x_forwarded_for  -- 代理链IP列表（X-Forwarded-For）
    if xff then
        -- 取最原始客户端IP（X-Forwarded-For格式：client_ip, proxy1_ip, proxy2_ip）
        local first_ip = string.match(xff, "^([^,]+)")
        ip = first_ip or ip
    end
    return ip
end

-- 第三部分：认证页面渲染
-- 3.1 HTML模板加载
-- 从文件系统加载HTML模板，支持通过配置动态指定模板路径，便于前端页面定制
local function load_template(name)
    if not name then
        log.error("模板名称为空")
        return "<p>系统错误：模板名称为空</p>"
    end

    local path = config.templates and config.templates[name]  -- 从配置获取模板路径
    if not path then
        log.error("模板路径未配置，模板名称: " .. name)
        return "<p>系统错误：模板未配置</p>"
    end

    -- 读取模板文件
    local file, err = io.open(path, "r")
    if not file then
        log.error("模板加载失败（路径: " .. path .. "）：" .. (err or "未知错误"))
        return "<p>系统错误：模板加载失败</p>"
    end

    local content = file:read("*a")
    file:close()
    return content or "<p>系统错误：模板内容为空</p>"
end
-- 3.2. 认证弹窗渲染
-- 生成认证弹窗页面，支持动态显示错误信息和剩余尝试次数，同时通过响应头禁用缓存，确保页面实时性。
local function show_auth_popup(redirect_url, error_msg, remaining_attempts)
    error_msg = error_msg or ""
    remaining_attempts = remaining_attempts or (config.auth and config.auth.max_attempts or 3)
    -- 错误信息显示控制（有错误时显示，否则隐藏）
    local display = error_msg ~= "" and "block" or "none"

    local template = load_template("auth_popup")  -- 加载弹窗模板
    -- 替换模板变量（将动态内容注入HTML）
    template = string.gsub(template, "{redirect_url}", redirect_url or "")
    template = string.gsub(template, "{error_msg}", error_msg)
    template = string.gsub(template, "{error_display}", display)
    template = string.gsub(template, "{remaining_attempts}", tostring(remaining_attempts))

    -- 设置响应头（禁用缓存、指定HTML类型）
    ngx.header["Content-Type"] = "text/html; charset=utf-8"
    ngx.header["Cache-Control"] = "no-store, no-cache, must-revalidate"
    ngx.header["Pragma"] = "no-cache"
    ngx.header["Expires"] = "0"
    ngx.say(template)  -- 输出HTML内容
    return false
end

-- 第四部分：用户状态管理
-- 4.1.封禁状态检查
-- 作用：检查用户是否因多次认证失败被封禁，为登录限流提供支持
local function check_ban_status(username)
    if not username then
        return false, "用户名不能为空"
    end
    -- 调用redis_utils查询封禁状态（封装Redis操作）
    local is_banned = redis_utils.is_user_banned(username)
    if is_banned then
        return true, "账号已封禁，请20分钟后重试"
    end
    return false, nil
end
-- 4.2.认证尝试次数记录
-- 核心机制：通过Redis的INCR命令原子记录失败次数，达到阈值时自动封禁用户，防止暴力破解。
local function record_attempt(username)
    if not username then
        log.error("记录尝试次数失败：用户名为空")
        return (config.auth and config.auth.max_attempts or 3)
    end
    -- 调用redis_utils记录失败次数（封装Redis自增操作）
    local attempts = redis_utils.record_attempt(username)
    if not attempts then
        log.error("记录尝试次数失败，用户: " .. safe_log_value(username))
        return (config.auth and config.auth.max_attempts or 3)
    end
    -- 达到最大尝试次数时自动封禁
    if attempts <= 0 then
        redis_utils.ban_user(username)
        log.warn("用户尝试次数超限，已封禁: " .. safe_log_value(username))
        return 0
    end
    return attempts
end

-- 第五部分：Cookie操作(会话管理核心)
-- 5.1. Cookie 读取
local function get_cookie(name)
    if not name then
        log.error("获取Cookie失败：Cookie名称为空")
        return nil
    end
    local cookie_header = ngx.var.http_cookie  -- 原始Cookie头
    log.info("请求Cookie头: " .. safe_log_value(cookie_header))
    
    if not cookie_header then
        log.info("未找到Cookie头")
        return nil
    end
    
    -- 解析Cookie（按";"分割，提取目标Cookie）
    local values = {}
    for cookie in string.gmatch(cookie_header, "[^;]+") do
        local key, value = cookie:match("^%s*(.-)%s*=%s*(.-)%s*$")
        if key and key == name then
            table.insert(values, value or "")
        end
    end
    
    -- 处理多值Cookie（取第一个）
    if #values == 0 then
        log.info("未找到指定Cookie: " .. name)
        return nil
    elseif #values > 1 then
        log.warn("发现" .. #values .. "个同名Cookie（名称: " .. name .. "），使用第一个值")
        return values[1]
    end
    
    -- 清洗Cookie值（仅保留字母数字，避免注入风险）
    local clean_value = string.gsub(values[1], "%s+", "")
    log.info("找到Cookie: " .. name .. "（清洗后: " .. safe_log_value(clean_value) .. "）")
    return clean_value
end
-- 5.2. Cookie 设置
local function set_cookie(name, value, expire_seconds)
    if not name or not value then
        log.error("设置Cookie失败：名称或值为空")
        return nil
    end
    -- 从配置读取Cookie属性（带默认值）
    local session_conf = config.session or {}
    local domain = session_conf.cookie_domain or ""
    local path = session_conf.cookie_path or "/"
    local secure = session_conf.cookie_secure or false  -- HTTPS时启用Secure标记
    local http_only = session_conf.cookie_http_only or true  -- 防止JS读取

    -- 清洗会话ID（仅保留字母数字，避免注入风险）
    local safe_value = string.gsub(value, "[^a-zA-Z0-9]", "")
    if safe_value ~= value then
        log.warn("会话ID包含特殊字符，已清洗: " .. safe_log_value(value) .. " → " .. safe_value)
        value = safe_value
    end

    -- 构建Cookie字符串
    local cookie = string.format("%s=%s", name, value)
    
    -- 添加domain（支持子域名共享）
    if domain and domain ~= "" then
        if not string.match(domain, "^%.") and domain ~= ngx.var.host then
            domain = "." .. domain  -- 自动补全前缀点（如 "example.com" → ".example.com"）
        end
        cookie = cookie .. "; Domain=" .. domain
    end
    
    -- 添加路径和过期时间
    cookie = cookie .. "; Path=" .. path
    if expire_seconds and expire_seconds > 0 then
        local expire_time = ngx.cookie_time(ngx.time() + expire_seconds)  -- 转换为Cookie时间格式
        cookie = cookie .. "; Expires=" .. expire_time .. "; Max-Age=" .. expire_seconds
    end
    
    -- 安全属性
    if secure and ngx.var.scheme == "https" then
        cookie = cookie .. "; Secure"  -- 仅HTTPS传输
    end
    if http_only then
        cookie = cookie .. "; HttpOnly"  -- 禁止JS访问
    end
    
    -- SameSite属性（防CSRF）
    cookie = cookie .. "; SameSite=" .. (secure and "None" or "Lax")

    ngx.header["Set-Cookie"] = cookie
    log.info("设置Cookie: " .. cookie)
    return value
end
-- 5.3. Cookie删除
-- 通过多路径/多域名组合删除 Cookie，确保在各种配置下都能彻底清除无效会话，避免残留的无效Cookie导致认证异常
local function delete_cookie(name)
    if not name then
        log.error("删除Cookie失败：名称为空")
        return
    end
    local session_conf = config.session or {}
    local domain = session_conf.cookie_domain or ""
    local path = session_conf.cookie_path or "/"
    
    -- 构建删除Cookie（过期时间设为过去）
    local cookie = string.format("%s=deleted; Path=%s; Expires=Thu, 01 Jan 1970 00:00:00 GMT", name, path)
    if domain and domain ~= "" then
        if not string.match(domain, "^%.") and domain ~= ngx.var.host then
            domain = "." .. domain
        end
        cookie = cookie .. "; Domain=" .. domain
    end
    
    -- 关键修复：覆盖所有可能的Cookie路径/域名组合（避免残留）
    local cookies = {cookie}
    -- 添加根路径Cookie删除（防止路径不匹配）
    if path ~= "/" then
        table.insert(cookies, string.format("%s=deleted; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Domain=%s", name, domain))
    end
    -- 添加无域名Cookie删除（兼容不同域名配置）
    table.insert(cookies, string.format("%s=deleted; Path=%s; Expires=Thu, 01 Jan 1970 00:00:00 GMT", name, path))
    
    ngx.header["Set-Cookie"] = cookies
    log.info("删除Cookie: " .. table.concat(cookies, "; "))
end

-- 第六部分：主认证流程（核心逻辑）
local function authenticate()
    local client_ip = get_client_ip()
    local log_prefix = "IP:" .. client_ip .. " - "

    -- 6.1. 全局禁用缓存（避免认证页面被缓存）
    ngx.header["Cache-Control"] = "no-store, no-cache, must-revalidate"
    ngx.header["Pragma"] = "no-cache"
    ngx.header["Expires"] = "0"

    -- 6.2. 免认证URL检查（优先级最高）
    if check_skip_auth() then
        log.info(log_prefix .. "URL在免认证列表中，允许访问")
        return true
    end

    -- 6.3. IP白名单检查（跳过认证）
    if ip_utils.check_ip_whitelist(client_ip) then
        log.info(log_prefix .. "IP在白名单中，允许访问")
        return true
    end

    -- 6.4. 会话验证（从Cookie获取session_id）
    local session_conf = config.session or {}
    local session_id = get_cookie(session_conf.cookie_name or "session_id")
    log.info(log_prefix .. "当前会话ID: " .. safe_log_value(session_id))

    if session_id and session_id ~= "" then
        -- 调用redis_utils统一处理会话验证（封装本地缓存+Redis查询）
        local username = redis_utils.get_user_session(session_id)
        
        -- 验证用户名有效性（防脏数据）
        if username and type(username) == "string" and username ~= "" and not string.find(username, "userdata:") then
            log.info(
                log_prefix .. "会话有效，" ..
                "session_id: [" .. safe_log_value(session_id) .. "], " ..
                "用户: [" .. safe_log_value(username) .. "]"
            )
            return true
        else
            log.info(
                log_prefix .. "会话无效（用户名无效），清理资源，" ..
                "session_id: [" .. safe_log_value(session_id) .. "], " ..
                "用户名: [" .. safe_log_value(username) .. "]"
            )
            -- 会话无效：强制删除Cookie并清理本地缓存
            delete_cookie(session_conf.cookie_name or "session_id")
            -- 额外清理本地缓存（双重保障）
            if ngx.shared.session_cache then
                local cache_key = "session:" .. (session_conf.cookie_domain or "") .. ":" .. session_id
                ngx.shared.session_cache:delete(cache_key)
                log.info("[本地缓存-清理] 主动删除无效会话（session_id: [" .. safe_log_value(session_id) .. "]）")
            end
        end
    else
        log.info(
            log_prefix .. "未获取到有效session_id（session_id为空或空白）"
        )
    end

    -- 6.5. 处理POST认证请求（提交用户名和验证码）
    if ngx.var.request_method == "POST" then
        ngx.req.read_body()  -- 读取POST请求体
        local args = ngx.req.get_post_args()
        local username = args.username
        local code = args.code
        local redirect_url = args.redirect_url or ngx.var.request_uri

        -- 参数校验：用户名和验证码不能为空
        if not username or not code then
            log.warn(
                log_prefix .. "参数缺失，" ..
                "username: [" .. safe_log_value(username) .. "], " ..
                "code: [" .. safe_log_value(code) .. "]"
            )
            return show_auth_popup(redirect_url, "请输入用户名和验证码")
        end

        -- 检查用户是否被封禁
        local is_banned, ban_msg = check_ban_status(username)
        if is_banned then
            log.warn(
                log_prefix .. "用户已封禁，" ..
                "username: [" .. safe_log_value(username) .. "], " ..
                "封禁原因: [" .. safe_log_value(ban_msg) .. "]"
            )
            return show_auth_popup(redirect_url, ban_msg, 0)
        end

        -- 获取用户TOTP密钥（Redis优先，数据库兜底）
        local secret, err = redis_utils.get_user_secret(username)
        
        -- 明确判断用户不存在（Redis无记录）
        if not secret then
            if err == "user_not_found" then
                log.warn(
                    log_prefix .. "用户不存在（Redis无记录），" ..
                    "username: [" .. safe_log_value(username) .. "]"
                )
            else
                log.error(
                    log_prefix .. "获取用户密钥失败，" ..
                    "username: [" .. safe_log_value(username) .. "], " ..
                    "错误: [" .. safe_log_value(err) .. "]"
                )
            end
            local attempts = record_attempt(username)
            return show_auth_popup(redirect_url, "用户不存在", attempts)
        end

        -- 过滤无效密钥（如null/空值）
        if secret == "null" or secret == "NULL" or secret == "" then
            log.error(
                log_prefix .. "用户密钥无效，" ..
                "username: [" .. safe_log_value(username) .. "], " ..
                "secret: [" .. safe_log_value(secret) .. "]"
            )
            local attempts = record_attempt(username)
            return show_auth_popup(redirect_url, "用户状态异常，请联系管理员", attempts)
        end

        -- 数据库兜底查询（确保数据一致性）
        local db_secret = db_utils.get_user_secret(username)
        if not db_secret then
            log.warn(
                log_prefix .. "用户不存在（数据库无记录），" ..
                "username: [" .. safe_log_value(username) .. "]"
            )
            -- 清理Redis无效记录
            redis_utils.set_user_secret(username, nil)
            local attempts = record_attempt(username)
            return show_auth_popup(redirect_url, "用户不存在", attempts)
        end

        -- 同步数据库中的密钥到Redis（双向一致性保障）
        if db_secret and db_secret ~= secret then
            log.info(
                log_prefix .. "更新Redis中的用户密钥，" ..
                "username: [" .. safe_log_value(username) .. "]"
            )
            redis_utils.set_user_secret(username, db_secret)
            secret = db_secret
        end

        -- 验证TOTP验证码
        log.info(
            log_prefix .. "开始验证TOTP，" ..
            "username: [" .. safe_log_value(username) .. "]"
        )
        local auth_conf = config.auth or {}
        local is_valid, err = totp_utils.verify_totp(
            secret,
            code,
            auth_conf.totp_time_step or 30,  -- 时间步长（秒）
            auth_conf.code_length or 6        -- 验证码长度
        )

        if is_valid then
            -- 认证成功：创建新会话
            redis_utils.reset_attempts(username)  -- 重置失败次数
            -- 生成随机会话ID（包含时间戳和随机数，确保唯一性）
            local new_session_id = ngx.md5(username .. ngx.time() .. math.random() .. client_ip)
            
            -- 使用redis_utils统一创建会话
            local expire_seconds = session_conf.expire_time or 3600
            local create_ok = redis_utils.create_user_session(new_session_id, username, expire_seconds)
            
            if not create_ok then
                log.error(
                    log_prefix .. "会话创建失败，" ..
                    "username: [" .. safe_log_value(username) .. "], " ..
                    "session_id: [" .. safe_log_value(new_session_id) .. "]"
                )
                return show_auth_popup(redirect_url, "系统错误：会话创建失败")
            end
            
            -- 设置会话Cookie（与Redis有效期一致）
            set_cookie(session_conf.cookie_name or "session_id", new_session_id, expire_seconds)
            
            -- 重定向到认证前的URL
            log.info(
                log_prefix .. "认证成功，重定向到: [" .. safe_log_value(redirect_url) .. "], " ..
                "username: [" .. safe_log_value(username) .. "], " ..
                "session_id: [" .. safe_log_value(new_session_id) .. "]"
            )
            ngx.header["Location"] = redirect_url
            ngx.exit(302)  -- 执行重定向
        else
            -- 认证失败：记录尝试次数并提示错误
            local attempts = record_attempt(username)
            log.warn(
                log_prefix .. "TOTP验证失败，" ..
                "username: [" .. safe_log_value(username) .. "], " ..
                "剩余次数: " .. attempts
            )
            local error_msg = "验证码错误"
            if attempts <= 0 then
                error_msg = "尝试次数过多，账号已被封禁20分钟"
            end
            return show_auth_popup(redirect_url, error_msg, attempts)
        end
    end

    -- 6.6. 显示认证弹窗（GET请求或认证失败时）
    log.info(
        log_prefix .. "显示认证弹窗，" ..
        "当前URL: [" .. safe_log_value(ngx.var.request_uri) .. "]"
    )
    return show_auth_popup(ngx.var.request_uri)
end

-- 第七部分：认证结果处理     
-- 执行认证流程并返回结果
local auth_result = authenticate()
if not auth_result then
    ngx.exit(ngx.HTTP_UNAUTHORIZED)  -- 认证失败，返回401
else
    ngx.exit(ngx.DECLINED)  -- 认证成功，继续后续处理
end

博文来自：www.51niux.com

1.12 auth_popup.html

# mkdir /usr/local/nginx/conf/auth/templates

#该文件是认证系统的前端弹窗模板，用于展示用户登录界面。当用户访问需要认证的资源且尚未登录时，系统会加载此模板生成一个全屏遮罩层，要求用户输入用户名和TOTP动态验证码进行身份验证。

# vi /usr/local/nginx/conf/auth/templates/auth_popup.html

<!DOCTYPE html>
<html>
<head>
    <title>身份验证</title>
    <style>
        /* 全屏遮罩层：覆盖整个页面，半透明黑色背景，居中显示认证框 */
        .auth-overlay { 
            position: fixed; 
            top: 0; 
            left: 0; 
            width: 100%; 
            height: 100%; 
            background: rgba(0,0,0,0.5); /* 半透明黑色，阻止用户操作底层页面 */
            display: flex; 
            justify-content: center; /* 水平居中 */
            align-items: center; /* 垂直居中 */
            z-index: 9999; /* 确保遮罩层在最上层 */
        }
        
        /* 认证框：白色背景，带阴影和圆角，固定宽度 */
        .auth-box { 
            background: white; 
            padding: 20px; 
            border-radius: 5px; /* 圆角边框 */
            width: 300px; 
            box-shadow: 0 0 10px rgba(0,0,0,0.3); /* 阴影效果增强层次感 */
        }
        
        /* 错误提示区域：红色文字，由后端控制显示/隐藏 */
        .auth-error { 
            color: red; 
            margin-bottom: 10px; 
            display: {error_display}; /* {error_display}由后端替换为block/none */
        }
        
        /* 安全提示：灰色小字，告知用户封禁规则 */
        .auth-note { 
            color: #666; 
            font-size: 12px; 
            margin-bottom: 15px; 
        }
        
        /* 表单样式：输入框和按钮占满宽度 */
        .auth-form input { 
            width: 100%; 
            padding: 8px; 
            margin-bottom: 10px; 
            box-sizing: border-box; /* 确保padding不影响总宽度 */
        }
        
        /* 提交按钮：绿色背景，白色文字，圆角 */
        .auth-form button { 
            width: 100%; 
            padding: 10px; 
            background: #4CAF50; 
            color: white; 
            border: none; 
            border-radius: 3px; 
            cursor: pointer; /* 鼠标悬停显示手型 */
        }
        
        /* 剩余尝试次数：橙色文字，提示用户剩余机会 */
        .auth-attempts { 
            color: orange; 
            margin-top: 10px; 
            font-size: 14px; 
        }
    </style>
</head>
<body>
    <!-- 全屏遮罩层：阻止用户操作页面其他内容 -->
    <div class="auth-overlay">
        <!-- 认证框：包含所有表单元素 -->
        <div class="auth-box">
            <h3>系统认证</h3>
            
            <!-- 错误提示区域：显示后端返回的错误信息（如验证码错误） -->
            <div class="auth-error" id="error-message">{error_msg}</div> <!-- {error_msg}由后端替换为具体错误文本 -->
            
            <!-- 安全提示文本：告知用户连续错误的后果 -->
            <div class="auth-note">提示：连续错误3次，账号将被临时锁定20分钟</div>
            
            <!-- 认证表单：提交用户名和验证码到后端 -->
            <form class="auth-form" method="post" action="{redirect_url}"> <!-- {redirect_url}由后端替换为原始请求URL -->
                <!-- 用户名输入框：必填，使用localStorage保存 -->
                <input type="text" name="username" placeholder="用户名" required>
                
                <!-- 验证码输入框：必填，6位动态码 -->
                <input type="text" name="code" placeholder="6位动态验证码" required>
                
                <!-- 隐藏字段：保存原始URL，用于认证成功后重定向 -->
                <input type="hidden" name="redirect_url" value="{redirect_url}">
                
                <!-- 提交按钮：触发表单提交到后端 -->
                <button type="submit">验证</button>
            </form>
            
            <!-- 剩余尝试次数：显示后端计算的剩余次数 -->
            <div class="auth-attempts">剩余尝试次数: {remaining_attempts}</div> <!-- {remaining_attempts}由后端替换为数字 -->
        </div>
    </div>
    
    <script>
        // 页面加载完成后执行：优化用户体验
        document.addEventListener('DOMContentLoaded', function() {
            // 获取用户名和验证码输入框元素
            const usernameInput = document.querySelector('input[name="username"]');
            const codeInput = document.querySelector('input[name="code"]');
            
            // 从localStorage读取上次保存的用户名并自动填充
            const savedUsername = localStorage.getItem('auth_username');
            if (savedUsername) {
                usernameInput.value = savedUsername;
            }
            
            // 每次加载页面时清空验证码输入框（避免重复提交旧验证码）
            codeInput.value = '';
            
            // 监听用户名输入变化，实时保存到localStorage（避免用户重复输入）
            usernameInput.addEventListener('input', function() {
                localStorage.setItem('auth_username', this.value);
            });
        });
    </script>
</body>
</html>

二、验证测试

2.1 IP不在白名单中登录弹窗

#vi /usr/local/nginx/conf/conf.d/lua.test.com.conf #配置一个最简单的域名进行测试,记得自己配置下hosts文件哦

server {
    listen 80;
    server_name lua.test.com;
    root /opt/web;
    charset utf-8;
    error_log /usr/local/nginx/logs/error.log debug;
    
    access_by_lua_file /usr/local/nginx/conf/auth/auth.lua;
    
    location / {
        root /opt/web;
        index index.html;
        # 确保不干扰Cookie
        proxy_set_header Cookie $http_cookie;
    }
}

#vi /opt/web/index.html #最简单的测试首页

<!DOCTYPE html>
<html>
<head>
    <title>Hello World</title>
</head>
<body>
    <h1>Hello, World!</h1>
</body>
</html>

#浏览器访问http://lua.test.com/index.html

# tail -f /usr/local/nginx/logs/error.log #从错误日志可以看到缺少授权

[error] 588087#0: *3945 attempt to set status 401 via ngx.exit after sending out the response status 200, 
client: 192.168.1.101, server: lua.test.com, request: "POST /index.html HTTP/1.1", 
host: "lua.test.com", referrer: "http://lua.test.com/index.html"

#上图为故意输错验证码可以看到有错误提示

# tail -f /opt/log/nginx/auth_error.log #看看错误日志怎么体现的呢？

[ERROR] [192.168.1.101] [1b90880fecccc634198dfa86824295d2] [获取密钥] Redis返回非字符串类型: 
[WARN] [192.168.1.101] [19dd9cb762b43c17096c689ac39260e0] IP:192.168.1.101 - TOTP验证失败（username: test3, 剩余尝试次数: 2）
[ERROR] [192.168.1.101] [6302ec80939f6e311ae7aa1edd30a8f2] [获取密钥] Redis返回非字符串类型: 
[WARN] [192.168.1.101] [a5136d3ddf1ddd619c1ca5af523e7e48] IP:192.168.1.101 - TOTP验证失败（username: test1, 剩余尝试次数: 2）
[ERROR] [192.168.1.101] [33885994750b49fa74e8182796c3d349] [获取密钥] Redis返回非字符串类型: 
[WARN] [192.168.1.101] [72cf3b0a64321ca26f77f63d19c42c39] IP:192.168.1.101 - 用户不存在（username: test12313）

# tail -f /opt/log/nginx/auth_access.log #可以看到完整的认证过程,这里就不粘贴日志了

#也可以自行查看redis内的key信息变化跟代码里面的逻辑一一对应哈

#然后我们输入正确的验证码,再看下变化,这里就不截图了哈,hello world页面也没啥好截图的。

# tail -f /opt/log/nginx/auth_access.log #可以看看日志最后的输出

[INFO] [192.168.1.101] [8de87d8836845f5ffd70d9776bafd7e5] IP:192.168.1.101 - 认证成功，重定向到: /index.html
[INFO] [192.168.1.101] [245518fd33b5eb2adf168ffb531219ee] 请求Cookie头: auth_session=15d4063c6ef40e65d9d35a590155e541
[INFO] [192.168.1.101] [147fd95be0607f4952edf94d78ebf495] 找到Cookie: auth_session（清洗后: 15d4063c6ef40e65d9d35a590155e541）
[INFO] [192.168.1.101] [4e036267e7ec4429748630c463853cc6] IP:192.168.1.101 - 当前会话ID: 15d4063c6ef40e65d9d35a590155e541
[INFO] [192.168.1.101] [7e34c6f7aebafcd4f0d1623450320c03] [本地缓存-读取] 命中（session_id: 15d4063c6ef40e65d9d35a590155e541）
[INFO] [192.168.1.101] [416f8fd60145319091b5a8b7a488a72b] IP:192.168.1.101 - 本地缓存会话有效，用户: test3

#127.0.0.1:6379> get session:.test.com:15d4063c6ef40e65d9d35a590155e541 #现在redis中也有一个以固定格式命名的key

"test3"

#现在你在反复刷新页面,浏览器也不会再有弹窗认证了,可以看到cookie已经存储到浏览器中了：

# tail -f /opt/log/nginx/auth_access.log #那么日志中怎么体现的呢？

[INFO] [192.168.1.101] [453edb8fc44ac3a8cf0ca6f753bfa9b9] 请求Cookie头: auth_session=15d4063c6ef40e65d9d35a590155e541
[INFO] [192.168.1.101] [9d974c9d8ada2092942e941a205f9751] 找到Cookie: auth_session（清洗后: 15d4063c6ef40e65d9d35a590155e541）
[INFO] [192.168.1.101] [69e8896b5171232d8feb13ccba2c5026] IP:192.168.1.101 - 当前会话ID: 15d4063c6ef40e65d9d35a590155e541
[INFO] [192.168.1.101] [ab5dcb76450c19e1a9af413fcec13ab6] [本地缓存-读取] 命中（session_id: 15d4063c6ef40e65d9d35a590155e541）
[INFO] [192.168.1.101] [3545864b2b5a1c4627d8ec1f3c896f9f] IP:192.168.1.101 - 本地缓存会话有效，用户: test3

2.2 验证锁定状态

#故意输错三次验证码就会进入封禁状态
# tail -f /opt/log/nginx/auth_access.log #我们看看日志怎么显示的

[INFO] [192.168.1.101] [5401fe6bb3378ce4007ad43e24e0191f] IP:192.168.1.101 - 开始验证TOTP，username: [test1]
[INFO] [192.168.1.101] [7f738a71d6186657b0bbc884c796ff34] verify_totp: 所有时间窗口验证失败
[INFO] [192.168.1.101] [1b0bdbe5124b9830ac7392d3c6da5505] [Redis连接] 成功，host: [127.0.0.1], port: [6379], db: [0]
[INFO] [192.168.1.101] [be3e9ed357cd56cb26c9c7e6cc56965c] [Redis连接] 成功，host: [127.0.0.1], port: [6379], db: [0]
[INFO] [192.168.1.101] [7b847c78ca94d76c60aa1d0ee996e347] [封禁用户] 成功，username: [test1], 封禁时间: [1200秒]

2.3 手工清理cookie让用户再次认证

#如果你想让一个用户重新认证,或者某些用户重新认证怎么搞呢？

127.0.0.1:6379> del session:.test.com:365439d445da4afa5a2957829980262c #删掉redis中的cookie

#然后nginx -s reload一下吗,切记reload是不行的,因为reload只是加载配置这些,共享缓存区内的数据是不是清理的,想要把共享缓存区里面的cookie缓存也清理掉应该怎么做呢,最简单粗暴的方法就是restart nginx,但是线上环境那会让你动不动就restart，最靠谱的方案就是写个小工具小脚本或者小页面,把redis和nginx共享缓存中的此用户的cookie键都删掉。

2.4 免认证url访问

#我们有些静态的url比如图片之类的是不需要验证的,我们前面也做了此类设计,下面简单验证一下

#浏览器访问一下 http://lua.test.com/static/1.html #因为没有所以是404页面哈,但是只要没有认证弹窗就说明调过认证了

# tail -f /opt/log/nginx/auth_access.log #我们看看日志怎么显示的

[INFO] [192.168.1.101] [cda930e363f8b9034dfccef8d41ebd67] [免认证检查] 全局免认证URL，允许访问（url: /static/1.html）
[INFO] [192.168.1.101] [8ad2d26a34d4e544d89bade39dc94665] IP:192.168.1.101- URL在免认证列表中，允许访问

Nginx结合Lua实现二次验证(二)

Wed, 11 Jun 2025 18:43:09 +0800

好了紧跟上文,上一篇 https://blog.51niux.com/?id=323 我们已经详细的了解了Nginx结合lua的一些简单用法,下面我们用一个现实中比较常见的例子来继续了解。

#我先描述一下场景啊,二次验证已经非常的司空见惯了啊,比如你登录阿里云腾讯云这些需要绑定MFA并且每次登录的时候都需要输入一个基于时间的6位数字,当然这种方式也是企业内部也是被广泛使用的,比如我们有些系统由于场景需要比如我们有很多分城市,需要公网访问一些个别的系统,你想除了账号密码认证外,还想结合每个人的身份分配一个唯一的秘钥字符串,以此生成一个6位验证数字,只有登录通过后才能1天内使用(当然也可以通过阿里云的sase等一些安全产品解决公网访问的问题)。

#比如你现在就是内网访问,但是你还是想多一层验证,比如每次登录堡垒机等跟权限相关的系统,除了账号密码外,还是想让用手机上的mfa验证一下(每个人都有内部账号,每个账号都会入职的时候分配一个唯一的字符串,用于结合当前时间产生一个变化只有30秒生命周期的的6位数字)。

#好了上面是一个实际场景的大概描述,下面就让我们一步步实现它吧

一、先用脚本产生一个固定字符串的随机验证

#vi totp_generator.lua

-- 导入bit32库，用于位操作，位操作就像搭积木，我们可以把数字拆成二进制的小块，然后移动或组合它们
-- Lua5.1中需要使用bit库，Lua5.2+可以直接使用bit32
local bit32 = require("bit")

-- Base32解码函数（阿里云MFA密钥通常为Base32编码）
-- Base32就像是一种密码本，用32个字母和数字表示二进制数据
local function base32_decode(base32_str)
    -- 移除所有空格并转为大写,就像整理信件一样，我们先去掉多余的空格，并且统一字母大小写
    base32_str = base32_str:gsub("%s", ""):upper()
    
    -- 检查输入长度,如果没有内容，就像空信封一样，我们无法处理
    if #base32_str == 0 then
        error("Base32字符串不能为空")
    end
    
    -- 检查是否有填充字符'=',Base32编码会用'='符号填充，就像拼图最后用空白块补齐一样
    local padding = base32_str:match("=+$")
    if padding then
        -- 移除字符串末尾的填充字符,从1开始,#base32_str:获取原字符串的长度,#padding:获取填充字符子串的长度
        -- 相减后得到的是不包含填充字符的字符串的结束位置,整体效果是：保留原字符串从开头到填充字符之前的部分
        base32_str = base32_str:sub(1, #base32_str - #padding)
    end
    
    -- 验证输入长度（必须是8的倍数），Base32的规则是每8个字符代表5个原始数据字节
    if #base32_str % 8 ~= 0 then
        error("Base32字符串长度必须是8的倍数")
    end
    
    -- Base32字符集定义，这是Base32编码的"密码本"，每个字母和数字对应一个0-31的数字
    local base32_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
    local result = ""       -- 存储解码后的结果
    local bits = 0          -- 累积的位数
    local value = 0         -- 累积的值
    
    -- 逐字符解码,一个字母一个字母地"翻译"Base32字符串
    for i = 1, #base32_str do
        local c = base32_str:sub(i, i)
        
        -- 验证字符是否有效,如果在密码本里找不到这个字符，就说明是无效的.
        if c == "" then
            error("Base32字符串包含空字符")
        end      
        -- 将字符映射到对应的值（0-31）,就像查字典一样，找到字符在密码本中的位置
        local digit = base32_chars:find(c, 1, true)
        if not digit then
            error("无效的Base32字符: " .. c)
        end
        digit = digit - 1   -- 减1是因为Lua的索引从1开始，而我们需要从0开始        
        -- 累积位值，每个Base32字符代表5位二进制数据
        value = bit32.lshift(value, 5) + digit
        bits = bits + 5     -- 增加5位
        
        -- 当累积了至少8位时，我们可以生成一个字节
        if bits >= 8 then
            bits = bits - 8 -- 用掉8位
            -- 提取最左边的8位（相当于取整钱）
            -- bit32.rshift(value, bits)将多余的位右移去掉,bit32.band(..., 0xFF)只保留低8位
            result = result .. string.char(bit32.band(bit32.rshift(value, bits), 0xFF))
        end
    end
    -- 返回解码后的二进制数据
    return result
end

-- SHA-1的常量值,SHA-1算法中的四个固定常量
local K = {0x5A827999, 0x6ED9EBA1, 0x8F1BBCDC, 0xCA62C1D6}

-- 左旋转函数,将一个32位数字向左旋转指定的位数
local function rotl32(n, b)
    -- 先将n左移b位，然后将移出的部分放到右边
    -- 例如：rotl32(0001, 1) = 0010 (左移) + 0000 (右移) = 0010
    return bit32.band(bit32.lshift(n, b), 0xFFFFFFFF) + bit32.rshift(n, 32 - b)
end

-- 将消息填充到512比特的倍数,SHA-1要求输入是512位(64字节)的倍数,就像把信折成特定大小才能放进信封
local function pad_message(message)
    local length_bits = #message * 8  -- 计算消息总位数
    message = message .. string.char(0x80) -- 添加0x80字节(10000000)
    -- 填充0x00，直到长度为512比特的倍数减64比特,最后64位要留给原始消息的长度
    while (#message * 8) % 512 ~= 448 do
        message = message .. string.char(0x00)
    end   
    -- 添加原始长度（64位，大端序）,就像在信封上标注信的原始大小
    local length_bytes = {}
    for i = 7, 0, -1 do
        -- 从高位到低位，依次提取长度的每8位
        local byte_val = bit32.band(math.floor(length_bits / (256 ^ i)), 0xFF)
        table.insert(length_bytes, string.char(byte_val))
    end    
    message = message .. table.concat(length_bytes)
    return message
end

-- 将512比特的消息块转换为16个32位字，把大消息分成小块处理
local function words_from_block(block)
    local words = {}
    for j = 1, 16 do
        -- 每4个字节组成一个32位字
        local byte1, byte2, byte3, byte4 = block:byte((j - 1) * 4 + 1, (j - 1) * 4 + 4)
        byte2 = byte2 or 0  -- 如果不足4个字节，用0填充
        byte3 = byte3 or 0
        byte4 = byte4 or 0
        
        -- 将4个字节合并成一个32位整数，就像把4个小积木拼成一个大积木
        words[j] = bit32.bor(
            bit32.lshift(byte1, 24), -- 第一个字节移到最高位
            bit32.lshift(byte2, 16), -- 第二个字节移到次高位
            bit32.lshift(byte3, 8),  -- 第三个字节移到次低位
            byte4           -- 第四个字节在最低位
        )
    end
    return words
end

-- SHA-1主函数，对消息进行哈希处理，生成160位的哈希值，就像给消息做一个"指纹"
function sha1(message)
    -- 初始哈希值，SHA-1算法定义的5个初始常量，就像拼图的5个角块
    local H0 = 0x67452301
    local H1 = 0xEFCDAB89
    local H2 = 0x98BADCFE
    local H3 = 0x10325476
    local H4 = 0xC3D2E1F0

    -- 填充消息，确保消息长度是512位的倍数
    message = pad_message(message)

    -- 处理每个512比特块，把消息分成多个小块依次处理
    for i = 1, #message, 64 do
        local block = message:sub(i, i + 63)
        local words = words_from_block(block)

        -- 扩展到80个字，从16个字扩展到80个字，增加数据的复杂性
        for t = 17, 80 do
            local word = bit32.bxor(words[t - 3], words[t - 8], words[t - 14], words[t - 16])
            words[t] = rotl32(word, 1)
        end

        -- 初始化工作变量，5个工作变量，用于临时存储计算结果
        local A, B, C, D, E = H0, H1, H2, H3, H4

        -- 主循环 - 80轮处理，对每个扩展后的字进行复杂的位运算
        for t = 1, 80 do
            local temp, f
            local k_index = math.floor((t - 1) / 20) + 1
            
            -- 根据当前轮数选择不同的逻辑函数，就像根据不同的步骤做不同的动作
            if t <= 20 then
                -- 逻辑函数1：(B AND C) OR (NOT B AND D)
                f = bit32.bor(bit32.band(B, C), bit32.band(bit32.bnot(B), D))
            elseif t <= 40 then
                -- 逻辑函数2：B XOR C XOR D
                f = bit32.bxor(B, C, D)
            elseif t <= 60 then
                -- 逻辑函数3：(B AND C) OR (B AND D) OR (C AND D)
                f = bit32.bor(bit32.band(B, C), bit32.band(B, D), bit32.band(C, D))
            else
                -- 逻辑函数4：B XOR C XOR D
                f = bit32.bxor(B, C, D)
            end
            
            -- 计算临时值，结合左旋转、逻辑函数、常量和当前字进行计算
            temp = bit32.band(rotl32(A, 5) + f + E + words[t] + K[k_index], 0xFFFFFFFF)
            
            -- 循环移位工作变量，就像5个人站成一圈，依次传递任务
            E = D
            D = C
            C = rotl32(B, 30)
            B = A
            A = temp
        end

        -- 更新哈希值，将这一轮的计算结果累加到最终哈希值上
        H0 = bit32.band(H0 + A, 0xFFFFFFFF)
        H1 = bit32.band(H1 + B, 0xFFFFFFFF)
        H2 = bit32.band(H2 + C, 0xFFFFFFFF)
        H3 = bit32.band(H3 + D, 0xFFFFFFFF)
        H4 = bit32.band(H4 + E, 0xFFFFFFFF)
    end

    -- 返回最终的哈希值（二进制格式），将5个32位整数转换为20字节的二进制数据
    local hash_bytes = {}
    for i, h in ipairs({H0, H1, H2, H3, H4}) do
        for j = 3, 0, -1 do
            -- 从高位到低位，提取每个整数的4个字节
            local byte_val = bit32.band(bit32.rshift(h, j * 8), 0xFF)
            table.insert(hash_bytes, string.char(byte_val))
        end
    end   
    return table.concat(hash_bytes)
end

-- 定义HMAC-SHA1函数，基于SHA-1的密钥哈希消息认证码，就像给消息加了一把带密码的锁
local function hmac_sha1(key, data)
    -- 如果密钥长度超过64字节，先进行SHA-1哈希，确保密钥长度不超过块大小
    if #key > 64 then
        key = sha1(key)
    end
    
    -- 将密钥填充到64字节，就像把钥匙磨成特定形状
    key = key .. string.rep("\0", 64 - #key)
    
    -- 内部和外部密钥，创建两个不同的密钥变体
    local inner_key = {}
    local outer_key = {}
    
    -- 对密钥的每个字节进行处理，内部密钥：与0x36异或外部密钥：与0x5C异或
    for i = 1, 64 do
        local byte_val = key:byte(i)
        table.insert(inner_key, string.char(bit32.bxor(byte_val, 0x36)))
        table.insert(outer_key, string.char(bit32.bxor(byte_val, 0x5C)))
    end    
    inner_key = table.concat(inner_key)
    outer_key = table.concat(outer_key)
    
    -- 计算内部哈希，先用内部密钥和数据计算哈希
    local inner_hash = sha1(inner_key .. data)
    
    -- 计算外部哈希，再用外部密钥和内部哈希结果计算最终哈希
    return sha1(outer_key .. inner_hash)
end

-- 定义TOTP函数，基于时间的一次性密码算法，就像一个随时间变化的密码锁
local function totp(secret, time_step, digits)
    -- 获取当前时间戳，记录从1970年1月1日到现在的秒数
    local current_time = os.time()
    -- 计算时间步长，将时间分成固定长度的"块"
    local counter = math.floor(current_time / time_step)
    
    -- 将计数器转换为8字节的大端序字节数组，就像把数字翻译成计算机能理解的语言
    local counter_bytes = {}
    for i = 7, 0, -1 do
        local byte_val = bit32.band(math.floor(counter / (256 ^ i)), 0xFF)
        counter_bytes[#counter_bytes + 1] = string.char(byte_val)
    end
    counter_bytes = table.concat(counter_bytes)
    
    -- 计算HMAC-SHA1，使用密钥和计数器生成哈希值
    local hash = hmac_sha1(secret, counter_bytes)
    
    -- 动态偏移量（从哈希结果的最后一个字节的低4位获取），就像从密码锁中随机选择一个位置开始
    local offset = bit32.band(hash:byte(20), 0x0F)
    
    -- 提取4字节数据（从offset位置开始），从哈希结果中提取一部分作为基础
    local binary_code = 0
    for i = 1, 4 do
        local byte_val = hash:byte(offset + i)
        binary_code = bit32.bor(binary_code, bit32.lshift(byte_val, (4 - i) * 8))
    end
    
    -- 移除最高位并取模，确保结果是一个正整数，并限制位数
    binary_code = bit32.band(binary_code, 0x7FFFFFFF)
    local otp = binary_code % (10 ^ digits)
    
    -- 格式化为固定长度的字符串，就像把密码格式化成固定位数的数字
    return string.format("%0" .. digits .. "d", otp)
end

-- 时间同步检查（可选），确保客户端和服务器的时间一致，就像校准两个钟表
local function check_time_synchronization(server_time_url)
    -- 实际应用中，应从服务器获取时间戳进行比对，这里仅为示例，实际实现需要HTTP请求
    print("警告：时间同步检查功能未实现，建议与服务器时间进行比对")
    return true
end

-- 主函数，程序的入口点
local function main()
    -- 阿里云MFA密钥（Base32编码），这是你在阿里云设置MFA时得到的密钥
    local base32_secret = "zABCDEghijklmnopqrstuvwxyzABCDEF"
    
    -- 解码Base32密钥，将密钥从"密码本语言"翻译成计算机能理解的二进制
    local secret = base32_decode(base32_secret)
    
    -- TOTP参数，时间步长：每30秒生成一个新密码，验证码位数：生成6位数字密码
    local time_step = 30  -- 步长为30秒
    local digits = 6      -- 验证码位数
    
    -- 检查时间同步，确保你的电脑时间准确
    if check_time_synchronization() then
        -- 生成当前验证码
        -- 基于当前时间和密钥计算出一次性密码
        local otp = totp(secret, time_step, digits)
        print("当前时间戳:", os.time())
        print("TOTP验证码:", otp)
    else
        print("错误：本地时间与服务器时间不同步，请调整系统时间")
    end
end

-- 执行主函数，启动整个程序
main()

# /usr/local/luajit/bin/luajit totp_generator.lua #手工执行一下(用手机阿里云或者谷歌验证器绑一下zABCDEghijklmnopqrstuvwxyzABCDEF核对一下)

警告：时间同步检查功能未实现，建议与服务器时间进行比对
当前时间戳:	1749723585
TOTP验证码:	097080

二、用标准目录形式为用户产生密钥串

#上面的例子我们已经可以用单一的秘钥生成了6位验证码,现实场景呢,一般也不会让用户自行生成秘钥,一般都是系统自动分配的唯一秘钥串,字符串长度呢就是8的倍数。你像阿里面向用户比较多所以它比较长64位,我们就给内部员工使用不需要那么长16位就可以了。

博文来自：www.51niux.com

2.1 准备mysql环境

#这里我们假设用户注册后的用户信息是存储到数据库中的(很多时候新员工入职的时候所有信息会存在一个指定的库表中,然后其他功能再依此延伸,你比如有个字段会自动创建一个16位的秘钥字符串,而我们就需要用户字母名称和秘钥串这两个字段,不管是定时任务式的还是触发式的很多时候我们会把这个信息存储到文本或者redis缓存中便于加载)。

MariaDB [(none)]> create database auth_db;
MariaDB [(none)]> grant all privileges on auth_db.* to 'auth'@'127.0.0.1' identified by 'auth123';
MariaDB [(none)]> flush privileges;

2.2 准备相关lua文件

# mkdir /usr/local/nginx/conf/auth

# vim /usr/local/nginx/conf/auth/config.lua #创建配置文件

-- 系统配置信息,创建了一个局部变量名为config的表,表Lua中最常用的数据结构，类似于其他语言中的字典、哈希表或对象
local config = {
    -- 数据库配置
    db = {
        host = "127.0.0.1", -- MySQL服务器地址
        port = 3306,  -- 端口
        database = "auth_db", -- 数据库名
        user = "auth",  -- 用户名
        password = "auth123", -- 密码
        max_idle_timeout = 10000, -- 连接池空闲超时(毫秒)
        pool_size = 100    -- 连接池大小
    },
    
    -- 二次验证配置
    otp = {
        code_length = 6, -- 验证码长度
        time_step = 30,  -- 时间步长(秒)
        window_size = 1,  -- 验证窗口(前后允许的时间步数)
        secret_length = 16 -- 密钥长度(字节)
    },
    
    -- 登录限制配置
    login_attempts = {
        max_attempts = 5, -- 最大尝试次数
        lockout_time = 60 -- 锁定时间(秒)
    },
    
    -- 会话配置
    session = {
        expires_in = 86400, -- 会话有效期(秒)
        cookie_name = "auth_token" -- Cookie名称
    },
    
    -- IP白名单配置
    whitelist_file = "/usr/local/nginx/conf/auth/ip_whitelist.txt",  -- 白名单文件路径
    reload_interval = 3600,
    
    -- 路径配置
    login_path = "/verify",       -- 登录页面路径
    register_path = "/register"   -- 注册页面路径
}
-- return语句用于将模块的内容导出，使其他模块可以通过 require函数加载和使用这些内容,将这个配置表导出为模块的公共接口
return config

# vim /usr/local/nginx/conf/auth/db.lua #创建数据库操作文件

-- 数据库操作模块
local mysql = require("resty.mysql")
local config = require("config").db

local _M = {}

-- 创建数据库连接
function _M.connect()
    local db, err = mysql:new()
    if not db then
        return nil, "创建MySQL实例失败: " .. err
    end
    
    -- 设置超时
    db:set_timeout(1000)  -- 1秒超时
    
    -- 连接数据库
    local ok, err, errno, sqlstate = db:connect({
        host = config.host,
        port = config.port,
        database = config.database,
        user = config.user,
        password = config.password,
        max_packet_size = config.max_packet_size
    })
    
    if not ok then
        return nil, string.format("连接数据库失败: %s, 错误码: %d, SQL状态: %s", err, errno, sqlstate)
    end   
    return db
end

-- 安全执行SQL查询
-- _M是模块的命名空间，代表当前模块,execute_query是函数名,sql是传入的SQL查询语句，字符串类型
function _M.execute_query(sql)
    -- 调用模块内部的connect函数创建数据库连接,如果连接失败(db为nil)，返回nil和错误信息
    local db, err = _M.connect()
    if not db then
        return nil, err
    end
    
    -- 执行查询，db:query(sql)是resty.mysql库提供的执行SQL查询的方法,其中errno:MySQL错误码(失败时),sqlstate:SQL状态码(失败时)
    local res, err, errno, sqlstate = db:query(sql)
    
    -- 将连接放回连接池,config.max_idle_timeout:连接在池中保持空闲的最长时间(ms),config.pool_size:连接池的最大大小
    db:set_keepalive(config.max_idle_timeout, config.pool_size)
    
    -- 如果查询失败（res为nil），返回nil和格式化的错误信息
    if not res then
        return nil, string.format("执行SQL失败: %s, 错误码: %d, SQL状态: %s", err, errno, sqlstate)
    end   
    -- 如果查询成功，返回查询结果res
    return res
end

-- 安全转义SQL字符串（防止SQL注入），将任意类型的值转换为适合在SQL语句中使用的安全字符串表示形式
function _M.escape_literal(str)
    -- 在SQL中，nil对应NULL关键字，返回字符串"NULL"（不带引号），使其能直接在SQL中作为空值使用
    if str == nil then
        return "NULL"
    end
    
    -- 处理布尔值,SQL中通常使用1和0表示布尔值true和false,将布尔值转换为对应的数字字符串
    if type(str) == "boolean" then
        return str and "1" or "0"
    end
    
    -- 处理数字,直接将数字转换为字符串，保持其数值表示
    if type(str) == "number" then
        return tostring(str)
    end
    
    -- 处理字符串确保输入值被视为字符串，用单引号将转义后的字符串包围，形成合法的SQL字符串字面量
    str = tostring(str)
    -- 转义单引号和反斜杠
    str = string.gsub(str, "\\", "\\\\")
    str = string.gsub(str, "'", "''")
    return "'" .. str .. "'"
end

-- 初始化数据库表
function _M.init_tables()
    -- 创建用户表
    local create_users_sql = [[
        CREATE TABLE IF NOT EXISTS users (
            id INT AUTO_INCREMENT PRIMARY KEY,
            username VARCHAR(50) UNIQUE NOT NULL,
            otp_secret VARCHAR(32) NOT NULL,
            login_attempts INT DEFAULT 0,
            last_attempt_time DATETIME,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP
        )
    ]]
    
    local res, err = _M.execute_query(create_users_sql)
    if not res then
        return false, "创建用户表失败: " .. err
    end
    
    -- 创建会话表
    local create_sessions_sql = [[
        CREATE TABLE IF NOT EXISTS sessions (
            session_id VARCHAR(64) PRIMARY KEY,
            user_id INT NOT NULL,
            expires_at DATETIME NOT NULL,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
            FOREIGN KEY (user_id) REFERENCES users(id)
        )
    ]]
    
    local res, err = _M.execute_query(create_sessions_sql)
    if not res then
        return false, "创建会话表失败: " .. err
    end
    
    return true
end
return _M

# vim /usr/local/nginx/conf/auth/utils.lua #工具函数模块，提供通用功能的文件

local config = require("config")

local _M = {}
-- 定义模块的公共函数generate_random_string，接受一个参数length表示要生成的随机字符串长度 
function _M.generate_random_string(length)
    -- 初始化空字符串result用于存储生成的随机字符串
    local result = ""
    -- 定义字符集chars，包含所有可能被使用的字符(大小写字母和数字)。
    local chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"

    -- 通过执行系统命令echo $$获取当前进程 ID。io.popen()打开一个管道执行命令，read()读取输出，tonumber()转换为数字。如果获取失败则默认为0
    local pid = tonumber(io.popen("echo $$"):read()) or 0

    -- 使用时间和进程ID组合作为种子,结合进程ID可以避免同一秒内生成相同的随机序列
    math.randomseed(os.time() + pid)

    -- 预调用math.random()三次，丢弃结果。这是Lua中提高随机数质量的常见做法，因为首次调用往往不够随机。
    for _ = 1, 3 do
        math.random()
    end
    
    -- ngx.log(ngx.INFO, "进入生成验证码阶段")
    -- 上面是打印一下内容,在排错阶段很有用,在开发阶段多加一些输出,可以知道代码在哪一步出错了,需要就打开注释
    -- 循环length次，每次生成一个1到字符集长度之间的随机索引
    for i = 1, length do
        -- 只调用一次math.random，获取单个字符
        local random_index = math.random(1, #chars)
        -- 使用sub()方法从字符集中提取对应位置的单个字符，并追加到result中
        result = result .. chars:sub(random_index, random_index)
    end
    -- 返回生成的随机字符串
    return result
end

-- 解析HTTP请求参数
function _M.parse_args()
    local args = {}
    
    -- 解析GET参数
    if ngx.var.request_method == "GET" then
        local query = ngx.var.query_string
        if query and query ~= "" then
            for k, v in string.gmatch(query, "([^&=]+)=([^&=]*)") do
                args[k] = ngx.unescape_uri(v)
            end
        end
    -- 解析POST参数
    elseif ngx.var.request_method == "POST" then
        ngx.req.read_body()
        local post_data = ngx.req.get_post_data()
        if post_data and post_data ~= "" then
            for k, v in string.gmatch(post_data, "([^&=]+)=([^&=]*)") do
                args[k] = ngx.unescape_uri(v)
            end
        end
    end
    
    return args
end

-- 检查字符串是否为空
function _M.is_empty(str)
    return str == nil or str == ""
end
-- 将模块表_M作为结果返回，使外部代码可以访问其公共函数
return _M

# vim /usr/local/nginx/conf/auth/otp.lua #注册用户产生随机密钥的文件

-- 导入三个外部模块
local db = require("db")
local config = require("config")
local utils = require("utils")

local _M = {}

-- 定义generate_secret函数，用于生成 OTP 密钥
function _M.generate_secret()
    -- 调用utils模块的generate_random_string函数，生成长度为config.otp.secret_length的随机字符串
    return utils.generate_random_string(config.otp.secret_length)
end

-- 注册新用户（生成OTP密钥）
function _M.register_user(username)
    -- 首先调用generate_secret生成OTP密钥
    local otp_secret = _M.generate_secret()

    -- 验证生成的密钥长度是否超过 32 个字符（假设数据库字段类型为 VARCHAR (32)）
    if #otp_secret > 32 then
        --如果超过则截断为前 32 个字符，防止数据库插入错误
        otp_secret = string.sub(otp_secret, 1, 32) 
    end
    -- ngx.log(ngx.INFO,"otp_secret:",otp_secret)
    
    -- 构建SQL插入语句，将用户名和OTP密钥存入users表
    local sql = string.format([[
        INSERT INTO users (username, otp_secret)
        VALUES (%s, %s)
    ]],
    -- 使用db.escape_literal对输入进行转义，防止SQL注入攻击
    db.escape_literal(username),
    db.escape_literal(otp_secret)
    )
    -- 执行SQL插入语句
    local res, err = db.execute_query(sql)
    if not res then
        return false, nil, "注册失败: " .. err
    end
    
    return true, otp_secret, "注册成功"
end

return _M

#vim /usr/local/nginx/conf/auth/main.lua #主程序入口文件

-- ngx是OpenResty提供的全局对象，用于访问Nginx API
local ngx = ngx
local otp = require("otp")
local db = require("db")
local utils = require("utils")
local config = require("config")

-- 调用db.init_tables()初始化数据库表(如果不存在),失败时返回500错误并终止请求处理
local ok, err = db.init_tables()
if not ok then
    -- ngx.log(ngx.ERR, "数据库连接失败: ", err)
    ngx.status = 500
    ngx.say("数据库初始化失败: ", err)
    ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
end

-- 显示登录弹窗
local function show_login_popup(error_msg, original_url)
    error_msg = error_msg or ""
    original_url = original_url or ngx.var.request_uri
    
    -- 创建HTML模板
    local html = [[
    <!DOCTYPE html>
    <html lang="zh-CN">
    <head>
        <meta charset="UTF-8">
        <title>二次验证</title>
        <style>
            body { font-family: Arial, sans-serif; }
            .overlay {
                position: fixed;
                top: 0;
                left: 0;
                width: 100%;
                height: 100%;
                background-color: rgba(0,0,0,0.5);
                display: flex;
                justify-content: center;
                align-items: center;
                z-index: 9999;
            }
            .popup {
                background-color: white;
                padding: 20px;
                border-radius: 5px;
                box-shadow: 0 0 10px rgba(0,0,0,0.3);
                max-width: 400px;
                width: 100%;
                animation: fadeIn 0.3s ease-in-out;
            }
            @keyframes fadeIn {
                from { opacity: 0; transform: scale(0.9); }
                to { opacity: 1; transform: scale(1); }
            }
            .form-group { margin-bottom: 15px; }
            .form-group label { display: block; margin-bottom: 5px; font-weight: bold; }
            .form-group input { 
                width: 100%; 
                padding: 10px; 
                border: 1px solid #ddd; 
                border-radius: 4px; 
                box-sizing: border-box;
            }
            button { 
                background-color: #4CAF50; 
                color: white; 
                padding: 10px 15px; 
                border: none; 
                border-radius: 4px; 
                cursor: pointer; 
                width: 100%;
                font-size: 16px;
            }
            button:hover { background-color: #45a049; }
            .error { 
                color: red; 
                margin-bottom: 10px; 
                padding: 8px; 
                background-color: #ffebee; 
                border-radius: 4px;
            }
            .info {
                margin-top: 15px;
                font-size: 14px;
                color: #666;
            }
        </style>
    </head>
    <body>
        <div class="overlay">
            <div class="popup">
                <h2>二次验证</h2>
                {{error_message}}
                <p>您需要进行二次验证才能访问此资源</p>
                <form method="post" action="{{action_url}}">
                    <input type="hidden" name="original_url" value="{{original_url}}" />
                    <div class="form-group">
                        <label for="username">用户名:</label>
                        <input type="text" id="username" name="username" required placeholder="输入您的用户名">
                    </div>
                    <div class="form-group">
                        <label for="code">二次验证码:</label>
                        <input type="text" id="code" name="code" required placeholder="输入6位数字验证码">
                    </div>
                    <button type="submit">验证并继续</button>
                </form>
                <div class="info">
                    <p>提示: 验证码每30秒更新一次</p>
                    <p>测试用注册: <a href="/register?username=test">/register?username=test</a></p>
                </div>
            </div>
        </div>
    </body>
    </html>
    ]]
    
    -- 安全替换函数
    local function safe_replace(html, placeholder, value)
        -- 确保替换值中的特殊字符被正确处理
        value = string.gsub(value, "%%", "%%%%")
        return string.gsub(html, placeholder, value)
    end
    
    -- 使用安全替换函数
    html = safe_replace(html, "{{error_message}}", 
    error_msg ~= "" and string.format('<div class="error">%s</div>', error_msg) or "")
    html = safe_replace(html, "{{original_url}}", ngx.escape_uri(original_url))
    html = safe_replace(html, "{{action_url}}", ngx.var.request_uri)
    
    ngx.header.content_type = "text/html; charset=utf-8"
    ngx.say(html)
    ngx.exit(ngx.HTTP_OK)
end

-- 处理注册请求(测试用)
if ngx.var.uri == config.register_path and ngx.req.get_method() == "GET" then
    local args = ngx.req.get_uri_args()
    local username = args.username
    if utils.is_empty(username) then
        ngx.header.content_type = "text/plain; charset=utf-8"
        ngx.status = 400
        ngx.say("请提供用户名")
        ngx.exit(ngx.HTTP_BAD_REQUEST)
    end
    
    -- 注册新用户,调用otp.register_user生成OTP密钥并存储到数据库
    local ok, otp_secret, message = otp.register_user(username)
    
    -- 成功时返回包含用户和OTP 密钥的HTML页面
    if ok then
        -- 设置Content-Type为text/html，确保浏览器正确解析HTML
        ngx.header.content_type = "text/html; charset=utf-8"
        ngx.say([[
        <!DOCTYPE html>
        <html lang="zh-CN">
        <head>
            <meta charset="UTF-8">
            <title>注册成功</title>
            <style>
                body { font-family: Arial, sans-serif; }
                .container { max-width: 600px; margin: 0 auto; padding: 20px; }
                .success { color: green; font-weight: bold; }
                .back-link { display: inline-block; margin-top: 20px; }
            </style>
        </head>
        <body>
            <div class="container">
                <h2>注册成功</h2>
                <p class="success">用户名: ]] .. username .. [[</p>
                <p class="success">OTP密钥: ]] .. otp_secret .. [[</p>
                <p>请使用此密钥在Google Authenticator中生成验证码</p>
                <a href="/verify" class="back-link">返回登录页面</a>
            </div>
        </body>
        </html>
        ]])
    else
        ngx.header.content_type = "text/plain; charset=utf-8"
        ngx.status = 500
        ngx.say("注册失败: ", message)
        ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
    end
    -- 处理完注册请求后，直接退出，不再执行后续代码
    ngx.exit(ngx.HTTP_OK)
end

-- 显示登录弹窗
show_login_popup(nil, ngx.var.request_uri)

# vim /usr/local/nginx/conf/nginx.conf #nginx主配置文件配置

#gzip  on;
    lua_package_path "/usr/local/lua_core/lib/lua/?.lua;/usr/local/nginx/conf/auth/?.lua;;";
......
    include /usr/local/nginx/conf/conf.d/*.conf;

# vim /usr/local/nginx/conf/conf.d/lua.test.com.conf #配置一个测试域名,然后本地电脑配置hosts

server {
    listen 80;
    server_name lua.test.com;
    root /opt/web;
    charset utf-8;
    error_log /usr/local/nginx/logs/error.log debug;

    # 主应用入口
    location / {
        default_type 'text/plain';
        # 指定 Lua 处理程序
        content_by_lua_file /usr/local/nginx/conf/auth/main.lua;
    }
    location ~ ^/favicon.ico$ {
        return 404;
        root    /opt/www/favicon;
    }
}

# /usr/local/nginx/sbin/nginx -s reload

2.3 访问验证一下

先注册一个test用户：http://lua.test.com/register?username=test #如果已经存在test用户了,web页面会提示：

注册失败: 注册失败: 执行SQL失败: Duplicate entry 'test' for key 'username', 错误码: 1062, SQL状态: 23000

再来注册一个不存在的用户：http://lua.test.com/register?username=test1 #下面是web页面显示效果

下面我们点击下返回登录页面进入验证页面(http://lua.test.com/verify),现在访问任何页面都会页面弹窗需要登录验证除了注册页面,如下图：

博文来自：www.51niux.com

三、增加一个IP白名单的功能

#如果我们有一些固定的出口IP,使用者不希望每天都进行一次登录验证,或者当程序验证有问题频繁弹出验证框的时候,IP白名单功能就很有用了。

3.1 代码编写

# vim /usr/local/nginx/conf/auth/utils.lua #增加IP处理逻辑

-- 日志函数
function _M.log(level, msg)
    -- 分级日志：支持 debug、info、warn、error 四种日志级别 
    local log_levels = {
        debug = ngx.DEBUG,
        info = ngx.INFO,
        warn = ngx.WARN,
        error = ngx.ERR
    }
    -- 默认级别：若传入的日志级别不合法，默认使用info级别
    local log_level = log_levels[level] or log_levels.info
    --日志前缀：所有日志都会自动添加 [auth] 前缀，方便在 Nginx 日志中快速定位和过滤
    ngx.log(log_level, "[auth] ", msg)
end

-- 读取文件内容
function _M.read_file(path)
        -- 使用io.open(path, "r") 以只读模式打开文件,若文件打开失败返回nil并记录错误
    local file = io.open(path, "r")
    if not file then
        _M.log("error", "Failed to open file: " .. path)
        return nil
    end
        -- 使用file:read("*all") 一次性读取整个文件内容，适合小文件。大文件可能导致内存溢出。
        -- 若处理大文件（如超过 100MB），建议改用循环读取（如 file:read(4096)）
        -- 可以使用pcall包裹读取逻辑，防止文件读取过程中出错导致Lua脚本崩溃
    local content = file:read("*all")
    -- 无论文件读取是否成功，file:close() 都会执行（在当前实现中隐含正确关闭，更健壮的写法可使用 finally 确保关闭）
    file:close()
    return content
end

-- 检查IP是否在CIDR范围内
function _M.ip_in_cidr(ip, cidr)
    local ip_parts = {}
    -- 使用 ip:gmatch("%d+") 提取IP地址的四个数字部分，解析IP地址为四部分数字
    for part in ip:gmatch("%d+") do
        table.insert(ip_parts, tonumber(part))
    end

    if #ip_parts ~= 4 then
        return false
    end
        -- 解析CIDR格式 
    local cidr_ip, cidr_mask = cidr:match("^([^/]+)/(%d+)$")
    if not cidr_ip or not cidr_mask then
            -- 若不是CIDR格式，直接比较IP是否相等 
        return ip == cidr
    end
        -- 解析CIDR中的IP部分
    local cidr_parts = {}
    for part in cidr_ip:gmatch("%d+") do
        table.insert(cidr_parts, tonumber(part))
    end

    if #cidr_parts ~= 4 then
        return false
    end
        -- 验证掩码合法性
    cidr_mask = tonumber(cidr_mask)
    if cidr_mask < 0 or cidr_mask > 32 then
        return false
    end
        -- 将IP转换为32位整数
    local ip_num = (ip_parts[1] * 2^24) + (ip_parts[2] * 2^16) + (ip_parts[3] * 2^8) + ip_parts[4]
    local cidr_num = (cidr_parts[1] * 2^24) + (cidr_parts[2] * 2^16) + (cidr_parts[3] * 2^8) + cidr_parts[4]
    local mask = bit.lshift(0xFFFFFFFF, 32 - cidr_mask)
        -- 通过按位与运算判断IP是否在CIDR范围内
    return bit.band(ip_num, mask) == bit.band(cidr_num, mask)
end

#vim /usr/local/nginx/conf/auth/main.lua #主程序入口文件,增加一些代码,代码分拆到文件中指定的位置哈

-- 获取客户端IP
local function get_client_ip()
    local ip = ngx.var.remote_addr
    
    -- 检查代理头
    if ngx.var.http_x_forwarded_for then
        ip = ngx.var.http_x_forwarded_for:match("^([^,]+)")
    end
    
    return ip
end

-- 检查IP是否在白名单中
local function check_ip_whitelist(ip)
    local whitelist_file = config.whitelist_file
    local content = utils.read_file(whitelist_file)
    
    if not content then
        ngx.log(ngx.WARN, "白名单文件不存在或无法读取: ", whitelist_file)
        return false
    end
    
    -- 检查IP是否在白名单中
    for line in content:gmatch("[^\r\n]+") do
        local whitelisted_ip = line:match("^%s*(.-)%s*$")
        if whitelisted_ip and whitelisted_ip ~= "" then
            if utils.ip_in_cidr(ip, whitelisted_ip) then
                return true
            end
        end
    end
    
    return false
end
-- 主逻辑开始
local client_ip = get_client_ip()
ngx.log(ngx.INFO, "客户端IP: ", client_ip)

-- 检查IP白名单
if check_ip_whitelist(client_ip) then
    ngx.log(ngx.INFO, "IP在白名单中，跳过验证: ", client_ip)
    -- return  -- 继续处理原始请求,return后面一定要跟ngx.exit(ngx.DECLINED),不然你访问什么都是200状态码但是没内容
    -- 声明当前阶段处理完成，让Nginx继续后续处理
    return ngx.exit(ngx.DECLINED)
end

#这里我们要着重了解一下单纯的rerurn、return ngx.exit(ngx.DECLINED)、return ngx.exec(ngx.var.uri)的区别：

return的作用：

终止当前 Lua 代码块的执行：当遇到 return 时，Lua 脚本会立即退出当前函数或代码块，但不会通知 Nginx 请求处理状态。适用场景：

在 if-else 分支中提前结束逻辑，继续执行后续 Lua 代码，当需要返回值给调用者时（但在 Nginx 处理阶段中很少使用）。

当Nginx 处于 content_by_lua_file 阶段（负责生成响应内容）。由于没有显式生成内容或转发请求，Nginx 最终返回一个空响应（状态码 200，但内容为空）。

return ngx.exit(ngx.DECLINED) 的作用：

显式通知 Nginx 当前阶段处理完成：ngx.DECLINED 是一个特殊状态码，表示 “我不处理这个请求，交给后续模块/阶段继续处理”。适用场景：

在access 阶段(如 access_by_lua_file)中，用于跳过当前验证逻辑，让 Nginx 继续处理请求(如寻找静态文件、执行 proxy_pass等)当需要将请求流程控制权交还给 Nginx 时。

ngx.exec(ngx.var.uri) 的作用：

强制 Nginx 重新路由请求，从头开始处理当前 URI（包括执行 index 指令、寻找静态文件等）。

适用于 content_by_lua_file 场景，确保请求被正确转发到后续处理流程。

#echo "客户端IP" >>/usr/local/nginx/conf/auth/ip_whitelist.txt #把你要加的IP添加到此白名单文件中,一个IP或者网段单独一行

# vim /opt/web/index.html #再来一个最简单的测试页面

哈哈少年,恭喜你通过了考验!

简单测试：

浏览器分别访问：http://lua.test.com/index.html和http://lua.test.com/dasdasdas (自己验证结果哈,就不截图了,会分别显示内容和404)

博文来自：www.51niux.com

3.2 分层设计

#上面得读取文件的例子简单,而且只要修改完白名单文件就能立即生效,但是问题嘛就是不适合线上场景,线上的请求量大频繁的i/o开销影响性能。

# 我们初步这么设计,Nginx一启动就添加白名单中的内容到内存中,server区域有一个全局的Ip白名单认证通过就放行,不通过再流转到location的cookie认证。

# vi /usr/local/nginx/conf/auth/init_whitelist.lua

local config = require("config")

local whitelist_cache = ngx.shared.ip_whitelist_cache

-- 工具函数：检查IP是否在CIDR范围内
local function ip_in_cidr(ip, cidr)
    -- 若属于标准CIDR格式（像"192.168.1.0/24"这样），就会把IP地址和CIDR网络地址都转换为32位整数，然后借助位运算来判断该IP是否在这个网络范围内
    local _, _, base_ip, bits = string.find(cidr, "^(%d+%.%d+%.%d+%.%d+)/(%d+)$")
    if not base_ip then
        return ip == cidr  -- 不是CIDR格式，直接精确匹配
    end
    
    local function ip_to_int(ip_str)
        local a, b, c, d = string.match(ip_str, "^(%d+)%.(%d+)%.(%d+)%.(%d+)$")
        return (a * 2^24) + (b * 2^16) + (c * 2^8) + d
    end
    
    local ip_num = ip_to_int(ip)
    local base_num = ip_to_int(base_ip)
    local mask = bit32.lshift(0xFFFFFFFF, 32 - tonumber(bits))
    
    return bit32.band(ip_num, mask) == bit32.band(base_num, mask)
end

-- 加载白名单到共享字典
local function load_whitelist()
    local file, err = io.open(config.whitelist_file, "r")
    if not file then
        ngx.log(ngx.ERR, "无法打开白名单文件: ", err)
        return false
    end
    
    local content = file:read("*a")
    file:close()
    
    -- 清空现有缓存
    whitelist_cache:flush_all()
    
    -- 解析并存储白名单条目
    local count = 0
    for line in string.gmatch(content, "[^\r\n]+") do
        line = string.gsub(line, "^%s*(.-)%s*$", "%1")  -- 去除首尾空格
        if line ~= "" and not string.find(line, "^#") then
            -- 直接将IP/CIDR作为键存入共享字典
            whitelist_cache:set("entry:" .. line, true)
            count = count + 1
        end
    end
    
    -- 存储元数据
    whitelist_cache:set("last_loaded", ngx.time())
    whitelist_cache:set("count", count)
    
    ngx.log(ngx.INFO, "加载白名单完成，共 ", count, " 条记录")
    return true
end

-- 导出加载函数供工作进程调用
local _M = {}
_M.load_whitelist = load_whitelist

-- 初始化执行（仅加载一次，不创建定时器）
local success = load_whitelist()
if not success then
    ngx.log(ngx.ERR, "白名单初始化失败，拒绝所有请求")
    whitelist_cache:set("initialized", false)
else
    whitelist_cache:set("initialized", true)
end

return _M

# vi /usr/local/nginx/conf/nginx.conf #定义共享内存加载启动初始化程序文件

lua_package_path "/usr/local/lua_core/lib/lua/?.lua;/usr/local/nginx/conf/auth/?.lua;;";
# 定义共享内存（根据白名单大小调整，1MB约可存储5万条IP）    
lua_shared_dict ip_whitelist_cache 5m;
# Nginx启动时执行初始化脚本
init_by_lua_file /usr/local/nginx/conf/auth/init_whitelist.lua;

# vi /usr/local/nginx/conf/auth/ip_utils.lua

local _M = {}

-- 检查IP是否在CIDR范围内
function _M.ip_in_cidr(ip, cidr)
    local _, _, base_ip, bits = string.find(cidr, "^(%d+%.%d+%.%d+%.%d+)/(%d+)$")
    if not base_ip then
        return ip == cidr
    end
    
    local function ip_to_int(ip_str)
        local a, b, c, d = string.match(ip_str, "^(%d+)%.(%d+)%.(%d+)%.(%d+)$")
        return (a * 2^24) + (b * 2^16) + (c * 2^8) + d
    end
    
    local ip_num = ip_to_int(ip)
    local base_num = ip_to_int(base_ip)
    local mask = bit32.lshift(0xFFFFFFFF, 32 - tonumber(bits))
    
    return bit32.band(ip_num, mask) == bit32.band(base_num, mask)
end

return _M

# vi /usr/local/nginx/conf/auth/shared_state.lua

local _M = {
    is_whitelisted = false
}

function _M.set_whitelisted(status)
    _M.is_whitelisted = status
end

function _M.get_whitelisted()
    return _M.is_whitelisted
end

return _M

# vi /usr/local/nginx/conf/auth/check_whitelist.lua

local shared_state = require("shared_state")

-- check_whitelist.lua
local whitelist_cache = ngx.shared.ip_whitelist_cache

-- 获取客户端IP
local function get_client_ip()
    local ip = ngx.var.remote_addr
    local xff = ngx.var.http_x_forwarded_for
    
    if xff then
        -- 从XFF头中提取出第一个IP地址，以此作为客户端的真实 IP
        local first_ip = string.match(xff, "^([^,]+)")
        if first_ip then
            ip = first_ip
        end
    end
    
    return ip
end

-- 检查IP是否在白名单中
local function check_ip_whitelist(ip)
    local initialized = whitelist_cache:get("initialized")
    -- 先确认白名单是否已经初始化，如果没有初始化，就会拒绝所有请求
    if not initialized then
        ngx.log(ngx.ERR, "白名单未初始化，拒绝请求")
        return false
    end
    
    -- 先检查精确匹配
    if whitelist_cache:get("entry:" .. ip) then
        return true
    end
    
    -- 若精确匹配不通过，就会遍历所有CIDR格式的条目，使用的ip_in_cidr函数进行网络范围匹配
    local max_count = 10000  -- 限制最大扫描数量，为了防止遍历操作消耗过多资源
    local keys = whitelist_cache:get_keys(max_count)
    
    for _, key in ipairs(keys) do
        if string.sub(key, 1, 6) == "entry:" then
            local cidr = string.sub(key, 7)  -- 提取实际IP/CIDR
            
            -- 跳过精确IP（已检查过）
            if string.find(cidr, "/") then
                local ip_in_cidr = require "ip_utils".ip_in_cidr
                if ip_in_cidr(ip, cidr) then
                    return true
                end
            end
        end
    end
    
    return false
end

-- 主逻辑
local client_ip = get_client_ip()
ngx.log(ngx.INFO, "客户端IP: ", client_ip)

if check_ip_whitelist(client_ip) then
  ngx.log(ngx.INFO, "IP在白名单中，允许访问: ", client_ip)
  shared_state.set_whitelisted(true)  -- 设置共享状态
  return ngx.exit(ngx.DECLINED)
else
    -- 继续处理请求，让后续模块显示登录弹窗
    ngx.log(ngx.WARN, "IP不在白名单中，走弹窗认证逻辑: ", client_ip)
    -- ngx.log(ngx.WARN, "IP不在白名单中，拒绝访问: ", client_ip)
    -- return ngx.exit(ngx.HTTP_FORBIDDEN)  --如果想不在白名单中就直接返回403就开启这两行
end

#把3.1加的IP白名单的函数去掉,这里就不再展示注释代码了(不注释的话就算你走过了全局的IP白名单认证还会卡在main.lua这里)

# vi /usr/local/nginx/conf/auth/main.lua

-- 开头添加导入
local shared_state = require("shared_state")
local is_whitelisted = shared_state.get_whitelisted()
-- 在底部添加
if is_whitelisted then
    return ngx.exit(ngx.DECLINED)
end

-- 显示登录弹窗
show_login_popup(nil, ngx.var.request_uri)

# vim /usr/local/nginx/conf/conf.d/lua.test.com.conf

server {
    listen 80;
    server_name lua.test.com;
    root /opt/web;
    charset utf-8;
    error_log /usr/local/nginx/logs/error.log debug;
    # 在access阶段进行IP白名单检查
    access_by_lua_file /usr/local/nginx/conf/auth/check_whitelist.lua;

    location / {
        default_type 'text/plain';
        content_by_lua_file /usr/local/nginx/conf/auth/main.lua;
        index index.html;
    }

    # 允许访问注册接口
    location = /register {
        default_type 'text/plain';
        content_by_lua_file /usr/local/nginx/conf/auth/main.lua;
    }

    location ~ ^/favicon.ico$ {
        return 404;
        root    /opt/www/favicon;
    }
}

# /usr/local/nginx/sbin/nginx -s reload #可以通过ip_whitelist.txt中修改ip来验证效果,这里就不再截图演示了

#上面是通过Lua模块共享状态的方式,仅在单次请求生命周期内有效，适合简单场景

#下面还有通过通过请求头传递白名单状态：ngx.var.is_whitelisted = "1"/"0"的方式，还有使用共享字典存储临时认证状态的方式,可跨请求持久化，适合需要更复杂认证的场景：

 -- check_whitelist.lua中为白名单IP创建临时认证标记
 --在共享字典中标记该IP已认证（有效期1小时）
local auth_cache = ngx.shared.auth_cache
auth_cache:set("ip_auth:" .. client_ip, true, 3600)
-- 在main.lua中引用
local auth_cache = ngx.shared.auth_cache
local client_ip = get_client_ip()
local is_ip_whitelisted = auth_cache:get("ip_auth:" .. client_ip)

Nginx结合Lua基础知识(一)

Tue, 25 Mar 2025 17:34:45 +0800

一、Nginx+Lua简单使用

1.1 简单方式直接使用openresty

1.1.1 openresty安装

#官网：https://openresty.org/en/

# yum install -y readline-devel pcre-devel openssl-devel

# wget https://openresty.org/download/openresty-1.27.1.1.tar.gz

# tar xf openresty-1.27.1.1.tar.gz

# cd openresty-1.27.1.1/

# ./configure --prefix=/opt/soft/openresty --with-luajit --with-http_stub_status_module --with-pcre --with-pcre-jit

# gmake && gmake install

# vim /opt/soft/openresty/nginx/conf/nginx.conf #在server区域中加上这么一句调用lua

location /hello {
  default_type text/html;
  content_by_lua 'ngx.say("hello,lua scripts")';
}

# /opt/soft/openresty/nginx/sbin/nginx

# curl 127.0.0.1/hello #直接curl调用测试一下会看到有内容数据,说明lua调用成功

hello,lua scripts

1.2 nginx编译安装支持lua

安装luajit

# wget https://codeload.github.com/openresty/luajit2/tar.gz/refs/tags/v2.1-20250117.tar.gz

# tar xf v2.1-20250117.tar.gz

# cd luajit2-2.1-20250117

# make install PREFIX=/usr/local/luajit

# vim /etc/profile.d/lua.sh

export LUAJIT_LIB=/usr/local/luajit/lib
export LUAJIT_INC=/usr/local/luajit/include/luajit-2.1

# source /etc/profile.d/lua.sh

# echo "/usr/local/luajit/lib/" >>/etc/ld.so.conf.d/lua.conf

# ldconfig

#首先安装2.1版本的lua,因为我们是用OpenResty得lua-resty-core会提示需要luajit2.1,下面为报错提醒[注意但是不影响nginx启动,所以大家常用的https://codeload.github.com/LuaJIT/LuaJIT/tar.gz/refs/tags/v2.0.4 还是可以用的 ]：

nginx: [alert] detected a LuaJIT version which is not OpenResty's; many optimizations will be disabled and performance will be compromised 
(see https://github.com/openresty/luajit2 for OpenResty's LuaJIT or, even better, consider using the OpenResty releases from https://openresty.org/en/download.html)
nginx: [alert] [lua] base.lua:42: use of lua-resty-core with LuaJIT 2.0 is not recommended; use LuaJIT 2.1+ instead
nginx: [alert] [lua] lrucache.lua:25: use of lua-resty-lrucache with LuaJIT 2.0 is not recommended; use LuaJIT 2.1+ instead

#然后你说我安装官网的 https://github.com/LuaJIT/LuaJIT/archive/refs/tags/v2.1.ROLLING.tar.gz 好了吧,但是还是会有提醒依旧不会影响你服务启动,下面提醒：

nginx: [alert] detected a LuaJIT version which is not OpenResty's; many optimizations will be disabled and performance will be compromised 
(see https://github.com/openresty/luajit2 for OpenResty's LuaJIT or, even better, consider using the OpenResty releases from https://openresty.org/en/download.html)

安装需要的lua模块

#wget https://codeload.github.com/openresty/lua-nginx-module/tar.gz/refs/tags/v0.10.28.tar.gz

#tar xf lua-nginx-module-0.10.28.tar.gz

#wget https://codeload.github.com/openresty/lua-resty-core/tar.gz/refs/tags/v0.1.31.tar.gz

#tar xf lua-resty-core-0.1.31.tar.gz

#cd lua-resty-core-0.1.31

#make install PREFIX=/usr/local/lua_core

#wget https://codeload.github.com/openresty/lua-resty-lrucache/tar.gz/refs/tags/v0.15.tar.gz

#tar xf lua-resty-lrucache-0.15.tar.gz

#cd lua-resty-lrucache

#make install PREFIX=/usr/local/lua_core

安装nginx并配置lua进行测试

# yum install pcre pcre-devel openssl openssl-devel gd gd-devel -y

#wget https://nginx.org/download/nginx-1.28.0.tar.gz

#tar xf nginx-1.28.0.tar.gz

# cd nginx-1.28.0/

#./configure --prefix=/opt/soft/nginx --sbin-path=/opt/soft/nginx/sbin/nginx --conf-path=/opt/soft/nginx/main-conf/nginx.conf --error-log-path=/opt/log/nginx/error.log --http-log-path=/opt/log/nginx/access.log --pid-path=/opt/soft/nginx/run/nginx.pid --lock-path=/opt/soft/nginx/run/nginx.lock --user=work --group=work --http-client-body-temp-path=/opt/soft/nginx/cache/client_temp --http-proxy-temp-path=/opt/soft/nginx/cache/proxy_temp --http-fastcgi-temp-path=/opt/soft/nginx/cache/fastcgi_temp --http-uwsgi-temp-path=/opt/soft/nginx/cache/uwsgi_tmp --http-scgi-temp-path=/opt/soft/nginx/cache/scgi_temp --with-http_v2_module --with-http_stub_status_module --with-http_ssl_module --with-http_realip_module --with-http_sub_module --with-http_gzip_static_module --with-pcre --with-http_addition_module --with-http_image_filter_module --with-http_dav_module --with-http_flv_module --with-http_mp4_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_gzip_static_module --with-file-aio --with-http_random_index_module --with-ld-opt=-Wl,-rpath,/usr/local/luajit/lib --add-module=/opt/soft/package/nginx_lua/lua-nginx-module-0.10.28

#make -j 8

#make install

# vim /opt/soft/nginx/main-conf/nginx.conf #增加一条lua测试location

location /lua { default_type 'text/plain'; content_by_lua 'ngx.say("hello, lua")'; }

location / {
  root   html;
  index  index.html index.htm;
}

#mkdir /opt/soft/nginx/cache

#/opt/soft/nginx/sbin/nginx -t #测试是没有报错的所以语法没问题

#/opt/soft/nginx/sbin/nginx #报错如下：

nginx: [alert] failed to load the 'resty.core' module (https://github.com/openresty/lua-resty-core); 
ensure you are using an OpenResty release from https://openresty.org/en/download.html (reason: module 'resty.core' not found:
	no field package.preload['resty.core']
	no file './resty/core.lua'
	no file '/usr/local/luajit/share/luajit-2.1/resty/core.lua'
	no file '/usr/local/share/lua/5.1/resty/core.lua'
	no file '/usr/local/share/lua/5.1/resty/core/init.lua'
	no file '/usr/local/luajit/share/lua/5.1/resty/core.lua'
	no file '/usr/local/luajit/share/lua/5.1/resty/core/init.lua'
	no file './resty/core.so'
	no file '/usr/local/lib/lua/5.1/resty/core.so'
	no file '/usr/local/luajit/lib/lua/5.1/resty/core.so'
	no file '/usr/local/lib/lua/5.1/loadall.so'
	no file './resty.so'
	no file '/usr/local/lib/lua/5.1/resty.so'
	no file '/usr/local/luajit/lib/lua/5.1/resty.so'
	no file '/usr/local/lib/lua/5.1/loadall.so') in /opt/soft/nginx/main-conf/nginx.conf:119

# vim /opt/soft/nginx/main-conf/nginx.conf #开启引用前面编译的lua模块

    #gzip  on;
    #就是增加下面这一段
    lua_package_path "/usr/local/lua_core/lib/lua/?.lua;;";

# /opt/soft/nginx/sbin/nginx #启动没有再报错

# curl 127.0.0.1/lua #测试输出正常

hello, lua

1.3 nginx调用lua的简单介绍

lua在nginx的指令执行顺序：

图片链接：https://github.com/openresty/lua-nginx-module/blob/master/doc/images/lua_nginx_modules_directives.drawio.png

我们顺着上面的流程图把贯穿整个 Nginx生命周期的Lua 脚本执行链路,也就是Nginx Lua 模块提供了一系列钩子函数（hook),允许我们在 Nginx 的不同阶段执行 Lua 脚本介绍一下。以下是这些钩子的主要作用和调用顺序：

#一、初始化阶段
init_by_lua钩子函数 #全局初始化阶段,这是Nginx启动时最早的一个阶段,发生在主进程(master process)启动期间,且只执行一次。
init_worker_by_lua钩子函数 #Worker初始化阶段,在每个worker进程启动时执行,每个worker 进程都会独立运行一次,初始化的内容仅对当前 worker进程有效

#二、TLS(传输层安全协议)相关的钩子函数主要用于处理与TLS 握手、证书动态加载以及客户端认证等相关的逻辑
ssl_client_hello_by_lua #TLS客户端握手阶段,在收到客户端的TLS ClientHello消息时触发,发生在SSL/TLS握手的最早阶段
ssl_certificate_by_lua #TLS证书动态加载阶段,在TLS握手期间,当客户端请求连接时触发。发生在SSL/TLS握手之前
ssl_session_fetch_by_lua #TLS会话恢复阶段,在TLS握手期间，尝试恢复之前保存的TLS会话时触发。发生在SSL/TLS握手之前
ssl_session_store_by_lua #TLS会话存储阶段,在TLS握手完成后,将新的TLS会话保存到外部存储时触发

#三、HTTP level阶段,Nginx处理HTTP请求的各个阶段
server_rewrite_by_lua #这个阶段主要用于URL重写和复杂的逻辑处理，如访问控制或动态内容生成
set_by_lua #允许通过Lua脚本计算并设置变量值。它通常用于实现复杂的逻辑处理,并返回结果,在请求的rewrite和access阶段之前完成⁠⁣ 
rewrite_by_lua #用于在Nginx的rewrite阶段执行Lua脚本，主要用于URL重写和转发等功能
access_by_lua #用于在访问阶段执行用户自定义的Lua代码,在请求到达后端服务前进行权限检查,可以用来做权限管理/动态路由/限流控制/黑名单机制
content_by_lua #处理请求内容并生成响应⁠⁣
balancer_by_lua #在Nginx的负载均衡阶段动态选择上游服务器,它主要用于实现复杂的、自定义的负载均衡逻辑，例如基于请求参数、哈希算法或动态服务发现来选择后端服务器。
header_filter_by_lua #允许用户在HTTP响应头发送给客户端之前执行自定义Lua脚本。这一阶段的主要用途是修改或设置响应头
body_filter_by_lua #用于在响应体发送到客户端之前对其进行修改。它允许开发者以流式处理的方式操作响应内容
log_filter_by_lua #允许使用Lua脚本在日志记录阶段执行自定义逻辑，可用于统计分析或添加额外信息到日志中

#四、Worker进程退出阶段
exit_worker_by_lua #当Nginx Worker进程需要关闭时(例如服务器重启、重新加载配置或正常关闭时)，这一阶段适合用于清理资源、记录日志或通知外部系统等操作⁠⁣

Nginx调⽤ Lua 模块指令,Nginx的可插拔模块加载执⾏：

set_by_lua set_by_lua_file    #设置Nginx变量,可以实现负载的赋值逻辑    
access_by_lua access_by_lua_file    #请求访问阶段处理, ⽤于访问控制    
content_by_lua content_by_lua_file    #内容处理器, 接受请求处理并输出响应

Nginx 调⽤ Lua API：

ngx.var    #nginx变量    
ngx.req.get_headers    #获取请求头    
ngx.req.get_uri_args    #获取url请求参数    
ngx.redirect    #重定向    
ngx.print    #输出响应内容体    
ngx.say    #输出响应内容体,最后输出⼀个换⾏符    
ngx.header    #输出响应头

博文来自：www.51niux.com

1.4 lua在nginx中的一些阶段简单用法介绍

1.4.1 初始阶段例子介绍

init_by_lua例子介绍：

# vim nginx.conf

--init_by_lua块:在这里我们定义了一个全局变量_G.my_global_variable和一个全局函数_G.say_hello
init_by_lua '
-- 定义一个全局变量
_G.my_global_variable = "Hello from init_by_lua"
-- 定义一个全局函数
_G.say_hello = function(name)
  return "Hello, " .. name .. "! This message is from init_by_lua."
end
';

server {
  ......
  location /init_by_lua {
    --- content_by_lua块:在处理HTTP请求时，我们通过ngx.say输出了这个全局变量和调用了这个全局函数
    content_by_lua '
      -- 使用预加载的全局变量
      ngx.say(_G.my_global_variable)

      -- 调用预加载的全局函数
      local greeting = _G.say_hello("World")
      ngx.say(greeting)
      ';
}

# curl 127.0.0.1/init_by_lua #访问一下查看效果

Hello from init_by_lua
Hello, World! This message is from init_by_lua.

init_worker_by_lua例子介绍：

# vim nginx.conf

-- init_worker_by_lua块:当每个worker进程启动时,这段Lua代码会被执行一次。记录了每个worker进程的PID到Nginx的日志中，并且将这个PID存储到了全局变量 _G.worker_pid 中。
init_worker_by_lua '
  -- 引入lua库,我们使用了ngx.log函数来记录不同级别的日志消息（如ERROR、WARN、INFO）。
  local ngx_log = ngx.log
  local ngx_ERR = ngx.ERR
  local ngx_WARN = ngx.WARN
  local ngx_INFO = ngx.INFO

  -- 每个worker进程启动时输出一条日志
  ngx_log(ngx_INFO, "Worker process started with pid: ", ngx.worker.pid())

  -- 可以在这里初始化worker级别的一些变量或连接池等
  _G.worker_pid = ngx.worker.pid()
';

server {
  location /init_worker_by_lua {
      -- content_by_lua块:在处理HTTP请求时,可以访问在init_worker_by_lua中初始化的全局变量 _G.worker_pid，并将其作为响应的一部分返回给客户端
    content_by_lua '
      -- 在处理请求时可以使用worker级别初始化的数据
      ngx.say("This request is handled by worker with pid: ", _G.worker_pid)
    ';
  }
  ......  
}

# curl 127.0.0.1/init_worker_by_lua

This request is handled by worker with pid: 2871584

1.4.2 HTTP Level阶段介绍

rewrite_by_lua例子介绍：

#rewrite_by_lua 是早期的语法形式，直接将 Lua 脚本作为字符串传入。rewrite_by_lua_block 是更现代的形式，支持多行脚本编写，可读性更高。

#如果你的 Nginx 版本较新，建议使用 rewrite_by_lua_block，因为它更易读、更易维护。

# vim /opt/soft/nginx/main-conf/nginx.conf

location / {
  rewrite_by_lua '
    local uri = ngx.var.uri
    ngx.log(ngx.ERR, "Original URI: ", uri)
    -- 判断是否以 /api/v2/ 开头
    if not string.match(uri, "^/api/v2/") then
      -- 如果不是，则重写为 /api/v2/ 前缀
      local new_uri = "/api/v2" .. uri
      ngx.log(ngx.ERR, "Rewritten URI: ", new_uri)
      ngx.req.set_uri(new_uri, true) -- 设置新的 URI 并应用
    end
  ';
  #将请求转发到后端服务
  proxy_pass http://192.168.1.101;
}

# /opt/soft/nginx/sbin/nginx -s reload

# curl 127.0.0.1/api/abc

# tail -f /opt/log/nginx/access.log #当前lua机器查看日志

"GET /api/abc HTTP/1.1" 404 153 "-" "curl/7.61.1"

# tail -f /usr/local/nginx/logs/access.log #登录后台机器查看请求日志,可以看到url被重写请求过来了

"GET /api/v2/api/abc HTTP/1.0" 404 153 "-" "curl/7.61.1"

server_rewrite_by_lua例子介绍：

#例子描述:检查请求的 URI 是否以 /api/v2/ 开头,如果不是，则将原始 URI 拼接到 /api/v2 后面形成新的 URI,将重写后的 URI 应用到当前请求中。

#通过这种方式，可以确保所有请求都以 /api/v2/ 开头，从而实现统一的 API 路径管理

# vim /opt/soft/nginx/main-conf/nginx.conf

location /api {
  -- 因为server_rewrite_by_lua提示不认,所以更换为rewrite_by_lua_block 
  rewrite_by_lua_block {
    ngx.log(ngx.ERR, "Original URI: ", ngx.var.uri)  -- 打印调试日志
    -- 避免重复嵌套,如果URI不以/api/v2/开头，则进入if 块内的逻辑；否则跳过该逻辑
    if not string.match(ngx.var.uri, "^/api/v2/") then
      -- 这一行的作用是将原始URI拼接到/api/v2后面,形成一个新的 URI 
      local new_uri = "/api/v2" .. ngx.var.uri
      ngx.log(ngx.ERR, "Rewritten URI: ", new_uri)  -- 打印重写后的 URI
      -- 设置新的URI,并应用重写规则,第二个参数true表示强制更新 URI,即使原始 URI 已经被重写过
      ngx.req.set_uri(new_uri, true)
    end
  }
}

# /opt/soft/nginx/sbin/nginx -s reload

# curl 127.0.0.1/api/reource

# tail -f /opt/log/nginx/error.log #因为是例子,所以访问资源不存在,直接看错误日志就行,从例子可看出这个请求是进入到url重写然后再出去重新进入判断然后响应

[error] 168085#0: *730 [lua] rewrite_by_lua(nginx.conf:46):2: Original URI: /api/reource, client: 127.0.0.1, server: localhost, request: "GET /api/reource HTTP/1.1", host: "127.0.0.1"
[error] 168085#0: *730 [lua] rewrite_by_lua(nginx.conf:46):5: Rewritten URI: /api/v2/api/reource, client: 127.0.0.1, server: localhost, request: "GET /api/reource HTTP/1.1", host: "127.0.0.1"
[error] 168085#0: *730 [lua] rewrite_by_lua(nginx.conf:46):2: Original URI: /api/v2/api/reource, client: 127.0.0.1, server: localhost, request: "GET /api/reource HTTP/1.1", host: "127.0.0.1"
[error] 168085#0: *730 open() "/opt/soft/nginx/html/api/v2/api/reource" failed (2: No such file or directory), client: 127.0.0.1, server: localhost, request: "GET /api/reource HTTP/1.1", host: "127.0.0.1"

set_by_lua例子介绍：

set_by_lua和set_by_lua_file区别介绍：

set_by_lua 和 set_by_lua_file ：这两个模块都⽤于设置 Nginx 变量。 set_by_lua 通过 inline Lua 代码设置变量的值， set_by_lua_file 则可以通过引⼊ Lua 脚本⽂件来设置变量。这两个模块通常⽤于实现负载的赋值逻辑，如根据请求的 headers 头部信息等进⾏动态变量设置。

先来一个set_by_lua的例子：

location ~ /ftest {
  #定义一个 Nginx 变量 $input，其初始值为 "Hello, Lua!"
  set $input "Hello,Lua!";
  #通过 Lua 脚本对变量$input使用string.upper 函数将字符串转换为大写，并将结果赋值给变量 $output
  set_by_lua $output 'return string.upper(ngx.var.input)';
  return 200 "Input: $input, Output: $output\n";
}

# curl 127.0.0.1/ftest

Input: Hello,Lua!, Output: HELLO,LUA!

博文来自：www.51niux.com

再来一个set_by_lua_block的例子(动态生成变量):

location /time {
  #用于动态生成变量 $current_time 的值
  set_by_lua_block $current_time {
     #获取当前时间并格式化为标准的日期时间字符串
     return os.date("!%Y-%m-%d %H:%M:%S")
  }
  #将生成的时间作为响应头的一部分返回
  add_header X-Current-Time $current_time;
  return 200 "The current time is: $current_time\n";
}

再来一个set_by_lua_file的简单例子：

location /multiply {
  # 定义一个变量 $result 来存储 Lua 脚本的返回值
  set $result "";
  # 调用外部Lua脚本进行计算,将$arg_number(即 URL参数number的值)作为参数传递给Lua脚本并将返回值赋值给变量$result
  set_by_lua_file $result '/opt/soft/openresty/nginx/conf/lua/multiply.lua' $arg_number;
  # 将计算结果返回给客户端
  return 200 "Result: $result\n";
}

# \vi /opt/soft/openresty/nginx/conf/lua/multiply.lua

-- 获取第一个参数(即$arg_number的值),并尝试将其转换为数字类型
local number = tonumber(ngx.arg[1])

-- 如果参数无效或无法转换为数字，则返回错误信息 "Invalid input"
if not number then
    return "Invalid input"
end

-- 将数字乘以2，并将结果转换为字符串类型后返回
return tostring(number * 2)

# curl 127.0.0.1//multiply?number=6

Result: 12

# curl 127.0.0.1//multiply?number=dadssa

Result: Invalid input

access_by_lua_block例子介绍：

#同上,access_by_lua得写法适合简单字符串的形式,access_by_lua_block是后来支持的新特性支持直接编写多行Lua 代码，适合复杂的逻辑场景。更直观、更易维护

#写个简单针对token认证的例子.为了确保所有访问受保护资源的请求都经过身份验证，可以使用 access_by_lua 来实现以下功能

# vim /opt/soft/nginx/main-conf/nginx.conf

location /protected {
    access_by_lua_block {
        local token = ngx.req.get_headers()["Authorization"]

        -- 检查是否有 Authorization 头部
        if not token then
            ngx.status = 401
            ngx.header["Content-Type"] = "application/json"
            ngx.say('{"error": "Unauthorized: Missing token"}')
            -- ngx.HTTP_UNAUTHORIZED是OpenResty中Nginx Lua模块的一个函数调用,用于立即终止当前请求的处理,并返回指定的 HTTP 状态码给客户端。
            ngx.exit(ngx.HTTP_UNAUTHORIZED)
        end     
        -- 假设简单的验证逻辑：token 必须以 "Bearer" 开头
        if not string.match(token, "^Bearer") then
            ngx.status = 402
            ngx.header["Content-Type"] = "application/json"
            ngx.say('{"error": "Unauthorized: Invalid token format"}')
            ngx.exit(ngx.HTTP_UNAUTHORIZED)
        end     
        -- 进一步的验证逻辑可以在这里添加，例如解码 JWT 并验证签名
        ngx.log(ngx.ERR, "Token is valid, allowing request")
    }
    #上面都if判断后没有退出自然就流转到了后端响应接口
    proxy_pass http://192.168.1.102;
}

# /opt/soft/nginx/sbin/nginx -s reload

# curl -I 127.0.0.1/protected #无token请求

HTTP/1.1 401 Unauthorized

# curl -H "Authorization: tokentest" 127.0.0.1/protected #token不规范请求

{"error": "Unauthorized: Invalid token format"}

# curl -H "Authorization: Bearer aabbccdd" 127.0.0.1/protected #正常请求

content_by_lua_block例子介绍：

#content_by_lua是 OpenResty中的一个指令，用于在 Nginx 的content 阶段嵌入Lua 脚本代码,它通常用来动态生成 HTTP响应内容。假设现在要实现一个 RESTful API，用于返回当前服务器的时间。如果用户提供了有效的 API Token，则返回时间；否则返回 401 Unauthorized 错误。

# vim /opt/soft/nginx/main-conf/nginx.conf

location /api/time {
    content_by_lua_block {
        -- 获取请求头中的 Authorization 字段
        local authorization = ngx.req.get_headers()["Authorization"]

        -- 检查是否提供了有效的 Token
        if not authorization or authorization ~= "Bearer" then
            ngx.status = ngx.HTTP_UNAUTHORIZED
            ngx.say("Unauthorized: Please provide a valid token") 
            ngx.exit(ngx.HTTP_UNAUTHORIZED)
        end     

        -- 如果通过了身份验证，返回当前服务器时间
        local time = os.date("!%Y-%m-%d %H:%M:%S")
        ngx.say("Current server time: ", time)
    }
}

# /opt/soft/nginx/sbin/nginx -s reload

# curl -H "Authorization: xxxxyyyy" 127.0.0.1/api/time

Unauthorized: Please provide a valid token

# curl -H "Authorization: Bearer " 127.0.0.1/api/time #注意这是UTC时间,如果想显示北京时区的时间并且服务配置的是北京时区就用local time = os.date("%Y-%m-%d %H:%M:%S")

Current server time: 2025-03-26 07:39:10

header_filter_by_lua_block例子介绍:

# vim /opt/soft/nginx/main-conf/nginx.conf

location / {
    content_by_lua_block {
        ngx.say("Hello, World!")
    }
    header_filter_by_lua_block {
        -- 动态设置 X-Custom-Header 的值
        if ngx.var.uri == "/" then
            ngx.header["X-Custom-Header"] = "This is the root path"
        elseif ngx.var.uri == "/about" then
            ngx.header["X-Custom-Header"] = "This is the about page"
        else    
            ngx.header["X-Custom-Header"] = "Unknown path"
        end     
    }
}
location /about {
    content_by_lua_block {
        ngx.say("About Page")
    }
    header_filter_by_lua_block {
        ngx.header["X-Custom-Header"] = "Custom value for about page"
    }
}

# /opt/soft/nginx/sbin/nginx -s reload

# curl -I http://localhost/

X-Custom-Header: This is the root path

# curl -I http://localhost/dsada

X-Custom-Header: Unknown path

# curl -I http://localhost/about

X-Custom-Header: Custom value for about page

body_filter_by_lua_block例子介绍：

#body_filter_by_lua_block指令允许用户通过 Lua 脚本对HTTP响应体进行修改或处理,主要用途:修改响应内容/分块传输处理/后处理逻辑(在响应发送给客户端之前，执行一些额外的逻辑。例如，压缩响应内容、加密数据或记录日志）

#工作原理: ngx.arg[1]: 表示当前块的响应体数据（字符串类型）/ngx.arg[2]: 表示是否为最后一块数据（布尔值）。修改 ngx.arg[1] 的值会影响最终发送给客户端的响应体内容。body_filter_by_lua_block会影响每个请求的响应阶段，确保脚本逻辑尽量简单以避免性能问题

# vim /opt/soft/nginx/main-conf/nginx.conf

location /body { 
    content_by_lua_block {
        ngx.say("Hello, this is the original response body.") 
    }
    body_filter_by_lua_block {
        -- 检查是否有剩余的响应数据
        if ngx.arg[2] then
            -- 如果是最后一块数据，则添加注释
            local last_part = ngx.arg[1]
            ngx.arg[1] = last_part .. "\n<!-- This is a dynamic footer added by Lua -->"
        end     
    }
}

# curl http://localhost/body

Hello, this is the original response body.

<!-- This is a dynamic footer added by Lua -->

1.4.3 work进程退出阶段介绍

#当我们进程退出的时候,我们想记录一些信息到日志中,这就需要用到exit_worker_by_lua_block

# vim /usr/local/nginx/conf/nginx.conf

#nginx进程多一点才能测出效果
worker_processes  4;
http {
......
    #在每个工作进程启动时初始化一个全局计数器worker_counter
    init_worker_by_lua_block {
        -- ngx.shared是nginx提供的一个共享内存区域，允许多个请求和工作进程之间共享数据。
        -- worker_counter是我们在共享内存中定义的一个键。如果该键不存在，则初始化为一个空表 {}。
        ngx.shared.worker_counter = ngx.shared.worker_counter or {}
        -- 在共享内存中，我们定义了一个count 键，用于记录当前工作进程处理的请求数
        -- 如果count键不存在(即第一次启动)，则初始化为 0；否则，将其值加1
        ngx.shared.worker_counter.count = (ngx.shared.worker_counter.count or 0) + 1
    }
    #在每个工作进程退出时执行清理操作。在这个例子中，它记录了该工作进程处理的请求数，并清除了计数器。
    exit_worker_by_lua_block {
        -- 从共享内存中读取当前工作进程处理的请求数，并赋值给变量count
        local count = ngx.shared.worker_counter.count
        -- 检查count是否存在。如果存在，则继续执行后续逻辑
        if count then
            -- 使用 ngx.log函数记录一条日志消息。日志级别为 INFO，表示这是一条普通信息日志。日志内容包括工作进程退出的信息以及它处理的总请求数
            ngx.log(ngx.INFO, "Worker process exiting. Total requests handled: ", count)
            -- 将共享内存中的count键设置为 nil，以清理数据
            ngx.shared.worker_counter.count = nil -- 清理计数器
        end
    }
}
server {
......
    #每次请求/count路径时，增加请求计数并返回当前计数值。
    location /count {
      content_by_lua_block {
      --从共享内存中读取当前工作进程处理的请求数，并赋值给变量count
      local count = ngx.shared.worker_counter.count
      -- 将共享内存中的count键的值加 1，表示处理了一个新的请求
      ngx.shared.worker_counter.count = count + 1
      ngx.say("Worker process  pid: ", ngx.worker.pid()..",".."Hello, worker counter: ", count)
      }
    }
}

# /usr/local/nginx/sbin/nginx -s reload

# curl 127.0.0.1/count #以此类推,多curl几回

Worker process  pid: 3373320,Hello, worker counter: 1

# curl 127.0.0.1/count

Worker process  pid: 3373321,Hello, worker counter: 1

# /usr/local/nginx/sbin/nginx -s reload

# tail -100f /usr/local/nginx/logs/error.log #可以看下打印的日志

[info] 3373321#0: [lua] exit_worker_by_lua(nginx.conf:46):5: Worker process exiting. Total requests handled: 2
[info] 3373322#0: [lua] exit_worker_by_lua(nginx.conf:46):5: Worker process exiting. Total requests handled: 2
[info] 3373323#0: [lua] exit_worker_by_lua(nginx.conf:46):5: Worker process exiting. Total requests handled: 2
[info] 3373320#0: [lua] exit_worker_by_lua(nginx.conf:46):5: Worker process exiting. Total requests handled: 3

二、lua常用模块使用

#nginx使用到的模块如何使用：https://github.com/openresty/lua-nginx-module#description

#从过上面的章节我们对lua在nginx各个阶段的使用有了一个初步的了解,但是如果要实现我们的功能还要结合mysql、redis等一些功能来使用

博文来自：www.51niux.com

2.1 lua-resty-mysql的学习使用

2.1.1 使用方法学习

#https://github.com/openresty/lua-resty-mysql?tab=readme-ov-file#methods #先根据文档把使用方法学习一下

new：

语法：db, err = mysql:new()

#创建MySQL连接对象。如果失败，则返回nil和一个描述错误的字符串。

connect：

语法: ok, err, errcode, sqlstate = db:connect(options)

#options参数是一个Lua表，其中包含以下键,详细的参照官网文档把

set_timeout:

语法: db:set_timeout(time)

#为后续操作(包括连接方法)设置超时(以毫秒为单位)保护。

set_keepalive：

语法: ok, err = db:set_keepalive(max_idle_timeout, pool_size)

#立即将当前MySQL连接放入ngx_lua cosocket连接池。

get_reused_times:

语法: times, err = db:get_reused_times()

#此方法返回当前连接的（成功）重用次数。如果发生错误，它将返回nil和一个描述错误的字符串。

#如果当前连接不是来自内置连接池，则此方法始终返回0，即连接从未被重用（尚未）。如果连接来自连接池，则返回值始终为非零。因此，此方法也可用于确定当前连接是否来自池。

close:

语法: ok, err = db:close()

#关闭当前mysql连接并返回状态。如果成功，返回1。如果发生错误，则返回nil，并返回一个描述错误的字符串。

send_query：

语法：bytes, err = db:send_query(query)

#将查询发送到远程MySQL服务器，而不等待其回复。返回成功发送的字节，否则返回nil和描述错误的字符串。之后，使用read_result方法读取MySQL的回复。

read_result:

语法: res, err, errcode, sqlstate = db:read_result()

语法: res, err, errcode, sqlstate = db:read_result(nrows)

#读取MySQL服务器返回的一个结果。它返回一个包含所有行的数组。每行包含每个数据字段的键值对。例如：

{
   { name = "Bob", age = 32, phone = ngx.null },
   { name = "Marry", age = 18, phone = "10666372"}
}

#如果发生错误，此方法最多返回4个值：nil、err、errcode和sqlstate。err返回值包含一个描述错误的字符串，errcode返回值包含MySQL错误代码（一个数值），最后，sqlstate返回值包含由5个字符组成的标准SQL错误代码。请注意，如果MySQL不返回errcode和sqlstate，它们可能为nil。

query：

语法: res, err, errcode, sqlstate = db:query(query)

语法: res, err, errcode, sqlstate = db:query(query, nrows)

#这是组合send_query调用和第一个read_result调用的快捷方式。如果成功，应该始终检查err返回值是否再次出现，因为此方法只会调用read_result一次。

server_ver:

语法: str = db:server_ver()

#返回MySQL服务器版本字符串，如“5.1.64”。

set_compact_arrays:

语法：db:set_compact_arrays(boolean)

#设置是否对后续查询返回的结果集使用“紧凑数组”结构。

2.1.2 环境支持

#如果不想使用 OpenResty，但仍然可以单独安装 lua-resty-mysql 模块。可以通过 LuaRocks 或手动编译安装。

LuaRocks安装方式：

#yum install libtermcap-devel ncurses-devel libevent-devel readline-devel -y

#wget https://luarocks.org/releases/luarocks-3.11.1.tar.gz

#tar xf luarocks-3.11.1.tar.gz

#cd luarocks-3.11.1/

#./configure --with-lua="/usr/local/luajit/" --lua-suffix="jit" --with-lua-include=/usr/local/luajit/include/luajit-2.1/

#make && make install

# luarocks --version

/usr/local/bin/luarocks 3.11.1
LuaRocks main command-line interface

#luarocks install lua-resty-mysql #因为拉取的是https://github.com/openresty/lua-resty-mysql/失败了就多执行几次

# find /usr/local/|grep mysql|grep resty #可以查看一下是否安装到了指定位置

/usr/local/lib/luarocks/rocks-5.1/lua-resty-mysql
/usr/local/lib/luarocks/rocks-5.1/lua-resty-mysql/0.15-0
/usr/local/lib/luarocks/rocks-5.1/lua-resty-mysql/0.15-0/lua-resty-mysql-0.15-0.rockspec
/usr/local/lib/luarocks/rocks-5.1/lua-resty-mysql/0.15-0/doc
/usr/local/lib/luarocks/rocks-5.1/lua-resty-mysql/0.15-0/doc/README.markdown
/usr/local/lib/luarocks/rocks-5.1/lua-resty-mysql/0.15-0/rock_manifest
/usr/local/share/lua/5.1/resty/mysql.lua

#然后写例子测试一下：

# vim /usr/local/nginx/conf/lua_conf/lua_mysql_script.lua

-- 通过Lua的require函数加载了resty.mysql模块，并将其赋值给局部变量mysql。这个模块提供了与 MySQL数据库交互的功能
local mysql = require "resty.mysql"

-- 创建一个新的MySQL连接对象。如果创建失败，err将包含错误信息；否则，db 将是新创建的数据库连接对象。
local db, err = mysql:new()
-- 如果未能成功创建数据库连接对象（即db为nil），则输出错误信息并通过 return 结束脚本执行。
if not db then
    ngx.say("failed to instantiate mysql: ", err)
    return
end

-- 设置MySQL操作的超时时间，单位为毫秒。这里设置的是1秒。如果操作在1秒内未完成，将抛出超时错误
db:set_timeout(1000) 

-- 使用db:connect方法尝试连接到MySQL数据库服务器
local ok, err, errno, sqlstate = db:connect{
    host = "127.0.0.1",
    port = 3306,
    database = "testdb",
    user = "root",
    password = "aabbccdd123",
    -- max_packet_size: 允许的最大数据包大小，这里设置为 1MB
    max_packet_size = 1024 * 1024
}
-- 如果连接失败(即ok为false),则输出详细的错误信息并结束脚本执行
if not ok then
    ngx.say("failed to connect: ", err, ": ", errno, " ", sqlstate)
    return
end

-- 执行一个SQL查询语句,从test表中选择所有列的第一行记录。如果查询失败，err, errno,和sqlstate将包含错误信息
local res, err, errno, sqlstate = db:query("SELECT * FROM users LIMIT 1")
if not res then
    ngx.say("bad result: ", err, ": ", errno, ": ", sqlstate)
    return
end

-- 遍历查询结果res中的每一行，并打印出每行的id和name字段。这里的ipairs是用于遍历数组形式的表
for i, row in ipairs(res) do
    ngx.say("Row: ", row.id, " - ", row.name)
end

-- 将当前的数据库连接放入连接池中，以便后续使用。set_keepalive方法的第一个参数是最大空闲时间（毫秒），第二个参数是连接池中的最大连接数
local ok, err = db:set_keepalive(10000, 100)
-- 如果无法将连接放入连接池，则输出错误信息并结束脚本执行。
if not ok then
    ngx.say("failed to set keepalive: ", err)
    return
end

# vim /usr/local/nginx/conf/nginx.conf

location /test {
    content_by_lua_file /usr/local/nginx/conf/lua_conf/lua_mysql_script.lua;
}

#/usr/local/nginx/sbin/nginx -s reload

# mysql -uroot -p -e "select * from testdb.users;" #查看一下数据库现在的测试信息

# curl 127.0.0.1/test

Row: 1 - dage

原生源码包的方式:

#wget https://github.com/openresty/lua-resty-mysql/archive/refs/tags/v0.27.tar.gz

#tar xf v0.27.tar.gz

#cd lua-resty-mysql-0.27/

# /usr/local/luajit/bin/luajit -e "print(package.path)" #查看lua加载的路径

#mkdir /usr/local/luajit/share/lua/5.1/resty/ #选取上面查出来的任意路径

#cp lib/resty/mysql.lua /usr/local/luajit/share/lua/5.1/resty/

#wget https://github.com/openresty/lua-resty-string/archive/refs/tags/v0.16.tar.gz #lua-resty-string 模块,它包含了 resty.sha256,如果不安装这个的话会有下面报错,需要加密的模块：

usr/local/luajit/bin/luajit: /usr/local/luajit/share/luajit-2.1/resty/mysql.lua:5: module 'resty.sha256' not found:
	no field package.preload['resty.sha256']
	......

#tar xf v0.16.tar.gz

#cd lua-resty-string-0.16/

#cp lib/resty/*.lua /usr/local/luajit/share/lua/5.1/resty/ #至此就可以用上面的lua例子测试一下mysql的连接了

#当然你还有另一种加载模块的方式,你说我不想cp太麻烦我想加载多目录就可以在nginx上面这样配置：

-- 路径之间用分号 (;) 分隔。双分号 (;;) 表示保留Lua默认的搜索路径。
lua_package_path "/opt/soft/package/nginx_lua/lua-resty-mysql-0.27/lib/?.lua;/opt/soft/package/nginx_lua/lua-resty-string-0.16/lib/?.lua;/usr/local/lua_core/lib/lua/?.lua;;";
-- 当然使用绝对路径太长了,可以把这个lua文件都放到nginx指定的目录下面,然后使用./modules/?.lua;这种相对路径的方式

2.2 lua-resty-redis的学习使用

#一般mysql和redis都结合者使用,所以我们照着上面的方法也学习一下redis的使用

2.2.1 使用方法学习

#除了小写之外，所有Redis命令都有自己的同名方法。你可以在这里找到Redis命令的完整列表：http://redis.io/commands

new：

语法: red, err = redis:new()

#创建redis对象。如果失败，则返回nil和一个描述错误的字符串。

connect:

语法: ok, err = red:connect(host, port, options_table?)

语法: ok, err = red:connect("unix:/path/to/unix.sock", options_table?)

#尝试连接到redis服务器正在侦听的远程主机和端口，或redis服务器侦听的本地unix域套接字文件。在实际解析主机名并连接到远程后端之前，此方法将始终在连接池中查找由此方法的先前调用创建的匹配空闲连接。可选的options_table参数是一个Lua表,包含以下键：ssl、ssl_verify、server_name、pool、pool_size、backlog

set_timeout:

语法: red:set_timeout(time)

#为后续操作（包括连接方法）设置超时（以毫秒为单位）保护。从该模块的v0.28版本开始，建议使用set_timeouts来支持此方法。

set_timeouts:

语法: red:set_timeouts(connect_timeout, send_timeout, read_timeout)

#分别设置后续套接字操作的连接、发送和读取超时阈值（以毫秒为单位）。使用此方法设置超时阈值比set_timeout提供了更多的粒度。因此，最好使用set_timeout而不是set_timeout。v0.28版本中添加了此方法。

set_keepalive:

语法: ok, err = red:set_keepalive(max_idle_timeout, pool_size)

#立即将当前Redis连接放入ngx_lua cosocket连接池。可以指定连接在池中时的最大空闲超时（以毫秒为单位）以及每个nginx工作进程的池的最大大小。

#如果成功，返回1。如果发生错误，则返回nil，并返回一个描述错误的字符串。

get_reused_times:

语法: times, err = red:get_reused_times()

#此方法返回当前连接的（成功）重用次数。如果发生错误，它将返回nil和一个描述错误的字符串。

close:

语法: ok, err = red:close()

#关闭当前的redis连接并返回状态。如果成功，返回1。如果发生错误，则返回nil，并返回一个描述错误的字符串。

init_pipeline:

语法: red:init_pipeline()

语法: red:init_pipeline(n)

#启用redis流水线模式。所有后续对Redis命令方法的调用都将自动缓存，并在调用commit_pipeline方法时一次性发送到服务器，或者通过调用cancel_pipeline来取消。

commit_pipeline:

语法: results, err = red:commit_pipeline()

#通过在一次运行中将所有缓存的Redis查询提交到远程服务器来退出流水线模式。这些查询的所有回复都将被自动收集，并作为最高级别的大型多批量回复返回。

cancel_pipeline：

语法: red:cancel_pipeline()

#通过丢弃自上次调用init_pipeline方法以来所有现有的缓存Redis命令来退出流水线模式。

hmset:

语法: res, err = red:hmset(myhash, field1, value1, field2, value2, ...)

语法: res, err = red:hmset(myhash, { field1 = value1, field2 = value2, ... })

#Redis“hmset”命令的特殊包装器。当只有三个参数（包括“red”对象本身）时，最后一个参数必须是一个包含所有字段/值对的Lua表。

array_to_hash:

语法: hash = red:array_to_hash(array)

#将类似数组的Lua表转换为类似哈希表的辅助函数。此方法首次在v0.11版本中引入。

read_reply:

语法: res, err = red:read_reply()

#正在从redis服务器读取回复。该方法例如对于Redis Pub/Sub API最有用

2.2.2 环境支持

原生源码包的方式:

# wget https://github.com/openresty/lua-resty-redis/archive/refs/tags/v0.29.tar.gz

# tar xf v0.29.tar.gz

# mkdir /usr/local/luajit/share/lua/5.1/resty

# cp lua-resty-redis-0.29/lib/resty/redis.lua /usr/local/luajit/share/lua/5.1/resty/

#下面举一个redis的set和get的最简单用法

#vim /opt/soft/nginx/conf/lua_conf/set_redis.lua

local redis = require "resty.redis"
local red = redis:new()

-- 连接 Redis
red:set_timeout(1000) -- 超时时间 1 秒
local ok, err = red:connect("127.0.0.1", 6379)
if not ok then
    ngx.say("failed to connect: ", err)
    return
end

-- 设置键值对
local res, err = red:set("test01", "hello_redis")
if not res then
    ngx.say("failed to set test01: ", err)
    return
end

ngx.say("成功设置test01的值为 hello_redis")

-- 关闭连接
local ok, err = red:set_keepalive(10000, 100) -- 设置连接池参数
if not ok then
    ngx.say("failed to set keepalive: ", err)
    return
end

#vim /opt/soft/nginx/conf/lua_conf/get_redis.lua

local redis = require "resty.redis"
local red = redis:new()

-- 连接 Redis
red:set_timeout(1000) -- 超时时间 1 秒
local ok, err = red:connect("127.0.0.1", 6379)
if not ok then
    ngx.say("failed to connect: ", err)
    return
end

-- 获取键值
local value, err = red:get("test01")
if not value then
    ngx.say("failed to get test01: ", err)
    return
end

ngx.say("test01 的值是: ", value)

-- 关闭连接
local ok, err = red:set_keepalive(10000, 100) -- 设置连接池参数
if not ok then
    ngx.say("failed to set keepalive: ", err)
    return
end

#vim /opt/soft/nginx/main-conf/nginx.conf

server {
    ......
    location /set_redis {
        content_by_lua_file /opt/soft/nginx/conf/lua_conf/set_redis.lua;
    }
    location /get_redis {
        content_by_lua_file /opt/soft/nginx/conf/lua_conf/get_redis.lua;
    }    
    ......
}

# /opt/soft/nginx/sbin/nginx -s reload

#下面是测试结果：

# curl 127.0.0.1/set_redis

成功设置test01的值为 hello_redis

# curl 127.0.0.1/get_redis

test01 的值是: hello_redis

Nginx+Consul+Upsync实现动态负载均衡(三)

Sat, 08 Feb 2025 18:34:15 +0800

以往我们都使用的静态后端配置文件的方式,这就导致了每次都需要修改配置文件并reload,每次后端有变动要手工修改配置文件,这时候你想让你的后端动态变化起来,后端的IP变化了比如测试环境的容器IP变化了,你nginx无需reload,请求的后端就改为了最新的后端,那么就是本次文章要介绍的内容了。

一、nginx编译并使用Upsync

1.1 nginx编译upsync

Upsync是微博开源的一个基于nginx实现动态配置的模块,通过拉取consul的上游数据,实现无需重新加载nginx,动态修改后端服务器属性的目录，git地址：https://github.com/weibocom/nginx-upsync-module

#cd /opt/soft/package

#wget https://github.com/weibocom/nginx-upsync-module/archive/master.zip

#unzip master.zip

#cd nginx-1.26.2 #nginx的下载和解压就不再演示了

#./configure --prefix=/opt/soft/nginx --sbin-path=/opt/soft/nginx/sbin/nginx --conf-path=/opt/soft/nginx/main-conf/nginx.conf --error-log-path=/opt/log/nginx/error.log --http-log-path=/opt/log/nginx/access.log --pid-path=/opt/soft/nginx/run/nginx.pid --lock-path=/opt/soft/nginx/run/nginx.lock --user=work --group=work --http-client-body-temp-path=/opt/soft/nginx/cache/client_temp --http-proxy-temp-path=/opt/soft/nginx/cache/proxy_temp --http-fastcgi-temp-path=/opt/soft/nginx/cache/fastcgi_temp --http-uwsgi-temp-path=/opt/soft/nginx/cache/uwsgi_tmp --http-scgi-temp-path=/opt/soft/nginx/cache/scgi_temp --with-http_v2_module --with-http_stub_status_module --with-http_ssl_module --with-http_realip_module --with-http_sub_module --with-http_gzip_static_module --with-pcre --with-http_addition_module --with-http_image_filter_module --with-http_dav_module --with-http_flv_module --with-http_mp4_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_gzip_static_module --with-file-aio --add-module=/opt/soft/package/nginx-upsync-module-master

#make -j 4

#make install

#mkdir /opt/soft/nginx/cache/

#chown work:work /opt/soft/nginx/cache -R

#vim /opt/soft/nginx/main-conf/nginx.conf #修改配置文件就不多做介绍了,主要增加include:include /opt/soft/nginx/conf.d/*.conf;

# cat /opt/soft/package/nginx-upsync-module-master/README.md #可以看看使用示例这里就不多做介绍了

1.2 nginx使用upsync

试验1(基本配置并拉取什么样的配置信息)：

#从上图我们可以看到配置了两种key一种带端口的一种不带端口的,我们看看是如何加载的

# cat /opt/soft/nginx/conf.d/grafana_pool_upstream.conf

upstream grafana_pool {
   #server 127.0.0.1:8080;
   upsync 192.168.1.166:8500/v1/kv/offline/upstream/grafana/ upsync_timeout=5s upsync_interval=500ms upsync_type=consul strong_dependency=off;
   upsync_dump_path /data/nginx/conf/grafana_upstream.conf;
   include  /data/nginx/conf/grafana_upstream.conf;
}

# /opt/soft/nginx/sbin/nginx -t #报错很清晰啊,找不到配置文件,不应该啊,不应该自动创建配置文件吗如果目录存在的话

nginx: [emerg] open() "/data/nginx/conf/grafana_upstream.conf" failed (2: No such file or directory) in /opt/soft/nginx/conf.d/grafana_pool_upstream.conf:5
nginx: configuration file /opt/soft/nginx/main-conf/nginx.conf test failed

# touch /data/nginx/conf/grafana_upstream.conf

# /opt/soft/nginx/sbin/nginx -t #又有新的错误了,注意我配置文件一直注释着一行呢,就是那里我们打开一下试一试

nginx: [emerg] no servers are inside upstream in /opt/soft/nginx/conf.d/grafana_pool_upstream.conf:6
nginx: configuration file /opt/soft/nginx/main-conf/nginx.conf test failed

# cat /opt/soft/nginx/conf.d/grafana_pool_upstream.conf

upstream grafana_pool {
      #server这是一个固定格式,配置文件配置上就行
   server 127.0.0.1:11111 down;
   #upsync_timeout从consul拉取的超时时间,upsync_interval从consul拉取服务信息的时间间隔,upsync_type指定使用什么类型的服务
   #strong_dependency配置nginx在启动时是否强依赖配置服务器,如果配置为on,则拉取配置失败时Nginx启动或者检测就会报错,如果是off就是拉取失败还读取本地配置
   upsync 192.168.1.166:8500/v1/kv/offline/upstream/grafana/ upsync_timeout=5s upsync_interval=500ms upsync_type=consul strong_dependency=off;
   #指定从consul拉取的上游服务器后持久化到的文件为止,这样即使consul配置拉取失败,本地有备份依旧会走本地
   upsync_dump_path /data/nginx/conf/grafana_upstream.conf;
   #加载本地的配置文件
   include /data/nginx/conf/grafana_upstream.conf;
}

# /opt/soft/nginx/sbin/nginx -t

nginx: the configuration file /opt/soft/nginx/main-conf/nginx.conf syntax is ok
nginx: configuration file /opt/soft/nginx/main-conf/nginx.conf test is successful

# /opt/soft/nginx/sbin/nginx

# cat /data/nginx/conf/grafana_upstream.conf #可以看到创建的文件中有内容了,里面只记录带端口的key信息,权重之类的现在是默认的

server 192.168.1.166:3000 weight=1 max_fails=2 fail_timeout=10s;
server 192.168.1.165:3000 weight=1 max_fails=2 fail_timeout=10s;
server 192.168.1.164:3000 weight=1 max_fails=2 fail_timeout=10s;

博文来自：www.51niux.com

试验2(自动创建配置文件)：

#上个例子我们可以看到,本地备份的配置文件是需要手工创建的,不然就会提示加载不到,怎么解决这个问题呢,其中有两种方法,第一种很简单就是这些nginx配置文件肯定也是程序生成的,就是在生成配置文件的时候同时生成include加载的配置文件,第二种也不复杂就是注意命名的唯一,好了下面展示第二种方法。

# rm -f /data/nginx/conf/grafana_upstream.conf #先把我们产生的测试upstream.conf配置文件删掉,确保目录是空的

# cat grafana_pool_upstream.conf #就是用include *正则配置文件的方式,所以要确保前缀是唯一的

upstream grafana_pool {
   server 127.0.0.1:11111 down;
   upsync 192.168.1.166:8500/v1/kv/offline/upstream/grafana/ upsync_timeout=5s upsync_interval=500ms upsync_type=consul strong_dependency=off;
   upsync_dump_path /data/nginx/conf/grafana_upstream.conf;
   include  /data/nginx/conf/grafana_*.conf;
}

# /opt/soft/nginx/sbin/nginx -t #可自行验证,是没问题的

试验3(测试一下把nginx配置文件中的consul服务停掉,请求是否会读取本地)：

这里的试验方式呢,就是写个for循环一直curl然后你通过nginx的请求日志看看后端的生效方式：

试验3.1

我们将offline/upstream/grafana/下面的key清空,或者估计配置错offline/upstream/grafana123/,或者你配置的consul服务端连接不上的时候,这时候你重启nginx会发现不报错,因为获取不到新的key信息,所以/data/nginx/conf/grafana_upstream.conf中保留的是最后一份能获取到信息的后端配置内容,当然将/data/nginx/conf/grafana_upstream.conf删除掉之后再重启nginx是灌不进来任何信息的。

但是啊,虽然grafana_upstream.conf是空的,因为获取不到具体的后端配置,这时候我们配置的127.0.0.1那个就登场了,如果换成一个优雅的报错页面是不是就更好了。

试验3.2

承接上面的例子,现在我们请求走的是127.0.0.1,这时候我们往grafana下面增加一个key,你会发现请求就到了新的key上面,也就是能获取到后端就走指定的后端,没获取到后端再走默认的server。

试验3.3

承接上面的例子,现在的grafana_upstream.conf已经有一个后端了,我们现在把nginx配置的consul关闭掉,看看请求会不会走本地的配置文件去转发,答案是依旧可以。

试验3.4

承接上面的例子,我们把nginx重启一下,让其直接加载后端配置文件,我们看看curl的效果,直接说结果,你会发现并不是完全请求后端配置文件中的后端,偶尔会出现请求127.0.0.1不通再跳转到新后端的情况,也不是一直出现,是间隔一段时间出现一次

 HTTP/1.1" 301 234 "-" "curl/7.29.0" "-" "-" 0.001 127.0.0.1:11111, 192.168.1.228:80 502, 301 0.001, 0.000
 HTTP/1.1" 301 234 "-" "curl/7.29.0" "-" "-" 0.001 192.168.1.228:80 301 0.001
 ......
 HTTP/1.1" 301 234 "-" "curl/7.29.0" "-" "-" 0.001 127.0.0.1:11111, 192.168.1.228:80 502, 301 0.000, 0.000

这时候我们将nginx连接的consul恢复,然后增加一个新key,然后查看下请求方式,可以看到后端开始交替轮询了：

HTTP/1.1" 301 234 "-" "curl/7.29.0" "-" "-" 0.000 192.168.1.228:80 301 0.000
HTTP/1.1" 404 170 "-" "curl/7.29.0" "-" "-" 0.001 192.168.1.230:80 404 0.001
HTTP/1.1" 301 234 "-" "curl/7.29.0" "-" "-" 0.001 192.168.1.228:80 301 0.001
HTTP/1.1" 404 170 "-" "curl/7.29.0" "-" "-" 0.001 192.168.1.230:80 404 0.001

试验3.5

承接上面的例子,这时候我们把consul再次关闭,不重启nginx,然后将grafana_upstream.conf里面的后端悄悄的删去一个只保留192.168.1.228,再次重新curl起来,你会发现只要请求的还是consul关闭之前的后端配置,也就是说算你consul关闭了,只要nginx不重新加载,缓存中一直是最后一次的配置依旧是可以正常使用的(当然是前提你consul集群没有更新新配置的情况下,因为现在nginx已经跟consul断开连接了,consul的更新nginx也不会及时更新了)。

当我们nginx重新reload的时候呢,就会发现它重新回到了试验3.4的效果,请求除了大部分走到192.168.1.228上面外偶尔还会请求下127.0.0.1。

总结：通过上面的几个试验,我们可以知道nginx+upsync在各种情况下的请求转发,主要就是当consul出问题的时候,只要你nginx不重启,nginx就走最后一份路由缓存中的后端配置,如果你nginx重启了因为consul连接不上嘛,它就会加载你备份的后端配置文件中的配置,当你consul恢复后,会重新更新缓存。

博文来自：www.51niux.com

1.3 结合使用nginx_upstream_check_module

又要一个新的问题,如果你不是一个单一的后端,你有多个后端,用这种key/value得方式并不会健康检测,现在如果你consul获取多个后端,如果有一个节点有问题,是不是通过nginx的主动探测,不将流量转发给异常节点是不是就更好一点了,这就是要介绍的模块,具体介绍可搜网上面的信息。

直接说问题,现阶段是这样啊,如果nginx-upsync-module和nginx_upstream_check_module不配合使用你是可以使用nginx的最新版本的,但是要配合使用的话,nginx就要降版本,不然会有下面的报错(当然如果nginx版本是1.20+的话也不能用https://github.com/yaoweibin/nginx_upstream_check_module.git得用https://github.com/xiaokai-wang/nginx_upstream_check_module.git)：

objs/addon/src/ngx_http_upsync_module.o：在函数‘ngx_http_upsync_add_peers’中：
/opt/soft/package/nginx-upsync-module/src/ngx_http_upsync_module.c:893：对‘ngx_http_upstream_check_add_dynamic_peer’未定义的引用
objs/addon/src/ngx_http_upsync_module.o：在函数‘ngx_http_upsync_del_peers’中：
/opt/soft/package/nginx-upsync-module/src/ngx_http_upsync_module.c:1126：对‘ngx_http_upstream_check_delete_dynamic_peer’未定义的引用
collect2: 错误：ld 返回 1
make[1]: *** [objs/nginx] 错误 1
make[1]: 离开目录“/opt/soft/package/nginx-1.26.2”
make: *** [build] 错误 2

nginx加载两个模块

# cd /opt/soft/package/

#wget https://nginx.org/download/nginx-1.20.2.tar.gz

#tar xf nginx-1.20.2.tar.gz

#git clone https://github.com/weibocom/nginx-upsync-module.git

#git clone https://github.com/xiaokai-wang/nginx_upstream_check_module.git

#cd nginx-1.20.2

#patch -p1</opt/soft/package/nginx_upstream_check_module/check_1.20.1+.patch

#./configure --prefix=/opt/soft/nginx --sbin-path=/opt/soft/nginx/sbin/nginx --conf-path=/opt/soft/nginx/main-conf/nginx.conf --error-log-path=/opt/log/nginx/error.log --http-log-path=/opt/log/nginx/access.log --pid-path=/opt/soft/nginx/run/nginx.pid --lock-path=/opt/soft/nginx/run/nginx.lock --user=work --group=work --http-client-body-temp-path=/opt/soft/nginx/cache/client_temp --http-proxy-temp-path=/opt/soft/nginx/cache/proxy_temp --http-fastcgi-temp-path=/opt/soft/nginx/cache/fastcgi_temp --http-uwsgi-temp-path=/opt/soft/nginx/cache/uwsgi_tmp --http-scgi-temp-path=/opt/soft/nginx/cache/scgi_temp --with-http_v2_module --with-http_stub_status_module --with-http_ssl_module --with-http_realip_module --with-http_sub_module --with-http_gzip_static_module --with-pcre --with-http_addition_module --with-http_image_filter_module --with-http_dav_module --with-http_flv_module --with-http_mp4_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_gzip_static_module --with-file-aio --add-module=/opt/soft/package/nginx-upsync-module --add-module=/opt/soft/package/nginx_upstream_check_module

#make -j 4

#make install

#/opt/soft/nginx/sbin/nginx -V #可以自行检测一下

#/opt/soft/package/nginx_upstream_check_module/README 可以查看示例

使用探测模块

# cat grafana_pool_upstream.conf

upstream grafana_pool {
   server 127.0.0.1:11111;
   upsync 192.168.1.165:8500/v1/kv/offline/upstream/grafana/ upsync_timeout=5s upsync_interval=1s upsync_type=consul strong_dependency=off;
   upsync_dump_path /data/nginx/conf/grafana_upstream.conf;
   include  /data/nginx/conf/grafana_*.conf;
   #interval:向后端发送的健康检查包的间隔。 rise:如果连续成功次数达到rise_count,服务器就被认为是up。fall:如果连续失败次数达到fall_count,服务器就被认为是down。
   #timeout:后端健康探测请求的超时时间。 type:健康检查包的类型，现在支持以下多种类型:tcp/ssl_hello/http/fastcgi/mysql/ajp
   #缺省配置：如果没有配置参数，默认值是：`interval=30000 fall=5 rise=2 timeout=1000 default_down=true type=tcp`
   check interval=3000 rise=2 fall=5 timeout=2000 type=http;
   #check_http_send：http健康检查包发送的请求内容,该指令可以配置http健康检查包发送的请求内容。为了减少传输数据量，推荐采用"HEAD"方法。
   #当采用长连接进行健康检查时，需在该指令中添加keep-alive请求头，如："HEAD / HTTP/1.1\r\nConnection: keep-alive\r\n\r\n"。 
   #同时，在采用"GET"方法的情况下，请求uri的size不宜过大，确保可以在1个interval内传输完成，否则会被健康检查模块视为后端服务器或网络异常。
   check_http_send "GET /health/defaultcheck HTTP/1.0\r\n\r\n";
   #该指令指定HTTP回复的成功状态，默认认为2XX和3XX的状态是健康的。
   check_http_expect_alive http_2xx http_3xx http_4xx;
}

# /opt/soft/nginx/sbin/nginx #可以看看后端有没有探测URL,然后你再curl一下会发现5xx的后端不会再被访问到了,这个就自己for循环curl验证一下就可以了

#然后你再把http_4xx去掉,就是4xx也认为异常请求,你再curl探测会发现5xx和4xx的后端都不会接收到请求了：

1.4 记录一下curl往consul里面添加key信息

添加操作：

#curl -X PUT http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port

default: weight=1 max_fails=2 fail_timeout=10 down=0 backup=0;

#下面是一个完整的添加例子：

# curl -X PUT -d "{\"weight\":1, \"max_fails\":2, \"fail_timeout\":10}" http://192.168.1.165:8500/v1/kv/offline/upstream/grafana/192.168.1.229:80 #成功得话返回true

# curl -X PUT -d '{"weight":1, "max_fails":2, "fail_timeout":10}' http://192.168.1.165:8500/v1/kv/offline/upstream/grafana/192.168.1.229:80

删除操作：

#curl -X DELETE http://$consul_ip:$port/v1/kv/upstreams/$upstream_name/$backend_ip:$backend_port

#curl -X DELETE http://192.168.1.165:8500/v1/kv/offline/upstream/grafana/192.168.1.229:80

调整权重操作：

#就是添加操作,不存在此key就是创建,存在就是覆盖

关闭服务：

#curl -X PUT -d "{\"weight\":2, \"max_fails\":2, \"fail_timeout\":10, \"down\":1}" http://192.168.1.165:8500/v1/kv/offline/upstream/grafana/192.168.1.229:80

#curl -X PUT -d '{"weight":2, "max_fails":2, "fail_timeout":10, "down":1}' http://192.168.1.165:8500/v1/kv/offline/upstream/grafana/192.168.1.229:80

Nginx结合Consul-Template(二)

Fri, 01 Nov 2024 18:46:28 +0800

一、Consul KV

#要先来了解consul的重要功能KV

1.1 先简单了解下KV

简单了解

Consul的KV存储是一个简单而强大键值存储系统,也是Consul的核心功能,但是请注意它是一个简单的KV存储。

Consul KV允许用户存储索引对象它被广泛用于分布式系统中的配置管理和共享数据。

Consul KV数据存储位于server上，但可以由任何agent（client或server）访问。本地集成的RPC功能允许客户端向服务器转发请求，包括读取和写入键/值。

KV存储可以通过consul KV CLI子命令、HTTP API和consul UI访问。如果需要限制访问，请启用并配置acl。

数据存储本身位于Consul服务器的数据目录中。为了确保在完全中断的情况下不会丢失数据，请使用consul快照特性来备份数据。

Objects对Consul来说是不透明的，这意味着存储在key/value条目中的对象类型没有限制。object的主要限制是大小，最大限制是512 KB。

Consul的KV存储提供了类似文件系统的键值存储模型,其中每个键都是一个路径,类似于/path/to/key,而每个键对应的值可以是任意字节序列。

consul-template的官网文档：https://developer.hashicorp.com/consul/tutorials/network-automation/consul-template-load-balancing?utm_source=docs

Consul KV 存储

Consul的KV存储是基于Raft算法实现的。Consul将KV存储看作一个状态机，每个节点都维护一个本地的状态机和日志。当客户端向任何一个节点发送写操作请求时，该节点会将操作转发给leader，

leader将操作应用到状态机和日志中，并将结果通知所有follower。当大多数节点确认了某个操作时，该操作被认为是已提交的，leader将操作应用到状态机中，并将结果返回给客户端。

Consul的KV存储支持多种操作，包括读取、写入、更新和删除。每个键值对都由一个唯一的key标识，并且可以关联一个可选的value。

Consul的KV存储支持版本控制，每个key都可以存储多个版本的value，客户端可以选择读取特定版本的value。

1.2 跟着官网的例子学习一下key/value操作

向KV存储中添加数据

# consul kv put redis/config/minconns 1 #插入key是redis/config/minconns,value是1,没有此key就是创建,有此key就是更新

Success! Data written to: redis/config/minconns

# consul kv put redis/config/maxconns 25 #插入key是redis/config/maxconns,value是25

# consul kv put -flags=42 redis/config/users/admin zaphod #该命令的flags值为42。key支持设置64位整数标志值，该标志值不用于Consul内部，但可用于客户端向KV对添加元数据。

查询KV存储数据

#consul kv get redis/config/minconns #查询key是redis/config/minconns的值

# consul kv get -detailed redis/config/users/admin

CreateIndex      473907
Flags            42  #如果put的时候不设置flags这里默认是0
Key              redis/config/users/admin
LockIndex        0
ModifyIndex      473907
Session          -
Value            zaphod

# consul kv get -recurse #要列出存储中的所有键,结果按字典顺序返回。

redis/config/maxconns:25
redis/config/minconns:1
redis/config/users/admin:zaphod
redis/config/users/admin1:zaphod

# consul kv get -keys redis/config/ #这是查询redis/config下面都有什么key,跟上面命令不同,只显示此层信息,如果是目录比如users就显示redis/config/users/

#consul kv get -keys #默认四列出根目录下的所有keys

下面让我们查看一下web ui上面的显示效果：

#注意上面web页面如果想创建目录而不是key的话,就这样test/,就是在后面加/就表示创建目录,么有/就是创建key就要输入value了。

删除数据

要删除KV存储中某个键的值，使用consul KV delete命令。

# consul kv delete redis/config/minconns

# consul kv delete -recurse redis/config/users #-recurse选项删除所有带有users前缀的键,如果你的config目录下有users和users1两个目录,这个命令就会把两个

目录都删除掉,如果你只想删除掉users这个目录就可以执行# consul kv delete -recurse redis/config/users/命令

博文来自：www.51niux.com

1.3 http操作key/value

创建kv

# curl --request PUT --data "admin 123456" http://127.0.0.1:8500/v1/kv/redis01/config/user

# curl --request PUT --data "123456" http://127.0.0.1:8500/v1/kv/redis01/config/user/admin

#从上面的例子可以看到如果一个目录下面是可以同时存在同名的key的但是要是两种类型

# curl --request PUT --data "123456" http://127.0.0.1:8500/v1/kv/redis01/config/user/admin?flags=6666 #如果要添加其他参数这样添加

true

#让我们看看还能带上哪些其他参数？

dc (string: "") - 指定要查询的数据中心。这将默认为正在查询的agent的数据中心。
flags (int: 0) - 指定一个介于0和(2^64)-1之间的无符号值来存储键。API消费者可以为他们的应用程序选择任何方式来使用这个字段。
cas (int: 0) - 指定使用检查与设置操作。这对于更复杂的同步原语来说是非常有用的构建块。如果索引为0，那么Consul只会在键不存在的情况下才会放入该键。如果索引不为零，则仅在索引匹配该键的ModifyIndex时才设置该键。
acquire (string: "") - 提供用于锁获取操作的会话ID。
release (string: "") - 提供一个会话ID用于释放操作。这在与?acquire=配对时很有用，因为它允许客户端产生锁。这将使LockIndex保持不变，但将清除该键的关联会话。该密钥必须由此会话持有才能解锁。

#那会不会像service一样添加key的consul节点关闭了,key就跟着消失了呢,答案是不会的,除非执行delete删除操作。

Read Key

如果给定路径中不存在键，则返回404而不是200响应。

如果递归或键查询参数为真，将返回一个键数组。如果ACL策略配置的原因响应数组不包含结果，则响应header中包含X-Consul-Results-Filtered-By-ACLs: true

# curl http://127.0.0.1:8500/v1/kv/redis01/config/user/admin

[{"LockIndex":0,"Key":"redis01/config/user/admin","Flags":6666,"Value":"MTIzNDU2","CreateIndex":476187,"ModifyIndex":477574}]
#CreateIndex表示条目创建时间的内部索引值
#ModifyIndex是最后一个修改此键的索引
#LockIndex是在锁中成功获取该键的次数。如果锁被持有，会话键提供拥有该锁的会话
#Key就是条目的完整路径
#Flags是一个不透明的无符号整数，可以附加到每个条目。
#Value是一个base64编码的数据块。

#可以看到value值并未明文而是base64加密的需要解密一下

# echo "MTIzNDU2"|base64 -d

下面是一些查询条件：

dc (string: "") 
recurse (bool: false) - 指定查找是否应该递归并将key视为前缀而不是文字匹配。
raw (bool: false) - 指定响应只是键的原始值，没有任何编码或元数据。
keys (bool: false) -指 定只返回键（不返回值或元数据）。指定此参数意味着递归。
separator (string: "") - 指定用于递归键查找的分隔符的字符串。此选项仅在与keys参数配对时使用，以限制返回的键的前缀，仅限给定的分隔符。

# curl http://127.0.0.1:8500/v1/kv/redis01/config/user/admin?raw #可以看到只是单纯的显示value

# curl http://127.0.0.1:8500/v1/kv/redis01/config/?keys #可以看到是显示指定目录下所有的keys,以数组的形式展示

["redis01/config/user","redis01/config/user/admin","redis01/config/user/admin1","redis01/config/user1/admin1"]

# curl http://127.0.0.1:8500/v1/kv/redis01/config?recurse=true #显示所有key的详细信息,跟config?recurse一个效果

# curl http://127.0.0.1:8500/v1/kv/redis01/config/user/admin?keys #注意这是获取admin为前缀的key列表并非admin的key

Delete Key

# curl --request DELETE http://127.0.0.1:8500/v1/kv/redis01/config/user/admin #这是删除为redis01/config/user/admin的key不会删目录

true

# curl --request DELETE http://127.0.0.1:8500/v1/kv/redis01/config/user/admin?recurse #这是删除admin为前缀开头的key和目录

二、先跟着官网结构简单学习下consul-template

2.1 安装

官网地址：https://github.com/hashicorp/consul-template

# wget https://releases.hashicorp.com/consul-template/0.39.1/consul-template_0.39.1_linux_amd64.zip

# unzip consul-template_0.39.1_linux_amd64.zip

#mv consul-template /usr/local/bin/

# consul-template -v

consul-template v0.39.1 (cc8f954)

举个简单的例子：

# cat /tmp/in.tpl #定义一个foo的key

{{ key "foo" }}

# consul-template -template "in.tpl:out.txt" -once #-once是执行一次,你会发现这个进程一直在监听等待,如果foo有值的话再次执行得话进程就不会再监测卡主了

# /opt/soft/consul/consul kv put foo bar #给foo赋值bar,然后会发现的进程会执行完毕

# cat /tmp/out.txt #会看到key名称是foo会把获取的值写入到out.txt文件中

bar

# consul-template -template "in.tpl:out.txt" #如果不加-once会怎么样？那么这个进程会一直监测着foo这个key，一旦值发生变化就会更新out.txt文件可以试下

2.2 配置Consul模板

Consul Template可以使用命令行标志和配置文件进行配置。

命令行标志

# consul-template -h

-config=<path> #设置磁盘上配置文件或文件夹的路径。这可能是指定多次以加载多个文件或文件夹。如果有多个给定值后，它们从左向右合并，CLI参数取最高优先级。
-consul-addr=<address> #设置Consul实例的地址
-consul-auth=<username[:password]> #设置consul通信的基本身份验证用户名和密码
-consul-retry #与Consul通信失败时使用重试逻辑
-consul-retry-attempts=<int> #重试失败通信时使用的尝试次数
-consul-retry-backoff=<duration> #用于回退持续时间的基数。这个数字将是每次重试都会成倍增加
-consul-retry-max-backoff=<duration> #重试回退持续时间的最大限制。默认为一分钟。0表示无穷。回退将呈指数增长，直到给定值
-consul-ssl #在连接到Consul时使用SSL
-consul-ssl-ca-cert=<string> #根据此CA证书文件列表验证服务器证书
-consul-ssl-ca-path=<string> #设置要用于TLS验证的CA的路径
-consul-ssl-cert=<string> #要发送到服务器的SSL客户端证书
-consul-ssl-key=<string> #用于客户端认证密钥交换的SSL/TLS私钥
-consul-ssl-server-name=<string> #设置验证TLS时要使用的服务器的名称
-consul-ssl-verify #通过SSL连接时验证证书
-consul-token=<token> #设置Consul API令牌
-consul-token-file=<path> #将路径设置为包含Consul API令牌的文件
-consul-transport-dial-keep-alive=<duration> #设置用于keep-alive的时间
-consul-transport-dial-timeout=<duration> #设置为建立连接而等待的时间
-consul-transport-disable-keep-alives #禁用keep-alive（这会影响性能）
-consul-transport-max-idle-conns-per-host=<int> #设置每台主机允许的最大空闲连接数
-consul-transport-tls-handshake-timeout=<duration> #设置握手超时时间
-dedup #启用重复数据删除模式—当有多个实例时，可以减少Consul上的负载
-default-left-delimiter #模板的默认左分隔符
-default-right-delimiter #模板的默认右分隔符
-dry #将生成的模板打印到标准输出，而不是呈现
-exec=<command> #启用exec模式，使其作为类似管理程序的进程运行
-exec-kill-signal=<signal> #在优雅地终止进程时发送的信号
-exec-kill-timeout=<duration> #强制杀死进程之前的等待时间
-exec-reload-signal=<signal> #重新加载时发送的信号
-exec-splay=<duration> #发送信号前的等待时间
-exec-env-pristine #子进程不继承父进程的环境变量
-exec-env-custom #子进程附加的自定义环境变量
-exec-env-allowlist #暴漏给子进程的环境变量列表
-exec-env-denylist #禁止暴漏给子进程的环境变量列表
-kill-signal=<signal> #优雅关闭进程的信号
-log-level=<level> #设置日志级别，取值为debug,info,warn,err
-max-stale=<duration> #设置最大过期时间
-once #不要将该进程作为守护进程运行
-parse-only #不要处理模板仅解析它们的结构
-pid-file=<path> #pid文件的路径
-reload-signal=<signal> #监听到信号重新加载配置
-retry=<duration>  #如果Consul在与API通信时返回错误，则需要等待的时间
-syslog #将输出发送到syslog，而不是标准错误和标准输出。
-syslog-facility=<facility> #设置syslog日志应该记录的功能
-syslog-name=<name> #设置将出现在syslog中的应用程序的名称
-template=<template> #在磁盘上以‘in:out(:command)’的格式添加一个要监视的新模板
-template-error-fatal=<bool> #控制模板错误是否会导致consul-template立即退出。这将覆盖每个模板的设置
......
关于vault的就不列了
......
-wait=<duration> #设置在编写模板（并触发命令）之前等待的‘min(:max)’时间
-v, -version  #打印版本

# consul-template -template "in.tpl:out.txt" -exec "echo 'haha'" #先来一个例子,这里我们in.tpl里面定义了一个footest得key,注意这有点一次执行的意思,如果这是个新key没有value值的话,这个进程会一直等待直到有value出现,然后输出haha,如果这个key有value值的话就立马执行一次打印haha进程也就结束了。

# consul-template -template "in.tpl:out.txt:/bin/bash -c 'echo haha'" #这样进程会是常驻状态

# consul-template -template "in.tpl:out.txt:/bin/bash -c 'service nginx1 restart||true'" #如果你希望就算命令执行错误,进程还依旧运行,而不是非0退出的话

2.3 配置文件

配置文件是用HashiCorp配置语言编写,使用带有-config标志来使用配置文件。可以多次指定此参数以加载多个配置文件。最右侧的配置具有最高优先级。如果提供了目录的路径，则给定目录中的所有文件将按词法顺序递归合并。CLI上指定的命令优先于配置文件。

先来一个最简单的例子

#cat /tmp/config.hcl

consul {
  address = "127.0.0.1:8500"
}

template {
  contents = "{{key \"hello\"}}"
  destination = "/tmp/out1.txt"
  exec {
    command = "cat /tmp/out1.txt"
  }
}

# consul-template -config "/tmp/config.hcl" #使用配置文件,进程也是一直监听着这个key,如果又变化就会更新文件打印内容到屏幕,只有value变化的时候才会触发

下面是官网的一个配置文件详解：

Consul Template部分：

下面这些选项是配置Consul Template的顶级值。它们不是必需的，并且在省略时将回退到默认值。

#这表示Consul Template的配置部分的开始。本节中包含的所有值都属于Vault。
reload_signal = "SIGHUP"
kill_signal = "SIGINT"
max_stale = "10m"
block_query_wait = "60s"
log_level = "warn"
template_error_fatal = true
err_on_failed_lookup = true
wait {  
  min = "5s"
  max = "10s"
}

要启用下面这些功能，请在配置文件中声明值

pid_file = "/path/to/pid"
syslog {
    #这将启用syslog日志记录。
    enabled = true
    #这是要进行日志记录的syslog设施的名称
    facility = "LOCAL5"
}
#这个块定义了记录到文件的配置
log_file {  
    #如果指定了路径，则启用该特性。
    path = "/var/log/something.log"
    #可以写入日志文件的字节数
    log_rotate_bytes = 1024000
    #默认情况下是24h小时轮转一次
    log_rotate_duration = "3h"
    #日志的数量.默认为0(不删除任何文件)。设置为-1表示在创建新日志文件时丢弃旧的日志文件
    log_rotate_max_files = 10
}

Consul部分：

通过声明Consul块，使Consul Template能够与Consul连接。

下面表示Consul配置部分的开始。本节中包含的所有值都与Consul有关。

consul {
    #此块指定与请求一起传递的基本身份验证信息。
    auth {    enabled  = true
      username = "test"
      password = "test"
    }    
    address = "127.0.0.1:8500"    
    #这是一个用于读/写的Consul Enterprise名称空间,这是一个测试功能
    namespace = ""
    #这是连接到Consul时要使用的ACL令牌.如果没有在Consul集群上启用acl，则不需要设置此选项。
    token = ""
    #可以使用此选项指定包含令牌的文件的路径
    token_file = ""
    #这将控制从Consul返回错误时的重试行为。Consul Template具有高度容错性，这意味着它在遇到故障时不会退出
    
    retry {
      #这启用了重试。默认情况下，重试是启用的，所以这是多余的。
      enabled = true
      #这指定在放弃之前尝试的次数。将其设置为零将实现无限次重试。
      attempts = 12
      #这是重试尝试之间的基本睡眠时间。每次重试休眠的时间比这个基数长2个指数。对于5次重试，睡眠时间将是：250ms、500ms、15秒、25秒，然后是4s。
      backoff = "250ms"
      #这是重试尝试之间的最大睡眠时间。当max_backoff设置为零时，重试尝试之间的指数睡眠没有上限。
      #如果max_backoff设置为10s， backoff设置为1s，则睡眠时间将为：1s， 2s, 4s, 8s, 10s, 10s，…
      max_backoff = "1m"
    }
    
    #该块配置tcp连接选项
    transport {
      #这控制在空闲状态下两个keepalive传输之间的持续时间
      dial_keep_alive = "10s"
      #这控制了重试之间的tcp超时。
      dial_timeout = "10s"
      #这允许禁用保持活动连接  
      disable_keep_alives = true
      #最大空闲连接的数量
      max_idle_conns_per_host = 100
      #tls与consul握手的超时
      tls_handshake_timeout = "30s"
    }
    
    #此块配置用于连接到Consul服务器的SSL选项。
    ssl {     
      #这将启用SSL。指定SSL的任何选项也将启用它。
      enabled = true
      #这将启用SSL对等验证。默认值为"true",将检查全局CA链,以确保给定的证书有效。如果使用的是尚未添加的自签名证书对于CA链,可能需要禁用SSL验证
      verify = false
      #这是用于身份验证的证书的路径。
      cert = "/path/to/client/cert"
      key  = "/path/to/client/key"
      #这是用作CA的证书颁发机构的路径。这对于自签名证书或使用自己内部证书颁发机构（CA）的组织非常有用。
      ca_cert = "/path/to/ca"
      #这是指向PEM编码的CA证书文件目录的路径。
      ca_path = "path/to/certs/"
      #这将设置用于验证的SNI服务器名称。
      server_name = "my-server.com"
    }
}

Templates部分：

模板块定义了模板的配置。与其他块不同，这个块可以被指定多次来配置多个模板。也可以直接通过CLI配置模板。

template {
  #这是磁盘上用作输入模板的源文件。这通常被称为“Consul Template模板”。如果不使用'contents'选项，则需要此选项。
  source = "/path/on/disk/to/template.ctmpl"
  #这是源模板将在其中呈现的磁盘上的目标路径。如果父目录不存在，Consul Template将尝试创建它们，除非create_dest_dirs为false。
  destination = "/path/on/disk/where/template/will/render.txt"
  #此选项告诉Consul Template，如果目标路径的父目录不存在，则创建它们。默认值为true。
  create_dest_dirs = true
  #这个选项允许在配置文件中嵌入模板的内容，而不是为模板文件提供“源”路径。这对于短模板很有用。此选项与‘source’选项互斥。
  contents = "{{ keyOrDefault \"service/redis/maxconns@east-aws\" \"5\" }}"
  #在访问不存在的结构体或映射field/key时出现错误退出。当访问不存在的字段时，默认行为将打印“<no value>”
  error_on_missing_key = false
  #控制模板中的错误是否会导致consul-template立即退出。
  error_fatal = true
  #目标文件的文件权限
  perms = 0600
  #创建文件的用户和用户组,如果不指定，Consul Template将保留现有文件的所有权。
  user = 1000
  group = 1000  
  #写入新模版之前会创建一份备份,它只保留一个备份
  backup = true
  #这些是要在模板中使用的分隔符。默认值是“{{”和“}}”
  left_delimiter  = "{{"
  right_delimiter = "}}"
  #这些是模板中不允许使用的函数。如果模板包含这些函数之一，它将退出并显示错误。
  function_denylist = []
  #沙盒路径
  sandbox_path = ""
  #新模版到执行命令之间等待的最小和最大时间
  wait {
    min = "2s"
    max = "10s"
  }
  #这是可选的exec块，用于在呈现模板时提供要运行的命令。该命令只会在生成的模板发生更改时运行。
  exec {     
    command = ["restart", "service", "foo"]      
    timeout = "30s"
  }
  #为了向后兼容，模板块还支持裸command和command_timeout设置。
  command = ["restart", "service", "foo"]  
  command_timeout = "60s"
}

Modes部分:

使用以下选项配置Consul Template以在各种模式下运行。

Once Mode(一次模式)：

将Consul Template配置为只执行每个模板一次，并使用标志退出-once或在配置文件中退出。

once = true

De-Duplication Mode(重复数据删除模式):

此块定义了在重复数据删除模式下运行Consul Template的配置。

deduplicate {  # 这将启用重复数据删除模式。指定任何其他选项也会启用
  # 这将启用重复数据删除模式。指定任何其他选项也会启用
  enabled = true
  #这是Consul的KV存储路径的前缀，重复数据删除模板将在这里被预渲染和存储。
  prefix = "consul-template/dedup/"}

Exec Mode(执行模式):

此块定义了在执行模式下运行Consul Template的配置。

exec {
  #这是作为子进程执行的命令。每个Consul Template进程只能有一个命令。
  command = ["/usr/bin/app"]
  #等待命令完成的最大时间。默认情况下，该值为0，表示永久等待
  timeout = "0"
  #这是在终止命令之前等待的随机显示。默认值为0（无等待），但大型集群应考虑设置一个splay值，以防止所有子进程在数据更改时同时重新加载。
  splay = "5s"
  env {
    #这指定了子进程是否不应继承父进程的环境。默认情况下，子节点将具有对父节点环境变量的完全访问权限。
    pristine = false
    #这将以如下所示的形式指定额外的自定义环境变量，以注入子进程的运行时环境。
    custom = ["PATH=$PATH:/etc/myapp/bin"]
    #这将指定一个环境变量列表，以独占地包含在向子进程公开的环境变量列表中。
    allowlist = ["CONSUL_*"]
    #这将指定一个环境变量列表，以便在向子进程公开的环境变量列表中独占禁止。如果指定，则任何与给定模式匹配的环境变量都不会公开给子进程，即使它们在allowlist中。
    denylist = ["VAULT_*"]
  }
  #这定义了当监视的模板发生更改时将发送给子进程的信号。只有在进程启动后才会发送信号，并且只有在所有依赖模板至少渲染一次后才会启动进程。
  reload_signal = ""
  #这定义了当Consul Template正常关闭时发送给子进程的信号。应用程序应该开始优雅的清理。
  kill_signal = "SIGINT"
  #这定义了当Consul Template退出时等待子进程优雅终止所需的时间。默认是30s
  kill_timeout = "2s"
}

2.4 Reload Configuration and Templates

虽然运行Consul Template有多种方式，但最常见的模式是将Consul Template作为系统服务运行。当Consul Template首次启动时，它从磁盘读取所有配置文件和模板，并将它们加载到内存中。从那时起，如果不重新加载，对磁盘上文件的更改不会传播到正在运行的进程。

如果要更新配置或模板，只需将HUP发送到正在运行的Consul Template进程，Consul Template将从磁盘重新加载所有配置和模板。

上面的解释很好理解,就是当你用consul-template加载一个配置文件启动后,类似于Nginx,配置就都加载到内存里面了,这时候如果你改变了比如config.hcl里面的配置,比如监听的key从hello变成了hellotest,或者输出的文件从out1.txt变成了out2.txt,改完之后是不生效的,需要重启consul-template进程或者重新加载。

# kill -HUP "consul-template的对应pid进程号" #就能重新加载配置文件了

2.5 模版语言(翻译官网内容,可忽略)

#我们将都有哪些参数简单了解一下：

Consul Template解析以Go模板格式编写的文件。如果您不熟悉语法，请阅读Go的文档和示例。除了go提供的模板函数外，Consul template还提供以下函数：

API Functions：

API函数与远程API调用交互，与Consul和Vault等外部服务通信

caLeaf #查询Consul以获取代表单个服务的leaf certificate
caRoots #查询Consul以获取所有连接的受信任证书颁发机构(CA)根证书
connect #根据可连接服务的运行状况查询Consul
datacenters #查询Consul目录中的所有数据中心
exportedServices #查询Consul以获取给定分区中的所有导出服务
file #读取并输出磁盘上本地文件的内容。如果无法读取文件,则会发生错误。当文件更改时,Consul Template将获取更改并重新渲染模板
key #查询Consul以获取给定键路径处的值。如果密钥不存在，Consul Template将阻止渲染，直到密钥存在。为了避免阻塞，请使用keyOrDefault或keyExists
keyExists #查询Consul以获取给定键路径处的值。如果密钥存在,返回true否则返回false。与key不同如果key不存在，此函数将不会阻塞。这对于控制流量非常有用
keyOrDefault #查询Consul以获取给定键路径处的值。如果密钥不存在，则将使用默认值。与key不同，如果key不存在，此函数将不会阻塞
ls #查询Consul以获取给定关键路径上的所有顶级kv对
safeLs #与ls相同，但如果KV前缀查询返回空白/空数据，则拒绝呈现模板。这对于渲染由consul模板填充的关键任务文件特别有用。
node #在Consul中查询目录中的节点
nodes #查询目录中所有节点的Consul
partitions #查询所有分区的Consul
secret #在给定路径上查询Vault中的密钥
secrets #查询Vault以获取给定路径上的机密列表。并非所有端点都支持列表
pkiCert #使用实例查询PKI证书的存储库。它返回用字符串编码的证书PEM。它返回PKI证书、CA和密钥作为字段：Cert、CA和Key。
service #根据Consul的健康状况查询服务
services #向Consul查询目录中的所有服务
tree #查询Consul给定关键路径上所有kv对
safeTree #与tree相同，但如果KV前缀查询返回空白/空数据，则拒绝渲染模板。这对于渲染由consul模板填充的关键任务文件特别有用。

Scratch：

scratchpad在模板上下文中可用，用于存储临时数据或计算。暂存数据不会在模板之间共享，也不会在调用之间缓存。

scratch.Key #如果在指定key处的scratchpad中存在数据，则返回一个布尔值。即使该key处的数据为nil，这仍然返回true
scratch.Get #返回scratchpad中指定键处的值。如果数据不存在，则返回nil
scratch.Set #在给定key处保存给定值。如果该键上已经存在数据，则会被覆盖
scratch.SetX #这与Set的行为完全相同，但如果值已存在，则不会覆盖
scratch.MapSet #将值保存在映射中的指定key中。如果该键处已经存在数据，则覆盖该键
scratch.MapSetX #这与MapSet的行为完全相同，但如果值已经存在，则不会覆盖
scratch.MapValues #返回指定映射中所有值的排序列表(按key)

Helper Functions(辅助函数)：

与API函数不同，helper函数不查询远程服务。这些函数对于解析数据、格式化数据、执行数学运算等都很有用

base64Decode #接受base64编码的字符串并返回解码结果，如果给定的字符串不是有效的base64字符串，则返回错误
base64Encode #接受一个字符串并返回一个base64编码的字符串
base64URLDecode #接受一个base64编码的url安全字符串并返回解码的结果，如果给定的字符串不是一个有效的base64 url安全字符串，则返回一个错误
base64URLEncode #接受字符串并返回base-64编码的url安全字符串
byKey #接受从tree调用返回的对列表，并创建一个映射，根据它们的顶级目录对它们进行分组
byTag #获取服务或服务函数返回的服务列表，并创建按标记分组服务的映射
byMeta #接受service返回的服务列表，并返回按ServiceMeta值对服务进行分组的映射。多个服务元键可以作为逗号分隔的字符串传递
contains #确定指针是否在可迭代元素内
containsAll #如果所有针头都在一个可迭代元素中，则返回true，否则返回false。如果指针列表为空，则返回true
containsAny #如果指针位于可迭代元素中，则返回true，否则返回false。如果指针列表为空，则返回false
containsNone #如果可迭代元素中没有针头则返回true，否则返回false。如果指针列表为空，则返回true
containsNotAll #如果某个指针不在可迭代元素中，则返回true，否则返回false。如果指针列表为空，则返回false
env #读取当前进程可访问的给定环境变量
mustEnv #读取当前进程可访问的给定环境变量。如果变量未定义或为空，则替换将失败并出现错误
envOrDefault #读取当前进程可访问的给定环境变量。如果找到了环境变量，将使用该变量的值。这包括空值。否则，将使用默认值
executeTemplate #执行并返回已定义的模板
explode #从tree或ls调用中获取结果，并将其转换为用于解析/遍历的深嵌套映射
explodeMap #使用与explosion相同的逻辑，获取map的值并将其转换为用于解析/遍历的深嵌套映射
indent #通过在每行前添加N个空格来缩进一段文本
in #确定指针是否在可迭代元素内
loop #接受不同的参数，并根据这些参数改变其行为。如果给loop一个整数，它将返回一个从0开始的程序，循环到但不包括给定的整数
join #将给定的字符串列表视为管道，并将它们连接到提供的字符串上
mergeMap #获取explode和一个explode参数的结果，然后合并这两个映射。参数的源不会被管道映射覆盖
mergeMapWithOverride #获取explode和一个explode参数的结果，然后合并这两个映射。参数的源将被管道映射覆盖
trimSpace #接受提供的输入并修剪所有空格、制表符和换行符
trim #接受提供的输入并裁剪所有前导和尾部的unicode
trimPrefix #接受提供的输入并修剪前导前缀字符串
parseBool #接收给定的字符串并将其解析为布尔值
parseFloat #获取给定的字符串并将其解析为以10为底的float64
parseInt #获取给定的字符串并将其解析为以10为基数的int64
parseJSON #接受给定的输入(通常是key的值)，并将结果解析为JSON
parseUint #获取给定的字符串并将其解析为以10为基数的int64
parseYAML #接受给定的输入(通常是key的值)并将结果解析为YAML
plugin #获取插件名称和可选有效负载，并执行Consul Template插件
regexMatch #将参数视为正则表达式，如果与给定字符串匹配，则返回true，否则返回false
regexReplaceAll #将参数视为正则表达式，并将正则表达式的所有出现替换为给定的字符串
replaceAll #将参数视为字符串，并将给定字符串的所有出现替换为给定字符串
sha256Hex #将参数视为字符串并计算sha256_hex值
md5sum #将字符串输入作为参数，并返回输入的十六进制编码的md5哈希
hmacSHA256Hex #将key和消息作为字符串输入。返回具有给定参数的十六进制编码的HMAC-SHA256哈希
split #在提供的分隔符上拆分给定字符串
splitToMap #在提供的分隔符上拆分给定字符串，并将每个结果项拆分为key和value
timestamp #以字符串(UTC)形式返回当前时间戳。如果没有给出参数，结果是当前RFC3339时间戳
toJSON #从tree或ls调用获取结果并将其转换为JSON对象
toJSONPretty #从tree或ls调用中获取结果，并将其转换为打印精美的JSON对象，缩进两个空格
toUnescapedJSON #从tree或ls调用中获取结果,并将其转换为JSON对象,而不进行HTML转义。当处理数据库连接字符串或包含查询参数的uri时，这个函数会派上用场
toUnescapedJSONPretty #从tree或ls调用中获取结果，并将其转换为打印精美的JSON对象，不使用HTML转义，缩进两个空格
toLower #将参数作为字符串接受，并将其转换为小写
toTitle #将参数作为字符串接受，并将其转换为标题大小写
toTOML #从tree或ls调用中获取结果并将其转换为TOML对象
toUpper #将参数作为字符串接受，并将其转换为大写
toYAML #从tree或ls调用中获取结果，并将其转换为打印精美的YAML对象，缩进两个空格
sockaddr #接受引号转义的模板字符串作为参数，并将其传递给hashicorp/go-sockaddr模板引擎
writeToFile #将内容写入具有权限、用户名（或UID）、组名（或GID）和可选标志的文件，以选择追加模式或添加换行符

Sprig Functions

Consul-template提供了在模板中访问Sprig库的功能。要在模板中使用sprrig函数，请在函数名前加上sprig_。Sprig函数的完整列表可以在Sprig函数文档中找到

Math Functions(数学函数)

以下函数可用于浮点数和整数值

add #返回两个值的和
subtract #返回第二个值与第一个值的差值
multiply #返回两个值的乘积
divide #返回第二个值与第一个值的除法
modulo #返回第二个值与第一个值的模
minimum #返回两个值的最小值
maximum #返回两个值的最大值

内容太多了,直接参照官网吧：https://github.com/hashicorp/consul-template/blob/main/docs/templating-language.md

博文来自：www.51niux.com

2.6 Multi-phase Execution（多阶段执行）

Consul Template对模板进行n次遍历评估，在每次遍历中累积依赖项。由于嵌套依赖，这是必需的，例如：

{{ range services }}
{{ range service .Name }}
  {{ .Address }}
{{ end }}{{ end }}

在第一次传递期间，Consul Template不知道Consul中的任何服务，因此它必须执行查询。当这些结果返回时，将使用该结果对内循环进行求值，从而可能创建更多查询和监视。下面这种方式仍然会将依赖项添加到监视列表中，但不会计算内部if，从而避免了索引外错误。

{{ with service "foo" }}
{{ with index . 0 }}
{{ .Node }}{{ end }}{{ end }}

三、nginx结合consul-template实现配置文件动态更新

3.1 使用示例例子了解一下

# cat test.ctmpl

{{range services}} {{$name := .Name}} {{$service := service .Name}}
upstream {{$name}} {
  zone upstream-{{$name}} 64k;
  {{range $service}}server {{.Address}}:{{.Port}} max_fails=3 fail_timeout=60 weight=1;
  {{else}}server 127.0.0.1:65535; # force a 502{{end}}
} {{end}}

# consul-template -template "/tmp/test.ctmpl:/tmp/out.conf" -exec "echo 'I GET'" #可见执行成功了

I GET

# cat out.conf #我们看下产生的内容,就能理解上面模版中的意思了

upstream consul {
  zone upstream-consul 64k;
  server 192.168.1.164:8300 max_fails=3 fail_timeout=60 weight=1;
  server 192.168.1.165:8300 max_fails=3 fail_timeout=60 weight=1;
  server 192.168.1.166:8300 max_fails=3 fail_timeout=60 weight=1;
  
}   
upstream redis01 {
  zone upstream-redis01 64k;
  server 192.168.1.165:6379 max_fails=3 fail_timeout=60 weight=1;
  
}   
upstream redis02 {
  zone upstream-redis02 64k;
  server 192.168.1.164:6379 max_fails=3 fail_timeout=60 weight=1;
  
}

#如果你想取消息中其他的内容可以通过获取service的信息或者通过下面的方式看一下,比如:
# cat /tmp/test.ctmpl #注意spew_sdump是记录消息到指定的文件,spew_dump则是将消息打印到屏幕而不会写入到指定的文件

{{range services}} {{$name := .Name}} {{$service := service .Name}}
  {{range $service}}
      {{- spew_sdump $service -}}
  {{end}} 
  {{range $service}}
      {{- spew_dump $name .Address .Port -}}
  {{end}}
{{end}}

#然后再稍微复杂一点,你想让nginx的location直接就是service得name,就可以像下面那样：

# cat /tmp/test2.ctmpl

upstream {{$name}} {
  zone upstream-{{$name}} 64k;
  {{range $service}}server {{.Address}}:{{.Port}} max_fails=3 fail_timeout=60 weight=1;
  {{else}}server 127.0.0.1:65535; # force a 502{{end}}
} {{end}}

server {
  listen 80 default_server;

  location / {
    root /usr/local/nginx/html/;
    index index.html;
  }

{{range services}} {{$name := .Name}}
  location /{{$name}} {
    proxy_pass http://{{$name}};
  }
{{end}}
}

# cat /tmp/test2.ctmpl #如果你只想针对某个service进行监听,那就是把name定义成固定值了,如下面的示例

{{$name := "redis01" }} {{$service := service $name}}
upstream {{$name}} {
  zone upstream-{{$name}} 64k;
  {{range $service}}server {{.Address}}:{{.Port}} max_fails=3 fail_timeout=60 weight=1;
  {{else}}server 127.0.0.1:65535; # force a 502{{end}}
}

3.2 k/v获取演示一下

先来一个最简单了获取指定key的value：

# cat /tmp/kv_test1.tpl #获取key是redis/config/users/admin1的值

{{ key "redis/config/users/admin1" }}

# consul-template -template "/tmp/kv_test1.tpl:/tmp/kv_out.txt" -once

# cat /tmp/kv_out.txt #看下输出结果

zaphod

再来一个稍微复杂的,遍历一个目录下面有哪些key：

# cat /tmp/kv_test1.tpl #注意只会遍历key,哪些目录不会显示

{{range tree "offline/"}}{{.}}
{{end}}

# consul-template -template "/tmp/kv_test1.tpl:/tmp/kv_out.txt" -once

# cat /tmp/kv_out.txt

{offline/upstream/grafana/192.168.1.164 upstream/grafana/192.168.1.164 3000 798755 798755 0 0 }
{offline/upstream/grafana/192.168.1.165 upstream/grafana/192.168.1.165 80 798759 798759 0 0 }
{offline/upstream/grafana1/192.168.1.197 upstream/grafana1/192.168.1.197 30001 811350 811350 0 0 }
{offline/upstream/grafana1/192.168.1.198 upstream/grafana1/192.168.1.198 30002 811354 811354 0 0 }
{offline/upstream_name/grafana upstream_name/grafana  811424 811424 0 0 }
{offline/upstream_name/grafana1 upstream_name/grafana1  811427 811427 0 0 }

# cat /tmp/kv_test1.tpl #假设我们已经到最深的目录了,只需要把里面的key和value渲染出来就可以了

{{range ls "offline/upstream/grafana"}}{{.Key}}:{{.Value}}
{{end}}

# consul-template -template "/tmp/kv_test1.tpl:/tmp/kv_out.txt" -once

# cat /tmp/kv_out.txt

192.168.1.164:3000
192.168.1.165:80

现在我们封装一下：

这就是一个比较贴合实际的场景了,比如你有多个集群,当然每个集群都有多个IP,你希望nginx的后端upstream以集群命名,然后集群名自动和后端关联,这样是不是就实现了动态变更的效果了,那么怎么实现一个nginx-template进程监听众多的集群key的变化呢,就是下面的例子了:

#cat /tmp/grafana_upstream.tpl #注意这里使用了printf将变量拼接,不然不太好实现字符串和变量的拼接

{{range tree "offline/upstream_name"}}{{ $server_name := .Key}} {{ $dir := "offline/upstream" }} {{$key := printf "%s/%s" $dir $server_name }}
upstream {{$server_name}}_pool {
  {{range ls $key}}
   server {{.Key}}:{{.Value}} max_fails=3 fail_timeout=60 weight=1;{{else}}server 127.0.0.1:65535 down;
  {{end}}
}{{end}}

# consul-template -template "grafana_upstream.tpl:/tmp/grafana_upstream.conf" -once

# cat /tmp/grafana_upstream.conf #看下产生的效果

upstream grafana_pool {
  
  server 192.168.1.164:3000 max_fails=3 fail_timeout=60 weight=1;
  server 192.168.1.165:80 max_fails=3 fail_timeout=60 weight=1;
}  
upstream grafana1_pool {
  
  server 192.168.1.197:30001 max_fails=3 fail_timeout=60 weight=1;
  server 192.168.1.198:30002 max_fails=3 fail_timeout=60 weight=1;
}

#这时候你可以把-noce参数去掉,然后去修改grafana和grafana1下面的value,然后你再看看/tmp/grafana_upstream.conf里面的内容也跟着变化了。

博文来自：www.51niux.com

3.3 做个关于nginx的试验

#上面可以看到文件是可以随时变化的,我们知道nginx是每次启动的时候将配置文件的信息加载到了内存里面,所以单纯的配置文件发生变更,其实nginx是不生效的,我们来验证一下。

首先创建两个grafan域名的配置文件.比如grafana.test.com引用grafana_pool做后端,同理grafana1.test.com使用grafana1_pool做后端。

然后启动一下template进程监控一下指定的k/v变化：

# consul-template --consul-addr 192.168.1.164:8500 --template "/tmp/kv_test1.tpl:/opt/soft/nginx/conf.d/upstream.conf" --log-level=info #加上log-level=info有变化就会输出到屏幕,如下图:

#你刷新web页面会发现虽然配置文件变化了,但是nginx域名指向的后端是没变化的,所以启动命令还需要变化一下：

# consul-template --consul-addr 192.168.1.164:8500 --template "/tmp/kv_test1.tpl:/opt/soft/nginx/conf.d/upstream.conf:/opt/soft/nginx/sbin/nginx -s reload" --log-level=info #就是让文件发生变化直接nginx重新加载配置文件,注意啊,这里又有一个新的问题,如果你upstream.conf文件修改的有问题,也就是nginx -t会报错,这时候你直接reload的话nginx报错就会直接退出整个template进程了。你说那么我修改成reload || true这种形式不就好了,不管命令怎么报错我template进程都不会退出,但是虽然进程不退出了,但是你nginx没办法reload就导致了你的修改一直不生效。所以还不如有问题template直接退出,然后对template进程做监控,一旦template进程退出了就报警出来然后迅速排查问题。

如果你想多个upstream后端配置文件启动得话：

# cat /tmp/grafana.tpl

{{ $server_name := "grafana"}} {{ $key := "offline/upstream/grafana" }}
upstream {{$server_name}}_pool {
  {{range ls $key}}
  server {{.Key}}:{{.Value}} max_fails=3 fail_timeout=60 weight=1;{{else}}server 127.0.0.1:65535 down;
  {{end}}
}

# cat /tmp/grafana1.tpl

{{ $server_name := "grafana1"}} {{ $key := "offline/upstream/grafana1" }}
upstream {{$server_name}}_pool {
  {{range ls $key}}
  server {{.Key}}:{{.Value}} max_fails=3 fail_timeout=60 weight=1;{{else}}server 127.0.0.1:65535 down;
  {{end}}
}

# consul-template --consul-addr 192.168.1.164:8500 --template "/tmp/grafana.tpl:/opt/soft/nginx/conf.d/grafana_upstream.conf:/opt/soft/nginx/sbin/nginx -s reload" --template "/tmp/grafana1.tpl:/opt/soft/nginx/conf.d/grafana1_upstream.conf:/opt/soft/nginx/sbin/nginx -s reload" --log-level=info

#上图为修改了value值之后的一个进程输出

3.4 使用配置文件启动template进程

#紧接上文,上面我们如果想生成多个文件都用的cli命令行传参的方式,我们换种方式把要监听并创建的配置文件都生成在配置文件中,这样我们的进程命令就不会太长

# cat grafana_upstream.hcl #为了方便查看输出,我命令就是直接输出,可以看到配置文件中可以指定多个template的,syslog表示日志打到message日志没必要加

wait {
  min = "3s"
  max = "9s"
}

syslog {
  enabled = true
  facility = "LOCAL5"
}

log_level = "info"

consul {
  address = "192.168.1.164:8500"
}

template {
  source = "/tmp/grafana.tpl"
  destination = "/tmp/grafana_upstream.conf"
  command = "echo aaa"
}
template {
  source = "/tmp/grafana1.tpl"
  destination = "/tmp/grafana_upstream1.conf"
  command = "echo bbb"
}

# consul-template -config=/tmp/grafana_upstream.hcl #可以尝试修改下这两个监听的key查看一下,下面是测试输出