Linux C# Web API HTTPS 配置指南：解决证书错误

解决 Linux 上 C# Web API “无法配置 HTTPS 端点” 问题

当你在 Linux 服务器上运行用 C# .NET 开发的 Web API 时，有时会遇到一个常见错误：“无法配置 HTTPS 端点。没有指定服务器证书。” 此错误通常表明 Kestrel（默认的 .NET Web 服务器）无法找到必要的 SSL/TLS 证书以启用 HTTPS。由于没有证书，你的应用程序无法安全地处理 HTTPS 请求，阻止服务启动。

该问题的根源在于 .NET 在默认情况下要求配置有效的 HTTPS 证书，即便你在 Nginx 等反向代理服务器之后部署服务。本文探讨问题的常见原因以及针对此问题的多种解决方案。

原因分析

错误信息已经明确指出，问题的核心是缺少服务器证书 。在生产环境中，我们不能像开发时那样依赖自动生成的开发证书。这意味着我们需要提供有效的、经过授权机构签名的证书或自己创建的自签名证书。

以下是一些可能出现此问题的情景：

• 应用配置缺失： appsettings.json 文件或者环境变量中没有配置 HTTPS 证书信息。
• 证书路径不正确： 配置了证书，但文件路径设置不正确，Kestrel 找不到证书。
• 证书格式不匹配： Kestrel 需要特定格式的证书文件（通常是 PFX 文件），使用了不兼容的格式。
• Linux 服务器权限问题： 运行应用程序的用户账户对证书文件没有读取权限。

解决方案

针对以上可能出现的原因，我们可以尝试下列几个解决方案：

1. 指定 PFX 证书路径和密码

最常见的解决办法是在你的 appsettings.json 配置文件中明确指定证书路径和密码。 这确保 Kestrel 在启动时可以加载你的 HTTPS 证书。你需要先有一个 PFX 文件（.pfx 或者 .p12）。

操作步骤：

1. 将你的 .pfx 文件复制到 Linux 服务器。

2. 假设证书名为 mycertificate.pfx，并位于 /home/user/certs 目录下，编辑 appsettings.json 文件：

   {
     "Kestrel": {
       "Certificates": {
         "Default": {
            "Path": "/home/user/certs/mycertificate.pfx",
            "Password": "your_certificate_password"
           }
       },
     "EndpointDefaults": {
       "Protocols": "Http2" 
       }
   
     }
   
   }
   

   • 替换 "Path" 为你实际的证书路径， "Password" 替换为你 .pfx 证书的密码。
   • "EndpointDefaults" 是一个可选配置，在此例子中开启了Http2， 这可能会优化连接性能。
   • 请注意妥善管理证书和密码，不应将密码直接写在配置文件里，在生产环境中考虑使用安全的环境变量或机密存储服务。

3. 重启你的应用程序。

2. 使用环境变量配置

另一种方法是使用环境变量，这可以在不修改 appsettings.json 文件的情况下配置证书信息。环境变量适合部署流水线，可以根据不同环境注入不同的配置信息。

操作步骤：

1. 在 Linux 服务器上设置环境变量，替换为你自己的证书路径和密码：

   export ASPNETCORE_Kestrel__Certificates__Default__Path=/home/user/certs/mycertificate.pfx
   export ASPNETCORE_Kestrel__Certificates__Default__Password=your_certificate_password
   

2. 像平时一样启动应用，不需要对appsetting文件进行任何改动

此方法会在应用程序启动时读取这些环境变量，并用来配置 HTTPS。

3. 使用命令行参数配置

也可以使用命令行参数指定证书，它类似使用环境变量，都适合不更改配置文件的场景。

操作步骤：

1. 启动应用的时候， 添加--urls 参数并配置端口号和证书

   dotnet your_app.dll --urls="https://*:5001"  --Kestrel__Certificates__Default__Path=/home/user/certs/mycertificate.pfx --Kestrel__Certificates__Default__Password="your_certificate_password"
   

--urls 指定应用程序监听的地址， 可以更改为其他可用的端口。 Kestrel__Certificates__Default__Path 和 Kestrel__Certificates__Default__Password 与以上方法作用相同。
需要根据实际情况，配置你真实的证书路径和密码。
2. 启动你的应用程序。

4. 生成自签名证书

假如你仅仅为了本地测试或有自己的证书生成方案， 你可以使用 openssl 命令来生成自签名证书：

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365

此命令将生成一个私钥 (key.pem) 和一个自签名证书 (cert.pem)，有效期 365 天。 在生产环境中，最好从证书颁发机构 (CA) 获取有效的 SSL 证书。
你可以通过下面的方法将证书转换为 pfx 格式：

openssl pkcs12 -export -out cert.pfx -inkey key.pem -in cert.pem -passout pass:your_pfx_password

将 cert.pfx复制到服务器上并按照之前的方式使用 appsettings.json、环境变量或命令行配置。

额外的安全建议

• 始终使用强大的密码来保护你的证书。
• 定期更换你的证书，以增强安全性。
• 将证书文件存放在受限制访问的目录，确保只有必要的用户才能访问。
• 谨慎处理自签名证书，因为浏览器会提示其安全性存在问题。在生产环境中，建议使用 CA 签发的证书。

通过实施上述任何解决方案，你的 C# Web API 应该能够顺利启动，并且能够在 Linux 服务器上提供安全的服务。记住，安全性是系统设计中的关键要素，任何轻率的决定都有可能导致严重的风险。 请务必采取措施保护你的服务。