HTTPS 与证书

当已连接设备上的某个应用暴露出 Web 界面时，appliance 会通过其内置隧道使其可达。您可以选择浏览器如何访问 appliance——共有三种模式，从零配置到完全由企业签名。选择其中一种并按其步骤操作。

这与位于企业代理之后并不相同。 那一页讲的是 appliance 为出站流量信任您的企业 CA（appliance → 云端，经过拦截 TLS 的代理）。本页讲的是相反的方向——从您网络中的浏览器到 appliance 的入站流量。两者相互独立。

模式 1 — 纯 HTTP（默认）

您能得到什么。 一切都在 appliance 地址上通过纯 HTTP 提供：

每个应用 UI 都发布在各自自动分配的端口上；IronFlock UI 会显示每一个的确切链接。应用 UI 始终位于 appliance 登录之后——打开某个 UI 会重定向到登录页，除非您已登录并获得了对该设备的授权（在您希望某个端口开放的地方，可以按应用将其标记为公开）。

您需要做什么。 无需任何操作。这是默认设置——只需在本地网络上使用 appliance 的 IP 或主机名即可。无需 DNS，无需证书，无需企业 IT 参与。

何时使用。 位于受信任的、经过分段的网络上的 appliance——例如机器/OT VLAN 上的控制柜——在这种环境中纯 HTTP 是常态，访问由网络分段和物理安全来控制。

模式 2 — 使用自签发 CA 的 HTTPS

您能得到什么。 appliance 开启其内置 HTTPS 入口，并在您的域名下通过 HTTPS 提供一切服务——使用它自己生成的证书。既无需运行反向代理，也无需重新配置任何 URL；安装程序会将这一切自动接好。

您需要做什么。

1. 选择一个能解析到 appliance 的域名，使其对每一个将要使用它的浏览器和设备都能解析，并将 APPLIANCE_HOST 和 APPLIANCE_DOMAIN 都设置为它。由于 appliance 自己签发证书，任何名称都可以使用——唯一的要求是它能够解析。除了快速测试之外的任何用途，都请使用一个由您掌控的内部域名（例如 appliance.corp.example.com），并在您自己的 DNS 中为其添加通配符记录：隔离的或受 DNS 限制的 appliance 网络通常无法访问默认的 <host-ip>.nip.io 名称所依赖的公共 nip.io 服务。（在网络能够访问互联网的场景下，该默认值确实有效——这也是它在开发机上能工作的原因。）

2. 添加通配符 DNS，为该域名添加两条记录，均指向 appliance 主机 IP：

   • *.<APPLIANCE_DOMAIN> — 涵盖应用 UI 以及每一个服务子域名。
   • <APPLIANCE_DOMAIN>（顶级） — 按名称访问主 UI。

   （像 nip.io 这样的通配符 DNS 服务已经自动解析这些名称，因此无需添加任何记录——但这取决于该外部服务是否可达。）

3. 使用 --tls 安装：

   curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
     | sudo bash -s -- <your-instance-key> --interactive --tls

   --interactive 会提示输入 APPLIANCE_HOST / APPLIANCE_DOMAIN（或设置 IRONFLOCK_APPLIANCE_HOST / IRONFLOCK_APPLIANCE_DOMAIN 以进行无人值守安装）。appliance 会在 /opt/ironflock/certs/ca/rootCA.crt 生成一个本地 CA，并生成一张由它签名的通配符证书。

4. 向客户端机器分发该 CA 根证书。 通过您的 MDM 推送 rootCA.crt，或将其添加到每台机器的操作系统/浏览器信任存储中。在某台机器信任它之前，其浏览器会发出警告。

5. 在一年内续期。 服务器证书的有效期上限约为 1 年——浏览器会拒绝有效期更长的证书。要续期，请删除证书目录中的 tls.crt/tls.key 并重新运行安装程序；它会针对同一个 CA 重新签发一张新证书，因此您分发出去的信任仍然有效。

设备仍然走纯 IP 路径。 只有浏览器一侧转为 HTTPS。已连接的设备仍通过 appliance 的 IP 访问它，因此您无需在每台设备上安装该 CA。

何时使用。 您希望在共享网络上使用 HTTPS，但没有（或不想等待）来自企业 IT 的证书，并且您能够向将要打开该 UI 的机器推送一张根 CA。

模式 3 — 使用您的企业证书的 HTTPS

您能得到什么。 与模式 2 相同的全 appliance HTTPS——但证书来自您组织的 CA，其根证书在每一台受管机器上都已受信任。没有浏览器警告，也无需分发任何东西。设备也会一同迁移到该域名上。

