：Lua指令碼規範與常見報錯

注意事項

Data Management控制台目前暫不支援使用Lua指令碼等相關命令，請通過用戶端或Redis-cli串連Tair執行個體使用Lua指令碼。

基本文法

更多關於Redis命令的介紹，請參見Redis Commands。

最佳化記憶體、網路開銷

現象：

EVAL "return redis.call('set', 'k1', 'v1')" 0
EVAL "return redis.call('set', 'k2', 'v2')" 0

清理Lua指令碼的記憶體佔用

現象：

-OOM command not allowed when used memory > 'maxmemory'.

解決方案：

同時，請避免編寫過大的Lua指令碼，防止佔用過多的記憶體；避免在Lua指令碼中大批量寫入資料，否則會導致記憶體使用量急劇升高，甚至造成執行個體OOM。在業務允許的情況下，建議開啟資料逐出（Tair預設開啟，模式為volatile-lru）節省記憶體空間。但無論是否開啟資料逐出，Tair均不會逐出Lua指令碼緩衝。

處理NOSCRIPT錯誤

現象：

(error) NOSCRIPT No matching script. Please use EVAL.

解決方案：

請通過EVAL命令或SCRIPT LOAD命令將目標指令碼緩衝至Tair中後進行重試。但由於Tair不保證Lua指令碼的持久化、複製能力，Tair在部分情境下仍會清除Lua指令碼緩衝（例如執行個體遷移、變更配置等），這要求您的用戶端需具備處理該錯誤的能力，詳情請參見。

import redis
import hashlib

# strin是一個Lua指令碼的字串，函數以字串的格式返回strin的sha1值。
def calcSha1(strin):
    sha1_obj = hashlib.sha1()
    sha1_obj.update(strin.encode('utf-8'))
    sha1_val = sha1_obj.hexdigest()
    return sha1_val

class MyRedis(redis.Redis):

    def __init__(self, host="localhost", port=6379, password=None, decode_responses=False):
        redis.Redis.__init__(self, host=host, port=port, password=password, decode_responses=decode_responses)

    def prepend_inLua(self, key, value):
        script_content = """\
        local suffix = redis.call("get", KEYS[1])
        local prefix = ARGV[1]
        local new_value = prefix..suffix
        return redis.call("set", KEYS[1], new_value)
        """
        script_sha1 = calcSha1(script_content)
        if self.script_exists(script_sha1)[0] == True:      # 檢查Tair是否已緩衝該指令碼。
            return self.evalsha(script_sha1, 1, key, value) # 如果已緩衝，則用EVALSHA執行指令碼
        else:
            return self.eval(script_content, 1, key, value) # 否則用EVAL執行指令碼，注意EVAL有將指令碼緩衝到Tair的作用。這裡也可以考慮採用SCRIPT LOAD與EVALSHA的方式。

r = MyRedis(host="r-******.redis.rds.aliyuncs.com", password="***:***", port=6379, decode_responses=True)

print(r.prepend_inLua("k", "v"))
print(r.get("k"))
            

處理Lua指令碼逾時

• 現象：

  由於Lua指令碼在Tair中是原子執行的，Lua慢請求可能會導致Tair阻塞。單個Lua指令碼阻塞Tair最多5秒，5秒後Tair會給所有其他命令返回如下BUSY error報錯，直到指令碼執行結束。

  BUSY Redis is busy running a script. You can only call SCRIPT KILL or SHUTDOWN NOSAVE.

  解決方案：

  您可以通過SCRIPT KILL命令終止Lua指令碼或等待Lua指令碼執行結束。

  說明

  • SCRIPT KILL命令在執行慢Lua指令碼的前5秒不會生效（Tair阻塞中）。

  • 建議您編寫Lua指令碼時預估指令碼的執行時間，同時檢查死迴圈等問題，避免過長時間阻塞Tair導致服務不可用，必要時請拆分Lua指令碼。

• 現象：

  若當前Lua指令碼已執行寫命令，則SCRIPT KILL命令將無法生效，報錯樣本如下。

  (error) UNKILLABLE Sorry the script already executed write commands against the dataset. You can either wait the script termination or kill the server in a hard way using the SHUTDOWN NOSAVE command.

  解決方案：

  請在控制台的執行個體列表中單擊對應執行個體重啟。

指令碼緩衝、持久化與複製

現象：

在不重啟、不調用SCRIPT FLUSH命令的情況下，Tair會一直緩衝執行過的Lua指令碼。但在部分情況下（例如執行個體遷移、變更配置、版本升級、切換等等），Tair無法保證Lua指令碼的持久化，也無法保證Lua指令碼能夠被同步至其他節點。

