登录
转载文章-Komari 探针手动安装教程 - 适用于端口受限VPS

转载文章-Komari 探针手动安装教程 - 适用于端口受限VPS

 次点击
 79 分钟阅读

Komari 探针手动安装教程 - 适用于端口受限VPS

转载自-https://www.nodeseek.com/post-613729-1

适用场景：VPS封禁了常用HTTP/HTTPS，导致官方一键安装脚本无法使用

📋 目录

环境要求

  • VPS系统：Debian 12（或其他使用systemd的Linux发行版）

  • 本地环境：能访问GitHub并执行curl/scp命令

  • SSH访问：能通过SSH连接到VPS（通常22端口可用）

  • Komari服务端：已部署并获取Token

问题背景

为什么官方脚本无法使用？

官方一键安装脚本依赖以下端口：

bash <(curl -sL https://raw.githubusercontent.com/.../install.sh) -e https://your-server.com -t YOUR_TOKEN

失败原因：

  1. ❌ VPS封禁了443端口，无法通过HTTPS下载脚本

  2. ❌ 无法通过HTTPS访问GitHub releases下载二进制文件

  3. ❌ 探针无法通过443端口与服务端通信（如果服务端用的是HTTPS）

  4. ❌ 自动更新功能会尝试访问GitHub API（443端口）

安装步骤

步骤1：本地下载二进制文件

在您的本地电脑（非VPS）执行：

# 根据VPS架构选择对应版本
# 查看VPS架构：ssh root@YOUR_VPS_IP "uname -m"
# x86_64 → amd64 | aarch64 → arm64

ARCH="amd64"  # 大多数VPS是amd64
OS="linux"

# 下载最新版本（注意文件名会带有OS和架构后缀）
curl -L -o komari-agent-${OS}-${ARCH} \
  "https://github.com/komari-monitor/komari-agent/releases/latest/download/komari-agent-${OS}-${ARCH}"

# 重命名为agent（重要！）
mv komari-agent-${OS}-${ARCH} agent

# 赋予执行权限
chmod +x agent

# 验证下载成功
file agent
# 应输出：agent: ELF 64-bit LSB executable...

步骤2：上传到VPS

使用SCP将文件上传到VPS：

# 替换为您的VPS IP地址
VPS_IP="YOUR_VPS_IP"

# 先在VPS上创建目录
ssh root@$VPS_IP "mkdir -p /opt/komari"

# 上传二进制文件（文件名已经是agent）
scp agent root@$VPS_IP:/opt/komari/agent

# 确保可执行权限
ssh root@$VPS_IP "chmod +x /opt/komari/agent"

# 验证安装
ssh root@$VPS_IP "/opt/komari/agent --help"

步骤3：配置systemd服务

SSH登录VPS后，创建服务文件：

# 登录VPS
ssh root@YOUR_VPS_IP

# 创建systemd服务文件
cat > /etc/systemd/system/komari-agent.service <<'EOF'
[Unit]
Description=Komari Agent Service
After=network.target

[Service]
Type=simple
ExecStart=/opt/komari/agent -e http://YOUR_SERVER_IP:PORT -t YOUR_TOKEN --disable-auto-update
WorkingDirectory=/opt/komari
Restart=always
User=root

[Install]
WantedBy=multi-user.target
EOF

⚠️ 重要配置说明：

参数

说明

示例

-e

服务端地址（必须加http://前缀）

http://192.168.1.100:26774

-t

从Komari面板获取的Token

abc123xyz456

--disable-auto-update

必须添加，否则会卡在更新检查

-

常见错误：

  • ❌ 192.168.1.100:26774 - 缺少协议前缀

  • ✅ http://192.168.1.100:26774 - 正确格式

步骤4：启动并验证

# 重新加载systemd配置
systemctl daemon-reload

# 启用开机自启
systemctl enable komari-agent.service

# 启动服务
systemctl start komari-agent.service

# 查看服务状态
systemctl status komari-agent.service

# 查看实时日志
journalctl -u komari-agent -f

✅ 成功标志：

Feb 10 19:00:22 debian agent[18214]: Komari Agent 1.1.41
Feb 10 19:00:22 debian agent[18214]: Using system default DNS resolver
Feb 10 19:00:22 debian agent[18214]: Monitoring Mountpoints: [/ (ext4)]
Feb 10 19:00:22 debian agent[18214]: Monitoring Interfaces: [ens5]
Feb 10 19:00:22 debian agent[18214]: Basic info uploaded successfully
Feb 10 19:00:22 debian agent[18214]: WebSocket connected

刷新Komari面板，服务器应显示在线状态。

常见问题解决

问题1：卡在"Checking update..."

现象：

Feb 10 18:49:47 debian agent[18126]: Checking update...
[卡住1分钟]
Feb 10 18:50:47 debian agent[18126]: [ERROR] failed to check for updates: context deadline exceeded

原因： VPS无法访问GitHub的443端口下载更新。

解决方案： 在启动参数中添加 --disable-auto-update：

ExecStart=/opt/komari/agent -e http://... -t ... --disable-auto-update

问题2：endpoint配置错误

现象：

Error: parse "192.168.1.1:26774/api/...": first path segment in URL cannot contain colon
Failed to connect to WebSocket: malformed ws or wss URL

原因： endpoint缺少 http:// 或 https:// 前缀。

解决方案：

# ❌ 错误
ExecStart=/opt/komari/agent -e 192.168.1.1:26774 -t ...

# ✅ 正确
ExecStart=/opt/komari/agent -e http://192.168.1.1:26774 -t ...

修改后执行：

systemctl daemon-reload
systemctl restart komari-agent.service

问题3：国旗显示不正确

现象： 探针在线，但显示的国旗不是预期的国家。

原因： Komari通过GeoIP自动识别VPS的真实IP地理位置。如果VPS在海外，会显示该国家的国旗。

解决方案： 使用 --custom-ipv4 参数指定目标国家的公网IP地址，可以帮助实现正确的国旗显示。

操作步骤：

  1. 修改systemd服务文件，添加 --custom-ipv4 参数：

# 停止服务
systemctl stop komari-agent.service

# 编辑服务文件
nano /etc/systemd/system/komari-agent.service

  1. 修改 ExecStart 行，添加自定义IP：

ExecStart=/opt/komari/agent -e http://YOUR_SERVER_IP:PORT -t YOUR_TOKEN --disable-auto-update --custom-ipv4 114.114.114.114

  1. 重启服务：

systemctl daemon-reload
systemctl start komari-agent.service

注意事项：

  1. 需确保Komari面板的GeoIP功能已启用（设置 → 系统设置 → GeoIP配置）

  2. 修改IP后需要等待1-2分钟，刷新面板查看效果

  3. 选择的IP地址应为目标国家的真实公网IP

问题4：服务启动失败 (203/EXEC)

现象：

Feb 10 18:47:37 debian systemd[1]: komari-agent.service: Failed at step EXEC spawning /opt/komari/agent: No such file or directory

原因： 二进制文件不存在或路径错误。

解决方案：

# 检查文件是否存在
ls -lh /opt/komari/agent

# 检查文件权限
chmod +x /opt/komari/agent

# 测试直接运行
/opt/komari/agent --help

完整配置参考

基础配置（推荐）

[Unit]
Description=Komari Agent Service
After=network.target

[Service]
Type=simple
ExecStart=/opt/komari/agent -e http://YOUR_SERVER_IP:PORT -t YOUR_TOKEN --disable-auto-update
WorkingDirectory=/opt/komari
Restart=always
User=root

[Install]
WantedBy=multi-user.target

高级配置（包含自定义IP）

[Unit]
Description=Komari Agent Service
After=network.target

[Service]
Type=simple
ExecStart=/opt/komari/agent -e http://YOUR_SERVER_IP:PORT -t YOUR_TOKEN --disable-auto-update --custom-ipv4 YOUR_PUBLIC_IP
WorkingDirectory=/opt/komari
Restart=always
User=root

[Install]
WantedBy=multi-user.target

2. 修改systemd服务：

[Service]
ExecStart=/opt/komari/agent --config /opt/komari/config.json

环境变量配置（可选）

Komari Agent支持通过环境变量配置，适用于容器化部署：

# 在systemd服务中使用环境变量
[Service]
Environment="AGENT_TOKEN=YOUR_TOKEN"
Environment="AGENT_ENDPOINT=http://YOUR_SERVER_IP:PORT"
Environment="AGENT_DISABLE_AUTO_UPDATE=true"
ExecStart=/opt/komari/agent

支持的环境变量：

环境变量

对应参数

说明

AGENT_TOKEN

-t

Token

AGENT_ENDPOINT

-e

服务端地址

AGENT_DISABLE_AUTO_UPDATE

--disable-auto-update

禁用自动更新

AGENT_CUSTOM_IPV4

--custom-ipv4

自定义IPv4

AGENT_INTERVAL

-i

数据采集间隔（秒）

验证清单

安装完成后，请逐项检查：

  • [ ] 服务状态为 active (running)

  • [ ] 日志显示 WebSocket connected

  • [ ] 日志显示 Basic info uploaded successfully

  • [ ] Komari面板显示服务器在线

  • [ ] 面板显示正确的系统信息（CPU、内存、磁盘等）

  • [ ] 国旗显示正确（如有需要）

验证命令：

# 查看服务状态
systemctl status komari-agent

# 查看最近50行日志
journalctl -u komari-agent -n 50 --no-pager

# 实时监控日志
journalctl -u komari-agent -f

卸载

如需卸载Komari Agent：

# 停止并禁用服务
systemctl stop komari-agent.service
systemctl disable komari-agent.service

# 删除服务文件
rm /etc/systemd/system/komari-agent.service

# 重新加载systemd
systemctl daemon-reload

# 删除二进制文件
rm -rf /opt/komari

# 在Komari面板删除该服务器记录

更新升级

由于我们禁用了自动更新，需要手动升级：

# 1. 在本地下载最新版本
curl -L -o komari-agent-linux-amd64 \
  "https://github.com/komari-monitor/komari-agent/releases/latest/download/komari-agent-linux-amd64"

# 重命名为agent
mv komari-agent-linux-amd64 agent
chmod +x agent

# 2. 停止服务
ssh root@YOUR_VPS_IP "systemctl stop komari-agent.service"

# 3. 备份旧版本
ssh root@YOUR_VPS_IP "cp /opt/komari/agent /opt/komari/agent.backup"

# 4. 上传新版本
scp agent root@YOUR_VPS_IP:/opt/komari/agent

# 5. 启动服务
ssh root@YOUR_VPS_IP "systemctl start komari-agent.service"

# 6. 验证版本
ssh root@YOUR_VPS_IP "journalctl -u komari-agent -n 5 | grep 'Komari Agent'"

参考资料

贡献与反馈

如果您在使用过程中遇到问题，或有改进建议，欢迎：

  • 在本文评论区留言

  • 在GitHub提交Issue

祝您使用愉快！ 🎉

© 本文著作权归作者所有，未经许可不得转载使用。