检查端口占用情况

确保默认端口（如7860）未被其他程序占用。在终端运行以下命令：

netstat -tulnp | grep 7860

若端口被占用，修改webui.py或启动命令中的端口号：

llamafactory-cli webui --port 7890

验证后端服务状态

通过API测试后端是否正常运行：

curl http://localhost:8000/api/status

正常应返回JSON格式的状态信息。若连接失败，检查后端日志：

journalctl -u llamafactory-backend -n 50

配置权限控制文件

检查config/permissions.yaml文件，典型配置示例：

roles:
  admin:
    access: ["/api/*", "/admin/*"]
  user:
    access: ["/api/query"]

权限规则需与路由定义匹配，路径需使用Ant风格通配符。

检查CORS设置

确保config/settings.py包含正确的跨域配置：

CORS_ALLOWED_ORIGINS = [
    "http://localhost:7860",
    "http://127.0.0.1:7860"
]

生产环境需替换为实际域名。

前端代理配置

若使用Nginx代理，确认/etc/nginx/conf.d/llamafactory.conf包含：

location /api {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
}

调试模式启动

临时启用调试输出：

export LLAMAFACTORY_DEBUG=1
llamafactory-cli webui --log-level debug

观察控制台输出的请求/响应日志，特别注意403/500等错误码。

数据库权限验证

检查用户角色是否正确写入数据库：

SELECT * FROM user_roles WHERE user_id = '[YOUR_USER_ID]';

需确保与permissions.yaml中定义的角色名称完全一致。

浏览器控制台检查

按F12打开开发者工具，查看Network选项卡：

• 确认API请求的Authorization头包含有效JWT
• 检查响应头是否包含access-control-allow-origin
• 过滤XHR请求，观察错误响应内容

防火墙规则更新

Linux系统需放行相关端口：

ufw allow 8000/tcp
ufw allow 7860/tcp

Windows系统需检查防火墙入站规则。