接入节点

要求复制链接

节点使用为 Edgeweir 构建的 OpenResty，与 edgeweir-node 一起发布，列在同一个已签名的 checksums.txt 中：

两个软件包只有 deb 与 rpm 格式（amd64、arm64）。不再使用 openresty.org 的软件源；早先由 install.sh 添加的 openresty.org 软件源与 openresty 软件包可以自行删除。

1. 生成安装命令复制链接

1. 打开 集群与节点，选择集群，点击 添加节点。对话框立即显示 安装命令：集群的默认节点组，有效期 1 小时，不带节点名称。
2. 需要节点名称、其他节点组或有效期时，打开 选项：填写 节点名称，选择 节点组（集群有多个节点组时显示）与 有效期（15 分钟、1 小时、24 小时），点击 重新生成。
3. 复制 安装命令。命令下方显示剩余时间、「仅显示一次」、地址提醒与 节点通道连接检查；关闭对话框后不再显示，再次打开生成新的 token。
4. 在节点上执行命令后，对话框的 注册进度 每 3 秒刷新：等待节点注册（或令牌已过期）、已注册（节点名称链接到节点详情）、在线、配置已应用、数据面正常、有可供 DNS 使用的地址。

节点通道连接检查复制链接

控制台用节点通道地址与自己的节点通道做一次 TLS 握手（不带客户端证书，不发送请求），比较对方出示的证书链与节点通道内部 CA；wss://、ws:// 地址先在 /node-channel 完成 WebSocket 握手，再在其中做这次 TLS 握手。结果在 系统设置 的「节点通道」卡片中显示在地址下方；在添加节点对话框中显示为一行，检查未通过时带「修改」链接，打开 系统设置。

检查只作提示，不阻止任何操作：控制台能连上自己的地址，不代表其他网络的节点也能连上；控制台所在网络不支持访问自己的公网地址（NAT 回流）时，结果为无法连接，节点仍可能正常注册。结果缓存 30 秒，地址改变后重新检查。API：GET /api/v1/settings/node-channel-check，返回 { url, result, checkedAt }，result 为 ok、unreachable、mismatch 或 refused。

2. 执行安装命令复制链接

在节点主机（不是控制台主机）上以具备 sudo 权限的账户执行生成的命令：

export EDGEWEIR_TOKEN='<一次性 token>'
curl -fsSL https://cdn-admin.example.com/install.sh | sudo --preserve-env=EDGEWEIR_TOKEN bash -s -- \
  --server https://cdn-admin.example.com:8443 --ca-sha256 <CA 指纹>

token 只经 EDGEWEIR_TOKEN 环境变量或 --token-file PATH 传递，不出现在进程参数中；--token 参数被拒绝。全部选项见 命令行。

3. 验证复制链接

install.sh 最后等待 edgeweir-node healthcheck 通过（install.sh 流程 第 11 步），输出 done: edgeweir-node is healthy (revision N, M sites)。之后：

systemctl status edgeweir-node
journalctl -u edgeweir-node -f

预期：edgeweir-node.service 为 active (running)；集群与节点 中该节点状态为「在线」，已应用版本 显示配置版本号。节点注册后、首次连接节点通道前状态为「等待心跳」；在线但尚未应用配置时 已应用版本 标「待应用配置」。

install.sh 流程复制链接

• 第 5、6 步通过前不执行任何下载的程序。--allow-unsigned 跳过第 5 步，仅用于开发，仍校验 SHA-256。
• 脚本全部由函数组成，最后一行才调用 main：下载中断时不执行任何内容。
• 已注册的主机可以重新运行同一命令：不下载、不重装，启动服务（运行中则重启）并做健康检查；加 --version <版本> 时先安装该版本。主机上没有 /usr/bin/edgeweir-node 时安装最新版本。
• 重新注册（例如证书已过期）：在控制台生成新的安装命令，在命令末尾加 --force 执行；之后删除控制台中原来的节点。
• 控制台不保存 SSH 凭据；节点私钥不离开节点。

安装结果：

deb、rpm 由包脚本创建 edgeweir 用户与目录；tar.gz 由 install.sh 创建。

端口与防火墙复制链接

节点在以下端口接受用户流量，主机防火墙与云安全组需要放行；节点只主动连接控制台的节点通道，不需要为控制台开放入站端口。

访客 IP复制链接

集群「网络」页签的「访客 IP」决定节点 HTTP / HTTPS 监听的访客地址：规则的 ip.src、封禁、CC、访问日志、错误页的 {{client_ip}}、维护模式的放行地址、PURGE 按访客地址的限频与回源的 X-Real-IP 都使用它。修改后发布配置版本，节点 reload。

