hoppscotch admin面板无法访问或使用，需依次检查：一、确认admin服务运行及数据库/jwt配置；二、手动设用户role为admin；三、修正cors白名单和api地址；四、启用.env中管理功能开关；五、内网调试可临时禁用认证。
如果您已完成Hoppscotch自托管部署，但无法访问或有效使用Admin面板进行用户管理，则可能是由于前端路由未正确指向管理后台、后端API未暴露管理接口，或认证权限配置缺失。以下是解决此问题的步骤：
一、确认管理后台服务已启动并可访问
管理后台（Admin Panel）是独立于主应用的服务模块，通常运行在http://localhost:3100（开发环境）或您在.env中配置的VITE_ADMIN_URL地址。该服务需与主应用共用同一套数据库和认证密钥，否则将出现“Unauthorized”或空白页面。
1、执行命令检查容器状态：docker-compose ps | grep admin 或 docker ps | grep hoppscotch-admin，确认admin服务进程存在且状态为Up。
2、查看admin服务日志：docker-compose logs hoppscotch-admin，重点排查是否报错Cannot connect to database或JWT_SECRET mismatch。
3、直接在浏览器中访问<strong><font color="green">http://{{SERVER_IP}}:3100</font></strong>（请将{{SERVER_IP}}替换为实际服务器IP），若返回404或连接拒绝，请检查docker-compose.yml中是否定义了hoppscotch-admin服务及对应端口映射。
二、验证管理员账户权限配置
Admin面板默认不自动创建超级管理员，必须通过数据库手动插入具备role = 'ADMIN'的用户记录，或启用邮箱注册后通过特定域名邮箱自动升权（如配置ADMIN_EMAIL_DOMAINS=company.com）。未完成此步骤时，即使登录成功，所有管理功能按钮也将灰显或返回403。
1、进入PostgreSQL容器：docker exec -it hoppscotch-db psql -U root -d public。
2、执行SQL更新用户角色：UPDATE users SET role = 'ADMIN' WHERE email = '<strong><font color="green">admin@yourdomain.com</font></strong>';。
3、若使用自建MailCatcher且未真实发送邮件，可跳过邮箱验证：在.env中设置SKIP_EMAIL_VERIFICATION=true并重启服务。
三、修正前端路由与CORS白名单
Admin界面加载时会向/v1/admin/等路径发起请求，若后端未开放对应API路由，或WHITELISTED_ORIGINS未包含Admin面板地址，将导致数据无法拉取、表格为空。
1、打开.env文件，确认WHITELISTED_ORIGINS值中包含Admin面板完整URL，例如：http://localhost:3100、http://192.168.0.66:3100、https://admin.yourdomain.com。
2、检查VITE_BACKEND_API_URL是否指向正确的后端API地址（应为http://{{SERVER_IP}}:3170/v1而非/v1/admin），Admin前端依赖该地址调用管理接口。
3、重启全部服务使配置生效：docker-compose down && docker-compose up -d。
四、启用并配置管理员专属功能开关
部分高级管理能力（如批量用户禁用、API请求审计日志导出、OAuth提供商强制启用）需在.env中显式开启对应标志位，否则即使登录Admin面板，相关菜单项也不会渲染。
1、编辑.env，添加或修改以下行：ENABLE_ADMIN_USER_MANAGEMENT=true、ENABLE_REQUEST_AUDIT_LOGS=true、ENABLE_OAUTH_PROVIDER_MANAGEMENT=true。
2、确保VITE_ALLOWED_AUTH_PROVIDERS包含EMAIL（至少保留邮箱登录），否则Admin无法完成初始登录流程。
3、重建前端镜像以注入新环境变量：docker-compose build hoppscotch-app，再执行docker-compose up -d hoppscotch-app。
五、绕过登录直接进入Admin调试模式（仅限内网测试）
当标准登录流程因SMTP未就绪或JWT密钥不一致而卡死时，可临时启用调试入口，跳过身份校验直接加载Admin UI，用于验证界面功能完整性及后端接口连通性。
1、在.env中添加：DISABLE_AUTH_FOR_ADMIN=true 与 DEBUG_ADMIN_MODE=true。
2、修改docker-compose.yml中hoppscotch-admin服务的环境变量部分，加入- DISABLE_AUTH_FOR_ADMIN=true。
3、访问<strong><font color="green">http://{{SERVER_IP}}:3100/?debug=true</font></strong>，页面将显示未认证状态下的全部管理组件，可点击各Tab观察网络请求是否返回200及有效JSON数据。
