Runixo

Appearance

故障排查 ​

本文列出常见问题的排查步骤和解决方案。

排查工具 ​

查看 Agent 日志 ​

bash
# 实时日志
sudo journalctl -u runixo-agent -f

# 最近 100 行
sudo journalctl -u runixo-agent -n 100

# 指定时间范围
sudo journalctl -u runixo-agent --since "2024-01-01 00:00:00"

# 日志文件
cat /var/log/runixo/agent.log

查看 Agent 状态 ​

bash
sudo systemctl status runixo-agent
sudo runixo info

客户端日志 ​

  • Windows: %APPDATA%/Runixo/logs/
  • macOS: ~/Library/Logs/Runixo/
  • Linux: ~/.config/Runixo/logs/

或在客户端按 Ctrl+Shift+I 打开开发者工具查看控制台。

Agent 问题 ​

Agent 无法启动 ​

症状：systemctl start runixo-agent 失败

排查步骤：

bash
# 1. 查看详细错误
sudo journalctl -u runixo-agent -n 20

# 2. 手动运行查看输出
sudo /usr/local/bin/runixo-agent --debug

# 3. 检查配置文件语法
cat /etc/runixo/agent.yaml

常见原因：

错误信息原因解决
bind: address already in use端口被占用修改端口或停止占用进程
permission denied权限不足以 root 运行或修复文件权限
yaml: unmarshal errors配置文件格式错误检查 YAML 缩进和语法
tls: failed to load key pair证书文件损坏删除证书重启自动重新生成

Agent 崩溃重启 ​

bash
# 查看崩溃前的日志
sudo journalctl -u runixo-agent -b -1

# 检查系统资源
free -h
df -h

# 检查 OOM killer
dmesg | grep -i "out of memory"

Agent 内存持续增长 ​

可能原因：

  • 大量失败认证请求（已有上限保护，最多 10000 条记录）
  • Docker 事件监听泄漏

解决：重启 Agent，如持续出现请提交 Issue。

连接问题 ​

连接超时 ​

bash
# 1. 从客户端机器测试连通性
telnet <server-ip> 50051
# 或
nc -zv <server-ip> 50051

# 2. 检查服务器防火墙
sudo iptables -L -n | grep 50051
sudo ufw status

# 3. 检查云服务商安全组
# AWS: EC2 → Security Groups → Inbound Rules
# 阿里云: ECS → 安全组 → 入方向

TLS 握手失败 ​

bash
# 检查证书有效性
openssl x509 -in /etc/runixo/cert.pem -noout -dates

# 检查证书 SAN
openssl x509 -in /etc/runixo/cert.pem -noout -text | grep -A1 "Subject Alternative Name"

# 如果 IP 变更，重新生成证书
sudo rm /etc/runixo/cert.pem /etc/runixo/key.pem
sudo systemctl restart runixo-agent

认证失败 ​

bash
# 查看正确的 Token
sudo runixo info

# 检查是否被暴力破解防护锁定
sudo journalctl -u runixo-agent | grep "locked"
# 锁定默认 5 分钟后自动解除

Docker 问题 ​

Docker 功能不可用 ​

bash
# 检查 Docker 是否运行
sudo systemctl status docker

# 检查 socket 权限
ls -la /var/run/docker.sock

# 测试 Agent 用户是否有权限
sudo -u runixo docker ps

容器操作失败 ​

bash
# 查看 Docker 日志
sudo journalctl -u docker -n 50

# 检查磁盘空间（Docker 需要空间）
df -h
docker system df

更新问题 ​

自动更新失败 ​

bash
# 查看更新日志
sudo journalctl -u runixo-agent | grep -i "update"

# 手动检查更新 API
curl -s "https://runixo.top/api/v1/agent/check?version=1.0.0&os=linux&arch=amd64"

# 手动更新
curl -fsSL https://raw.githubusercontent.com/Zhang142857/runixo/main/scripts/install.sh | sudo bash

更新后无法启动 ​

bash
# 回滚到旧版本（如果有备份）
sudo cp /usr/local/bin/runixo-agent.bak /usr/local/bin/runixo-agent
sudo systemctl restart runixo-agent

性能问题 ​

客户端卡顿 ​

  • 关闭不需要的服务器连接
  • 减少同时打开的终端数量
  • 检查是否有插件导致性能问题（禁用插件测试）

监控数据延迟 ​

  • 检查网络延迟：ping <server-ip>
  • gRPC 流可能因网络波动中断，客户端会自动重连

获取帮助 ​

如果以上方法无法解决问题：

  1. 收集信息：Agent 日志、客户端日志、系统信息
  2. 在 GitHub Issues 提交问题
  3. 附上错误日志和复现步骤

MIT License

© 2026 Runixo