本地中控监控（Ubuntu 22.04）部署文档

面向 Ubuntu 22.04 中控机：Python 3 + FastAPI + Paramiko（SSH）轮询采集 3 台云服务器指标与 PM2 日志，并提供 Web 面板。

所有文本文件请使用 UTF-8 保存（含 .env）。

1. 环境依赖安装

sudo apt update
sudo apt install -y python3 python3-venv python3-pip

进入项目目录：

cd /path/to/project
chmod +x run.sh

2. 配置文件（.env）

cp example.env .env
nano .env

2.1 密码登录 vs 密钥登录

• 密码模式：SERVER_x_AUTH_TYPE=password，填写 SERVER_x_PASSWORD
• 密钥模式：SERVER_x_AUTH_TYPE=key，填写 SERVER_x_KEY_PATH（中控机可读私钥路径）
• 私钥有口令：填写 SERVER_x_KEY_PASSPHRASE

2.2 PM2 日志路径（root 启动 PM2）

常见路径类似 /root/.pm2/logs/<name>-out.log。把 SERVER_x_PM2_LOG_1 与 SERVER_x_PM2_LOG_2 改成两台固定进程对应日志的绝对路径。

2.3 参数说明

• WEB_HOST / WEB_PORT：监听地址与端口
• POLL_INTERVAL_SECONDS：采集轮询间隔（秒）
• THRESHOLD_CPU_PERCENT / THRESHOLD_MEM_PERCENT / THRESHOLD_DISK_PERCENT：阈值（百分比）
• THRESHOLD_NET_MBPS：网络合量阈值（RX+TX，Mbps）
• SERVER_1_* ~ SERVER_3_*：三台机器连接信息与两份日志路径

注意：必须同时配置 SERVER_1、SERVER_2、SERVER_3 三组变量。

3. 启动命令（前台）

./run.sh

手动等价流程：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export PYTHONUTF8=1
python -m app

4. 访问地址

默认浏览器打开：http://<中控机IP>:8080/（端口以 .env 的 WEB_PORT 为准）

5. 后台常驻运行（systemd）

创建 /etc/systemd/system/ops-monitor.service（把路径与用户改成你的实际值）：

[Unit]
Description=Local ops monitor (FastAPI)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/path/to/project
Environment=PYTHONUTF8=1
ExecStart=/path/to/project/.venv/bin/python -m app
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

启用：

sudo systemctl daemon-reload
sudo systemctl enable --now ops-monitor.service
sudo systemctl status ops-monitor.service --no-pager

6. 常见问题排查

• 启动失败：检查 .env 是否存在且为 UTF-8；确认三台 SERVER_*_HOST 都已填写。
• SSH 失败：在中控机用 ssh -p <port> <user>@<host> 手工验证；核对密码或私钥路径与权限（建议 chmod 600 私钥与 .env）。
• 日志为空：核对日志路径；root PM2 日志通常需要以 root SSH 读取。
• 网络速率显示 -：第二轮起才计算 Mbps，属正常现象。
• 主机指纹：默认自动接受新主机指纹，适合内网；更高安全要求请自行改为严格 known_hosts 校验（需改代码）。

7. 安全建议

• .env：chmod 600 .env
• 面板默认无登录，不建议直接暴露公网；需要时请用反向代理加鉴权