SSL 配置指南

Netty-Boot 内置了对 HTTPS 的支持，以下将详细介绍如何配置和使用 SSL 以确保您的 Web 应用的安全性。

使用内置自签名证书

Netty-Boot 提供了内置的自签名证书，适用于开发和测试环境。通过以下配置，您可以快速启用 HTTPS 支持。

配置文件

在 app.properties 文件中添加以下配置：

server.ssl.enable=true
server.ssl.port=443

启动项目

配置完成后，启动项目，Netty-Boot 将自动在端口 443 上启用 HTTPS，并使用 Netty 提供的 SelfSignedCertificate 生成自签名证书。启动日志示例如下：

2024-10-18 14:56:32.115 [main] INFO  c.l.n.b.s.NettyBootServer.start:122 - Enable SSL: io.netty.handler.ssl.util.SelfSignedCertificate@1372ed45
2024-10-18 14:56:32.939 [main] WARN  i.n.b.ServerBootstrap.setChannelOption:464 - Unknown channel option 'TCP_NODELAY' for channel '[id: 0x8d599d06]'
2024-10-18 14:56:32.949 [main] INFO  c.l.n.b.s.DefaultNettyServerBootstrap.lambda$start$0:42 - Netty started successfully on port 443
2024-10-18 14:56:32.949 [main] WARN  i.n.b.ServerBootstrap.setChannelOption:464 - Unknown channel option 'TCP_NODELAY' for channel '[id: 0xf61bbdfa]'
2024-10-18 14:56:32.950 [nioEventLoopGroup-2-1] INFO  c.l.n.b.s.DefaultNettyServerBootstrap.lambda$start$0:42 - Netty started successfully on port 80

处理客户端不信任证书的问题

由于使用的是自签名证书，客户端可能会提示证书不被信任，可以正常连接失败,但是日志会出多余的异常信息。为避免日志中出现不必要的警告信息，您可以通过配置 logback.xml 来忽略相关日志：

在 logback.xml 的 <configuration> 节点中添加以下内容：

<logger name="io.netty.channel.DefaultChannelPipeline" level="OFF"/>

这将关闭 DefaultChannelPipeline 的日志输出，避免因证书问题产生的警告日志。

使用 PEM 格式证书

在生产环境中，建议使用由受信任的证书颁发机构（CA）签发的证书。以下是使用 PEM 格式证书的配置步骤。

证书要求

公钥证书：PEM 格式的 X.509 证书链文件。
私钥：PKCS#8 格式的私钥文件。

获取证书

通常，您可以通过如下配置在 Nginx 中使用 SSL 证书：

ssl_certificate /www/ssl/full_chain.crt;
ssl_certificate_key /www/ssl/privkey.pem;

注意：Nginx 使用的 privkey.pem 通常是 PKCS#1 格式，需要将其转换为 PKCS#8 格式以供 Netty-Boot 使用。

转换私钥格式

使用 openssl 工具将 PKCS#1 格式的私钥转换为 PKCS#8 格式：

openssl pkcs8 -topk8 -nocrypt -in privkey.pem -out privkey_pkcs8.pem

配置文件

在 app.properties 中添加以下配置：

server.ssl.enable=true
server.ssl.port=443
server.ssl.key.file=classpath:ssl/private_key_pkcs8.pem
server.ssl.key.cert.chain.file=classpath:ssl/full_chain.crt
server.ssl.key.password=your_private_key_password

说明：

server.ssl.key.file：指定转换后的 PKCS#8 格式私钥文件路径。
server.ssl.key.cert.chain.file：指定证书链文件路径。
server.ssl.key.password：如果私钥文件设置了密码，请在此处填写；否则可以省略或留空。

验证配置

配置完成后，重新启动项目，确保 HTTPS 端口 443 正常启动，并且使用了您提供的证书。

仅启动 HTTPS 端口

如果您只需要启用 HTTPS 而不启动 HTTP 端口，可以通过以下方式配置：

配置文件

在 app.properties 中移除或注释掉 server.port 配置项，并添加 HTTPS 配置：

#server.port=80
server.context-path=/im

server.ssl.enable=true
server.ssl.port=443
server.ssl.key.file=classpath:ssl/private_key_pkcs8.pem
server.ssl.key.cert.chain.file=classpath:ssl/full_chain.crt
server.ssl.key.password=your_private_key_password

说明：

注释掉 server.port=80，使应用仅监听 HTTPS 端口 443。
保持 server.context-path 配置以设置应用的上下文路径。

启动和测试

1. 构建项目

确保已安装 Maven 和 JDK 1.8 或更高版本。

在项目根目录下运行以下命令以构建项目：

mvn clean install

2. 运行应用

使用以下命令启动应用程序：

mvn spring-boot:run -Pdevelopment

此命令将使用 development 配置文件启动应用，并在 app.properties 中配置的端口（默认 443 或您自定义的端口）上运行。

3. 测试 HTTPS 接口

测试 `/txt` 接口

使用 curl 命令发送 GET 请求：

curl -k https://localhost/im/txt

说明：

-k 参数用于忽略自签名证书的验证，仅适用于测试环境。

预期响应：

Hello, this is the HTTP response!

测试 `/json` 接口

使用 curl 命令发送 GET 请求：

curl -k https://localhost/im/json

预期响应（JSON 格式）：

{
  "status": "OK",
  "message": "Request successful"
}

测试 `/echo` 接口

使用 curl 命令发送 POST 请求：

curl -k -X POST https://localhost/im/echo -d "This is an echo test"

预期响应：

This is an echo test

4. 测试 WebSocket 接口

您可以使用 WebSocket 客户端工具或 WebSocket UI 来测试 WebSocket 接口。

连接到 `/ws` 路由

打开 WebSocket 客户端工具。
输入连接地址：

wss://localhost/im/ws

连接后，发送一条消息，例如：

Hello WebSocket!

预期响应：

Server received: Hello WebSocket!

连接到 `/ws2` 路由

打开另一个 WebSocket 客户端窗口。
输入连接地址：

wss://localhost/im/ws2

连接后，发送一条消息，例如：

Hello WebSocket 2!

预期响应：

Server received: Hello WebSocket 2!

注意：在生产环境中，确保使用受信任的 SSL 证书，以避免客户端因证书不信任而无法建立连接。

常见问题

1. 端口被占用

如果启动时提示端口被占用，可以：

修改 app.properties 中的 server.ssl.port 为其他未被占用的端口。
终止占用该端口的进程。

2. 证书格式错误

确保：

公钥证书为 PEM 格式的 X.509 证书链文件。
私钥为 PKCS#8 格式。如果是 PKCS#1 格式，请使用 openssl 转换。

3. SSL 配置错误导致启动失败

检查 app.properties 中的 SSL 配置项是否正确，包括文件路径和密码（如果有）。

4. 客户端无法信任自签名证书

在生产环境中，建议使用由受信任的证书颁发机构（CA）签发的证书，以确保客户端能够信任并建立安全连接。