如何在Unifi Cloud Key上安装SSL证书

本教程为您提供了如何在 UniFi Cloud Key 上安装 SSL 证书的分步说明。Cloud Key 在 Java 密钥库之上运行 UniFi Network 应用程序，因此安装通过 SSH 完成：您需要从证书、私钥和 CA 证书链创建一个 PKCS#12 包，然后使用 Java keytool 工具将其导入 Cloud Key 密钥库，并重启 UniFi 服务。

在 UniFi Cloud Key 上生成 CSR 代码

证书签名请求（CSR）是一段编码文本，包含您的联系方式，例如域名和组织信息。每位申请者都必须生成一个 CSR 并将其发送给证书颁发机构（CA）进行验证，之后才能签发证书。对于 Cloud Key，CSR 中的公用名应为您用来访问控制器的主机名，例如 unifi.yoursite.com。

您有两种选择：

• 使用我们的CSR 生成器自动创建 CSR。
• 按照我们的分步教程在 UniFi Cloud Key 上生成 CSR。

您可以使用任何文本编辑器（例如记事本）打开 CSR 文件，并在向 SSL 供应商申请证书时粘贴该内容。请妥善保管配套的私钥：在第 3 步创建 PKCS#12 包时还需要再次使用它。一旦 CA 验证了您的请求并通过电子邮件发送 SSL 文件，就可以继续进行下面的安装步骤。

在 UniFi Cloud Key 上安装 SSL 证书

Cloud Key 从位于 /usr/lib/unifi/data/keystore 的 Java 密钥库提供 HTTPS 服务。默认情况下，该密钥库中保存的是一个自签名证书，别名为 unifi，密码为 aircontrolenterprise。要安装您自己的证书，需要替换该条目：将您的文件打包为 PKCS#12 归档文件，将其导入到相同的别名下，然后重启 UniFi 服务。整个操作需要通过 SSH 完成，因此请先连接到 Cloud Key（Gen1 的默认 SSH 用户为 root，Gen2 则使用您在设备接入时设置的管理员账户）。

步骤 1：准备您的 SSL 文件

检查您的邮箱，下载包含证书的 ZIP 压缩包并解压。根据您的 SSL 提供商不同，您可能会获得以下部分或全部文件：

• 主 SSL 证书（您的服务器证书）。
• 中间 SSL 证书。
• 根 SSL 证书。
• CA 证书包，这是一个已经包含根证书和中间证书的单一文件。

您还需要与 CSR 一起生成的私钥。如果您使用的是我们的 CSR 生成器，该私钥在当时就已提供下载。

步骤 2：将 SSL 文件复制到 Cloud Key

通过 SCP 或 SFTP 将文件上传到 Cloud Key，并放置在 /etc/ssl/private/ 目录下。请使用以下名称，以便与后续步骤中的命令相匹配：

• 主证书命名为 /etc/ssl/private/cloudkey.crt
• 私钥命名为 /etc/ssl/private/cloudkey.key
• CA 证书包（根证书和中间证书）命名为 /etc/ssl/private/yourcaname.crt

注意：每个 PEM 文件在结尾行之后必须以换行符结束。证书的最后一行正是五个连字符，接着是 END CERTIFICATE 字样，再接五个连字符（—–END CERTIFICATE—–）；请确保其后有换行。缺少末尾的换行符是导入出错的常见原因。

步骤 3：将证书打包为 PKCS#12 文件

将您的私钥、主证书和 CA 证书包合并为一个 PKCS#12 文件。别名必须为 unifi，因为这正是 UniFi 密钥库所期望的别名。请将 enteryourpassword 替换为您自己选择的密码，并记住它：在第 4 步中，您需要将相同的值作为源密码传递给 keytool。

openssl pkcs12 -export -in /etc/ssl/private/cloudkey.crt -inkey /etc/ssl/private/cloudkey.key -out /etc/ssl/private/cloudkey.p12 -name unifi -CAfile /etc/ssl/private/yourcaname.crt -caname root -password pass:enteryourpassword

