控制器和代理
状态、heartbeat、版本和操作都在项目内。
代理解决什么
访问服务，而不是整个网络
代理运行在现场常驻设备上并保持出站连接。本地 LAN 不对外开放。
访问边界
仅允许已保存的 host:port。
用户没有子网路由，也不能替换目标。
默认拒绝
注册后 LAN 保持关闭。先配置端口策略、ACL 和角色。
服务和设备
允许 IP:port 的工作列表，不绕过 ACL。
隧道和公开地址
稳定的 name.access.xyz.su 不受外部 IP 变化影响。
规则、地图和日志
记录谁访问、开放什么以及拒绝原因。
三种角色，一个 runtime
根据工作位置选择代理
一个 shd-agent 二进制，模式取决于运行位置。
01
Controller-agent
现场网络内。出站 TLS、heartbeat，仅访问已保存 TCP 目标。
02
User-agent
工程师电脑上。一个 QUIC 会话，并行承载 HTTP、SSH 和 TCP。
03
Server-agent
服务器上。按 route policy 提供 Gateway、Exit-node 和 speed test。
请求路径
从授权到第一个字节
服务器负责授权。数据优先 P2P，直连不可用时切换 relay。
01
用户或应用
Overlay、公开 endpoint 或 tunnel。
02
SHD 检查访问
用户、项目、服务、角色和代理版本。
03
P2P 或 relay
先用直接 QUIC，否则使用二进制 relay。
04
Controller-agent
仅向精确的 host:port 打开本地 TCP。
05
精确服务
HTTP、SSH 和 Loxone 保留自身认证。
P2P QUIC
流量直接在代理之间传输，Relay 看不到数据。
Relay fallback
NAT 或防火墙阻止 P2P 时，数据帧经过 relay。
每个代理一个 QUIC 会话 · 每个 TCP 连接一个独立 stream。
安全
不是 VPN，也不是开放的 LAN
项目权限不会打开网络。需要角色、端口和 ACL。
访问模型
每个请求的四个边界
项目提供上下文，策略定义服务，ACL 选择通行者。撤销立即关闭路径。
模块角色
读取代理不等于修改设置的权限。
访问端口策略
192.168.1.3:443 不会打开 :80 或邻近设备。
ACL 规则
用户或组、精确服务、allow/deny。
撤销与审计
会话立即关闭，所有操作写入日志。
运维边界
连接与运维工具
从安装代理到终端、路由和故障分析。
01
HTTP、HTTPS 和 WebSocket
已保存服务的 Web 界面和 API。
02
Terminal 和 SFTP
浏览器 SSH 不需要本地代理。SFTP 使用独立角色。
03
公开地址
name.access.xyz.su。应用登录和 ACL 仍然有效。
04
Overlay 与路由
Native L3 100.126.0.0/16。普通互联网路由不受影响。
05
Exit Network
按 route policy 从服务器代理 IP 释放流量。
06
Heartbeat 和 jobs
Push-first：sync、update、reboot；HTTP 作为备用。
投入运行
从安装到实际连接
先注册 runtime，再配置精确服务、权限并检查传输。
- 01
安装并注册
常驻设备、shd-agent、enrollment token。
- 02
等待 online
出站 TLS、heartbeat、服务列表。
- 03
保存需要的端口
仅添加必要目标：443、875、8123、22。
- 04
分配角色和规则
角色和 ACL，默认关闭 LAN。
- 05
打开并观察
Overlay 或 endpoint、首个响应和日志。
接入前
现场最重要的问题
简要说明 runtime 角色、数据路径、访问边界、终端和诊断。
什么是 shd-agent？
这是一个包含多个角色的 Go runtime。Controller-agent 运行在现场网络，user-agent 运行在工程师工作设备，server-agent 运行在带专用模块的服务器上。
需要 VPN 或入站端口吗？
不需要。Controller-agent 建立出站安全连接。用户只能访问已保存服务，而不是整个本地网络。
P2P 不可用时会怎样？
直接 QUIC 尝试失败后，user-agent 激活 relay fallback。第一个请求会被保留，数据通过 relay 和 controller-agent 以二进制帧传输。
可以覆盖整个子网吗？
不可以，这不是模块模型。访问必须是精确 service/host/port；broadcast、multicast、metadata、backend 和 relay 地址会被阻止，hostname 的每个解析 IP 都会检查。
可以打开哪些服务？
任何代理在本地可以访问且被明确保存的 TCP 服务：HTTP/HTTPS、WebSocket、SSH、Loxone、Home Assistant 和其他精确端口。
浏览器可以使用 terminal 吗？
可以。浏览器 SSH terminal 在手机或电脑上不需要本地 user-agent，但需要 terminal 角色、保存的 SSH 用户名和 credential；SFTP 还需要 sftp 角色。
什么是 Exit Network？
这是 server-agent 路径：Routing gateway 接收 route group，relay 将其连接到 Exit-node，Exit-node 从自己的 IP 向目标地址发送允许的流量。
如何快速撤销访问？
删除或修改规则、端口、endpoint 或角色。Backend 会关闭活动会话、更新代理 allowlist 并记录操作，不需要等待旧会话过期。
如何定位故障？
检查 controller-agent online、user-agent、route policy、代理到 target 的连通性、shd99 和 100.126.0.0/16。传输方面查看 p2p_first_byte、last_path、p2p_sent 和 relay_sent。
已经运行的现场可以接入吗？
可以。先检查网络、控制器、目标端口、服务方式和所需角色，再加入最小服务集合，不会自动访问剩余 LAN。
连接现场
设计访问边界
告诉我们需要远程维护哪些控制器、设备和操作。我们会梳理现场网络、runtime 角色、精确端口、传输方式和启动计划。
第一次沟通前可准备网络图、控制器清单、服务 host:port、terminal/SFTP 需求以及组织访问模型。