> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytespike.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting · ByteSpike × DOSIA

> 员工 / admin 一站式 troubleshoot — 装机 / SSO / 模型权限 / 余额 / abuse / 紧急处置 SOP 全在这里。

<Note>
  **适用场景**：在 [员工 onboarding](./employee-onboarding) 或 [admin 运营手册](./admin-operations) 上某一步卡住、报错、看到非预期空状态。下方按角色 (Tabs) + 场景 (AccordionGroup) 排版，先按身份对号入座再找症状。
</Note>

<Tabs>
  <Tab title="员工视角">
    ## 装机 / 启动

    <AccordionGroup>
      <Accordion title="首次启动报 &#x22;文件已损坏&#x22; / &#x22;来自身份不明的开发者&#x22;">
        macOS Gatekeeper 拦截未公证 dmg — Terminal 跑：

        ```bash theme={null}
        xattr -cr /Applications/DOSIA.app
        ```

        然后重新启动 DOSIA。
      </Accordion>

      <Accordion title="DOSIA 启动后无 &#x22;ByteSpike 共享&#x22; provider">
        按顺序排查（最常见在前）：

        1. **企业模式没切** → 进 **Settings → Deploy Mode**，确认显示「企业版」非「个人版」
        2. **企业服务地址 typo** → 同页核对地址，admin 给的字符串复制要完整（默认 `http://122.51.0.230:3012`）
        3. **admin 没 publish token** → 联系 admin 在 DOSIA Settings → **ByteSpike tab** 顶部应有「已配置 · 员工启动时自动拉取」绿条；如缺，admin 重新 publish 一次
        4. **员工 lark OAuth 过期** → DOSIA **Settings → "我的账户"** 看 SSO 状态；过期就点退出 + 重登
        5. 全做完仍无 → 截图 lark 群 @ByteSpike Ops
      </Accordion>

      <Accordion title="lark 授权后 DOSIA 卡死 / 反复登录">
        清掉本地 auth state 重启：

        ```bash theme={null}
        rm -rf ~/Library/Application\ Support/DOSIA/auth
        ```

        重启 DOSIA 触发新 OAuth。如还不行，截图 + lark 私聊 admin。
      </Accordion>
    </AccordionGroup>

    ## 模型权限

    <AccordionGroup>
      <Accordion title="对话框报 &#x22;无权限&#x22; / &#x22;model not allowed&#x22;">
        Admin 没给你的组开通该模型权限。联系 admin 在 [llm.bytespike.ai/admin](https://llm.bytespike.ai/admin) → **Users** → 你的账户 → **Allowed Models** 勾上对应模型组。
      </Accordion>

      <Accordion title="测试连接 modelCount = 0（DOSIA 配置面板）">
        DOSIA Settings → ByteSpike tab 测试连接时显示 `modelCount: 0`：

        1. 之前 W1/W2 修过 `/admin/available-models` 401 → 现在用 `/me/available-models`，**对正常用户应该 ≥ 1**
        2. 仍为 0 → admin 没给 user 绑 group。按上一条联系 admin 处理
        3. token 本身有问题 → 见下「测试连接报 401」
      </Accordion>

      <Accordion title="图片识别报错 (vision)">
        选的模型不含 vision capability。在 [console.bytespike.ai/zh/models](https://console.bytespike.ai/zh/models) 「模型库」找带 vision 标签的（如 Claude Sonnet 4.6、GPT-5-4、Gemini 3.5 Flash），切回 DOSIA 选这些模型再重试。
      </Accordion>

      <Accordion title="图像 / 视频生成 tab 看不到">
        多模态权限是独立 grant 的（独立于文本模型）。Admin 在 [llm.bytespike.ai/admin](https://llm.bytespike.ai/admin) → 你的组 → 加上 `image` / `video` capability，DOSIA 重启即可看到对应工具。
      </Accordion>
    </AccordionGroup>

    ## 余额 / 测试

    <AccordionGroup>
      <Accordion title="对话框报 &#x22;余额不足&#x22;">
        组织钱包余额耗尽。截图 + 联系 admin，admin 在 [console.bytespike.ai/billing](https://console.bytespike.ai/billing) 充值后立即恢复。
      </Accordion>

      <Accordion title="测试连接报 401 (token invalid)">
        Token 失效。回 [console.bytespike.ai/keys](https://console.bytespike.ai/keys) 重新创建一个 key，粘贴到 DOSIA Settings → ByteSpike tab → 重测连接。

        如新 key 仍 401 → 联系 admin 检查你的 user 状态（可能被暂停了）。
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Admin 视角">
    ## 紧急处置 SOP

    <AccordionGroup>
      <Accordion title="余额突降（怀疑被刷）">
        <Steps>
          <Step title="查审计日志">
            [llm.bytespike.ai/admin](https://llm.bytespike.ai/admin) → **审计日志** → 按 `created_at desc` → 找异常高频 `admin.api_key.*` 或异常调用。
          </Step>

          <Step title="定位可疑 api_key">
            **用量** → `group_by api_key` → 找 24h 内消费异常的 key
          </Step>

          <Step title="立即 revoke">
            **用户管理** → 点该 user → 点 key → **吊销 / Revoke**。被吊销的 key 立即返 401，再无成本。
          </Step>

          <Step title="复盘">
            如果是员工泄露 key：联系员工换 key + 教育安全意识。如果是 admin 误操作：在 audit log 反查 + 补还员工额度。
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="某个模型暂时不可用（单个模型 5xx 升高）">
        <Steps>
          <Step title="确认故障">
            **模型分组** → 找到服务该模型的 group → 看 schedulable / health 状态
          </Step>

          <Step title="临时下线">
            group 详情页 → 切受影响的条目 `schedulable=false`。router 立即停止往它派流量，自动在同 group 内 fallback。
          </Step>

          <Step title="恢复后">
            切回 `schedulable=true`。期间的请求已自动在同 group 内被接住 — 用户层面感知不到（除非整 group 都不可用）。
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="某员工 abuse（高频调用 / 拉爆余额）">
        路径 1 · **限速**：**用户管理** → 点员工 → **Concurrency** 调到 1 + **RPM** 调到 6 → 保存。该员工后续调用会被 429 拦截。

        路径 2 · **暂停账号**：**用户管理** → 点员工 → **Status**: active → disabled → 保存。该员工的 key 立即 401，DOSIA 也无法 SSO。

        路径 3 · **调倍率**（针对特定 model）：**模型分组** → 把该 group 倍率从 1.0 调到 5.0 — 全局生效，慎用。
      </Accordion>
    </AccordionGroup>

    ## 员工反馈处置

    <AccordionGroup>
      <Accordion title="员工反馈 &#x22;暂无可用模型&#x22;">
        最常见原因是员工**没被 grant 任何 group**（新员工默认 0）。按 [admin-operations § 2 路径 1](./admin-operations#2-给员工-grant-模型权限-核心运营动作) bulk 给员工勾上 11 个公开 group 即可。

        如果 bulk grant 后员工仍报 — 让员工 DOSIA 退出账号重新登录（清 token cache）。
      </Accordion>

      <Accordion title="员工反馈 &#x22;ByteSpike 共享&#x22; provider 不出现">
        跟员工 onboarding 卡住的同症状。让员工按「员工视角 → 装机 / 启动」第二条排查 5 个 check。多数情况是 **企业服务地址 typo** 或 **admin token 没 publish**。
      </Accordion>

      <Accordion title="员工反馈测试连接 modelCount = 0">
        检查 admin 是否给该员工绑了 group：[llm.bytespike.ai/admin](https://llm.bytespike.ai/admin) → 用户管理 → 点该员工 → 「可用模型」tab 看勾选项。如全空 → bulk 勾上 11 个公开 group → 员工重启 DOSIA。
      </Accordion>

      <Accordion title="通知中心收到 admin.api_key.revoke 但不是我吊销的">
        可能 platform admin（如运维同事）吊销了。在 audit log filter `action=admin.api_key.revoke` → 看 actor。如果是误操作，让对方撤销 + 给员工补发 key。如果是合法 abuse 处置，不用动。
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## 还是搞不定？

* **员工**：lark 群 @ByteSpike Ops
* **Admin / OP**：lark 私聊 W1，或者直接 SSH lisahost (`38.78.146.204`) + 122.51 backend 自查
* **集成 issue**：[GitHub Issues](https://github.com/leave1206/bytespike-website/issues)（仓库内部，需登录）