您需要做什么。

1. 选择一个由您掌控的内部域名，并将 APPLIANCE_HOST 和 APPLIANCE_DOMAIN 设置为它（例如 appliance.corp.example.com）。此处必须是您自己的域名——CA 只会为您拥有的域名签发证书，因此 nip.io 名称在此模式下无法使用。
2. 添加通配符 DNS — *.<APPLIANCE_DOMAIN> 和顶级域名，均指向 appliance 主机 IP——与模式 2 第 2 步相同。
3. 获取一张通配符证书，用于 *.<APPLIANCE_DOMAIN>，来自您的内部 CA，形式为两个 PEM 文件：tls.crt（最好是完整证书链）和一个未加密的 tls.key。
4. 使用您的证书安装：

   curl -fsSL https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
     | sudo bash -s -- <your-instance-key> --interactive \
         --tls-cert /path/to/wildcard.crt \
         --tls-key  /path/to/wildcard.key

   --tls-cert 会隐含 --tls。等效的环境变量：IRONFLOCK_TLS_CERT / IRONFLOCK_TLS_KEY。
5. 按您 CA 的计划轮换。 将新的 PEM 文件放入证书目录并重启：

   sudo cp wildcard.crt /opt/ironflock/certs/tls.crt
   sudo cp wildcard.key /opt/ironflock/certs/tls.key
   sudo chmod 0600 /opt/ironflock/certs/tls.key
   sudo systemctl restart ironflock.service

   当文件发生变化时，appliance 会自动重新加载证书；重启只是为了立即应用它。除非您传入 --tls-cert，否则重新运行安装程序绝不会覆盖已有的证书。

设备也会迁移到该域名上。 由于该证书在整个机群范围内都受信任，设备流量——设备链接、容器镜像拉取和设备代理程序更新——也会通过 TLS 走该域名，insecure-registries 变通方案不再需要。 这适用于切换之后构建的应用镜像；切换之前安装的应用仍保留其构建时所用的 registry 地址，而 0.21.3 及更新版本的代理程序会自行解析该地址，参见下面的要求 4。

该模式下已连接设备的要求

连接到 appliance 的每台边缘设备必须：

1. 能解析该域名。 <APPLIANCE_DOMAIN> 及其子域（通配符记录）必须能从设备所在网络解析到 appliance 的 IP——与为浏览器服务的是同一批 DNS 记录。
2. 能通过端口 443 访问 appliance——这是设备为平台连接、为设备代理程序更新（由 https://registry.<APPLIANCE_DOMAIN>/dl 提供，此模式下不再需要端口 15002）以及为切换后构建的应用镜像所需的唯一端口（切换前安装的应用参见要求 4）。这正是模式 3 适合处于严格受限网络中设备的原因：出站 443 几乎在所有环境中都被允许，并且该连接经由企业 HTTP 代理同样可用（按 位于企业代理之后 → 边缘设备 的说明把代理提供给代理程序）。相比之下，在简单模式下设备需要直接访问 appliance 的多个服务端口，而企业防火墙和代理经常封锁它们——参见 设备连接。
3. 信任你的企业根 CA。 代理程序和 Docker 会用设备操作系统的信任存储来校验 appliance 的证书：
   • 受管机器（加入域的 Windows、由 MDM 管理的 Linux）通常已经信任你的企业根证书——无需处理。
   • 非受管 Windows： 在管理员命令提示符中把根 CA 安装到计算机存储——certutil -addstore -f Root corporate-root-ca.crt——然后重启 Docker Desktop（它在启动时从 Windows 存储导入受信任的根证书）和代理服务（Restart-Service reagent）。
   • Linux： sudo cp corporate-root-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates，然后重启 Docker（sudo systemctl restart docker）和代理程序。
   • 应用容器会自动继承这份信任（代理程序 0.21.3 及更高版本）。容器只带有基础镜像自带的 CA 集合，而没有任何基础镜像会包含企业内部根证书，因此通过 TLS 连接一体机的应用此前无法验证其证书。现在代理程序会把设备自身的信任库以只读方式挂载到每个应用容器的 /etc/ironflock/certs/ca-bundle.crt，并让常见运行时指向它（SSL_CERT_FILE、REQUESTS_CA_BUNDLE、NODE_EXTRA_CA_CERTS）。无需任何配置，但设备本身必须信任该根证书，因为代理程序传递的正是设备的这份信任。若应用自行设置了 SSL_CERT_FILE，则保留其设置。
