常见问题

收集一些插件使用时遇到的常见问题。

🔐 认证方式相关

Cookie模式和Access Token方式有什么区别？

插件支持两种认证方式：

推荐使用 Access Token 方式，除非遇到以下情况：

• 站点不支持访问令牌
• 使用魔改版本的中转站
• Token 功能被禁用

如何切换认证方式？

在添加账号时，在账号对话框中选择对应的认证方式：

1. 点击"新增账号"
2. 输入站点地址
3. 在"认证方式"下拉框中选择 Access Token 或 Cookie
4. 点击"自动识别"

🔧 特殊站点问题

AnyRouter 网站报错怎么办？

AnyRouter 是魔改版的中转站，不支持标准的 Access Token 方式。

解决方案：

1. 在添加账号时，选择 Cookie 模式
2. 先在浏览器中登录 AnyRouter 站点
3. 然后使用插件的自动识别功能添加账号

Sub2API（JWT 站点）怎么添加？

Sub2API 站点常见特征：控制台接口在 /api/v1/*，并使用 短期 JWT（auth_token）+ refresh token（会轮转） 的登录态。控制台会把登录信息写入 localStorage：

• auth_token：JWT access token（短期）
• auth_user：用户信息（含 id 等）
• refresh_token：refresh token（可选；用于刷新 access token，且通常会轮转）
• token_expires_at：access token 过期时间戳（毫秒，可选）

插件支持两种工作模式：

模式一：控制台会话模式（默认/兼容）

该模式不在插件内保存 refresh_token，插件需要从控制台 localStorage 读取 auth_token / auth_user 才能自动识别与刷新余额，因此 必须先在浏览器中登录站点控制台。

添加步骤：

1. 在浏览器中打开目标站点控制台并登录（确保没有被重定向回登录页）。
2. 打开插件 → 新增账号。
3. 输入站点 URL，点击「自动识别」。

注意与限制：

• 同一站点（同一 origin）在一个浏览器会话里 localStorage 只能有一套登录态，因此该模式下 同站点多账号体验很差：你切换控制台账号会覆盖 localStorage，插件也会跟着“换人”。
• 如果刷新出现 401，插件会尝试重新读取 auth_token 并重试一次；如果仍失败，请重新登录站点控制台后再刷新/重新识别。

模式二：插件托管会话（多账号，推荐）

启用后，插件会把 refresh_token 作为 账号私有 凭据保存（并会跟随导出/WebDAV 备份），从而让每个 Sub2API 账号可以独立刷新 JWT，支持 同站点多账号。

推荐导入流程（无痕/隐私窗口，减少轮转冲突）：

1. 打开无痕/隐私窗口并登录目标 Sub2API 控制台。
2. 在插件里新增/编辑账号，点击「从当前登录账号导入」（或「自动识别/重新识别」）导入会话信息。
3. 在表单中开启「插件托管会话（多账号）」并确认已带入 refresh_token，然后保存。
4. 关闭无痕/隐私窗口（清理该站点的 localStorage/cookies），避免控制台与插件并行刷新同一 refresh_token 导致相互失效。

安全提醒：

• refresh_token 属于长期凭据；开启该模式后会随账号导出/WebDAV 备份一起保存，请妥善保管备份文件与 WebDAV 凭据。
• 若浏览器需要，请在扩展管理里开启“允许在无痕/隐私窗口运行”。

故障排查：

• 如果提示 refresh_token 失效/已轮转，请重新按上述流程导入（或手动粘贴新的 refresh_token）后重试。

其他已知限制：

• 仅支持 访问令牌（JWT） 模式，不支持 Cookie 认证。
• 暂不支持站点签到功能（会自动关闭签到检测）。
• 当前版本主要同步 余额/额度；“今日用量/收入”等统计可能为 0。

自动识别失败怎么办？

如果自动识别失败，可以尝试以下方法：

1. 切换认证方式：尝试从 Access Token 切换到 Cookie 模式
2. 手动添加：在自动识别失败后，手动填写以下信息：
   • 用户名
   • 用户ID
   • 访问令牌
   • 充值比例
3. 检查登录状态：确保已在浏览器中登录目标站点
4. 检查站点兼容性：确认站点是否基于支持的项目（见下文）

哪些站点可能不兼容？

如果站点进行了深度二次开发，修改了关键接口（如 /api/user），可能导致插件无法正常工作。

常见不兼容情况：

• 修改了用户信息接口
• 禁用了访问令牌功能
• 自定义了认证方式
• 修改了 API 响应格式

🐛 功能和Bug相关

遇到功能问题或Bug怎么办？

1. 查询Issue：前往 GitHub Issues 搜索是否有相同问题
2. 使用最新版本：
   • 商店版本更新较慢，建议使用 GitHub Release 版本
   • 或直接使用 main 分支的开发版本

如何获取最新版本？

插件在多个平台发布，更新速度有差异：

⚙️ 功能使用问题

如何使用WebDAV备份？

WebDAV 备份可以帮你在多设备间同步数据：

1. 配置 WebDAV：

   • 打开"设置" → "WebDAV 备份"
   • 填写 WebDAV 服务器地址（完整URL）
   • 填写用户名和密码

2. 选择同步策略：

   • 合并（推荐）：智能合并本地和远程数据
   • 仅上传：只上传本地数据到服务器
   • 仅下载：只从服务器下载数据

3. 启用自动同步：

   • 勾选"启用自动同步"
   • 设置同步间隔（默认3600秒/1小时）

如何导出到 CherryStudio / New API？

快速导出功能可以一键将站点配置导入到其他平台：

配置步骤：

1. 对于 New API：

   • 打开"设置" → "基础设置"
   • 配置 New API 服务器地址
   • 填写管理员令牌（Admin Token）
   • 填写用户ID

2. 对于 CherryStudio：

   • 无需额外配置
   • 确保 CherryStudio 正在运行

导出流程：

1. 进入"密钥管理"页面
2. 找到要导出的站点
3. 点击操作菜单
4. 选择"导出到 CherryStudio"或"导出到 New API"

如需更完整的导出与集成说明，请参阅 快速导出站点配置；若希望对接 CLIProxyAPI 管理接口，可参阅 CLIProxyAPI 集成。

如何使用站点签到功能？

部分中转站支持每日签到获取奖励：

1. 启用签到检测：

   • 编辑账号
   • 勾选"启用签到检测"

2. 自定义签到URL（可选）：

   • 如果站点签到页面不是标准路径
   • 可以填写"自定义签到URL"
   • 填写"自定义充值URL"（可选）

3. 执行签到：

   • 需要签到的账号会显示签到图标
   • 点击账号卡片上的签到按钮
   • 自动打开签到页面

如何自定义账号排序？

插件支持多种排序方式的优先级设置：

1. 进入排序设置：

   • 打开"设置" → "排序优先级设置"

2. 调整优先级：

   • 拖动排序条件调整优先级
   • 勾选/取消勾选启用/禁用条件

3. 可用的排序条件：

   • 📌 当前站点置顶
   • 🏥 健康状态排序（错误 > 警告 > 未知 > 正常）
   • ✅ 需要签到的账号置顶
   • 🔗 有自定义签到URL的账号置顶
   • 📊 用户自定义字段排序（余额/消费/收入/名称）

如需了解各排序规则的详细含义与示例配置，请参阅 排序优先级设置。

自动刷新如何设置？

自动刷新可以让账号数据保持最新：

1. 启用自动刷新：

   • 打开"设置" → "自动刷新"
   • 勾选"启用定时自动刷新"

2. 设置刷新间隔：

   • 默认：360秒（6分钟）
   • 最小：60秒（1分钟）
   • 根据站点数量调整

3. 其他选项：

   • ✅ 打开插件时自动刷新
   • ✅ 显示健康状态

如何使用余额历史（Balance History）？

余额历史用于长期查看账号余额变化与每日收支趋势。启用后会在本地记录按天聚合的快照并用图表展示。

记录内容（每个账号每天最多一条）：

• 余额/额度：quota
• 今日收入：today_income（来自充值/系统日志统计）
• 今日支出：today_quota_consumption（来自消费日志统计）
• 记录时间：capturedAt
• 来源：source（刷新 / 日终抓取）

记录方式：

1. 刷新驱动：账号刷新成功后，会更新当天快照。该流程遵循“显示今日收支”开关，不会为了余额历史额外强制拉取日志。
2. 日终抓取（可选）：启用后会在每天接近 23:55 进行一次后台抓取，并强制包含今日收支，用于尽量补齐当天的收入/支出数据。

前置条件（重要）：

• 如果关闭“显示今日收支”，刷新驱动的收入/支出字段将为空。
• 若你希望记录收入/支出历史，请启用以下任意一项：
  • “显示今日收支”（刷新时计算今日收支）
  • “日终抓取”（每天一次强制拉取今日收支）

限制与说明：

• Best-effort：浏览器休眠、网络中断或站点限制可能导致某些天缺失，图表会显示断点/空白。
• 不回填历史：不会为了补齐过去日期而反查历史日志（避免产生大量网络请求）。
• 保留与清理：仅保留最近 N 天（默认 365 天），写入时会自动清理超出窗口的快照；也可以在页面内手动执行“清理”。
• 本地存储：余额历史仅保存在本地（当前版本不会随导入导出 / WebDAV 同步一起迁移）。

📱 移动端使用

如何在手机上使用？

插件支持在移动设备上使用：

Android 设备：

1. 安装 Kiwi Browser（推荐）

   • 完美兼容 Chrome 扩展
   • 支持所有功能

2. 或安装 Firefox for Android

   • 从 Firefox Add-ons 安装

iOS 设备：

• 暂不支持（iOS 限制）

移动端使用建议

1. 使用侧边栏模式：更适合手机屏幕
2. 启用自动刷新：避免频繁手动刷新
3. 配置 WebDAV 同步：在电脑和手机间同步数据

🔒 数据安全

数据存储在哪里？

• 本地存储：所有数据保存在浏览器本地存储中
• 完全离线：插件核心功能无需联网
• 不上传数据：不会向任何第三方服务器上传数据

数据会丢失吗？

建议定期备份数据：

1. JSON导出：

   • 进入"设置" → "数据与备份"
   • 点击"导出数据"
   • 保存JSON文件

2. WebDAV同步（推荐）：

   • 自动备份到云端
   • 支持多设备同步

🆘 其他问题

站点重复检测是什么？

添加站点时，插件会自动检测是否已存在相同站点：

• 基于站点URL判断
• 如果已存在，会提示并允许快速修改
• 避免重复添加相同站点

健康状态是什么意思？

健康状态表示账号的可用性：

插件消耗流量吗？

• 仅在刷新账号数据时访问站点API
• 请求量非常小（每个站点约几KB）
• 建议在WiFi环境下使用自动刷新

如何贡献代码？

欢迎提交 Pull Request：

1. Fork 项目仓库
2. 创建功能分支
3. 提交代码
4. 发起 Pull Request

详见：CONTRIBUTING.md

📚 相关文档

• 使用教程
• GitHub 仓库
• 问题反馈
• 更新日志