Web 界面 JWT 认证保护 · 局域网暴露时的必要安全层

为什么要 JWT 认证

关闭"仅本机访问"后，RikkaHub Web 服务器对同一局域网内的所有设备开放。没有密码保护意味着：

• 任何人都能打开你的 RikkaHub Web 界面
• 能看到你的完整对话历史
• 能看到你配置的所有 AI 提供商 API 密钥
• 能在你的账户里发消息、创建对话、修改设置

JWT 认证是 RikkaHub 提供的保护机制——建议所有暴露到局域网的 Web 服务器都开启。

工作原理

1. 首次浏览器访问 → RikkaHub 返回登录页面
2. 你输入访问密码 → RikkaHub 验证密码正确性
3. 验证成功 → RikkaHub 签发一个 JWT 令牌
4. 浏览器存储令牌（localStorage / cookie）
5. 后续请求自动携带令牌
6. RikkaHub 验证令牌签名 → 放行
7. 令牌过期 → 浏览器弹出密码输入框重新获取

JWT（JSON Web Token）是一个签名令牌，RikkaHub 用密码作为签名密钥生成。只要密码不变、令牌未过期，就能一直通过验证。

配置步骤

第一步：设置访问密码

在 设置 → Web 访问 页面的"访问密码"字段里输入密码。任何字符串都行——你自己记住就好。

第二步：启用 JWT 认证

密码字段非空后，"启用 JWT 认证"开关自动可用。开启。

第三步：重启 Web 服务器

必须先停止再启动，认证配置才会生效。

第四步：浏览器首次访问

1. 打开浏览器，输入服务器地址（如 http://192.168.1.42:8080）
2. 看到密码输入页面
3. 输入你刚才设置的访问密码
4. 点击登录 → 进入完整 RikkaHub Web 界面

令牌有效期

RikkaHub JWT 令牌的有效期目前固定（通常是几小时到一天）。过期后：

• 浏览器会自动弹出密码输入框
• 你输入密码后获取新令牌
• 同一浏览器会话中不会频繁弹窗

浏览器行为

• Chrome / Edge：JWT 令牌存储在 localStorage，关闭浏览器标签后令牌仍然有效（直到过期）
• Firefox：同样存储方式
• 手机浏览器：同上

如果想"强制重新输入密码"，可以：

• 在浏览器开发者工具里清除 localStorage
• 或 RikkaHub 侧重启 Web 服务器（会使旧令牌失效）

安全注意事项

密码不要和 AI 提供商 API 密钥相同

如果泄露了，攻击者既能进 Web 界面，又能直接调用你的 AI 提供商 API——双重损失。

清空密码会禁用认证

清空"访问密码"字段会自动关闭 JWT 认证，恢复到无保护状态。清空时 RikkaHub 可能会弹出确认提示。

局域网本身不安全

JWT 认证保护的是 Web 界面的访问控制。但如果你的局域网本身被入侵（如公共 Wi-Fi），攻击者可以：

• 嗅探 HTTP 流量（虽然 JWT 令牌本身是签名的，但令牌可能被窃取重放）
• 进行中间人攻击

建议：

• 只在可信局域网（家里、办公室）开启非"仅本机"模式
• 公共 Wi-Fi 环境下用"仅本机访问"模式（配合 ADB 端口转发在电脑上访问）
• 如果一定要在公共网络暴露，考虑在 RikkaHub 服务器外面加一层 HTTPS 代理

HTTPS 不是内置的

RikkaHub Web 服务器目前提供的是 HTTP 明文。这意味着：

• JWT 令牌在网络上以明文传输（被窃听就会泄露）
• 任何人都能看到浏览器和 RikkaHub 之间的所有请求

解决方法（如果你真的需要 HTTPS）：

1. 在手机上或旁边的设备部署一个 HTTPS 反向代理（如 Caddy、Nginx）
2. 代理把 HTTPS 请求转发到 RikkaHub 的 HTTP 服务器（默认 8080）
3. 局域网设备访问 HTTPS 端点

这是高级玩法，大多数用户不需要。但要知道 HTTP 明文的安全边界。

常见问题

忘记访问密码

回到手机上 RikkaHub 的 设置 → Web 访问 页面，清空密码字段（会自动禁用 JWT 认证），然后重新设置新密码。

JWT 认证开启后浏览器打不开

1. 确认你在浏览器里输入了正确的密码
2. 清空浏览器 localStorage 里的 JWT 令牌，重新登录
3. 确认手机和浏览器设备在同一网络
4. 确认 RikkaHub Web 服务器正在运行