位于企业代理之后

许多工厂和企业网络只能通过企业 HTTP 代理访问互联网（例如运行在 3128 端口上的 Squid 代理）。IronFlock Appliance 在这种环境下也能干净地安装和运行——您只需在安装命令中提供代理，其余配置由安装程序为您完成。

本页假设 appliance 主机未设置任何代理环境变量——由您显式提供代理。本页将说明安装程序自动处理的部分，以及对于拦截 TLS 的代理所需的那一个额外步骤。

这是 Appliance 指南中防火墙配置一节的代理配套说明。需要可达的 IronFlock 端点完全相同——区别在于这里是通过您的代理来访问它们。

为什么代理需要特别处理

IronFlock 平台镜像由 Docker 守护进程拉取——这是一个拥有自身网络配置的后台服务，与您的 shell 相互独立。即使主机本身可以通过代理访问互联网，除非显式告知，守护进程并不知道代理的存在。如果不加配置，它会尝试直接连接，网络将其阻断，安装便在登录步骤处因超时而中断：


Error response from daemon: Get "https://instance-registry.ironflock.com/v2/":
net/http: request canceled while waiting for connection (Client.Timeout exceeded)

安装程序为您处理的部分

当您在安装命令中提供代理时，安装程序会为您配置 Docker 守护进程——它会在 /etc/systemd/system/docker.service.d/http-proxy.conf 写入一个代理 drop-in 文件，并重启 Docker 一次，使其能够访问 IronFlock 仓库。这一步骤是：

无需干预 — 您只需提供一次代理（见下文）；安装程序会写入配置并为您重启 Docker，无需手动设置守护进程。
幂等的 — 在后续更新时，只有当代理确实发生变化时才会重启 Docker，因此不会打扰正在运行的应用。
完全跳过 — 当未提供代理时跳过——直连互联网的安装不受影响。

安装程序还会将 appliance 自身与云端的连接路由通过代理——包括许可证校验，以及让您能够从 ironflock.com 访问实例的远程管理上行链路。它会将您的代理记录到 appliance 的中央配置文件 /opt/ironflock/.env 中，平台会自动使用它——在之后的每一次更新中，该文件始终是权威来源（参见日后更改或移除代理）。无需为 appliance 上线进行任何单独的设置。

在代理之后运行安装程序

代理在两个地方都需要：curl 需要它来下载安装程序，安装程序需要它来配置 Docker。用一条命令将代理同时提供给两者——设置一次代理 URL，用 --proxy 传给 curl，用 --http-proxy / --https-proxy 传给安装程序：


# 您的企业代理——请修改此行
PROXY="http://proxy.your-company.com:3128"
 
curl -fsSL --proxy "$PROXY" \
  https://instance-registry.ironflock.com/dl/appliance/install_ironflock.sh \
  | sudo bash -s -- <your-instance-key> --http-proxy "$PROXY" --https-proxy "$PROXY"

请将代理 URL 和 <your-instance-key> 替换为您自己的值。如果您的代理需要身份验证，请将凭据包含在 URL 中：http://user:[email protected]:3128——应使用哪个账户，请参阅代理身份验证。

安装程序代理标志：

标志	用途
`--http-proxy <url>`	用于 Docker 守护进程的纯 HTTP 流量的代理。
`--https-proxy <url>`	用于 HTTPS 流量的代理（这是对镜像拉取真正重要的那个）。
`--no-proxy <list>`	额外的、应绕过代理的逗号分隔主机列表。

相同的值也可以通过 IRONFLOCK_HTTP_PROXY、IRONFLOCK_HTTPS_PROXY 和 IRONFLOCK_NO_PROXY 环境变量提供。

如果主机确实已经导出了 HTTP_PROXY / HTTPS_PROXY，您可以改为运行 sudo -E bash（不带这些标志），安装程序会自动检测它们——但在全新的 appliance 上，这些变量通常未设置，因此如上所示显式传入它们才是可靠的做法。shell 环境变量只用于首次安装的初始设置：appliance 一旦安装完成，其记录下来的配置便会优先生效（参见日后更改或移除代理）。

本地流量始终绕过代理

您无需手动管理 NO_PROXY。安装程序始终会将 localhost、127.0.0.1 以及 appliance 自身的主机地址排除在代理之外（您通过 --no-proxy 传入的任何内容都会被保留并合并）。这确保了 appliance 的本地 App Store 和仓库被直接访问，而不会被路由出去经过企业代理。

代理身份验证

如果您的代理要求登录，请为 appliance 分配专用的服务账户，而不是使用某个人的账户。这样，它的流量会以一个由您的网络团队掌控的名称出现在代理日志中：他们可以限制它能访问的内容，也可以停用该账户或轮换其凭据，而不会影响任何人的个人登录。这是 IronFlock 主机的网络身份在代理侧的对应做法。