旧 worker 的关闭时间复制链接

reload 后，旧 worker 默认一直服务已有的连接（四层长连接、HTTP keep-alive、WebSocket），直到连接结束；频繁的结构性变更会留下多组旧 worker。节点参数 --stream-shutdown-timeout（环境变量 EDGEWEIR_STREAM_SHUTDOWN_TIMEOUT）限制这段时间：

EDGEWEIR_STREAM_SHUTDOWN_TIMEOUT=30m

修改后执行 sudo systemctl restart edgeweir-node。容器节点用 -e EDGEWEIR_STREAM_SHUTDOWN_TIMEOUT=30m。

区域探针复制链接

区域探针从所在区域探测各节点的调度地址，结果驱动备用 IP 与智能调度，见区域探针与智能调度。探针是 edgeweir-node 的 probe 模式：不运行 OpenResty，不监听端口，身份与节点分开。注册令牌在 系统设置 →「监控」→「添加探针」生成，只显示一次。

容器复制链接

控制台给出的「启动命令」是 docker run，见添加探针。Compose 写法：

services:
  probe:
    image: ghcr.io/marvinli001/edgeweir-node:latest
    entrypoint: ["/usr/local/bin/edgeweir-node", "probe"]
    environment:
      EDGEWEIR_STATE_DIR: /var/lib/edgeweir-probe
      EDGEWEIR_SERVER: https://cdn-admin.example.com:8443
      EDGEWEIR_CA_SHA256: <CA 指纹>
      EDGEWEIR_TOKEN: <注册令牌>   # 只在首次启动时使用
    volumes:
      - probe-state:/var/lib/edgeweir-probe
    healthcheck:
      disable: true
    restart: unless-stopped
volumes:
  probe-state:

systemd复制链接

edgeweir-node 的 deb、rpm 软件包含 edgeweir-probe.service（默认不启用），tar.gz 在 systemd/ 目录中提供同一单元。软件包依赖 edgeweir-openresty，探针模式不启动它；安装前按 SECURITY.md 校验发布物，探针主机不启用 edgeweir-node.service。

sudo tee /etc/default/edgeweir-probe >/dev/null <<'CONF'
EDGEWEIR_SERVER=https://cdn-admin.example.com:8443
EDGEWEIR_CA_SHA256=<CA 指纹>
EDGEWEIR_TOKEN=<注册令牌>
CONF
sudo chmod 600 /etc/default/edgeweir-probe
sudo systemctl enable --now edgeweir-probe
journalctl -u edgeweir-probe -f

命令行复制链接

EDGEWEIR_TOKEN=<注册令牌> edgeweir-node probe --server URL --ca-sha256 HEX [--server-name NAME] [--state-dir DIR]
edgeweir-node probe [--state-dir DIR]     # 已注册

参数也可由环境变量 EDGEWEIR_<参数名> 设置（如 --state-dir → EDGEWEIR_STATE_DIR），命令行优先。

注册与身份复制链接

下载镜像复制链接

节点访问 GitHub 受限时，控制台可在 /downloads/* 提供发布文件。镜像只是传输通道：签名与 SHA-256 仍在节点上校验。

目录结构：

downloads/
  edgeweir-node/
    latest                      # 版本号，例如 0.2.0
    v0.2.0/
      checksums.txt
      checksums.txt.sigstore.json
      edgeweir-node_0.2.0_amd64.deb
      edgeweir-node-0.2.0-1.x86_64.rpm
      edgeweir-node_0.2.0_linux_amd64.tar.gz
      edgeweir-openresty_1.31.1.1-2_amd64.deb
      edgeweir-openresty-1.31.1.1-2.x86_64.rpm
      edgeweir-openresty-modsecurity_1.31.1.1-2_amd64.deb
      edgeweir-openresty-modsecurity-1.31.1.1-2.x86_64.rpm
      ...
  cosign/
    v3.1.3/
      cosign-linux-amd64
      cosign-linux-arm64

启用步骤（compose.yml）：

1. 将 edgeweir-node 发布页的文件按上述结构放入 /opt/edgeweir/downloads。

2. 在 compose.yml 的 console 服务取消 volumes 注释：./downloads:/srv/edgeweir-downloads:ro。

3. 在 .env 设置 EDGEWEIR_DOWNLOADS_DIR=/srv/edgeweir-downloads，执行 docker compose up -d。

4. 验证：

   复制

   curl -s https://cdn-admin.example.com/downloads/edgeweir-node/latest

   预期：输出版本号。

节点 agent 自升级使用的发布源在 系统设置 → 节点发布源 配置，与本镜像无关，见 节点升级。

排障复制链接