.NET 程序部署 Linux,时区、编码、权限常见问题汇总

一、时区问题

1.1 问题现象

• DateTime.Now 返回的时间比北京时间晚 8 小时（实际为 UTC 时间）

• 日志时间、定时任务执行时间与预期不符

• Docker 容器内时间与宿主机不一致

• TimeZoneInfo.FindSystemTimeZoneById("China Standard Time") 抛出异常

1.2 根本原因

.NET Core/.NET 5+ 在 Linux 上使用 IANA 时区标准，与 Windows 时区 ID 不兼容。

1.3 解决方案

方案一：系统级设置时区（推荐）

方案二：环境变量 TZ（Docker 常用）

方案三：挂载宿主机时区文件

方案四：代码内跨平台时区转换

1.4 最佳实践

1. 存储用 UTC，显示转本地：数据库统一存 UTC，展示时按用户时区转换

2. 优先使用 DateTimeOffset：自带偏移量信息，跨平台更安全

3. Docker 镜像显式设置 TZ：不要依赖宿主机默认值

4. 定时任务用 UTC 或明确时区：避免夏令时切换导致执行异常

二、编码问题

2.1 问题现象

• 控制台输出中文显示为问号或乱码

• 读取 GBK/GB2312 编码文件内容乱码

• Encoding.GetEncoding("GBK") 抛出 ArgumentException

• 日志文件中文乱码

• 跨平台序列化/反序列化中文异常

2.2 根本原因

.NET Core/.NET 5+ 默认仅内置 UTF-8、UTF-16、ASCII 等少数编码。GBK/GB2312（代码页 936）等 Windows 常用代码页需要通过 System.Text.Encoding.CodePages NuGet 包显式注册才能使用。

Linux 系统默认 locale 多为 en_US.UTF-8，控制台不支持中文输出时也会显示异常。

2.3 解决方案

步骤 1：安装 NuGet 包

步骤 2：程序入口处注册代码页提供程序

注意

：整个 AppDomain 只需注册一次，重复注册无害。ASP.NET Core 推荐放在 Program.cs 最开头或 Startup.ConfigureServices 顶部。

步骤 3：正确读取指定编码文件

步骤 4：控制台输出中文设置

步骤 5：Linux 系统 locale 设置

2.4 常见编码对照表

2.5 最佳实践

1. 新项目统一使用 UTF-8：源码、配置文件、日志全部 UTF-8

2. 读取外部文件显式指定编码：不要依赖系统默认编码

3. 用代码页编号替代名称：Encoding.GetEncoding(936) 比 "GBK" 更可靠

4. 注册代码页放在程序最开头：避免任何编码操作在注册前执行

5. 编码转换正确姿势：先用源编码解码为 string，再用目标编码编码

三、权限问题

3.1 问题现象

• Permission denied 错误，应用无法启动

• 日志文件写入失败

• 无法监听 1024 以下端口

• 读取配置文件无权限

• SELinux 阻止 .NET 运行时访问文件

• Docker 容器内以 root 运行存在安全风险

3.2 常见权限错误与修复

3.2.1 文件/目录权限不足

修复方案：

3.2.2 低端口绑定权限

Linux 中 1024 以下端口需要 root 权限才能绑定。

方案一：使用高位端口（推荐）

方案二：赋予程序端口绑定能力

3.2.3 以专用用户运行应用

生产环境不应以 root 运行 .NET 应用。

3.2.4 SELinux 权限问题

CentOS/RHEL 默认启用 SELinux，可能阻止 .NET 应用的文件访问、网络绑定等。

3.3 systemd 服务部署权限配置

3.4 Docker 容器权限最佳实践

3.5 权限排查命令速查

四、综合工具类源码

4.1 LinuxDeploymentHelper.cs

4.2 使用示例

五、部署检查清单

部署完成后，按以下清单逐项验证：

六、总结

三大问题的核心解决思路：

1. 时区：系统层面设置 Asia/Shanghai，代码层面区分 Windows/Linux 时区 ID，存储优先 UTC

2. 编码：注册 CodePagesEncodingProvider，读写文件显式指定编码，新项目统一 UTF-8

3. 权限：专用用户运行，遵循最小权限原则，注意低端口和 SELinux 限制

掌握以上要点，可以解决 90% 以上的 .NET 跨 Linux 部署基础问题。