🛠 排障手册

按「先看日志 → 再查端口/权限 → 最后查授权」的顺序排查，绝大多数问题都能定位。

第 0 步：确认服务真的起来了

curl -s http://127.0.0.1:9999/api/health

返回正常即服务在跑。任何平台都可以用这条命令自查。

第 1 步：看启动日志里的验签公钥指纹

这一行是判断二进制是否正确的关键

启动日志应出现 授权验签公钥指纹：278D-4852-7191-E7CE。对不上说明二进制不是当前版本产物 —— 旧版本曾内置错误的验签公钥，会导致所有授权码校验失败。

# Linux
journalctl -u opsmonitor --no-pager | grep -i 指纹

# Windows
Get-Content C:\OpsMonitor\logs\server.log | Select-String 指纹

# macOS
grep -i 指纹 /usr/local/opsmonitor/logs/server.log

授权与机器码问题

现象	原因与处理
授权显示社区版、页面提示「等待签发」	本机没有有效授权。去「系统 → 授权购买」看本机机器码，把机器码交给授权方签发；签发后在「导入授权码」粘贴即可
授权码导入失败	确认二进制是当前版本（指纹 `278D-4852-7191-E7CE`）；确认授权码是给本机机器码签发的；粘贴时不要漏字符
Docker 容器重建后授权掉了	机器码随容器变化。起一次容器 → 复制机器码 → 填到 `.env` 的 `OPSM_LICENSE_MACHINE=` → 重建
启动日志报「授权系统同步失败 401」	这是授权中心侧的 hub-token 问题，不影响控制台功能与本地授权，可忽略或修正授权中心配置
内网完全离线、不想连授权中心	启动参数加 `-hub=`（不能用 `OPSM_HUB=`）→ 平台不再访问授权中心 → 手工导入授权码
页面上客户端显示「已授权」，但又有「等待签发」字样	以本机实际授权为准。若确认本机已有有效授权仍显示矛盾，重启一次服务刷新状态

端口与网络

现象	原因与处理
本机能开页面，别的机器打不开	① 主机防火墙未放行 9999；② 云服务器安全组未放行；③ 反向代理未配 `OPSM_PUBLIC_URL`
`address already in use`	端口被占：`ss -tlnp \| grep 9999`（Windows 用 `netstat -ano \| findstr 9999`）找占用进程，或换端口
大屏 / 升级下载很慢或超时	反代 `proxy_read_timeout` 调大（如 300s），`client_max_body_size` 调大（如 200m）

数据库与权限

现象	原因与处理
日志报「打开数据库失败」	`OPSM_DB` 指向的目录不存在或无写权限；确认目录存在且属主正确
`permission denied` 启动失败（Linux）	`chown -R opsmonitor:opsmonitor /opt/opsmonitor`
SELinux `avc: denied`	`semanage fcontext -a -t bin_t '/opt/opsmonitor(/.*)?' && restorecon -R /opt/opsmonitor` 后重启
想备份数据	拷数据目录即可：Linux `/opt/opsmonitor/data/`、Windows `C:\OpsMonitor\data\`、macOS `/usr/local/opsmonitor/data/`、Docker `./data/`

采集端相关

现象	原因与处理
控制台看不到主机	密钥不一致（采集端 `-token` vs 监控端 `OPSM_TOKEN`）；地址不可达；采集端未启动
主机显示「离线」	默认 180 秒未上报即离线（`OPSM_OFFLINE_SEC`）；检查采集端进程与网络
采集端不自动升级	远端登记过同版本号产物时，同号主机不触发升级 → 改内容必须改版本号

命令下发（指令通道）注意

Windows 上的管道符会被拆开

Windows 走 cmd /C 执行，裸 | 会被当管道拆开，需转义为 ^|，或整段包进 PowerShell。内层双引号会被吞。部分系统策略还会拒绝 wmic / fsutil。

其他进程/自启问题

平台	现象	处理
Linux	CentOS 7 systemd 报 `Unknown lvalue LimitNOFILE`	老 systemd 语法差异，删掉该行即可（非必需）
Windows	计划任务「已就绪」但无进程	看 `C:\OpsMonitor\logs\server.log`，常见端口占用或目录无权限
macOS	提示「Apple 无法检查是否含恶意软件」	`sudo xattr -dr com.apple.quarantine /usr/local/opsmonitor/opsmonitor-server`
macOS	`Bad CPU type in executable`	Apple 芯片误用了 Intel 版，换 `darwin-arm64`

还找不到原因？

把「服务启动日志（含指纹那一行）+ curl /api/health 结果 + 系统与架构」三样收集齐，基本可以一眼定位。仓库的 DEPLOY.md 里有更完整的排障手册。