解決方案：

由於Tair不保證Lua指令碼的持久化、複製能力，請您在本機存放區所有Lua指令碼，在必要時通過EVAL或SCRIPT LOAD命令將Lua指令碼重新緩衝至Tair中，避免執行個體重啟、HA切換等操作時Tair中Lua指令碼被清空而帶來的NOSCRIPT錯誤。

叢集中Lua指令碼的限制

Redis Cluster對使用Lua指令碼增加了一些限制，在此基礎上，Tair叢集版對使用Lua指令碼存在如下額外限制：

• 小版本限制，若無法執行EVAL的相關命令，並報錯ERR command eval not support for normal user時，請升級小版本後重試，具體操作請參見升級小版本。

• 所有Key必須在一個slot上，否則報錯-ERR eval/evalsha command keys must be in same slot\r\n。

  您可以通過CLUSTER KEYSLOT命令擷取目標Key的雜湊槽（Hash Slot）進行確認。

• 對單個節點執行SCRIPT LOAD命令時，不保證將該Lua指令碼存入至其他節點中。

• 不支援發布訂閱命令，包括PSUBSCRIBE、PUBSUB、PUBLISH、PUNSUBSCRIBE、SUBSCRIBE和UNSUBSCRIBE。

• 不支援UNPACK函數。

代理模式（Proxy）對Lua的額外檢測項

您也可以通過script_check_enable參數關閉以下檢查項（不推薦）。

• 所有key都應該由KEYS數組來傳遞，redis.call/pcall中調用的Tair命令，key的位置必須是KEYS array，且不能使用Lua變數替換KEYS，否則返回錯誤資訊：-ERR bad lua script for redis cluster, all the keys that the script uses should be passed using the KEYS array\r\n。

  說明

  僅Tair記憶體型（相容Redis 5.0），且小版本低於5.0.9的執行個體存在該限制。

  正確與錯誤命令樣本如下：

  # 本樣本的準備工作需執行如下命令。
  SET foo foo_value
  SET {foo}bar bar_value
  
  # 正確樣本：
  EVAL "return redis.call('mget', KEYS[1], KEYS[2])" 2 foo {foo}bar
  
  # 錯誤樣本：
  EVAL "return redis.call('mget', KEYS[1], '{foo}bar')" 1 foo                      # '{foo}bar'作為Key，應該使用KEYS數組進行傳遞。
  EVAL "local i = 2 return redis.call('mget', KEYS[1], KEYS[i])" 2 foo {foo}bar    # 在代理模式（Proxy）不允許執行此指令碼，因為KEYS資料的索引是變數，但在直連模式中無此限制。
  EVAL "return redis.call('mget', KEYS[1], ARGV[1])" 1 foo {foo}bar                # 不應該使用ARGV[1]資料元素作為Key。

• redis.call/pcall中調用的Tair命令必須是字串常量，否則返回錯誤資訊：-ERR bad lua script for redis cluster, first parameter of redis.call/redis.pcall must be a single literal string。

  正確與錯誤命令樣本如下：

  # 正確樣本
  eval "redis.call('GET', KEYS[1])" 1 foo
  
  # 錯誤樣本
  eval "local cmd = 'GET'; redis.call(cmd, KEYS[1])" 1 foo

• 調用必須要帶有Key，否則返回錯誤資訊：-ERR for redis cluster, eval/evalsha number of keys can't be negative or zero\r\n。

  說明

  僅Tair記憶體型（相容Redis 5.0），且小版本低於5.0.9的執行個體存在該限制。

  正確與錯誤命令樣本如下：

  # 正確樣本
  EVAL "return redis.call('get', KEYS[1])" 1 fooeval
  
  # 錯誤樣本
  EVAL "return redis.call('get', 'foo')" 0

• 不支援Redis嵌套方式調用，否則直接返回錯誤資訊：-ERR bad lua script for redis cluster, nested redis.call/redis.pcall。

  您可以使用局部變數的方式進行調用，正確與錯誤命令樣本如下：

  # 正確樣本
  EVAL "local value = redis.call('GET', KEYS[1]); redis.call('SET', KEYS[2], value)" 2 foo bar
  
  # 錯誤樣本
  EVAL "redis.call('SET', KEYS[1], redis.call('GET', KEYS[2]))" 2 foo bar

• 不支援在MULTI、EXEC事務中使用EVAL、EVALSHA、SCRIPT系列命令。

• 不支援在Lua中執行跨Tair節點的命令，例如KEYS、SCAN等。

  為了保證Lua執行的原子性，Proxy會根據KEYS參數將Lua發送到一個Tair節點執行並擷取結果，從而導致該結果與全域結果不一致。