常见问题

1. 服务端无法手动启动

手动执行 source startup.sh 时提示端口被占用或启动失败，检查以下两种情况：

1.1 情况一：自启动服务已在运行

如何判断：执行以下命令查看服务状态

sudo systemctl status joy_service

如果看到如下输出，说明自启动服务正在运行：

● joy_service.service - 机器人web启动服务
     Loaded: loaded (/etc/systemd/system/joy_service.service; enabled; ...)
     Active: active (running) since Thu 1970-01-01 09:16:04 CST; 23s ago
   Main PID: 60380 (ti5robotserver)
      ...

该输出表明自启动服务已经启动了程序，无需再手动启动，直接在浏览器访问即可。

如果确实需要手动启动（例如调试），先停止自启动服务：

sudo systemctl stop joy_service    # 停止服务
sudo systemctl disable joy_service # （可选）禁用开机自启

1.2 情况二：端口被其他程序占用

如何判断：执行以下命令查看端口占用（config.ini 中 port = -1 时使用 443/80，否则使用配置的端口）

# port = -1 时检查 443 端口（HTTPS为443，HTTP为80）
sudo lsof -i :443

# port = 5000 等具体值时
sudo lsof -i :5000

如果有输出，说明端口已被占用。

解决方法：

# 方法一：强制终止占用端口的进程（将 443 替换为实际端口）
sudo fuser -k 443/tcp

# 方法二：根据 PID 终止指定进程
sudo kill -9 <PID>

然后重新启动服务即可。也可在 config.ini 中修改 port 为其他未被占用的端口。

2. 权限问题

如果提示 “Permission denied” 或 “无法执行”：

# 为可执行文件添加执行权限
sudo chmod +x ti5robotserver
sudo chmod +x startup.sh

3. 串口搜索不全

部分串口设备可能使用非标准命名，导致搜索时无法识别。

解决方法：在 config.ini 的 serial_device_patterns 中添加对应的串口匹配规则（详见 配置文件使用详解），保存后重启服务

4. 通过 mDNS 无法访问网页

排查步骤：

  1. 确认网络：检查电脑与机器人是否连接同一个 WiFi

  2. 确认 mDNS 已启用：检查 config.ini 中 mdns_enabled = True

  3. 测试解析：在电脑终端输入 ping <服务名>.local（服务名即 mdns_service_name）

    • 如果无响应：mDNS 服务可能未启动，检查服务端是否正常运行

    • 如果IP 与机器人实际 IP 不符：说明该服务名已被局域网内其他设备占用

  4. 修改服务名：编辑 config.ini 中的 mdns_service_name，改为唯一名称后重启服务

5. 查看运行日志

遇到问题时，查看日志可以帮助定位原因：

# 查看自启动服务的最近 50 条日志
sudo journalctl -u joy_service -n 50

# 实时监控日志输出
sudo journalctl -u joy_service -f