此命令会生成 /etc/ssl/private/cloudkey.p12，其中包含私钥、您的证书以及证书链，全部保存在别名 unifi 下。

步骤 4：将 PKCS#12 文件导入到 Cloud Key 密钥库

将 PKCS#12 文件导入到位于 /usr/lib/unifi/data/keystore 的现有密钥库中。目标密钥库已经使用密码 aircontrolenterprise，因此目标密钥库密码和密钥密码必须保持为 aircontrolenterprise。源密码是您在第 3 步中为 PKCS#12 文件设置的密码。

keytool -importkeystore -deststorepass aircontrolenterprise -destkeypass aircontrolenterprise -destkeystore /usr/lib/unifi/data/keystore -srckeystore /etc/ssl/private/cloudkey.p12 -srcstoretype PKCS12 -srcstorepass enteryourpassword -alias unifi

如果 keytool 提示别名 unifi 已存在，这指的是默认的自签名条目。在提示时确认覆盖，或者先使用下面的命令删除旧条目，然后重新运行导入命令：

keytool -delete -alias unifi -keystore /usr/lib/unifi/data/keystore -storepass aircontrolenterprise

重要提示：请不要将密钥库密码修改为您自己的值。UniFi 服务被硬编码为使用 aircontrolenterprise 打开密钥库；如果您更改了该密码，控制器将无法读取证书，HTTPS 也将无法正常工作。

步骤 5：设置权限并删除临时文件

收紧 /etc/ssl/private/ 目录中文件的所有权和权限，确保私钥不会被所有人读取，然后删除不再需要的中间文件。请逐条运行以下命令：

chown root:ssl-cert /etc/ssl/private/*
chmod 640 /etc/ssl/private/*
rm /etc/ssl/private/cloudkey.p12

证书现在已保存在密钥库中，因此不再需要 PKCS#12 文件。如果您在此过程中还上传了 CSR 或 CA 文件，也可以将它们一并删除：

rm /etc/ssl/private/cloudkey.csr
rm /etc/ssl/private/yourcaname.crt

提示：在重启之前，您可以先备份密钥库，以便在需要时进行回滚。在 /usr/lib/unifi/data/ 目录下，使用 tar -cvf keystore-backup.tar keystore 进行归档。

步骤 6：使控制器主机名与证书匹配

为了让浏览器信任该证书而不出现名称不匹配的警告，请将控制器的主机名或 IP 设置为证书中的名称。在 UniFi Network 应用程序中，进入设置 > 系统（旧版本为：设置 > 控制器），将控制器主机名/IP设置为证书上的公用名，例如 unifi.yoursite.com。请确保该主机名在您的 DNS 中解析到 Cloud Key。

步骤 7：重启 UniFi 服务

新证书只会在 UniFi 服务启动时被读取，因此请重启服务以加载您的证书：

service unifi restart

在使用 systemd 的较新版 Cloud Key 固件上，等效命令为：

systemctl restart unifi

等待一分钟，让服务重新启动，然后在浏览器中重新加载控制器。恭喜，您的 SSL 证书现已成功安装在 UniFi Cloud Key 上。

测试您的 SSL 安装

安装证书后，请检查您的配置是否存在错误或漏洞，例如缺少中间证书或证书链不受信任。使用我们的SSL 检测工具可即时扫描并生成报告。由于 UniFi 控制器通常监听 8443 端口，请将检测工具指向完整地址，例如 unifi.yoursite.com:8443。您也可以通过命令行确认结果：

echo | openssl s_client -connect unifi.yoursite.com:8443 -servername unifi.yoursite.com 2>/dev/null | openssl x509 -noout -issuer -dates

此命令会打印证书的颁发者和有效期，让您确认 Cloud Key 正在提供您的证书，而不是之前的自签名证书。

常见问题