Euonia.Concurrency.FileSystem
2026.5.0
dotnet add package Euonia.Concurrency.FileSystem --version 2026.5.0
NuGet\Install-Package Euonia.Concurrency.FileSystem -Version 2026.5.0
<PackageReference Include="Euonia.Concurrency.FileSystem" Version="2026.5.0" />
<PackageVersion Include="Euonia.Concurrency.FileSystem" Version="2026.5.0" />
<PackageReference Include="Euonia.Concurrency.FileSystem" />
paket add Euonia.Concurrency.FileSystem --version 2026.5.0
#r "nuget: Euonia.Concurrency.FileSystem, 2026.5.0"
#:package Euonia.Concurrency.FileSystem@2026.5.0
#addin nuget:?package=Euonia.Concurrency.FileSystem&version=2026.5.0
#tool nuget:?package=Euonia.Concurrency.FileSystem&version=2026.5.0
Euonia.Concurrency.FileSystem
Euonia 分布式同步的文件系统提供程序:以目录中的锁文件实现跨进程互斥,适用于单机多进程或已挂载共享卷的场景,无需额外基础设施。
- 目标框架:
net10.0、net11.0 - 根命名空间:
Nerosoft.Euonia.Concurrency.FileSystem - NuGet 包:
Euonia.Concurrency.FileSystem - 依赖:
Euonia.Concurrency、Euonia.Modularity - 配置节:
FileSynchronization
安装
dotnet add package Euonia.Concurrency.FileSystem
快速开始
配置锁目录(FileSystemLockModule 会自动绑定该配置节):
{
"FileSynchronization": {
"Directory": "/var/lib/myapp/locks"
}
}
环境变量(两种写法等价,仓库 alias 见 Euonia.Modularity):
export FileSynchronization__Directory=/var/lib/myapp/locks # .NET 原生:双下划线表示层级
export FILESYNCHRONIZATION_DIRECTORY=/var/lib/myapp/locks # 仓库 alias:大写单下划线
也可在代码中覆盖(显式 Configure 优先于配置节):
using Nerosoft.Euonia.Concurrency.FileSystem;
services.Configure<FileSynchronizationOptions>(options =>
{
options.Directory = "/var/lib/myapp/locks";
});
声明模块依赖:
using Nerosoft.Euonia.Concurrency.FileSystem;
using Nerosoft.Euonia.Modularity;
[DependsOn(typeof(FileSystemLockModule))]
public sealed class WorkerModule : ModuleContextBase
{
}
使用锁:
public sealed class SchedulerService(ILockFactory lockFactory)
{
public async Task RunAsync(CancellationToken cancellationToken)
{
var locker = lockFactory.Create("nightly-job");
await using var handle = await locker.TryAcquireAsync(TimeSpan.Zero, cancellationToken);
if (handle is null)
{
return; // 其他进程正在执行
}
// 独占执行
}
}
主要功能
- 文件锁:
FileSystemLockModule注册ILockFactory,由FileSynchronizationFactory创建FileLockProvider。 - 自动建目录:获取锁时若目录不存在会自动创建;创建目录失败时抛出带目录信息的
InvalidOperationException。 - 跨进程互斥:以
FileShare.None独占打开锁文件;进程退出时操作系统关闭句柄并删除文件。 - 可移植文件名:锁名称被转换为“安全前缀 + Base32 哈希 +
.lock”,避免特殊字符与大小写差异。 - 轻量无依赖:不需要 Redis、ZooKeeper 或数据库。
核心类型
| 类型 | 作用 |
|---|---|
FileSystemLockModule |
注册 ILockFactory 的模块 |
FileSynchronizationFactory |
基于 DirectoryInfo 创建锁提供程序 |
FileLockProvider / FileSynchronizationHandle |
文件锁实现与句柄 |
FileSynchronizationOptions |
同步目录配置(Directory) |
配置项
| 配置键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
FileSynchronization:Directory |
string |
无(必填) | 锁文件目录;不存在时在获取锁时创建 |
{
"FileSynchronization": {
"Directory": "/var/lib/myapp/locks"
}
}
FileSynchronization__Directory=/var/lib/myapp/locks # .NET 原生
FILESYNCHRONIZATION_DIRECTORY=/var/lib/myapp/locks # 仓库 alias
注意事项 / 限制
- 未配置目录会失败:
Directory为空时,创建ILockFactory会抛InvalidOperationException,错误信息中给出配置键与环境变量名。 - 仅提供锁:本包不实现
ISemaphoreFactory;需要信号量请使用 Redis 或 ZooKeeper 提供程序。 - 跨主机依赖文件系统语义:
FileShare.None在本地文件系统可靠,但在 NFS/SMB 等网络卷上是否具备原子互斥取决于服务端实现,跨主机强互斥应先验证。 - 忙等待参数不可配置:竞争时固定以 50ms–1s 的随机间隔重试;锁文件被长期占用时等待方会持续轮询。
- 锁文件是临时的:释放(或进程退出)时文件被删除;不要依赖锁文件中的内容,它只是互斥标记。
相关包
Euonia.Concurrency—— 同步抽象Euonia.Modularity—— 模块、配置绑定与环境变量 aliasEuonia.Application——[DistributedLock]/[SemaphoreLock]拦截器
常见问题与故障排查
InvalidOperationException: FileSynchronizationOptions.Directory is not configured
原因:模块没有绑定到目录:配置节/环境变量/显式 Configure 都为空,或模块没有随应用加载。
解决:设置 FileSynchronization:Directory 或 FileSynchronization__Directory,或在 services.Configure<FileSynchronizationOptions> 中赋值;确保声明了 [DependsOn(typeof(FileSystemLockModule))]。
获取锁时抛 UnauthorizedAccessException
原因:进程账号对目录或锁文件没有写权限;目录可能由其他用户创建。
解决:用运行账号检查 Directory 的读写权限;在容器中挂载可写卷;确认不是只读文件系统。
InvalidOperationException: ... because it is already the name of a directory
原因:清理后的锁文件路径恰好是一个已存在目录(通常是手工创建的目录占用了名称)。 解决:换一个专用且空的锁目录,或移除与锁文件同名的目录;不要手工在锁目录中创建同名文件/目录。
跨主机部署时锁偶尔失效
原因:FileShare.None 在 NFS/SMB 等网络文件系统上的原子性取决于服务端实现与挂载参数,不能等同于本地磁盘。
解决:跨主机强互斥改用 Redis/ZooKeeper/Azure;若必须共享卷,先在目标环境做并发抢占验证并固定挂载选项。
注入 ISemaphoreFactory 失败
原因:本包只实现 ILockFactory,没有信号量实现。
解决:需要并发限流时改用 Euonia.Concurrency.Redis 或 Euonia.Concurrency.ZooKeeper 的信号量模块。
最佳实践
- 专用目录:每个应用/环境使用独立的绝对路径目录,避免不同服务互相清理锁文件。
- 确保可写且持久:目录对运行账号可写;容器部署使用持久卷而不是临时层。
- 锁名带前缀:使用
{app}:{resource}:{id}形式,名称会哈希成可移植文件名,避免特殊字符与大小写差异。 - 短临界区:竞争时以 50ms–1s 随机退避轮询,长任务会持续占用等待者;把耗时工作移到锁外。
- 监控失败率:持续出现权限异常或等待超时通常意味着目录权限/网络卷语义问题,应告警而不是无限重试。
版本与兼容
- 目标框架:
net10.0、net11.0;仓库统一包版本2026.5.0(project.props)。 - 关键依赖:
Euonia.Concurrency、Euonia.Modularity;不需要额外基础设施。 - 已知边界:仅锁、无信号量;忙等待固定 50ms–1s;
UnauthorizedAccessException最多重试 400 次;文件名使用“安全前缀 + Base32 哈希 +.lock”,极长路径可能抛PathTooLongException。 - 升级注意:锁文件在释放时删除,不承载数据,无需迁移;升级后保持
Directory与锁名不变即可继续互斥。
许可证
本项目依据仓库根目录的 GNU General Public License v3.0 发布。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- Euonia.Concurrency (>= 2026.5.0)
- Euonia.Modularity (>= 2026.5.0)
-
net11.0
- Euonia.Concurrency (>= 2026.5.0)
- Euonia.Modularity (>= 2026.5.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2026.5.0 | 92 | 11/13/2026 |
| 2026.4.7 | 101 | 11/3/2026 |
| 2026.4.6 | 108 | 10/28/2026 |
| 2026.4.5 | 103 | 10/19/2026 |
| 2026.4.4 | 95 | 10/19/2026 |
| 2026.4.3 | 118 | 10/1/2026 |
| 2026.4.1 | 112 | 9/24/2026 |
| 2026.4.0 | 107 | 9/22/2026 |
| 2026.3.16 | 136 | 9/8/2026 |
| 2026.3.15 | 126 | 9/2/2026 |
| 2026.3.14 | 136 | 8/30/2026 |
| 2026.3.13 | 127 | 8/29/2026 |
| 2026.3.12 | 129 | 8/28/2026 |
| 2026.3.11 | 129 | 8/27/2026 |
| 2026.3.10 | 124 | 8/26/2026 |
| 2026.3.9 | 130 | 8/25/2026 |
| 2026.3.8 | 131 | 8/24/2026 |
| 2026.3.7 | 125 | 8/20/2026 |
| 2026.3.6 | 127 | 8/20/2026 |
| 2026.3.5 | 123 | 8/19/2026 |