4. 把设备代理程序升级到 0.21.3 或更新版本，或者重新发布在切换之前安装的应用。 应用保存的 compose 文件中带有完全限定的镜像引用——<APPLIANCE_IP>:15001/apps/…——它们在应用构建时就被写死了。这些引用属于数据：把 appliance 切换到域名不会改写任何 compose 文件。0.21.3 及更新版本的代理程序会把这样的引用解析到设备自身所配置的 registry 上，因此切换前安装的应用无需任何操作即可继续通过域名运行——升级后的首次启动会以新名称把每个镜像拉取一次。更老的代理程序则按写死的引用使用，继续访问旧的 IP 和端口：在该应用重新构建并针对 registry.<APPLIANCE_DOMAIN> 重新发布之前，它所在的设备仍需要能在本地网络访问 registry 端口（15001），仅有端口 443 对它并不够。 appliance 会自动处理自己这一侧：只要它自己的代理程序早于 0.21.3 且还存在这样的引用，它就让 registry 保持在 LAN 上可访问，并在安装程序输出中列出受影响的 compose 文件。代理程序升级到位之后——或者这些应用重新发布之后——下一次 sudo ironflock-update 就再无可等之物，会自行把 registry 移出 LAN。

何时使用。 标准的企业本地部署路径：您的组织已经运行着一个内部 CA，因此只需签发一次通配符证书，即可在各处受信任，无需任何逐机设置。

故障排查

某个应用 UI 链接打不开 / 连接被拒绝。 在纯模式下，应用 UI 位于 http://<host>:<port>——请确保您使用的是 IronFlock UI 中显示的确切链接（端口按应用分配），并确保网络上没有任何东西阻断该端口。

浏览器警告证书不受信任（在使用 --tls 之后）。 客户端尚未信任该证书的 CA。在模式 2 中，将 appliance 生成的 CA（/opt/ironflock/certs/ca/rootCA.crt）部署到客户端。在模式 3 中，确保客户端信任您的内部 CA 根证书。

证书已过期（自签发）。 自签发的服务器证书有效期约为一年（浏览器会拒绝有效期更长的证书）。请续期：删除证书目录中的 tls.crt/tls.key 并重新运行安装程序，以针对同一张仍受信任的 CA 重新签发——或改用来自您自己 CA 的 --tls-cert。

证书名称不匹配。 该证书不是所用域名的通配符证书。它必须涵盖 *.<APPLIANCE_DOMAIN>，且 URL 的域名必须与 APPLIANCE_DOMAIN 匹配。

某个子域名无法解析（在使用 --tls 之后）。 缺少通配符 DNS。添加一条指向 appliance 主机的 *.<APPLIANCE_DOMAIN> A 记录——它涵盖应用 UI 和每一个服务子域名。

切换到模式 3 后应用无法启动或无法拉取镜像——端口 15001 上出现 “connection refused”。 该应用的 compose 文件仍按 appliance 的 IP 地址引用 registry，因为它就是照此构建的，而该设备的代理程序早于 0.21.3——从该版本起，代理程序会自行把这样的引用解析到自己的 registry 上。请升级设备代理程序，或者重新构建并重新发布该应用，使其镜像通过 registry.<APPLIANCE_DOMAIN> 解析。在此之前 registry 必须保持在本地网络可访问，这一点由 appliance 自行安排——一次普通的 sudo ironflock-update 会恢复 LAN 绑定，并列出仍持有旧引用的 compose 文件。

应用在运行却始终连接不上，日志每隔几秒重复同一次连接尝试。 应用容器无法验证一体机的证书：TLS 握手在服务器证书之后立即中断，SDK 会无限重试；而设备本身仍然在线，因为代理程序使用操作系统的信任库，容器则不会。请将设备代理程序升级到 0.21.3 或更高版本，该版本会把设备的信任库传递给应用容器，并确认设备信任贵组织的根证书（上面的要求 3）。在设备上运行 docker logs <容器> 可以看到证书验证错误。若代理程序版本较旧，则需逐个应用处理：把根 CA 加入镜像，或挂载后在应用的 compose 文件中设置 SSL_CERT_FILE。

切换到模式 3 后设备无法连接。 逐项核对上面四条设备要求：该域名必须能从设备所在网络解析，appliance 上的端口 443 必须可达（直接可达或经设备的代理），设备必须信任你的企业根 CA，并且切换前安装的应用需要 0.21.3 代理程序或一次重新发布，之后才不再需要 registry 端口。在 Windows 上，位于 C:\ProgramData\IronFlock\Reagent\reagent.log（Linux 上为 /var/log/reagent.log）的代理日志会给出确切的连接错误——DNS 失败、超时或证书校验错误分别指向前三条要求之一。