SqlSugar升级后连接字符串未加Enc导致SSL异常

Question

SqlSugar升级至5.x版本后，部分用户在使用MySQL或SQL Server连接时出现“SSL connection error”异常。经排查，主要原因为连接字符串未显式配置加密选项（如`Encrypt=false`或`SslMode=none`）。新版本默认启用SSL加密，若服务器不支持或未正确配置证书，且连接字符串未添加`Encrypt=False;`（SQL Server）或`SslMode=None;`（MySQL），便会引发握手失败。解决方法是在连接字符串中根据数据库类型明确关闭SSL或配置对应加密方式，确保与服务端兼容。

Answer 1

SqlSugar 5.x 升级后数据库连接 SSL 异常深度解析

1. 问题现象：SSL Connection Error 的普遍性

在将 SqlSugar 从旧版本（如 4.x）升级至 5.x 后，大量用户反馈在连接 MySQL 或 SQL Server 数据库时出现“SSL connection error”或“Handshake failed”异常。该问题并非偶发，而是具有较强的可复现性，尤其是在本地开发环境或内网测试环境中。

典型错误日志示例如下：

[MySqlException] SSL Connection Error: handshake failure.
[SqlException] A connection was successfully established with the server, but then an error occurred during the login process. (provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)
    

2. 根本原因分析：加密策略的默认变更

SqlSugar 5.x 版本底层依赖的数据库驱动（如 MySqlConnector、Microsoft.Data.SqlClient）在安全性方面进行了强化，默认启用了 SSL/TLS 加密连接。这意味着：

• 对于 MySQL：使用 MySqlConnector 驱动时，默认 SslMode=Preferred，即优先尝试 SSL 连接。
• 对于 SQL Server：使用 Microsoft.Data.SqlClient 时，默认 Encrypt=True，要求加密通信。

若数据库服务器未配置有效的 SSL 证书，或处于自签名/内部 CA 环境，客户端无法验证证书链，导致握手失败。

3. 技术演进背景：为何 5.x 会引入此变化？

随着数据安全合规要求（如 GDPR、等保）的提升，主流 ORM 框架和数据库驱动逐步将“安全优先”作为默认策略。SqlSugar 5.x 跟随这一趋势，提升了默认安全级别。虽然增强了生产环境的安全性，但也对开发和测试环境提出了更高适配要求。

该设计符合现代 DevSecOps 理念，但需开发者显式处理非标准安全配置场景。

4. 解决方案路径：根据数据库类型调整连接字符串

核心原则是：在连接字符串中显式声明加密模式，与服务端能力匹配。以下是常见数据库的配置方式：

数据库类型	驱动	默认行为	推荐连接字符串参数
MySQL	MySqlConnector	SslMode=Preferred	SslMode=None 或 UseSSL=false
SQL Server	Microsoft.Data.SqlClient	Encrypt=True	Encrypt=False 或 TrustServerCertificate=True

5. 实际配置示例

以下是针对不同数据库的连接字符串修改建议：

// MySQL 示例（关闭 SSL）
Server=localhost;Port=3306;Database=testdb;User=root;Password=123456;SslMode=None;

// SQL Server 示例（禁用加密）
Server=localhost;Database=TestDB;User Id=sa;Password=123456;Encrypt=False;

// SQL Server 示例（信任服务器证书，保留加密）
Server=localhost;Database=TestDB;User Id=sa;Password=123456;Encrypt=True;TrustServerCertificate=True;
    

6. 架构层面的影响与最佳实践

在微服务或分布式系统中，若多个服务共用同一数据库访问层组件，升级 SqlSugar 后需统一审查所有连接字符串配置。建议通过配置中心（如 Apollo、Nacos）集中管理数据库连接参数，便于批量调整加密策略。

同时，应建立环境分级策略：

1. 开发/测试环境：可临时关闭 SSL，提升调试效率。
2. 预发布/生产环境：必须启用 SSL，并配置有效证书，确保传输安全。

7. 可视化流程：SSL 连接失败诊断流程图

graph TD
            A[应用启动, 初始化 SqlSugar] --> B{连接数据库}
            B --> C[尝试 SSL/TLS 握手]
            C --> D{服务器支持 SSL?}
            D -- 是 --> E{证书可信?}
            D -- 否 --> F[握手失败 → SSL Connection Error]
            E -- 是 --> G[连接成功]
            E -- 否 --> H[握手失败 → Certificate Not Trusted]
            F --> I[检查连接字符串 SslMode/Encrypt]
            H --> I
            I --> J[显式设置 SslMode=None 或 Encrypt=False]
            J --> K[重试连接]
            K --> L[成功 or 继续排查]

8. 高级配置选项与潜在风险

除简单关闭 SSL 外，还可采用更精细的控制方式：

• MySQL：使用 CertificateFile 指定客户端证书，实现双向认证。
• SQL Server：结合 Active Directory 认证与加密，提升整体安全性。

但需注意，TrustServerCertificate=True 虽可绕过证书验证，存在中间人攻击风险，仅限受控网络使用。

9. 自动化检测脚本建议

为预防此类问题，可在 CI/CD 流程中加入连接字符串合规性检查脚本：

def check_connection_string(conn_str):
    if "mysql" in conn_str and "SslMode" not in conn_str:
        print("警告：MySQL 连接未指定 SslMode，可能引发 SSL 错误")
    if "sqlserver" in conn_str and "Encrypt" not in conn_str:
        print("警告：SQL Server 连接未设置 Encrypt，存在安全或兼容性风险")
    

10. 社区反馈与官方文档更新趋势

GitHub 上多个 SqlSugar 用户已提交相关 issue，社区普遍呼吁在升级文档中明确标注此 breaking change。目前官方已在 v5.0.33+ 版本的 release notes 中补充说明，并建议开发者在迁移时重点审查连接字符串。

未来版本可能提供运行时警告机制，在检测到不安全或不兼容配置时输出提示日志。