umbrad
公网入口
TLS 1.3 控制通道、服务端口监听、临时放行的内核丢弃、热升级，以及内置 Web 控制台与 API。控制台不是独立程序；界面以节点和服务为中心，带月食标识、明暗主题和中英文。
它解决什么
把内网服务接入公网，访问方式由你选择。
只转发 TCP 和 UDP，不处理 HTTP 路由，也不终止客户端业务流量的 TLS。公网入口与节点之间的控制和隧道连接使用 TLS 1.3。公开访问与临时放行下，客户端到入口的业务协议是否加密，取决于服务自身是否使用 SSH、HTTPS、TLS 等。入口是服务配置的数据源：变更经现有控制通道下发，节点应用后返回确认；重连后会重新同步当前配置快照。
组成
三个程序，一个控制平面。
umbra-node
内网节点
只主动连接入口。服务配置由入口统一管理，节点无需维护独立的服务配置文件。可注册为系统服务。
umbra-visit
访问端
使用控制台签发的访问凭证，在访问者本机打开 TCP 或 UDP 端口。该服务不在入口监听公网业务端口。
节点凭证默认 90 天，也可设为永不过期。访问凭证默认 24 小时，是持有者凭证，不是用户身份认证。均只显示一次，吊销在控制台。
访问方式
三种访问方式，按暴露面选择。
控制台新建服务默认凭证访问（visitor），不开放公网业务端口。公开服务需明确选择公开访问。API 省略 mode 时仍为 public。需要来源 IP 临时授权时选择临时放行。
入口不监听该服务端口。客户端用访问凭证在本机打开端口。控制台新建服务默认使用该方式。
扫描侧看到的
无公网服务端口
PORT STATE SERVICE 4400/tcp open control — — no listener
设计
服务配置由公网入口统一管理。
配置经控制通道下发
入口是服务配置的数据源。变更后通过现有控制通道向节点下发；节点应用配置并返回确认。重连后会重新同步当前配置快照。
升级不中断已有连接
入口可在运行中绑定或释放端口。更换程序后，已有隧道留在旧进程直到结束。
只做端口转发
转发 TCP 与 UDP。不解析域名，不终止客户端业务流量的 TLS，也不是七层反向代理。
未授权流量可被丢弃
Linux 上具备 nftables 与 CAP_NET_ADMIN 时，临时放行对未授权 IPv4 在内核丢包，扫描通常显示 filtered；否则回退为用户态拒绝，端口仍可能被识别。
探测与可观测
探测会通过公网入口 → 节点 → 本地目标发送实际探测数据，必须收到目标响应才算成功。配置就绪表示节点已确认配置，不代表目标服务或外网路径已验证。
跨入口复制配置
控制台可导出选中节点及其服务，再导入到另一台独立公网入口。不含节点凭证、证书私钥、管理认证、访问凭证或运行状态。导入先预览再写入；复制配置不会自动建立内网隧道，新节点仍需部署并连接当前入口。
部署
先启动入口，再登记节点。
推荐在 Linux 公网主机上用 Docker Compose。固定 0.3.0，不要使用 latest。
部署前准备
- 一台具有公网访问能力的 Linux 主机
- Docker 与 Docker Compose
- 节点能够访问公网入口的域名或 IP
- 开放 4400/TCP
- 如果使用独立 UDP 数据面，同时开放 4400/UDP
- 一台能生成六位 TOTP 的 Authenticator 应用
01
启动入口
克隆仓库，把 compose 里的对外地址改成节点真正能连上的那个，再启动。证书与状态保存在同一卷。
02
打开控制台
管理口默认只绑 127.0.0.1:8080。用 SSH 转发后在本机打开。首次访问会设定管理员口令、绑定 Authenticator，并展示只出现一次的恢复码；保存恢复码后才算完成初始化。不要把明文管理口暴露到公网。
03
登记节点
控制台按平台生成安装命令（systemd、launchd 或 Windows 服务）。凭证只显示一次，命令已内嵌入口证书。
04
添加并连接服务
控制台首页是节点。在节点内添加服务会自动选中当前节点，默认凭证访问。配置就绪表示配置已送达；探测必须收到目标响应才算成功。
05
跨入口复制配置
需要在多台独立公网入口之间复用节点和服务时，可在控制台导出后再导入。导出不是完整备份，不含凭证与认证状态。新建的目标节点仍须独立部署，并连接到当前这台入口。
入口（Linux host 网络）
git clone https://github.com/chenow9/umbra.git cd umbra UMBRA_TAG=0.3.0 docker compose -f deploy/compose.gate.yml up -d
打开控制台
ssh -L 8080:127.0.0.1:8080 [email protected]
节点（手动等价）
./umbra-node \ --server gate.example.com:4400 \ --tls-ca /etc/umbra/ca.crt \ --token umbra_boot_…
访问端 umbra-visit
umbra-visit --server gate.example.com:4400 \ --tls-ca /etc/umbra/ca.crt \ --ticket umbra_vis_… \ --local 127.0.0.1:2222
部署完成后，Web 控制台应显示节点在线。配置就绪表示配置已送达节点；探测必须收到目标响应，才可进一步确认转发链路。
平台
amd64 与 arm64。
Linux
临时放行的内核丢弃仅此平台
amd64 · arm64
macOS
临时放行在进程内断开
amd64 · arm64
Windows
可注册为系统服务
amd64 · arm64
Docker
需要 Linux 宿主机网络
amd64 · arm64
安全
控制台默认不绑定公网地址。
- 公网入口与节点之间的控制和隧道连接使用 TLS 1.3，节点必须信任入口证书。公开访问与临时放行下，客户端到入口的业务协议是否加密，取决于服务自身是否使用 SSH、HTTPS、TLS 等。
- 管理面默认 127.0.0.1；绑定非本机地址必须启用 TLS。不要把明文管理口暴露到公网。
- 控制台默认要求口令加 TOTP 或一次性恢复码。新安装必须绑定 Authenticator。解绑只能在入口本机执行 umbrad -reset-2fa。
- 不要把 TOTP 密钥、二维码、恢复码或迁移码发到聊天或日志。生产环境不要关闭 2FA，也不要使用会跳过控制台认证的选项。
- 临时放行是认证后来源 IP 的临时授权，不是设备或用户身份。共用同一公网出口 IP 的设备，在窗口内可能共享访问权限。
- 临时放行窗口过期只阻止新连接，不会主动断开已经建立的 TCP 连接或仍然活跃的 UDP 流。它不替代 SSH、TLS 或应用自身的认证。
- Linux 上具备 nftables 与 CAP_NET_ADMIN 时，未授权 IPv4 在内核丢弃，扫描通常显示 filtered；否则回退为用户态拒绝，端口仍可能被识别。
- 访问凭证是持有者凭证，默认 24 小时，获得凭证的人即可在有效期内使用。节点凭证默认 90 天，也可永不过期；均只显示一次。
- 控制台新建服务默认凭证访问，不开放公网业务端口。公开访问需明确选择。API 省略 mode 时仍为 public。
- 配置导出只复制节点和服务，不是完整备份，不含身份凭证或认证状态。升级前备份完整 tls-dir 并继续使用原目录。不要把它提交到仓库。