Lsyncd Auto-Image-Magic 配置实战:用 Layer 1 Inlet 构建自动图片格式转换目录
Lsyncd Auto-Image-Magic 配置实战:用 Layer 1 Inlet 构建自动图片格式转换目录
导读
auto-image-magic 是 Lsyncd 官方提供的一个 Layer 1 示例配置,它把某个目录变成一个"魔法目录":任何放入其中的 jpg、gif、png 图片都会自动被转换出其余两种格式,删除其中一种时其他格式会同步被清理,且转换后的文件就落在源目录中、与原始图片并排存放。本篇将以 docs/manual/examples/auto-image-magic/index.md 为主线,结合仓库中完整的 examples/limagemagic.lua 脚本和 lsyncd.lua 的底层实现,逐行拆解 inlet 接口、事件排除、bash 命令拼接等关键技术,帮助你掌握 Lsyncd Layer 1 自定义 action 的完整写法。
一、脚本全貌:一个不依赖目标目录的"魔法目录"
这个例子的特殊之处在于:它没有 target,也不做任何同步——它把 Lsyncd 的文件系统事件监控当作触发器,直接在源目录内完成图片格式转换。这是 Layer 1 脚本的典型形态:action 接收 inlet,自行决定每个事件要做什么。
以下是文档给出的完整脚本(与仓库 examples/limagemagic.lua 中的版本一致,仅示例版本在 sync 声明处使用了 recursive=false,仓库版本使用等价的 subdirs=false):
local formats = { jpg = true, gif = true, png = true }
convert = {
delay = 0,
maxProcesses = 99,
action = function(inlet)
local event = inlet.getEvent()
if event.isdir then
-- ignores events on dirs
inlet.discardEvent(event)
return
end
-- extract extension and basefilename
local p = event.pathname
local ext = string.match(p, ".*%.([^.]+)$")
local base = string.match(p, "(.*)%.[^.]+$")
if not formats[ext] then
-- an unknown extenion
log("Normal", "not doing something on ."..ext)
inlet.discardEvent(event)
return
end
-- autoconvert on create and modify
if event.etype == "Create" or event.etype == "Modify" then
-- builds one bash command
local cmd = ""
-- do for all other extensions
for k, _ in pairs(formats) do
if k ~= ext then
-- excludes files to be created, so no
-- followup actions will occur
inlet.addExclude(base..'.'..k)
if cmd ~= "" then
cmd = cmd .. " && "
end
cmd = cmd..
'/usr/bin/convert "'..
event.source..p..'" "'..
event.source..base..'.'..k..
'" || /bin/true'
end
end
log("Normal", "Converting "..p)
spawnShell(event, cmd)
return
end
-- deletes all formats if you delete one
if event.etype == "Delete" then
-- builds one bash command
local cmd = ""
-- do for all other extensions
for k, _ in pairs(formats) do
if k ~= ext then
-- excludes files to be deleted, so no
-- followup actions will occur
inlet.addExclude(base..'.'..k)
if cmd ~= "" then
cmd = cmd .. " && "
end
cmd = cmd..
'rm "'..event.source..base..'.'..k..
'" || /bin/true'
end
end
log("Normal", "Deleting all "..p)
spawnShell(event, cmd)
return
end
-- ignores other events.
inlet.discardEvent(event)
end,
-----
-- Removes excludes when convertions are finished
--
collect = function(event, exitcode)
local p = event.pathname
local ext = string.match(p, ".*%.([^.]+)$")
local base = string.match(p, "(.*)%.[^.]+$")
local inlet = event.inlet
if event.etype == "Create" or
event.etype == "Modify" or
event.etype == "Delete"
then
for k, _ in pairs(formats) do
inlet.rmExclude(base..'.'..k)
end
end
end,
}
sync{convert, source="magicdir", recursive=false}
二、核心机制逐段解读
2.1 支持格式表:用键而非值
local formats = { jpg = true, gif = true, png = true }
脚本创建了一张以文件扩展名为键的本地表。这样做的好处是可以用一次 formats[ext] 查表操作完成"该扩展名是否被支持"的判断(见 2.4),后续循环遍历格式、跳过源格式时也只需比较键名。要支持更多格式(如 bmp、tiff),只需在这一行追加键。
2.2 即时响应与并发上限
convert = {
delay = 0,
maxProcesses = 99,
delay = 0:事件到达后立即触发 action,不做延迟合并,保证"魔法目录"的转换近乎实时。maxProcesses = 99:允许最多 99 个转换进程同时运行。"unlimits the amount the conversion to be done at once. Well not unlimited but set the limit pretty high"——文档原意是把它设为较高的上限,避免并发转换互相阻塞。注意它是在每个 sync 表内设置的;docs/manual/config/file/index.md 中说明,settings里的maxProcesses是跨所有 sync{} 全局累加的进程上限,而这里放在 sync 配置表内,作用范围限于本 sync。
2.3 为什么用 Layer 1 而不是 Layer 2
action = function(inlet)
local event = inlet.getEvent()
文档明确解释:这个脚本用的是 Layer 1 的 inlet 接口,虽然它每次只抓单个事件(getEvent())而不用事件列表(getEvents()),之所以不写成 Layer 2 的 onCreate/onModify/onDelete 回调,是因为它需要对所有类型的事件做统一的公共处理(先判断目录、再抽扩展名、再查格式表),用单一 action 入口天然合适。
Layer 1 意味着脚本要自己负责一切:每个未被处理的事件都必须显式丢弃(inlet.discardEvent),否则会产生不符合预期的后续动作。关于 inlet 的完整接口清单(getEvent/getEvents/discardEvent/getConfig/addExclude/rmExclude/createBlanketEvent)可参见 docs/manual/config/layer1/index.md。
2.4 目录事件与扩展名提取
if event.isdir then
-- ignores events on dirs
inlet.discardEvent(event)
return
end
目录不是图片,action 明确丢弃目录事件。Layer 1 脚本里所有"不处理"的事件都必须走这一分支,否则事件会滞留在队列中。
local p = event.pathname
local ext = string.match(p, ".*%.([^.]+)$")
local base = string.match(p, "(.*)%.[^.]+$")
这里用 Lua string patterns(不是正则)从相对路径中拆分扩展名和主文件名:
"%.([^.]+)$"匹配最后一个点号及之后的内容,捕获得到扩展名(如photo.jpg的jpg);"(.*)%.[^.]+$"捕获点号之前的全部内容作为 base(如photo)。
在 lsyncd.lua 中,event.pathname 被定义为"相对于监控根目录、目录不带尾部斜杠"的路径;而 event.source(lsyncd.lua)返回解析了所有符号链接后的监控根绝对路径,因此 event.source..p 就拼出了文件的完整绝对路径——这正是后面拼 shell 命令所需的输入。
2.5 查表过滤未知扩展名
if not formats[ext] then
-- an unknown extenion
log("Normal", "not doing something on ."..ext)
inlet.discardEvent(event)
return
end
由于 formats 以扩展名为键,formats[ext] 即可完成"是否为受支持图片格式"的判断。对未知扩展名(例如 readme.txt、隐藏文件、转换过程中产生的临时文件)直接丢弃事件,并在 Normal 级别留下日志,方便排查。
2.6 Create/Modify:拼一条 bash 命令完成全部转换
if event.etype == "Create" or event.etype == "Modify" then
local cmd = ""
for k, _ in pairs(formats) do
if k ~= ext then
inlet.addExclude(base..'.'..k)
if cmd ~= "" then
cmd = cmd .. " && "
end
cmd = cmd..
'/usr/bin/convert "'..
event.source..p..'" "'..
event.source..base..'.'..k..
'" || /bin/true'
end
end
log("Normal", "Converting "..p)
spawnShell(event, cmd)
return
end
这是整个脚本最精巧的部分,包含三个关键技巧:
技巧一:遍历所有格式、排除源格式。 pairs(formats) 遍历 jpg/gif/png 三个键,if k ~= ext 跳过源图片自身的扩展名,其余两个格式各生成一条 /usr/bin/convert 源文件 目标文件 命令。例如放入 a.jpg 会生成转换出 a.gif 与 a.png 两条命令。
技巧二:动态排除转换产物,防止事件循环。 inlet.addExclude(base..'.'..k) 是本例的核心 trick。转换出来的文件(如 a.png)就生成在被监控的源目录里,如果不排除,它们会作为新的 Create 事件再次触发 action,形成无穷的转换连锁。文档原话是:"As this images are not placed in a target directory but right next to the source image in the source directory they would otherwise trigger Create actions as well."(这些图片不放在目标目录,而是紧挨着源图放在源目录里,否则会同样触发 Create 动作)。addExclude 在 lsyncd.lua 中的实现是向 sync 的 excludes 集合追加一个模式。
技巧三:用 && 顺序链式执行、用 || /bin/true 容忍失败。 命令之间以 && 连接,保证逐条顺序执行;每条命令末尾追加 || /bin/true,即使某一次转换失败,shell 也会以成功状态继续执行下一条,避免中途中断。文档原话:"It uses " || /bin/true " to let the shell continue if one conversion fails."
最后通过 spawnShell(event, cmd) 触发执行。spawnShell 在 lsyncd.lua 中被定义为 spawn(agent, 'sh', '-c', command, 'sh', ...)——即以 sh -c 方式运行拼接好的命令串,event 作为 agent 标记相关文件为已处理(blocked)。
2.7 Delete:删除一个,清理全部格式
if event.etype == "Delete" then
local cmd = ""
for k, _ in pairs(formats) do
if k ~= ext then
inlet.addExclude(base..'.'..k)
if cmd ~= "" then
cmd = cmd .. " && "
end
cmd = cmd..
'rm "'..event.source..base..'.'..k..
'" || /bin/true'
end
end
log("Normal", "Deleting all "..p)
spawnShell(event, cmd)
return
end
删除分支结构上与转换分支对称:用户删除 a.jpg 时,脚本排除 a.gif/a.png 并对它们执行 rm。因为删除行为同样发生在源目录内,addExclude 同样必要——否则删除产物文件会触发新的 Delete 事件。每条 rm 同样带 || /bin/true,某个文件不存在(如从未转换过)也不会中断整条命令。
2.8 其余事件一律丢弃
-- ignores other events.
inlet.discardEvent(event)
end,
除此之外的事件类型(如 Move 拆分、Attrib 等)在 action 末尾被统一丢弃。再次强调:Layer 1 中这一步必不可少,它是"本事件不产生任何动作"的显式声明。
2.9 collect:转换结束后的"善后"
collect = function(event, exitcode)
local p = event.pathname
local ext = string.match(p, ".*%.([^.]+)$")
local base = string.match(p, "(.*)%.[^.]+$")
local inlet = event.inlet
if event.etype == "Create" or
event.etype == "Modify" or
event.etype == "Delete"
then
for k, _ in pairs(formats) do
inlet.rmExclude(base..'.'..k)
end
end
end,
当子进程结束、Lsyncd 回收其僵尸进程时,会调用 collect 回调(见 docs/manual/config/layer1/index.md 对 collect 的说明)。collect 在这里对 Create/Modify/Delete 三类事件逐键调用 inlet.rmExclude(base..'.'..k),把 2.6/2.7 中添加的动态排除成对地移除——否则排除模式会永久留在 excludes 集合里,导致以后真正新增/删除同名图片时事件被错误吞掉。rmExclude 在 lsyncd.lua 中对应 self.excludes:remove(pattern)。
注意 collect 拿到的参数是 event(而非 action 中的 inlet),脚本通过 event.inlet 取回 inlet 来调用 rmExclude,这是 Layer 1 编程中容易踩的细节。
2.10 sync 声明
sync{convert, source="magicdir", recursive=false}
把 convert 配置挂到一个名为 magicdir 的源目录上,recursive=false(仓库版本写作 subdirs=false)表示只监控该目录一层、不递归子目录。sync 是全局函数,在 lsyncd.lua 中定义为仅允许在初始化阶段调用(lsyncdStatus == 'init'),返回新建 sync 的 inlet。
三、仓库源码佐证与运行准备
3.1 与仓库脚本的一致性
文档展示的脚本与仓库中的 examples/limagemagic.lua 是同一份配置。仓库版本头部注释给出了明确的运行前提:
- 需要先
mkdir magicdir("Be sure to mkdir 'magicdir' first."); - 转换后的图片与源图放在同一目录;
- 依赖 ImageMagick 的
/usr/bin/convert命令,因此运行前需确认系统已安装 ImageMagick; - 支持格式为
.jpg、.gif、.png。
仓库版本还多出一个小小的 collapse 函数,返回固定值 3(表示不折叠任何事件),文档示例省略了它;如果你的场景有大量连续事件需要保持逐一处理,可以参考仓库版本补上。
3.2 底层 API 对照
| 脚本用到的接口 | 源码位置 | 行为 |
|---|---|---|
inlet.getEvent() |
lsyncd.lua 附近的 inlet 构造 | 取下一个就绪事件;未 spawn 前重复调用返回同一事件 |
inlet.addExclude(pattern) |
lsyncd.lua | 向 sync 的 excludes 集合追加排除模式 |
inlet.rmExclude(pattern) |
lsyncd.lua | 从 excludes 集合移除排除模式 |
spawnShell(agent, cmd) |
lsyncd.lua | 等价于 spawn(agent, 'sh', '-c', cmd, 'sh') |
event.pathname / event.source |
lsyncd.lua | 相对路径(不带前导斜杠、目录无尾斜杠)/ 监控根绝对路径 |
sync{...} |
lsyncd.lua | 仅初始化期可调用,注册 sync 并返回 inlet |
3.3 运行方式
将上述配置保存为 Lsyncd 配置文件后,以标准方式启动(示例未包含守护进程设置,可结合 docs/manual/config/file/index.md 中 settings{} 的 logfile、nodaemon 等参数调整运行方式):
lsyncd -log Exec magicsync.lua
随后向 magicdir 放入任意 jpg/gif/png 图片,观察日志中的 Converting 记录,另两种格式的副本会出现在同一目录;删除其中一种,其余格式会被一并清理。日志输出可借助 log("Normal", ...) 在 Normal 级别观察,例如 not doing something on .txt 用于确认未知格式被正确忽略。
四、从本例可以带走的通用模式
- Layer 1 的事件消费契约:拿到事件后要么 spawn 动作,要么
discardEvent,二者必居其一,否则事件悬置。 - 排除与反排除必须成对:
addExclude在action中添加,rmExclude在collect中移除,保证动态排除的生命周期与对应动作一致。 - shell 命令串的容错设计:用
&&串联有序步骤、用|| /bin/true兜底单步失败,是 Lsyncd 自定义 action 中处理"多步命令"的通用写法。 - 自产事件的防回环思路:凡是"处理结果落在被监控目录内"的动作,都必须先排除产物路径,这是把文件系统监控当作触发器时的通用陷阱。
需要更复杂的 Layer 1 事件列表处理时,可参考 docs/manual/config/layer1/index.md 中 getEvents() 与事件列表 API,并结合仓库其他示例(examples/lbash.lua、examples/lpostcmd.lua)对比不同 action 的组织方式。