前置机数据网关 · 安装部署手册

≡ 目录

按顺序从上到下即可完成安装与上线；点任意条目可直接跳到对应章节。

· 它是什么，装在哪 1 在哪下载 2 Windows 安装 3 Linux 安装 4 配置说明 5 装完怎么验收 · 设备激活 6 日常运维 7 常见问题

i 它是什么，装在哪

前置机是院内唯一同时通内网与外网的那台电脑。网关就装在它上面，站在采集盒和云中台之间：向内收盒子数据，向外转发云中台，并让盒子保持可升级、可对时。

🐝

采集盒 ×N

院内网 · 只连前置机

→POST 数据

🖥️

前置机网关

落盘队列 + 转发

→按接口转发

☁️

云中台

上游数据需求方

网关同时向 运维服务器 心跳并自动对时、反代盒子 OTA 固件下载——盒子端零改动，只把上报/OTA 地址指向网关。

📥可靠不丢数

写盘 fsync 成功才回执，断点续传；医院接口挂了本地排队，恢复后按序补发，at-least-once。

🔌盒子零改动

盒子照常上报，只把地址指向网关（多数靠局域网发现自动指向）。OTA 与固件下载由网关反代。

🕐自动对时

网关对运维服务器（公网权威时钟）应用层对时，再下发给盒子，保证治疗记录时间戳准确。

🛠️装完即服务

Linux systemd / Windows 原生服务：开机自启、崩溃自动重启、自带 Web 控制台看板。

1 在哪下载

当前版本 v0.4.97。按前置机的操作系统选一个下载。Windows 电脑推荐第一个「图形化安装向导」。

★ 推荐 · 图形向导

🪟Windows · 安装向导

hd-gateway-setup.exe · 约 4 MB · Win10/11 / Server 2019+

单个安装程序，双击一路「下一步」：填几个配置项即自动装服务、开防火墙、开时间同步。

⬇ 下载安装向导或下载 PowerShell 脚本包 (.zip) →

🐧Linux · 一键脚本包

gateway-pack-linux.tar.gz · 约 2.6 MB · Ubuntu 24.04 / Debian 13 (x86_64)

解压后一条 sudo ./install-gateway.sh 交互式装好 systemd 服务，回车即取默认。

⬇ 下载 Linux 脚本包

🪟Windows 安装步骤前置机是普通 Windows 电脑，选这里 🐧Linux 安装步骤前置机是 Ubuntu / Debian 服务器

2 Windows 安装

三种装法，从图形向导到手动。装完都会注册成 Windows 服务（services.msc 可见、开机自启、崩溃自动重启），无需 NSSM 等第三方工具。

脚本方式二 · PowerShell 一键脚本包（.zip）

下载 gateway-pack-win.zip，解压，在管理员 PowerShell 里跑安装脚本。适合喜欢命令行或要批量预填配置的场景。

管理员 Windows PowerShell

# 1. 解压 zip 后，cd 进目录，然后：
PS> Set-ExecutionPolicy -Scope Process Bypass -Force
PS> .\install-gateway.ps1
# 交互式逐项问，回车取默认。也可先设环境变量预填、免交互：
PS> $env:GW_ID='gw-hosp01'; $env:HOSP_URL='https://云中台/上报'
PS> $env:VENDOR='https://fc.admin.yijiangsoft.com'; .\install-gateway.ps1

✓ 二进制 -> C:\ProgramData\hd-gateway\hd-gateway.exe (v0.4.97)
✓ 配置 -> C:\ProgramData\hd-gateway\gateway.json
✓ 已启用系统时间同步（Windows Time）作时钟兜底
✓ /status 可访问（网关已就绪）
== 完成 ==  控制台: http://192.168.1.20:9090/   admin 密码: Xf7k9Qm2Ab3C

一定要「管理员身份」运行 PowerShell。注册服务、开防火墙、配时间同步都需要管理员权限，否则会静默失败。

手动方式三 · 手动注册（等价）

把配置放好后，用 exe 自带的服务命令注册即可：

管理员 PowerShell

PS> & "C:\ProgramData\hd-gateway\hd-gateway.exe" install -c "C:\ProgramData\hd-gateway\gateway.json"
PS> Get-Service hd-gateway          # 查看服务状态
PS> Restart-Service hd-gateway      # 重启 / Stop-Service 停止

防火墙：若控制台打不开，检查 Windows 防火墙是否放行 9090 端口的院内入站（安装向导会自动放行，手动/脚本装法请确认）。

3 Linux 安装

目标系统 Ubuntu Server 24.04 LTS 或 Debian 13（x86_64）。一键脚本会建目录、装二进制、生成配置、注册 systemd 服务并开启系统 NTP 兜底。

