移动网关安装与配置
Sight 移动网关的下载、安装、与 SightReport 对接、服务注册、升级、配置项、端口规划与排障。适用于外网连不进内网、只允许内网往外连的现场。
概述
Sight 移动网关是一个单文件程序，部署在手机能访问到的机器上（DMZ 前置机、云主机等）。内网的 SightReport 主动连出到网关，建立一条加密隧道；手机访问网关，请求经隧道转回 SightReport。
手机 ──https──▶ [Sight 移动网关] ◀══ 加密隧道（SightReport 从内网主动连出）══ SightReport
└─▶ 钉钉 / 飞书 / 企业微信接口（由网关代发，出口 IP = 网关）
它解决两件事：
- 前置机连不进内网时，外网手机也能使用移动端，内网不需要开任何入站端口；
- 内网服务器不能上外网时，免登和消息推送需要的钉钉 / 飞书 / 企业微信接口由网关代为访问，平台白名单里登记网关的公网 IP 即可。
网关只放行移动端路径（/m、/mapi 和根目录的域名校验文件），PC 端、设计器和管理接口在外网一律不可见。网关不保存任何业务数据。
三种外网接入方式怎么选，见移动端网络部署。
下载
在官网「下载中心」的「Sight 移动网关」分类下，按网关机器的系统下载对应的包：
| 下载项 | 适用系统 |
|---|---|
| Sight 移动网关 · Linux x86_64 | x86_64 架构 Linux（含麒麟、统信 x86 版） |
| Sight 移动网关 · Linux ARM64 | ARM64 架构 Linux（鲲鹏、飞腾等） |
| Sight 移动网关 · Linux 龙芯 | 龙芯 LoongArch64 架构 Linux（新世界 ABI） |
| Sight 移动网关 · Windows | Windows Server 2016 及以上、Windows 10 / 11（64 位） |
网关版本号与 SightReport 一致，请下载与 SightReport 相同版本的网关。解压后目录里只有可执行文件 sight-mobile-gateway（Windows 为 sight-mobile-gateway.exe）和一份 README.md，不需要安装 Java 或其它运行库。
操作步骤
以下以 Linux 为例；Windows 用管理员身份打开命令行，把命令里的 ./sight-mobile-gateway 换成 sight-mobile-gateway.exe。
准备 SightReport
- 在 SightReport 的
application.yml设置移动端独立端口sight.mobile.port，重启。详见移动端网络部署。 - 确认 SightReport 所在机器能访问到网关机器的隧道端口（默认 7443）。
初始化网关
- 把下载的 zip 拷到网关机器并解压，进入解压目录。
- 执行初始化，
-hostnames填 SightReport 访问网关时使用的域名或 IP，多个用逗号分隔：./sight-mobile-gateway init -hostnames dmz.example.com,203.0.113.10 - 命令会在同目录生成配置文件
gateway.yaml和隧道证书data/tunnel.crt、data/tunnel.key，并打印「证书指纹」和「接入令牌」。记下这两项；以后可用./sight-mobile-gateway show再次查看。 - 按需编辑
gateway.yaml（文件里有中文注释），常改的是手机侧端口和 HTTPS 证书，见下文「配置项」。
在 SightReport 中对接
- 打开
移动 > 设置 >「网络与部署」，在「移动网关」里打开「启用移动网关」。 - 「网关地址」填
wss://dmz.example.com:7443/tunnel（主机必须是初始化时-hostnames里的某一项或网关机器的 IP）。 - 粘贴「接入令牌」和「证书指纹」，点右上角「保存」。
- 如需由网关代发钉钉 / 飞书 / 企业微信接口，在「钉钉 / 飞书 / 企业微信接口出站」选「经移动网关」。
注册为系统服务并启动
sudo ./sight-mobile-gateway install # Linux 注册为 systemd 服务，Windows 注册为 Windows 服务
sudo ./sight-mobile-gateway start
服务名为 sight-mobile-gateway，开机自动启动，异常退出会自动拉起。只想临时试用，也可以不注册服务，直接 ./sight-mobile-gateway run 前台运行。
验证
- 回到「网络与部署」，「连接状态」显示「已连接（2/2）」。
- 在「基础」页填写「对外访问地址」（手机访问网关的地址，如
https://m.example.com），打开「允许外网访问」，保存。 - 用「手机连通自检」的二维码扫码，显示「连接正常」并说明经过移动网关。
升级
- 下载与新版 SightReport 相同版本的网关包。
sudo ./sight-mobile-gateway stop，用新的可执行文件替换旧的。sudo ./sight-mobile-gateway start。
gateway.yaml 和 data/ 目录保留不动，令牌和证书指纹不变，SightReport 侧不用改。建议先升级 SightReport，再升级网关。
卸载
sudo ./sight-mobile-gateway stop
sudo ./sight-mobile-gateway uninstall
属性/参数说明
命令
| 命令 | 说明 |
|---|---|
init [-hostnames a,b] [-force] |
生成 gateway.yaml、隧道证书和接入令牌。配置已存在时需加 -force，会换新的令牌和指纹 |
show |
再次打印证书指纹和接入令牌 |
run |
前台运行（不带命令时默认就是它） |
install / uninstall |
注册 / 卸载系统服务 |
start / stop |
启动 / 停止系统服务 |
version |
查看版本号 |
所有命令都可以加 -c <路径> 指定配置文件，默认是可执行文件同目录的 gateway.yaml。
配置项（gateway.yaml）
| 属性 | 说明 | 取值/默认值 |
|---|---|---|
listen |
手机侧监听地址。直接对外提供 HTTPS 时常用 :443 |
默认 :8080 |
tls.cert_file / tls.key_file |
手机侧 HTTPS 证书（PEM，含证书链）。都留空为明文 HTTP，仅用于前面还有负载均衡做 HTTPS 的情况 | 默认空 |
trusted_proxies |
网关前面的负载均衡 / 反向代理的 IP 或 CIDR，只有它们转来的请求才采信 X-Forwarded-For |
默认空 |
max_body_bytes |
请求体上限（字节），超出返回 413 | 默认 20971520（20 MB） |
rate_limit.per_ip_per_minute |
单个 IP 每分钟请求数上限，超出返回 429；-1 关闭 |
默认 600 |
tunnel.listen |
隧道监听地址，路径固定为 /tunnel |
默认 :7443 |
tunnel.tls |
隧道是否加密（wss）。false 为明文，SightReport 会给出警告，仅限可信内网 |
默认 true |
tunnel.cert_file / tunnel.key_file |
隧道证书，默认是 init 生成的自签证书，也可换成正式证书 | 默认 data/tunnel.crt / data/tunnel.key |
tunnel.hostnames |
init 生成证书时写入的域名 / IP（本机全部 IP 和 localhost 自动加入） | init 时填写 |
tunnel.token |
接入令牌，机密。修改后要同步修改 SightReport 中的令牌 | init 生成 |
egress.enabled |
是否代发钉钉 / 飞书 / 企业微信接口 | 默认 true |
egress.allow |
允许代发的主机，必须完全一致，只允许 443 端口，解析到内网地址一律拒绝 | 默认 qyapi.weixin.qq.com、oapi.dingtalk.com、api.dingtalk.com、open.feishu.cn |
log.file |
日志文件；作为服务运行时建议配置，如 logs/gateway.log |
默认空（只输出到屏幕） |
log.max_size_mb |
日志超过该大小自动轮转，保留 3 份历史 | 默认 50 |
配置中的相对路径都相对 gateway.yaml 所在目录。修改配置后需要 stop 再 start。访问日志不记录查询串，令牌不会写进日志。
端口与防火墙
| 端口 | 谁访问它 | 防火墙 / 安全组 |
|---|---|---|
手机侧 listen（如 443） |
手机 | 对公网开放 |
隧道 tunnel.listen（默认 7443） |
只有 SightReport 所在机器 | 只允许 SightReport 的出口 IP 或内网网段访问，不要对公网开放 |
| 网关访问外部的 443 | 钉钉 / 飞书 / 企业微信 | 开启代发时放行到这几个域名的出站 443 |
SightReport 是主动连出，内网一侧不需要开放任何入站端口。隧道端口上的 GET /healthz 无需鉴权，只返回当前连接数 {"agents":n}，可用于监控探活。
示例
网关前面还有云负载均衡（负载均衡做 HTTPS，转发到网关 8080 明文端口，负载均衡内网网段 10.0.0.0/24）时，gateway.yaml 的相关部分：
listen: ":8080"
tls:
cert_file: ""
key_file: ""
trusted_proxies:
- 10.0.0.0/24
log:
file: logs/gateway.log
负载均衡需要带上 X-Forwarded-For 与 X-Forwarded-Proto: https。预期结果：网关日志与 SightReport 审计中看到的是手机的真实 IP，限流按每部手机分别计算。
注意事项
注意：接入令牌等同于隧道的钥匙，只填在 SightReport 里，不要外传。怀疑泄露时执行
init -force换新，并同步更新 SightReport。
注意：网关与 SightReport 之间的隧道协议有版本号，两边版本不一致时会拒绝连接（SightReport 提示「网关版本与本系统不兼容」），请保持同版本。
提示：Linux 下普通用户不能监听 1024 以下端口。用系统服务方式运行时以 root 启动；也可以对可执行文件执行
setcap cap_net_bind_service=+ep。
提示：集群部署时，每个 SightReport 节点都会各自连上网关，网关在全部连接间轮流分配请求；某个节点宕机不影响其它节点。
排障
| 现象 | 原因 | 解决方法 |
|---|---|---|
| 连接状态显示「接入令牌不正确」 | 令牌填错，或网关重新 init 过 | show 查看令牌后重新填写，注意不要带空格 |
| 连接状态显示「网关证书指纹与设置不一致」 | 指纹填错、换过证书，或中间有设备在解密 HTTPS | show 取最新指纹；排除中间设备 |
| 连接状态显示「连不上网关地址」 | 隧道端口被防火墙拦截、地址或端口错误、网关没启动 | 在 SightReport 机器上测试能否连到网关 7443 端口；检查网关服务状态与日志 |
| 连接状态显示「网关版本与本系统不兼容」 | 网关与 SightReport 版本不一致 | 下载与 SightReport 同版本的网关 |
| 手机打开提示「服务暂不可用」 | 没有 SightReport 连上网关 | 访问 /healthz 看 agents 是否为 0；检查「网络与部署」的连接状态 |
| 手机访问返回 504 | SightReport 60 秒内没有响应 | 检查 SightReport 的负载与日志 |
| 手机访问返回 404 | 访问了网关不放行的路径 | 移动端地址应为 对外访问地址/m/m.html |
| 手机访问返回 429 | 同一 IP 请求过于频繁；或前面有负载均衡但没配 trusted_proxies，所有手机被当成同一个 IP |
配置 trusted_proxies，必要时调大限流 |
| 钉钉 / 企业微信提示 IP 不在白名单 | 网关公网 IP 没登记 | 把网关机器的公网 IP 加到平台白名单；出站方式选「经移动网关」 |
| 网关日志提示解析到内网或保留地址、已拒绝 | 网关机器的 DNS 把平台域名解析成了内网地址 | 给网关机器配置能正常解析公网域名的 DNS |
| 启动时提示监听端口失败 | 端口被占用，或 Linux 普通用户监听 443 | 换端口，或按上面的提示授予权限 |
install / start 失败 |
权限不足 | Linux 用 sudo，Windows 用管理员命令行 |
