Lua沙箱(Lua Sandbox)核心功能与配置详解

什么是Lua沙箱

Lua沙箱是一个安全执行环境，它允许在受控条件下运行Lua代码。沙箱通过限制资源使用、控制模块访问和提供隔离环境来确保系统安全性和稳定性。这种技术常用于需要执行不可信代码的场景，如插件系统、数据分析管道等。

核心配置参数

资源限制配置

• input_limit - 允许处理的最大输入字符串大小（单位：字节，默认65536，0表示无限制*）
• output_limit - 插件可以注入到主机的最大输出字符串大小（单位：字节，默认65536，0表示无限制）
• memory_limit - 插件在被终止前可使用的最大内存量（单位：字节，默认8388608，0表示无限制）
• instruction_limit - 插件在单个API函数调用中可以执行的Lua指令最大数量（默认1000000，0表示无限制）

注：0值实际对应SIZE_MAX，不一定等于UINT_MAX上限

模块与路径配置

• path - 用于require搜索Lua加载器的路径（遵循Lua 5.1的package.loaders语法）
• cpath - 用于require搜索C加载器的路径
• disabled_modules - 指定哪些模块完全不可访问的哈希表

disabled_modules = {io = 1}  -- 禁用io模块

• remove_entries - 指定模块中哪些函数应该被移除

remove_entries = {
    os = {"getenv", "execute"},  -- 移除os模块的getenv和execute函数
    string = {"dump"}           -- 移除string模块的dump函数
}

日志级别

• log_level - 系统日志严重级别，设置为debug(7)时，print函数将连接到指定的记录器（默认error(3)）

自定义配置

任何其他变量（字符串、布尔值、数字、表）都会原样传递，并可通过read_config函数访问。

沙箱提供的核心Lua功能

require函数

默认只加载基础库，其他库必须通过require()加载。

参数

• libraryName (字符串)

返回值

• 表 - 对于非用户提供的库，表也会以库名全局注册

修改说明

• 基础库：修改了require()函数，不向沙箱暴露任何package表
• 数学库：增加了erf(误差函数)和erfc(互补误差函数)
• os库：所有沙箱的本地时区都设置为UTC

read_config函数

提供对沙箱配置变量的访问。

参数

• key (字符串) - 配置键名

返回值

• 值（字符串、数字、布尔值、表）

output函数

接收任意数量的参数并将数据追加到输出缓冲区，大小不能超过output_limit配置参数。

参数

• arg (数字、字符串、布尔值、nil、支持输出的userdata)

返回值

• 无

print函数

接收任意数量参数并向主机的记录器函数发送调试消息。非可打印字符会被替换为空格以保证日志完整性，任何嵌入的NUL都会终止每个参数。

特殊全局变量

_PRESERVATION_VERSION (数字) - 在状态恢复期间检查此变量；如果先前版本与当前版本不匹配，则中止恢复并干净地启动沙箱。当对全局数据模式进行不兼容更改时，应增加此版本号。

推荐使用配置变量preservation_version：

-- 初始版本（允许用户因配置更改而提升版本）
_PRESERVATION_VERSION = read_config("preservation_version") or 0

-- 当插件代码以不兼容方式更改全局数据模式时
_PRESERVATION_VERSION = (read_config("preservation_version") or 0) + 1

如何与沙箱交互（创建API）

单元测试API示例

Lua暴露给C的函数：

• int process (double) - 处理函数，接收测试用例编号，返回整数结果码
• void report (double) - 报告函数，接收测试用例编号，无返回值

C暴露给Lua的函数：

• void write_output (可选参数...) - 捕获输出缓冲区内容供主机应用使用

实际应用建议

1. 安全性：始终设置合理的资源限制，特别是处理不可信代码时
2. 模块控制：仔细选择需要禁用的模块和函数，平衡功能与安全
3. 版本控制：使用_PRESERVATION_VERSION管理状态兼容性
4. 日志记录：合理设置日志级别以平衡调试需求和性能

通过合理配置和使用这些功能，可以构建既安全又功能丰富的Lua执行环境，满足各种应用场景的需求。