把脚本包传到前置机

scp 或 U 盘均可，然后解压。

进目录执行一键安装

sudo ./install-gateway.sh，交互式逐项问，回车取默认。

记下控制台地址与 admin 密码

脚本末尾会打印。

前置机终端 · bash

$ tar xzf gateway-pack-linux.tar.gz && cd gateway-pack
$ sudo ./install-gateway.sh
== 医院前置机网关一键装机 ==
  # 首次安装，逐项问（回车取默认）：
  网关 id (gateway_id) [hosp-frontend]: gw-hosp01
  云中台上报地址 (hospital.url) [...]: https://云中台/上报
  运维服务器 (vendor_server，对时源) [https://fc.admin.yijiangsoft.com]: ↵
  网关对盒子可达地址 (advertise_addr) [http://192.168.1.20:9090]: ↵
  控制台密码 (admin_pass，回车自动生成) [Xf7k9Qm2Ab3C]: ↵
✓ 二进制 -> /opt/hd-gateway/hd-gateway (v0.4.97)
✓ 配置 -> /opt/hd-gateway/gateway.json
✓ 已启用系统 NTP（systemd-timesyncd）作时钟兜底
== 自检 ==  服务状态: active
✓ /status 可访问（网关已就绪）
== 完成 ==  控制台: http://192.168.1.20:9090/   admin 密码: Xf7k9Qm2Ab3C

批量 / 免交互：用环境变量预填即可一行装完，适合脚本化多台前置机：
GW_ID=gw-hosp01 HOSP_URL=https://云中台/上报 VENDOR=https://fc.admin.yijiangsoft.com sudo -E ./install-gateway.sh

幂等升级：再次运行 install-gateway.sh 会保留已有 gateway.json 不覆盖，只换二进制并重启服务——升级新版直接重跑即可。

4 配置说明

安装时问的每一项都对应配置文件里的一个键。配置文件位置：Linux /opt/hd-gateway/gateway.json、Windows C:\ProgramData\hd-gateway\gateway.json（含明文密码，已收紧权限）。改完重启服务生效。

配置项	安装时怎么填	说明
`gateway_id`必填	网关在后台的名字，如 `gw-hosp01`	一家医院一个，用于后台识别与心跳。
`hospital.url`必填	云中台上报地址	数据最终转发到的接口地址（上游数据需求方）。留空则只落盘不转发。
`hospital.adapter`	默认 `hospital_v1`	对接哪套云中台接口的适配器；换新版接口用 `hospital_v2`。
`vendor_server`	运维服务器地址（对时源）	网关自动对时的权威时钟来源。离线医院可留空，此时必须配好前置机系统 NTP 兜底。
`advertise_addr`必填	盒子可达的网关地址，安装时自动探测	形如 `http://192.168.1.20:9090`，盒子据此下载固件。多网卡时确认填的是盒子那侧网段。
`admin_pass`	控制台密码，可自动生成	后台写操作密码。留空=控制台只读（任何修改都会被拒）。
`require_activation`	默认 `true`	激活门禁：开启时未激活的设备数据不转发（防私自加机）。不用授权就设 `false`。
`listen`	默认 `:9090`	监听端口，全网统一 9090。防火墙需放行院内入站。
`queue_dir`必填	脚本自动设为数据目录	磁盘队列目录，务必在持久盘上（断点续传靠它）。
`vendor_token`可选	一般留空	治疗状态同步令牌，仅当运维后台配了对应令牌时才填。

设备映射台账（mapping.json）不用手写：盒子上电后在控制台「待激活」页逐台激活时，机构 / 设备信息就落进台账了。见下一节。

5 装完怎么验收

浏览器打开控制台 http://前置机IP:9090/，对着这三条勾一遍，一家医院就上线了。

对时绿灯

概览页「本机钟 vs 运维服务器」一行是绿的（synced、偏差小）= 对时链路通。

盒子上电、数据涨

采集盒接通后，概览的「已接收」计数开始增长，设备出现在「待激活」列表。

逐台激活

在「待激活」页给每台盒子填床号 / 设备类型 / 医保 SN 等并激活，激活后数据才转发云中台。

前置机网关 Web 控制台概览（真实截图） — 网关自带的 Web 控制台概览（**真实截图**）：顶部标签「概览 / 待激活 / 已激活台账 / 配额」，对时绿灯、累计收到与转发成功计数、剩余可激活配额、以及各采集盒最近上报，一屏可读。

设备激活与授权码

控制台顶部四个标签就是激活相关的操作台：

概览

整体运行状态：对时、收发计数、队列积压、剩余配额、各盒最近上报。

待激活

新上电、尚未入册的盒子会出现在这里（按物理 MAC 识别）。逐台点「激活」，填床号 / 设备类型 / 设备型号 / 医保 SN 等即可入册。

已激活台账

已入册设备的清单，可编辑或解绑。

配额

登记「授权码」的地方。授权码由云端签发、网关离线验签，登记一次即产生对应数量的「可激活配额」；激活设备时自动从有余量的授权码里扣一台。概览页右侧「剩余可激活配额」实时显示余量。

为什么要激活？配置项 require_activation=true 时，只有激活过的设备数据才会转发云中台——防止未授权设备私自接入。不需要这道门禁时，把它设为 false 即全部放行。

对接不同云中台：适配器

数据按哪套云中台接口转发，由 hospital.adapter 决定：hospital_v1 / hospital_v2 对应两套上报接口，mock / passthrough 用于联调。对接方明确后在配置里改这一项即可，无需改动盒子。

盒子怎么指向网关？

多数情况盒子零配置——网关会在院内网广播发现信标，盒子上电后自动把上报 / OTA 地址指向网关。跨网段或需手动时，用现场助手的采集配置，把上报地址填成 http://前置机IP:9090/ingest 即可。

6 日常运维

启停、看日志、升级、卸载的常用命令。

Linux

bash

# 查看状态 / 启停
$ systemctl status hd-gateway
$ systemctl restart hd-gateway
# 实时日志
$ journalctl -u hd-gateway -f
# 升级：重跑安装脚本（保留配置换二进制）
$ sudo ./install-gateway.sh
# 卸载（--purge 连数据一起删）
$ sudo ./uninstall-gateway.sh

Windows

管理员 PowerShell

# 查看状态 / 启停
PS> Get-Service hd-gateway
PS> Restart-Service hd-gateway
# 日志看「事件查看器」，或前台调试：
PS> & "$env:ProgramData\hd-gateway\hd-gateway.exe" `
      -c "$env:ProgramData\hd-gateway\gateway.json"
# 升级：重装向导 / 重跑 install-gateway.ps1（保留配置）
# 卸载
PS> .\uninstall-gateway.ps1

网关能远程自动升级。装到 v0.4.7+ 后，运维中台发布新版清单，网关会定时拉取、校验、原地替换并重启，带确认窗口与崩溃自愈回滚——1000 台前置机不用逐台上门。首次仍需手动装一次。

7 常见问题

前置机该选 Windows 还是 Linux？

用医院现成的那台就行——两个版本功能一致。医院前置机常是 Windows，直接用图形化安装向导即可；若是机房里的 Ubuntu/Debian 服务器，用 Linux 脚本包。硬性要求：x86_64、能同时连院内网（盒子侧）和外网（云中台 / 运维服务器）、有一块持久盘放队列。

控制台打不开 / 打不开 9090？

先确认服务在跑（Linux systemctl status hd-gateway、Windows Get-Service hd-gateway）。再确认防火墙放行了 9090 院内入站——安装向导会自动放行，PowerShell/手动装法需自己确认。用 http://前置机IP:9090/ 访问，别用外网地址。

「本机钟 vs 运维服务器」不是绿的？

说明网关连不到 vendor_server（运维服务器）。检查前置机能否访问该地址；若这家医院不出公网，把对时源留空是允许的，但必须配好前置机系统自身的 NTP（Windows Time / chrony 对院内 NTP 或公网时间服务器）作兜底，否则盒子和治疗记录时间会漂。

盒子上电了，但「已接收」不涨？

①确认盒子和前置机在同一二层网段（发现信标靠多播）；②跨网段时用现场助手手动把盒子上报地址填成 http://前置机IP:9090/ingest；③检查前置机 9090 入站防火墙。数据到了但没转发云中台，多半是设备还没在「待激活」页激活（require_activation=true 时未激活不转发）。

云中台接口暂时挂了，数据会丢吗？

不会。网关把收到的数据先写盘排队（fsync 成功才给盒子回执），云中台不可用时本地积压，恢复后按序补发，保证 at-least-once 不丢数。概览页的「队列积压」会临时上涨，恢复后回落。默认队列上限 4GB，超限才丢最老数据。

升级网关会中断数据吗？

升级只重启网关服务，重启期间盒子的上报会短暂积压在盒子侧、恢复后补上，不丢数。Linux 重跑安装脚本、Windows 重装向导都会保留原配置只换程序。装到较新版本后还支持由运维中台远程推送、网关自动升级（带回滚保护）。

院内一台前置机，
把采集盒数据可靠汇聚 · 转发云中台。