apisix升级完整流程

Apache APISIX 2.15.3 完整安装指南

一、环境要求

组件 最低版本 验证命令 说明
etcd 3.5.x etcdctl version 配置中心
OpenResty 1.19.x openresty -v 运行环境
LuaRocks 3.x luarocks --version Lua包管理工具
APISIX 2.15.3 apisix version API网关核心
系统 CentOS 7 cat /etc/redhat-release 推荐操作系统

二、etcd 3.5.6 安装

安装节点：172.25.69.180

安装位置：/data01/zhenghaosheng/project/etcd-v3.5.6-linux-amd64/data

参考安装教程：https://www.cnblogs.com/freeweb/p/17726690.html

三、OpenResty 1.19.x 安装

安装节点：172.25.71.28

安装位置：/home/zhs/openresty/nginx/

参考安装教程：https://www.cnblogs.com/freeweb/p/13446663.html

1. 下载源码

https://openresty.org/cn/download.html

2. 编译安装

	./configure --prefix=/home/zhs/openresty --with-http_stub_status_module --with-http_realip_module --with-http_ssl_module --with-http_v2_module --with-http_gunzip_module --with-stream --with-stream_ssl_module --with-threads --with-pcre-jit --with-file-aio   

gmake && gmake install

3. 配置环境变量

echo 'export PATH=/usr/local/openresty/nginx/sbin:$PATH' >> ~/.bashrc

source ~/.bashrc

4. 验证安装

openresty -v# 应输出：nginx version: openresty/1.19.3.2

四、LuaRocks 3.10.0 安装

1. 下载源码

下载地址：http://luarocks.org/rocks/luarocks-3.9.1.tar.gz

2. 解决依赖问题

sudo yum install lua-devel -y

3. 编译安装

./configure --prefix=/usr/local/luarocks --with-lua-include=/usr/include/

make

make install

4. 配置环境变量

export PATH=/usr/local/luarocks/bin:$PATH   # 添加系统环境变量

source ~/.bashrc

5. 验证安装

luarocks --version# 应输出：/usr/local/luarocks/bin/luarocks 3.10.0

6. 卸载旧版本（如存在）

sudo yum remove luarocks -y

# 查看安装的版本
/usr/local/luarocks/bin/luarocks --version

luarocks --version

7. 永久设置系统环境变量

[root@szdpl592 apisix-2.15.3]# echo $PATH  # 查看原来的系统环境变量配置
/root/.luarocks/bin:/sbin:/bin:/usr/sbin:/usr/bin
[root@szdpl592 apisix-2.15.3]# echo 'export PATH=$PATH:/usr/local/luarocks/bin' >> ~/.bashrc
[root@szdpl592 apisix-2.15.3]# source ~/.bashrc

五、APISIX 2.15.3 安装

1. 下载源码

wget https://downloads.apache.org/apisix/2.15.3/apache-apisix-2.15.3-src.tgz

tar -zxvf apache-apisix-2.15.3-src.tgz

cd apache-apisix-2.15.3

2. 解决依赖

make deps

3. 安装APISIX

make install

4. 修改配置文件

编辑 conf/config.yaml，确保etcd配置正确：

deployment:  
	role: traditional 
    role_traditional:    
    	config_provider: etcd
    etcd: 
    	host:    
   		 - "http://172.25.69.180:2379"

5. 初始化APISIX

apisix init

6. 启动服务

apisix start

7. 验证安装

curl http://127.0.0.1:9080/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'# 应返回路由信息

六、常见问题解决方案

问题1：LuaRocks编译时报头文件缺失

lua.h for Lua 5.1 not found

解决方案：

sudo yum install lua-devel./configure --prefix=/usr/local/luarocks --with-lua-include=/usr/include/

问题2：LuaRocks版本冲突

$ luarocks --version # 显示旧版本

解决方案：

# 删除旧版本sudo yum remove luarocks -y # 更新PATHecho 'export PATH=/usr/local/luarocks/bin:$PATH' >> ~/.bashrcsource ~/.bashrc

问题3：APISIX启动失败

排查步骤：

  1. 检查etcd是否正常运行：

    etcdctl endpoint health

  2. 检查端口冲突：

    netstat -tunlp | grep 9080

  3. 查看日志：

    tail -f /usr/local/apisix/logs/error.log

问题4：插件安装失败

解决方案：

  1. 确保LuaRocks配置正确：

    luarocks config --scope system

  2. 清除缓存后重试：

    luarocks purge --tree=/home/zhs/apisix-2.15.3/depsluarocks make --tree=/home/zhs/apisix-2.15.3/deps

五、APISIX 2.15.3 安装

1. 下载源码

wget https://downloads.apache.org/apisix/2.15.3/apache-apisix-2.15.3-src.tgz