支持：Basic 身份验证。 将账户写入代理 URL——http://user:[email protected]:3128——并在安装命令中传入，或写入 /opt/ironflock/.env 后运行 sudo ironflock-update。密码中的特殊字符需进行 URL 编码（例如 @ → %40）。
暂不支持：Windows 集成身份验证（Kerberos、NTLM）。如果您的代理只接受这类方式，请让网络团队允许该服务账户使用 Basic 身份验证，或将 appliance 的地址作为命名主机免身份验证放行。

关于这些流量，需要告知网络团队的内容：

流量只发往防火墙配置列表中的端点，经由端口 443 上的 HTTPS 传输。端口 2525 上的邮件中继从不经过代理。
发往 cbw.ironflock.com 的远程管理连接是一条长时间保持的 WebSocket 连接，每隔几秒就会发送保活（keep-alive）流量。如果代理会在固定时长后切断长连接，appliance 会在几秒内自动重新连接，但远程用户每次都可能察觉到短暂中断——请尽可能将这条连接从连接时长限制中豁免。

日后更改或移除代理

代理会被记录在 appliance 的中央配置文件 /opt/ironflock/.env 中。该文件是权威来源：每一次更新所应用的都是文件中的内容。因此，在已安装的 appliance 上重新配置代理只需两步：

编辑 /opt/ironflock/.env 中的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 条目。
运行 sudo ironflock-update。

更新会一次性将这些设置重新应用到所有位置——Docker 守护进程、平台服务、设备代理程序以及远程访问隧道——并且只重启确实发生变化的部分。

或者，也可以将新值作为标志传入——它们会覆盖该文件，并被保存回文件中：


sudo ironflock-update --https-proxy "http://user:[email protected]:3128"

每项设置相互独立：只传入 --https-proxy 不会改动您现有的 NO_PROXY 列表（缺失的 HTTP 代理设置会自动镜像补全）。

要移除代理——例如在将 appliance 迁移到可直连互联网的网络之后——请清空 /opt/ironflock/.env 中的相应条目（HTTP_PROXY=、HTTPS_PROXY=），或显式传入空标志，然后执行更新：


sudo ironflock-update --http-proxy "" --https-proxy ""

代理配置会重新从 Docker 守护进程和设备代理程序中移除，appliance 将恢复直接连接。您的 NO_PROXY 列表会被保留，以便日后重新启用。

边缘设备

以上所有内容同样适用于使用设备设置工具（ironflock-init）设置的边缘设备。它接受相同的代理标志，并以相同的方式进行自我配置——在运行它时传入代理，它就会为您将其下载（包管理器、Docker 安装、代理程序下载）和 Docker 守护进程都路由通过代理：


sudo ./ironflock-init -c mydevice.flock \
  --http-proxy "$PROXY" --https-proxy "$PROXY"

下载该设置工具的引导脚本会在它之前运行，因此也要为该步骤提供代理——先在 shell 中将其导出，使其下载能够成功：


export HTTP_PROXY="$PROXY"
export HTTPS_PROXY="$PROXY"
curl -sSL --proxy "$PROXY" https://instance-registry.ironflock.com/dl/reswarmify/install.sh | bash

如果设备从本地 appliance App Store 而非云端拉取应用镜像，请用 --no-proxy 添加该仓库的主机，使这些拉取保留在本地网络上。

在 Windows 设备上，代理程序作为 Windows 服务运行。请将代理传递给服务安装程序——它同时覆盖平台连接和代理程序的自动更新：


reagent.exe service install -config path\to\config.flock -proxy "http://proxy.example.com:3128"

哪些主机绕过代理

NO_PROXY 匹配的是客户端拨号使用的主机名，而绝不是该名称解析到的地址。设备通过名称访问的一体机——也就是域模式下的所有一体机，参见应用界面与 HTTPS——因此必须显式列出。否则代理程序会把发往本地一体机的连接送往企业代理，而大多数代理拒绝把流量路由回内部网络，设备便永远无法上线。

安装程序会从设备自身的 .flock 推断这一点。除 localhost 和 127.0.0.1 外，它会加入一体机域名——同时写入不带点和以点开头的两种写法——以及所有以非 TLS 方式访问的镜像仓库主机。云端设备除两个回环条目外不会获得任何额外条目，因为它们的端点是公网地址，确实需要代理。

本站点所需的其他主机通过 -no-proxy 指定，它对应 ironflock-init 中的同名参数：


reagent.exe service install -config path\to\config.flock `
  -proxy "http://proxy.example.com:3128" `
  -no-proxy "buildserver.corp.example,10.0.0.0/8"

之后如何修改设置

结果会写入 %ProgramData%\IronFlock\Reagent\proxy.env，此后以该文件为准：


