客户端连不上服务器：JWT、端口、HTTPS、内网穿透逐个排查

症状

• 客户端填完服务器地址点保存 → 连接失败
• 或能打开 Web 界面但播放器加载不了音频
• 或间歇性断连、图片加载不出来

排查步骤一：Web 界面能不能打开

同一个地址用浏览器打开：

• 浏览器也打不开：服务器本身就没跑起来、或端口没映射对、或防火墙没放行 → 先回去检查部署
• 浏览器能打开但客户端连不上：说明服务器本身没问题，问题出在客户端 → 继续排查

排查步骤二：JWT Token 过期或密码错

• 现象：Web 界面能打开，能看到登录页面，但登不上
• 检查：config/config.json 里 JWT 用户的密码是否正确、Token 有效期到没到
• 修复：
• 重设密码（config.json 里改 password 字段）
• 清空 Token 黑名单（如果有）
• 关掉 JWT 先临时测试能不能连通，确认连通后再开回来

排查步骤三：端口映射 / 防火墙

Docker 用户

# 看端口映射是不是对的
docker port kikoeru

# 看容器日志有没有收到请求
docker logs kikoeru --tail 100 -f   # 持续追踪，客户端连一下看日志

云服务器

• 安全组里是否放行 Kikoeru 的端口
• 本地防火墙（ufw / Windows Defender）是否放行

内网穿透 / DDNS

• DDNS 域名解析到的 IP 是不是你当前的公网 IP（很多家庭宽带 IP 每天变）
• Cloudflare Tunnel 或 frp/ngrok 这类工具是否在运行

排查步骤四：HTTPS 证书问题

症状

• iOS PWA / Android Chrome 里地址栏有感叹号
• 有的浏览器版本强制 HTTPS，不给 HTTP 了
• JWT Token 能拿到但后续请求被 Mixed Content 拦截

常见证书问题

• 自签名证书：浏览器会警告"不安全"，需要手动信任
• 证书过期：Let's Encrypt 90 天到期，忘了续
• 域名不匹配：证书签给了 A 域名但你用 B 域名访问

快速验证

浏览器打开 Kikoeru → 点地址栏的小锁 → 查看证书详情 → 看有效期和域名匹配。

排查步骤五：跨域（CORS）

• 现象：Web PWA 打开后空白，Console 里有 CORS 错误
• 原因：前端和后端不在同一个源（不同域名、不同端口、不同协议）
• 修复：后端 config.json 里设置 cors.origin（允许的来源域名）

排查步骤六：客户端版本过旧

• iOS TestFlight 版本太老，后端 API 有 breaking change
• Android 第三方客户端（KikoFlu）不兼容最新版后端
• Web PWA 缓存了老版本的 JS（Service Worker 没更新）

修复：

• iOS：检查 TestFlight 里的更新 → 装最新版
• Android：去 GitHub 找 KikoFlu 最新 release
• Web：强制刷新（Ctrl+Shift+R），或手动清除浏览器缓存

排查步骤七：网络类型差异

• Wi-Fi 下能连，4G/5G 连不上：运营商可能封了某些端口（比如 8888、48488）→ 换个高端口（比如 8080、8443、9000）试试
• 在公司 Wi-Fi 下连不上：公司防火墙可能拦截了非标准端口 → 用 HTTPS + 443 端口试试

快速诊断流程

客户端连不上
 ├─ 浏览器打开同一地址 → 能不能访问？
 │   ├─ 不能 → 回查部署（docker ps / netstat / 防火墙）
 │   └─ 能 → 继续
 ├─ JWT 开了吗？
 │   ├─ 开了 → 密码对不对？关掉 JWT 试试
 │   └─ 没开 → 继续
 ├─ HTTPS？
 │   ├─ 是 → 证书有没有过期/域名不匹配？
 │   └─ 否 → 客户端是不是强制 HTTPS 了？
 ├─ 同网络类型下换客户端试试
 │   ├─ iOS 不行但 Android 行 → iOS 版本过旧/证书问题
 │   └─ 都不行 → 网络层问题（运营商/公司防火墙）
 └─ 换个端口映射 → 重新测试