tar -zxvf apache-apisix-2.15.3-src.tgz

cd apache-apisix-2.15.3

2. 解决依赖

make deps

3. 安装APISIX

make install

4. 修改配置文件

编辑 conf/config.yaml，确保etcd配置正确：

deployment:  
	role: traditional 
    role_traditional:    
    	config_provider: etcd
    etcd: 
    	host:    
   		 - "http://172.25.69.180:2379"

5. 初始化APISIX

apisix init

6. 启动服务

apisix start

7. 验证安装

curl http://127.0.0.1:9080/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'# 应返回路由信息

六、常见问题解决方案

问题1：LuaRocks编译时报头文件缺失

lua.h for Lua 5.1 not found

解决方案：

sudo yum install lua-devel./configure --prefix=/usr/local/luarocks --with-lua-include=/usr/include/

问题2：LuaRocks版本冲突

$ luarocks --version # 显示旧版本

解决方案：

# 删除旧版本sudo yum remove luarocks -y # 更新PATHecho 'export PATH=/usr/local/luarocks/bin:$PATH' >> ~/.bashrcsource ~/.bashrc

问题3：APISIX启动失败

排查步骤：

  1. 检查etcd是否正常运行：

    etcdctl endpoint health

  2. 检查端口冲突：

    netstat -tunlp | grep 9080

  3. 查看日志：

    tail -f /usr/local/apisix/logs/error.log

问题4：插件安装失败

解决方案：

  1. 确保LuaRocks配置正确：

    luarocks config --scope system

  2. 清除缓存后重试：

    luarocks purge --tree=/home/zhs/apisix-2.15.3/depsluarocks make --tree=/home/zhs/apisix-2.15.3/deps

local consumer_label_value_def = {
    anyOf = {
        { type = "string" },
        {
            type = "array",
            items = {
                type = "object",
                properties = {
                    api_code = { type = "string", minLength = 1, maxLength = 64 },
                    api_id = { type = "string", minLength = 1, maxLength = 64 }
                },
                required = { "api_code", "api_id" }
            }
        },
        {
            type = "object",
            patternProperties = {
                [".*"] = {
                    type = "object",
                    properties = {
                        api_code = { type = "string", minLength = 1, maxLength = 64 },
                        api_id = { type = "string", minLength = 1, maxLength = 64 }
                    },
                    required = { "api_code", "api_id" }
                }
            }
        }
    }
}
_M.consumer_label_value_def = consumer_label_value_def


_M.consumer = {
    type = "object",
    properties = {
        username = {
            type = "string", minLength = 1, maxLength = rule_name_def.maxLength,
            pattern = [[^[a-zA-Z0-9_]+$]]
        },
        plugins = plugins_schema,
        labels = {
            description = "key/value pairs to specify attributes",
            type = "object",
            patternProperties = {
                [".*"] = consumer_label_value_def
            },
            maxProperties = 16
        },
        create_time = timestamp_def,
        update_time = timestamp_def,
        desc = desc_def,
    },
    required = {"username"},
}

问题2：鉴权插件加载失败

size of C type is unknown or too large at line 39

参考地址：https://blog.csdn.net/songfeihu0810232/article/details/127003632

hmac.lua 源码地址：https://github.com/jkeys089/lua-resty-hmac/blob/master/lib/resty/hmac.lua

全量替换 resty.hmac.lua


local str_util = require "resty.string"
local to_hex = str_util.to_hex
local ffi = require "ffi"
local ffi_new = ffi.new
local ffi_str = ffi.string
local ffi_gc = ffi.gc
local ffi_typeof = ffi.typeof
local C = ffi.C
local setmetatable = setmetatable


local _M = { _VERSION = '0.06' }

local mt = { __index = _M }


ffi.cdef[[
typedef struct engine_st ENGINE;
typedef struct evp_pkey_ctx_st EVP_PKEY_CTX;
typedef struct hmac_ctx_st HMAC_CTX;

//OpenSSL 1.0
void HMAC_CTX_init(HMAC_CTX *ctx);
void HMAC_CTX_cleanup(HMAC_CTX *ctx);

//OpenSSL 1.1
HMAC_CTX *HMAC_CTX_new(void);
void HMAC_CTX_free(HMAC_CTX *ctx);
]]

local buf = ffi_new("unsigned char[64]")
local res_len = ffi_new("unsigned int[1]")

local ctx_new, ctx_free
local openssl11, e = pcall(function ()
    local ctx = C.HMAC_CTX_new()
    C.HMAC_CTX_free(ctx)
end)
if openssl11 then
    ffi.cdef [[
    typedef struct evp_md_ctx_st EVP_MD_CTX;
    typedef struct evp_md_st EVP_MD;
    ]]
    ctx_new = function ()
        return C.HMAC_CTX_new()
    end
    ctx_free = function (ctx)
        C.HMAC_CTX_free(ctx)
    end
