Lsyncd Auto-Image-Magic 配置实战:用 Layer 1 Inlet 构建自动图片格式转换目录

原创2026-10-09 10:58:331,986 阅读
文章标签:后端

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 的组织方式。

登录后查看全文
lsyncd