# OpsHub-Release **Repository Path**: fensnote/ops-hub-release ## Basic Information - **Project Name**: OpsHub-Release - **Description**: 云枢设备运维平台部署包 - **Primary Language**: Go - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 0 - **Created**: 2026-11-15 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 云枢设备运维平台(OpsHub) · 使用说明 版本适配:`opshub-svr-win` / `opshub-svr-linux-amd64-i386` / `opshub-svr-linux-arm` + `agent` 设备端 --- ## 1. 系统简介 OpsHub 是一套「设备集中接入 + 远程访问」系统。设备端部署在目标设备上,通过 WebSocket 隧道主动连接服务端;用户在浏览器里登录服务端,即可远程访问设备本地 Web 页面、执行命令、传输文件。 ``` 浏览器 ⇄ 服务端(HTTPS/WSS) ⇄ 设备端(WebSocket 隧道) ⇄ 设备本地 Web 服务 / Shell ``` 设备端只主动向外连接,不需要在设备上开放入站端口,适合内网设备、边缘网关等场景。 ### 1.1 软件界面 ![云枢设备运维平台主界面](opshub.png) 主界面自上而下分为四块:顶部授权状态徽标与用户菜单、在线 / 离线设备统计、搜索与批量脚本入口、设备列表(每台设备提供「终端 / WEB 页面 / 文件」操作入口)。 --- ## 2. 功能特性 | 功能 | 说明 | |---|---| | 设备管理 | 设备在线状态、名称、归属用户编码、最后在线时间一览 | | 远程 Web 访问 | 通过 `/proxy/{设备ID}/` 直接在浏览器访问设备本地 Web 页面 | | 远程终端 | 在页面中打开设备 Shell(WebSocket 实时回传) | | 批量脚本 | 选择多台设备执行脚本,实时输出,并保留历史脚本 | | 文件传输 | 向设备上传文件、从设备下载文件 | | 用户与权限 | 内置管理员/普通用户两种角色,用户编码(usercode)用于设备归属 | | 登录安全 | 图形验证码;同一 IP + 用户名连续 6 次失败锁定 10 分钟 | | 传输加密 | 服务端 HTTPS/WSS,自签证书 + 设备端证书指纹固定,防抓包与中间人 | | 授权管理 | 免费版最多 5 台在线设备;授权文件支持页面导入,导入后立即生效 | --- ## 3. 发布包结构 ### 3.1 服务端 | 目录 | 适用平台 | 主程序 | |---|---|---| | `opshub-svr-win` | Windows x64 | `opshub-svr.exe` | | `opshub-svr-linux-amd64-i386` | Linux x86_64 / x86 32 位 | `opshub-svr_amd64` / `opshub-svr_i386` | | `opshub-svr-linux-arm` | Linux ARM 32 位 | `opshub-svr_armv5` | 每个服务端目录包含: ``` opshub-svr* 服务端主程序 opshub.json 服务端配置文件 static/ 前端页面(index.html / login.html / terminal.html) certs/ TLS 证书目录(cert.pem / key.pem,由 deploy_tls 生成) deploy_tls.sh Linux 一键生成证书并写入配置 deploy_tls.ps1 Windows 一键生成证书并写入配置 start.bat Windows 启动脚本 opshub.service Linux systemd 服务模板 license.dat 授权文件(如有,与主程序同目录即可生效) ``` > `certs/`、`machine.id`、`info.db`、`license.dat` 都是**运行时文件**:首次启动或在客户现场生成,不需要事先准备。 ### 3.2 设备端(`agent` 目录) | 文件 | 适用平台 | |---|---| | `opshub-agent.exe` | Windows x64 | | `opshub-agent_linux_amd64` | Linux x86_64 | | `opshub-agent_linux_i386` | Linux x86 32 位 | | `opshub-agent_linux_arm64` | Linux ARM64 | | `opshub-agent_linux_armv5` | Linux ARM 32 位(ARMv5 及以上) | | `opshub.json` | 设备端默认配置(需按现场修改) | --- ## 4. 部署前准备 1. **操作系统**:Windows x64,或常见 Linux 发行版(x86_64 / i386 / ARM)。 2. **端口**:服务端默认监听 `0.0.0.0:8080`,需在防火墙放行;如需外网访问,建议配合反向代理或端口映射。 3. **安装目录**:建议固定目录,避免移动后授权指纹变化: - Linux:`/usr/local/opshub` - Windows:`C:\opshub` 4. **写权限**:安装目录必须可写,服务端会在其中生成 `machine.id`、`info.db`、`license.dat`。 5. `static/` 目录必须与主程序放在一起,且**启动时的工作目录就是该目录**,否则页面会 404。 --- ## 5. 服务端部署 > **TLS 证书推荐在管理页面生成**:配置模板中的 `cert_file/key_file` 默认留空,首次启动后通过 `http://服务器IP:8080/` 使用 admin 登录,点击顶栏「TLS 证书」,填写实际访问 IP / 域名并生成,然后重启服务端并改用 HTTPS。下文的 `deploy_tls` 脚本是启动前或自动化部署的命令行方式,两种方式二选一即可。1.2.5 起重新生成证书后可直接点击「下发到所有在线设备」,设备自动切换并重连,再点「立即启用」热加载证书;10 分钟内未连上的设备自动回退旧指纹,离线设备仍需人工更新 `tls_pin`。 ### 5.1 Windows 1. 将 `opshub-svr-win` 整个目录复制到 `C:\opshub`。 2. 编辑 `opshub.json`(见 5.3),务必修改 `device_token` 与 `jwt_secret`。 3. 生成自签证书:`powershell -ExecutionPolicy Bypass -File .\deploy_tls.ps1`(自动生成 `certs/` 并写回 `opshub.json`)。 4. 双击 `start.bat`,或在该目录打开命令行执行: ```bat opshub-svr.exe -c opshub.json ``` 5. 首次启动会自动创建 `info.db`(SQLite 数据库)与 `machine.id`(机器指纹),控制台会打印监听地址、授权状态与机器指纹。 6. 浏览器访问 `https://服务器IP:8080/`,首次会提示证书不受信任,选择「继续访问」即可。 > 需要开机自启时,可用「任务计划程序」创建开机任务(**起始位置**设为 `C:\opshub`),或用 nssm 注册为 Windows 服务。 ### 5.2 Linux 以下以 `amd64` + systemd 为例: ```bash # 1. 创建目录并解压 mkdir -p /usr/local/opshub # 将发布目录内文件上传到 /usr/local/opshub # 2. 按架构选用主程序,并统一改名为 opshub-svr cd /usr/local/opshub mv opshub-svr_amd64 opshub-svr # x86_64 # 32 位 x86 用:mv opshub-svr_i386 opshub-svr # ARM 用:mv opshub-svr_armv5 opshub-svr chmod +x opshub-svr deploy_tls.sh # 3. 生成自签证书(自动写回 opshub.json),然后前台试运行 ./deploy_tls.sh ./opshub-svr -c opshub.json # 4. 注册为系统服务 cp opshub.service /etc/systemd/system/ systemctl daemon-reload systemctl enable --now opshub-svr journalctl -u opshub-svr -f ``` 防火墙放行示例: ```bash # firewalld firewall-cmd --add-port=8080/tcp --permanent && firewall-cmd --reload # ufw ufw allow 8080/tcp ``` > `opshub.service` 中默认工作目录为 `/usr/local/opshub`,如部署到其他路径,请同步修改 `WorkingDirectory` 与 `ExecStart`。 ### 5.3 服务端配置文件 `opshub.json` 服务端默认读取**工作目录下的 `opshub.json`**,也可以用 `-c` 指定其他路径。 | 字段 | 默认值 | 说明 | |---|---|---| | `listen` | `0.0.0.0` | 监听地址;只允许本机访问可改为 `127.0.0.1` | | `port` | `8080` | 监听端口 | | `device_token` | 示例值 | 设备接入令牌,必须与设备端 `device_token` 一致;为空表示不校验(不建议) | | `jwt_secret` | 示例值 | 登录 Token 签名密钥,**必须修改**;修改后已登录用户需重新登录 | | `cert_file` | 空 | TLS 证书路径,页面生成后自动写入;与 `key_file` 同时配置才启用 HTTPS/WSS | | `key_file` | 空 | TLS 私钥路径,页面生成后自动写入 | 示例: ```json { "listen": "0.0.0.0", "port": 8080, "device_token": "请改成随机字符串", "jwt_secret": "请改成另一串随机字符串", "cert_file": "", "key_file": "" } ``` 命令行参数优先级高于配置文件: | 参数 | 说明 | |---|---| | `-c <路径>` | 指定配置文件(默认工作目录 `opshub.json`) | | `-host <地址>` | 监听地址 | | `-port <端口>` | 监听端口 | | `-device-token <令牌>` | 设备接入令牌(空=不校验) | | `-cert <证书>` / `-key <私钥>` | 启用 HTTPS/WSS | | `-fingerprint` | 打印本机机器指纹后退出(申请授权用) | | `-license-info` | 打印当前授权状态后退出 | ### 5.4 Docker 部署(可选) 如使用容器方式部署,请联系供应商获取专用镜像与编排文件。部署时注意: | 项 | 说明 | |---|---| | 数据卷 | 配置、数据库、机器指纹、授权与证书都放在同一个数据卷,**不要删除**,否则机器指纹变化需重新授权 | | 端口 | 容器内监听 `0.0.0.0:8080`,建议只映射到宿主机 `127.0.0.1:8080`,公网入口交给 Nginx(见 11.1) | | 时区 | 设置 `TZ=Asia/Shanghai`,审计日志时间才与本地一致 | | 授权文件 | 把 `license.dat` 复制进数据卷后重启容器生效 | | 备份 | 直接打包整个数据卷目录即可 | --- ## 6. 登录与用户管理 - 登录地址:未启用 TLS 时为 `http://服务端IP:8080/`,生成证书并重启后为 `https://服务端IP:8080/` - 初始管理员:`admin` / `admin123`,**首次登录后请立即修改密码** - 登录需要输入图形验证码;同一 IP + 用户名连续失败 6 次会锁定 10 分钟 - 用户可在「用户管理」中新增,每个用户都有唯一 `usercode`,设备接入时必须填写已存在的 `usercode` | 角色 | 权限 | |---|---| | `admin` | 全部功能,含用户管理、导入授权 | | `user` | 设备查看/访问、终端、脚本、文件传输等日常操作 | ### 6.1 操作日志(审计) 仅管理员可用:点击顶栏 **📋 操作日志**。系统会把关键操作写入 `info.db` 的 `audit_log` 表,用于事后追溯: | 类型 | 记录内容 | |---|---| | 登录认证 | 登录成功、登录失败、连续失败触发锁定、退出登录 | | 设备 | 接入被拒(令牌错误 / 用户编码不存在 / 超出授权台数);设备上下线不记录 | | 用户管理 | 新增用户、删除用户、重置密码、修改用户编码 / 名称、修改本人密码 | | 脚本 | 执行批量脚本(设备数量、设备列表、超时、脚本内容摘要) | | 文件 | 上传文件、下载文件(设备、路径、大小) | | 终端 | 打开远程终端(设备、窗口尺寸) | | 授权 | 导入授权、设备超限被系统断开 | | TLS 证书 | 生成证书(适用地址、有效期、是否覆盖、新指纹) | | 审计 | 导出操作日志、修改审计保留天数 | - **保留期**:授权版默认保留 **180 天(半年)**,管理员可在「操作日志」弹窗中调整为 7 ~ 3650 天,保存后立即清理超期记录;免费版固定 **60 天**,不支持修改。服务每小时自动清理一次过期记录。 - **筛选**:日期区间、用户名 / 用户编码、类型、关键字(操作 / 对象 / 详情),每页 50 条。 - **导出 Excel**:筛选栏右侧的「导出 Excel」按**当前筛选条件**导出(不是只导当前页),文件名形如 `audit-20261115-153000.xlsx`。是真正的 Excel 表格,表头加粗、冻结首行、列宽已调好,打开即可用;单次最多 5 万条,超出请缩小时间范围分批导出。 - **来源 IP**:经过 Nginx 等反向代理时,只要代理传了 `X-Real-IP` / `X-Forwarded-For`,记录的就是真实客户端 IP(配置见 11.1)。 - 审计数据随 `info.db` 一起备份即可;导出的 Excel 建议另存归档。 --- ## 7. 设备端部署 ### 7.1 选择对应架构的程序 | 目标设备 | 使用文件 | |---|---| | Windows x64 | `opshub-agent.exe` | | Linux x86_64 | `opshub-agent_linux_amd64` | | Linux x86 32 位 | `opshub-agent_linux_i386` | | Linux ARM64 | `opshub-agent_linux_arm64` | | Linux ARM 32 位 | `opshub-agent_linux_armv5` | ### 7.2 设备端配置文件 `opshub.json` 设备端默认读取 `/work/opshub.json`(Windows 为 `C:\work\opshub.json`),建议始终用 `-c` 显式指定。 | 字段 | 说明 | |---|---| | `server` | 服务端地址,TLS 开启时用 `wss://IP:8080/ws` | | `tls_pin` | 服务端证书 SHA-256 指纹(管理页面或 `deploy_tls` 显示的 64 位小写十六进制) | | `device_token` | 与服务端 `device_token` 一致 | | `usercode` | 归属用户编码,**必填**,必须是服务端已存在的用户 | | `id` | 设备唯一 ID,不能与其他设备重复 | | `name` | 页面显示名称 | | `host` / `port` | 设备本地 Web 服务的 IP 与端口(默认 `127.0.0.1:80`) | | `path` | 设备本地 Web 服务基础路径(默认 `/`) | 示例: ```json { "server": "wss://192.168.1.100:8080/ws", "tls_pin": "管理页面或 deploy_tls 显示的 64 位指纹", "device_token": "与服务端 device_token 一致", "usercode": "10001", "id": "site-a-gateway-01", "name": "A 站点网关", "host": "127.0.0.1", "port": 80, "path": "/" } ``` 注意:JSON 键名是下划线形式 `tls_pin`,写成 `tls-pin` 不会生效(`tls-pin` 只是命令行参数名)。 ### 7.3 启动方式 ```bash # Linux chmod +x opshub-agent_linux_amd64 ./opshub-agent_linux_amd64 -c /work/opshub.json ``` ```bat :: Windows opshub-agent.exe -c C:\work\opshub.json ``` 命令行参数:`-c` 配置文件、`-server`、`-id`、`-name`、`-token`、`-usercode`、`-host`、`-port`、`-path`、`-tls-pin`、`-tls-insecure`。 Linux 常驻示例(`/etc/systemd/system/opshub-device.service`): ```ini [Unit] Description=OpsHub Agent After=network-online.target Wants=network-online.target [Service] Type=simple ExecStart=/opt/opshub/opshub-agent_linux_amd64 -c /opt/opshub/opshub.json Restart=always RestartSec=10 User=root [Install] WantedBy=multi-user.target ``` ### 7.4 验证接入 1. 服务端日志出现 `[设备接入] id=... name=... usercode=...` 2. 登录管理页面,设备列表中该设备显示在线 3. 点击设备即可访问 `/proxy/{设备ID}/`,或在终端页打开 Shell --- ## 8. 授权说明 ### 8.1 授权版与免费版的区别 | 项目 | 免费版(未导入授权) | 授权版 | |---|---|---| | 同时在线设备 | 最多 **5 台**,第 6 台接入被拒绝 | 按授权文件的设备数放行;设备数为 `0` 表示不限 | | 有效期 | 长期可用,无需续期 | 按授权到期时间;永久授权无到期时间 | | 功能范围 | 与授权版一致:Web 页面代理、远程终端、文件传输、批量脚本、用户管理、操作日志 | 同左,无功能裁剪 | | 审计保留期 | 固定 60 天,不可修改 | 默认 180 天,管理员可调整为 7 ~ 3650 天 | | 状态显示 | 顶栏徽章显示「免费版」 | 顶栏徽章显示客户名称、设备数与到期时间 | | 到期或降级后 | — | 回到免费版配额,超出 5 台的设备被断开并提示「设备数量已达上限」 | | 更换服务器 / 安装目录 | 不受影响 | 机器指纹变化,需重新签发授权 | ### 8.2 授权管理 - 未导入授权时为**免费版**,最多同时在线 **5 台**设备。 - 查看当前机器指纹(申请授权时需要): ```bash ./opshub-svr -fingerprint ``` 也可以直接看启动横幅里的「机器指纹」,或在页面「授权导入」弹窗中查看。 - 导入授权的两种方式: 1. **页面导入(推荐)**:管理员登录后点击顶栏「授权状态」徽章 → 选择 `license.dat` 或粘贴内容 → 「导入并生效」。校验通过后**立即生效,无需重启**;校验失败会给出原因,且不会影响原有授权。 2. **文件放置**:把 `license.dat` 放到服务端主程序同目录,重启服务端或等待下一次定时校验后生效。 - 授权与机器指纹绑定,更换服务器/安装目录/重装系统都可能导致指纹变化,需要重新申请授权。 - 授权到期或降级后,超出配额的设备会被断开并提示「设备数量已达上限」。 - 查看授权状态:`./opshub-svr -license-info`。 --- ## 9. 容量与性能参考 ### 9.1 接入能力(实测) | 指标 | 实测结果 | |---|---| | 并发设备隧道 | 500 / 1000 / 1500 条 TLS 长连接全部建立成功(1500 条约 6 秒) | | 单连接占用 | 空闲隧道约 30–40 KB 内存,1 万台在线设备约 300–400 MB | | 接口吞吐 | 单机约 1.5 万请求/秒(设备列表等读接口,多并发压测) | | 管理页面 | 页面每 3 秒轮询一次设备列表,按 1/3 余量规划,单机可支撑约 1.5 万个在线页面 | | 静态页面 | 单机 2300–4800 请求/秒(约 35 MB/s) | ### 9.2 服务器配置建议 | 规模 | 同时在线设备 | 建议配置 | 说明 | |---|---|---|---| | 小型 | ≤ 50 台 | 2 核 / 4 GB / 50 GB 磁盘 | 单机部署,普通虚拟机即可 | | 中型 | ≤ 500 台 | 4 核 / 8 GB / 100 GB 磁盘 | 建议 SSD;审计保留 180 天 | | 大型 | ≤ 2000 台 | 8 核 / 16 GB / 200 GB 磁盘 | 建议配合 Nginx 反向代理与定期备份 | - 设备隧道虽然是长连接,但流量很小,服务端 CPU / 内存主要消耗在浏览器页面轮询、审计查询与文件传输上。 - 带宽:设备空闲时只有心跳;远程终端、文件传输、Web 页面代理的实际带宽取决于两端网络与同时操作的人数。 - 磁盘:`info.db` 随设备数量、脚本历史与审计记录增长,建议定期备份并预留空间。 - 规模超过上表或并发很高时,建议先按实际规模试运行,观察 CPU、内存、带宽水位后再扩容。 --- ## 10. 常见问题 | 现象 | 可能原因 | 处理 | |---|---|---| | 设备反复重连,服务端无接入日志 | `tls_pin` 与当前证书不一致;`server` 地址/端口错误;防火墙拦截 | 重新执行 `deploy_tls` 获取最新指纹并同步到所有设备;确认 `wss://` 与端口 | | 服务端日志提示 usercode 不存在 | 设备填写的 `usercode` 在服务端没有对应用户 | 在「用户管理」中先创建用户,或修正设备 `usercode` | | 服务端日志提示设备 token 错误 | 设备 `device_token` 与服务端不一致 | 两端改成同一个值并重启 | | 设备数量已达上限 | 免费版限 5 台,或授权配额已用完 | 下线多余设备或导入更高配额授权 | | 浏览器提示证书不受信任 | 自签证书未被系统信任 | 选择「继续前往」,或导入 `certs/cert.pem` 到受信任根证书 | | 页面 404 / 样式丢失 | 启动时工作目录不是安装目录,找不到 `static/` | 在安装目录启动,或改用绝对路径的 `-c` 并保持工作目录正确 | | 修改配置后不生效 | JSON 键名写错(如 `tls-pin`)、Windows 路径未转义 | 键名用下划线;Windows 路径写成 `C:/opshub/certs/cert.pem` 或双反斜杠 | | 登录提示锁定 | 连续 6 次密码/验证码错误 | 等待 10 分钟后重试,或确认账号密码正确 | | 授权突然失效 | 系统时间大幅回拨、安装目录变化、硬件变化 | 校正系统时间;重新用当前指纹申请授权 | | Linux 启动报 `No such file or directory` | 该版本依赖系统 glibc,运行环境不兼容 | 改用其他架构/静态版本,或在目标环境自行编译 | --- ## 11. 安全建议 1. 首次部署后立即修改 `admin` 密码,并修改 `device_token`、`jwt_secret` 为随机值。 2. 仅放行必要端口;公网暴露时建议在 Nginx 等反向代理后使用,并限制来源 IP。 3. `certs/key.pem` 权限设为 `600`,不要上传到代码仓库或通过聊天工具传输。 4. 定期备份 `info.db`(用户、脚本历史等数据都在其中)。 5. 保留 `deploy_tls` 生成的指纹记录,换证时一次性同步所有设备。 6. `license.dat` 与机器指纹绑定,迁移服务器前先确认是否需要重新授权。 ### 11.1 Nginx 反向代理配置(可选) 服务端本身已支持 HTTPS/WSS,公网暴露时通常再加一层 Nginx:由 Nginx 提供 443 证书、限制来源 IP,服务端只监听本机。 > **关键点:设备隧道 `/ws` 和远程终端都是 WebSocket。** 下面三行必须写,否则会出现「页面能打开,但终端一直黑屏、设备反复重连」。 1)在 `nginx.conf` 的 `http {}` 块内(**不是** `server {}` 里)加: ```nginx map $http_upgrade $connection_upgrade { default upgrade; '' close; } ``` 2)站点配置: ```nginx server { listen 443 ssl; server_name opshub.example.com; ssl_certificate /etc/nginx/certs/opshub.crt; ssl_certificate_key /etc/nginx/certs/opshub.key; # 远程文件上传,按最大文件大小调整 client_max_body_size 64m; location / { proxy_pass https://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket 透传(设备隧道 /ws、终端、脚本输出) proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; # 长连接不能被默认 60 秒超时切断 proxy_read_timeout 3600s; proxy_send_timeout 3600s; # 上游是自签证书,必须关闭校验,否则 502 proxy_ssl_verify off; } } server { listen 80; server_name opshub.example.com; return 301 https://$host$request_uri; } ``` 3)配套把 `opshub.json` 的 `listen` 改为 `127.0.0.1`,只允许本机反代访问,避免有人绕过 Nginx 直连 8080。 4)设备端 `tls_pin` 怎么填: | 设备接入方式 | `server` 写法 | `tls_pin` 取值 | |---|---|---| | 直连服务端端口(推荐) | `wss://内网IP:8080/ws` | `deploy_tls` 输出的指纹,不受 Nginx 影响 | | 也走 Nginx 域名 | `wss://opshub.example.com/ws` | **Nginx 证书**指纹,见下 | ```bash openssl x509 -in /etc/nginx/certs/opshub.crt -noout -fingerprint -sha256 # 去掉冒号、转小写后填入设备端 opshub.json 的 tls_pin ``` > 排障:页面能开但终端黑屏 / 设备反复重连 → 先查 `proxy_http_version 1.1`、`Upgrade`、`Connection` 这三行;出现 502 → 查 `proxy_ssl_verify off`,以及 `proxy_pass` 是否误写成 `http://`。 --- *如需进一步定制(端口、证书、授权、界面文案),请联系供应商获取开发说明书。*