else
    ffi.cdef [[
    typedef struct env_md_ctx_st EVP_MD_CTX;
    typedef struct env_md_st EVP_MD;
    struct env_md_ctx_st
    {
        const EVP_MD *digest;
        ENGINE *engine;
        unsigned long flags;
        void *md_data;
        EVP_PKEY_CTX *pctx;
        int (*update)(EVP_MD_CTX *ctx,const void *data,size_t count);
    };
 struct env_md_st
    {
        int type;
        int pkey_type;
        int md_size;
        unsigned long flags;
        int (*init)(EVP_MD_CTX *ctx);
        int (*update)(EVP_MD_CTX *ctx,const void *data,size_t count);
        int (*final)(EVP_MD_CTX *ctx,unsigned char *md);
        int (*copy)(EVP_MD_CTX *to,const EVP_MD_CTX *from);
        int (*cleanup)(EVP_MD_CTX *ctx);

        int (*sign)(int type, const unsigned char *m, unsigned int m_length, unsigned char *sigret, unsigned int *siglen, void *key);
        int (*verify)(int type, const unsigned char *m, unsigned int m_length, const unsigned char *sigbuf, unsigned int siglen, void *key);
        int required_pkey_type[5];
        int block_size;
        int ctx_size;
        int (*md_ctrl)(EVP_MD_CTX *ctx, int cmd, int p1, void *p2);
        };

    struct hmac_ctx_st
    {
        const EVP_MD *md;
        EVP_MD_CTX md_ctx;
        EVP_MD_CTX i_ctx;
        EVP_MD_CTX o_ctx;
        unsigned int key_length;
        unsigned char key[128];
    };
    ]]

    local ctx_ptr_type = ffi_typeof("HMAC_CTX[1]")

    ctx_new = function ()
        local ctx = ffi_new(ctx_ptr_type)
        C.HMAC_CTX_init(ctx)
        return ctx
    end
    ctx_free = function (ctx)
        C.HMAC_CTX_cleanup(ctx)
    end
end
ffi.cdef [[
int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int len, const EVP_MD *md, ENGINE *impl);
int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, size_t len);
int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len);

const EVP_MD *EVP_md5(void);
const EVP_MD *EVP_sha1(void);
const EVP_MD *EVP_sha256(void);
const EVP_MD *EVP_sha384(void);
const EVP_MD *EVP_sha512(void);
]]

local hashes = {
    MD5 = C.EVP_md5(),
    SHA1 = C.EVP_sha1(),
    SHA256 = C.EVP_sha256(),
    SHA384 = C.EVP_sha384(),
    SHA512 = C.EVP_sha512()
}

_M.ALGOS = hashes


function _M.new(self, key, hash_algo)
    local ctx = ctx_new()

    local _hash_algo = hash_algo or hashes.MD5

    if C.HMAC_Init_ex(ctx, key, #key, _hash_algo, nil) == 0 then
        return nil
    end

    ffi_gc(ctx, ctx_free)

    return setmetatable({ _ctx = ctx }, mt)
end


function _M.update(self, s)
    return C.HMAC_Update(self._ctx, s, #s) == 1
end


function _M.final(self, s, hex_output)

    if s ~= nil then
        if C.HMAC_Update(self._ctx, s, #s) == 0 then
            return nil
        end
    end

    if C.HMAC_Final(self._ctx, buf, res_len) == 1 then
        if hex_output == true then
            return to_hex(ffi_str(buf, res_len[0]))
        end
        return ffi_str(buf, res_len[0])
    end

    return nil
end
function _M.reset(self)
    return C.HMAC_Init_ex(self._ctx, nil, 0, nil, nil) == 1
end


return _M

问题3：调用接口时出现异常

lua entry thread aborted: runtime error: /home/zhs/apisix-2.15.3/apisix/plugins/vivo-hmac-auth.lua:185: attempt to call field 'plugin' (a nil value)

解决方案：

根据apisix 2.15.3提供 的自定义插件模板修改源插件中的部分代码

问题4：access 日志中不打印服务code

解决方案:

apisix/init.lua http_access_phase方法中添加

    if route.value.service_protocol == "grpc" then
        return ngx.exec("@grpc_pass")
    end

    --add X-Gateway-Serve field to header for every query and print it in access.log
    local serve = route.value.labels and route.value.labels.serve
    if not serve then
        if core.string.has_prefix(route.value.id, "route_") then
            serve = string.sub(route.value.id, 7)
        end
    end

    if serve then
        core.request.set_header("X-Gateway-Serve", serve)
    end
posted @ 2025-10-19 19:11  小郑[努力版]  阅读(10)  评论(0)    收藏  举报