HTTP_PROXY=http://proxy.example.com:3128
HTTPS_PROXY=http://proxy.example.com:3128
NO_PROXY=localhost,127.0.0.1,appliance.corp.example,.appliance.corp.example

编辑该文件后重新运行 reagent.exe service install 即可生效。之后的安装绝不会覆盖此文件，而 service uninstall 会保留代理程序目录——因此重新安装服务所需的卸载／安装流程不会影响你的设置。若要用参数值有意替换该文件，请使用 -force-proxy。

如果本站点是通过代理访问一体机，请删除相应条目。 两种部署都真实存在：位于同一厂区局域网的一体机可直接访问，而集中托管的一体机可能只能经企业代理访问。安装程序无法区分二者，因此会逐条写出主机——请删除不适用于你网络的条目。

Docker 需单独配置

Docker Desktop 既不读取 proxy.env，也不读取服务环境。镜像由 Docker 守护进程拉取，它在 Settings → Resources → Proxies 下有自己的设置，包括自己的绕过列表——该列表同样需要一体机主机。在代理程序一侧修正代理并不能解决 docker pull。

Linux 设备

ironflock-init 直接支持 --no-proxy，因此可在安装时指定一体机：


sudo ./ironflock-init -c mydevice.flock \
  --http-proxy "$PROXY" --https-proxy "$PROXY" \
  --no-proxy "appliance.corp.example.com"

这会在 /etc/systemd/system/reagent.service.d/http-proxy.conf 生成一个 systemd drop-in 文件。之后不要通过编辑该文件来调整设置——安装工具会重写它。请改用 systemctl edit reagent，它会创建 override.conf，systemd 会在安装程序的 drop-in 之后应用它，且 IronFlock 从不触碰：


sudo systemctl edit reagent


[Service]
Environment="NO_PROXY=localhost,127.0.0.1,appliance.corp.example.com"


sudo systemctl restart reagent

TLS 拦截型代理（企业 CA）

许多企业代理会通过用公司证书颁发机构（CA）重新签名来检查 HTTPS 流量。对于这类代理，配置代理是必要的但还不够——appliance 主机还必须信任该 CA，否则每一个云端连接（镜像拉取、许可证校验、管理上行链路）都会被拒绝。

只需将该 CA 安装一次到主机的系统信任存储中。appliance 会将该信任存储挂载到它的所有容器中，因此 Docker 和每一个 IronFlock 服务都会读取到该 CA——无需针对每个容器或每个服务进行配置。由于各容器在启动时读取它，因此在添加或更改 CA 后请重启整个堆栈（见下方步骤 3）。

1. 获取企业 CA

向您的网络团队索取该代理的 “SSL 检查” / “TLS 拦截” 根 CA——即已部署到受管企业机器上的那张相同证书——以 .crt 文件形式提供。这是最干净的来源。

请安装签发用的 CA，而不是某一台主机的证书。 常见的错误是只保存代理为某一个主机名（例如仅 instance-registry.ironflock.com）重新签名的证书。这只会让那一个主机可用，而其余所有云端主机仍会失败。您需要的是签发这些证书的那个 CA。

如果您无法直接拿到该文件，但代理会出示其完整证书链，您可以从连接中提取该 CA——请将 <PROXY_HOST>:<PROXY_PORT> 替换为您的代理：


# 抓取证书链，每张证书一个 PEM。c1 是每主机的叶子证书（跳过它）；
# c2..cN 是需要信任的企业 CA 链。
echo quit | openssl s_client -connect instance-registry.ironflock.com:443 \
  -proxy <PROXY_HOST>:<PROXY_PORT> -showcerts 2>/dev/null \
  | awk '/BEGIN CERTIFICATE/{n++; c=1} c{print > ("/tmp/proxy-c" n ".pem")} /END CERTIFICATE/{c=0}'
 
# 可选——查看返回的内容：
for f in /tmp/proxy-c*.pem; do echo "== $f =="; openssl x509 -in "$f" -noout -subject -issuer; done

2. 安装它并重建信任存储

如果您的 IT 团队直接给了您 .crt 文件：


sudo cp corporate-root-ca.crt /usr/local/share/ca-certificates/corporate-proxy-ca.crt
sudo update-ca-certificates

如果您是从上面的证书链中提取的，请信任除叶子证书（c1）之外的每一张证书：


i=0; for f in $(ls -v /tmp/proxy-c*.pem | tail -n +2); do
  i=$((i+1)); sudo cp "$f" "/usr/local/share/ca-certificates/corporate-proxy-ca-$i.crt"
done
sudo update-ca-certificates

3. 验证

现在每一个 IronFlock 云端主机都必须能够通过代理完成校验——返回的是 HTTP 状态码，而不是 TLS 错误：


for H in instance-registry.ironflock.com web.ironflock.com cbw.ironflock.com \
         registry.ironflock.com regauth.ironflock.com; do
  curl -x http://<PROXY_HOST>:<PROXY_PORT> -sS -o /dev/null -w "$H -> %{http_code}\n" "https://$H/"
done

如果五者全部返回诸如 200、401 或 404 之类的状态码，则说明该 CA 正确无误。然后重启整个堆栈，使各服务读取到它（或重新运行安装程序）：


sudo systemctl restart ironflock.service

设备用户界面的远程访问

IronFlock 让您可以随时随地在 IronFlock 内部直接打开运行在边缘设备或机器上的用户界面——机器 HMI、PLC 页面、设备上的配置或仪表板画面。这是远程服务与支持的一项关键能力：工程师无需身处现场或本地网络，即可访问机器的界面。访问始终由 IronFlock 权限系统中介和把关，因此只有获得授权的用户才能访问指定设备。

这条远程访问隧道基于 frp (Fast Reverse Proxy) 构建——一项成熟、广泛使用的开源技术。IronFlock 仅将其用于提供上述的设备界面访问功能。

为什么企业代理可能造成阻碍

frp 具备强大的网络穿透能力，正因如此，杀毒软件和代理安全产品常常笼统地将其标记为风险软件（riskware）——尽管作为一个久经考验的开源组件，它是安全的，并且在这里仅用于经过许可的远程访问功能。一旦发生这种情况，代理就会阻止下载包含 frp 的那个 IronFlock 组件。

这不会破坏您的 appliance：远程访问隧道是一项可选功能，因此即使该组件被阻止，平台也会正常安装和运行，只是在没有设备界面访问的情况下运作。此时在仪表板中，某个设备的远程访问控件会提示此 appliance 上不提供远程访问。

企业 IT 需要放行的内容

如果您的组织希望享受 IronFlock 的远程服务功能，就必须允许包含 frp 的那个 IronFlock 组件通过企业代理下载。请向您的网络/安全团队提出以下两项具体要求：

为来自 instance-registry.ironflock.com 的镜像下载设置扫描例外，使笼统的风险软件（riskware）判定不会拦截隧道组件。这比将所有 IronFlock 流量排除在 TLS 检查之外范围更窄——appliance 的其余流量仍可继续接受检查。
将该检测记录为已知误报。 frp 是一款广泛使用的开源反向代理；IronFlock 仅将其用于上文所述、受访问控制的远程访问功能。

已为 appliance 列出的相同 IronFlock 端点在此同样适用——参见防火墙配置；这里说的是在仅仅路由该流量之外，还要不对其进行扫描/拦截。

一旦放行了 frp，只需重新运行更新——下载一旦成功，该功能便会自动开启，无需任何其他改动：


sudo ironflock-update

在不启用远程访问的情况下运行

如果您不需要设备界面访问——或希望在安排代理例外期间进行一次干净的安装——您可以显式禁用该隧道。其余一切照常安装：


# 安装时，附加在安装命令之后
... | sudo bash -s -- <your-instance-key> --no-tunnel
 
# 或在已安装的 appliance 上
sudo ironflock-update --no-tunnel

该选择会在多次更新之间被记住。之后（在 frp 获得放行后）可用 --tunnel 重新启用它：


sudo ironflock-update --tunnel

故障排查

安装在 “Logging in to instance-registry.ironflock.com” 处停止，并出现 Client.Timeout 错误。 Docker 守护进程无法访问仓库。请重新运行安装程序，并按上文所示用 --http-proxy / --https-proxy 传入您的代理。

配置代理后登录仍然失败。 您的代理很可能拦截了 TLS。请按 TLS 拦截型代理中所述安装企业 CA，然后重新运行。

检查 Docker 守护进程是否看到了代理：


sudo systemctl show --property=Environment docker
sudo docker login instance-registry.ironflock.com

如果 docker login 单独执行成功，appliance 安装就能通过那个失败的步骤。

只有单个组件下载失败，而其余一切都正常安装。 这通常是基于 frp 的远程访问组件被您的代理或杀毒软件作为风险软件拦截所致。安装仍会完成——只是设备界面访问不可用。要启用它，请让您的代理团队按设备用户界面的远程访问中所述放行该流量，然后重新运行 ironflock-update。若要有意在不启用它的情况下安装，请传入 --no-tunnel。

更新

一旦 appliance 在代理之后完成安装，其代理设置就会被记录在 /opt/ironflock/.env 中，并在每一次更新时重新应用。手动更新和后台自动更新都会继续通过代理工作，无需任何额外操作——请参阅 Appliance 指南中的维护。要让 appliance 指向另一个代理——或使其完全脱离代理——请参见日后更改或移除代理。

如果设备界面的远程访问在安装时被阻止，那么每一次更新都会自动重试它——因此一旦您的代理放行了 frp，下一次更新便会开启该功能，无需任何额外步骤。