AI 网关（Sub2API）与网盘配额
云桌面里的 AI 开发环境、AI 教学环境要调用大模型，绕不开两件事：接口地址和密钥从哪儿来、谁用了多少。没有网关的时候，这两件事只能靠人管——把上游订阅的密钥抄进每一台桌面模板里，密钥就此散在几十上百台机器上；谁调了多少次、花掉多少额度，事后没有任何账可查；学生毕业、老师调岗，密钥还留在镜像里照样能用。
AI 网关（Sub2API）是装在本机的一套服务，把上游订阅统一换成标准的模型调用接口对内提供。它最要紧的一个设计是：网关自己不维护账号——用户和分组直接以个人网盘的用户表、分组表为唯一数据源。也就是说，人还是在网盘那边建，网关这边只负责给这些人开通、发密钥、记用量、设余额。
在管理台上，它对应左侧顶级菜单 AI网关。
它和「AI 助手」的点数不是一回事
控制台里还有一处会显示「余额」，那是 AI 助手 的云端点数——助手每次回答走的是云端出口，按点数计费、在「AI 助手 → 点数与计费」页充值。本页说的余额是 Sub2API 网关侧按网盘用户记的额度，两套东西各记各的账，互不相通。
一、开始之前：两道门与一条权限
AI网关整个菜单是可裁剪的。 它受两道门控，任意一道没过，左侧菜单里根本不会出现这个入口：
1，授权位要开通了 AI 网关这一项。授权情况见「服务器 → 授权服务」。
2，本机要装了 Sub2API 组件。组件没装，入口不展示。
「配了」不等于「装好了」
系统判定网关是否可用时，要求同时满足两件事：管理密钥（Admin Key）已配置，并且服务端确实能连上这个网关服务。只配了密钥但连不通，仍然算作未安装，页面不会正常出数据。排查顺序建议先确认 Sub2API 服务在本机是否处于运行状态，再看配置。
另外，AI网关下的这些管理页由管理服务代为转发到 Sub2API。打开它们需要管理员登录态，且该账号要具备用户管理权限；权限不够时页面取不到数据。角色权限怎么勾见权限管理相关说明。
管理密钥不会经过浏览器
转发时由服务端在后台附加网关的管理密钥，前端既看不到也拿不到。所以不用担心管理员打开页面就把网关的最高权限密钥暴露在浏览器里。
二、用户管理：谁开通了、还剩多少、这个月用了多少
菜单位置：AI网关 → 用户管理
这一页以网盘用户分页展示，逐人聚合下面几项：
| 列 | 说明 |
|---|---|
| 是否已开通 | 这个网盘用户在网关侧有没有对应账号 |
| 余额 | 网关侧给这个人记的额度，单位与口径以实机页面为准 |
| 当月用量 | 本月累计调用量 |
| API 密钥 | 脱敏显示，只够用来核对是哪一把，看不到完整值 |
单人开通并设余额
1，在列表里找到这个人（可按网盘用户检索）。
2，对未开通的用户执行开通，可以在开通的同时把余额一并设好。
3，已开通的用户随时可以再改余额。
余额是「覆盖」，不是「增减」
设置余额时填进去的是这个人余额最终应该是多少，服务端按这个值直接覆盖，不是在原有基础上加或减。想给某人在现有 100 的基础上再加 50，必须自己算清楚填 150；顺手填 50 的结果是把他的余额改小。
这一页不建人、不改人、不删人
用户管理页只做「开通」和「配额」两件事，没有新建、编辑、删除用户的操作。 这是有意为之：人的唯一来源是网盘用户表。
| 你想做的事 | 实际该去哪儿 |
|---|---|
| 加一个人 | 个人网盘 → 网盘用户，新建或批量导入；建好后再回本页开通 |
| 改姓名、部门、证件号 | 个人网盘 → 网盘用户 |
| 让一个人彻底用不了网关 | 停用 / 删除他名下的 API 密钥（见第三节） |
个人网盘那边怎么建组、怎么用 Excel 批量导入，见 个人网盘。
批量开通：一次把全部网盘用户补齐
新学期一次导进来两三百个网盘用户，逐个点开通显然不现实。AI网关 → 用户管理 提供一次性批量开通：把全部网盘用户一次开通到网关，已经开通过的自动跳过，不会重复建。
执行完成后返回三个计数：成功 / 跳过 / 失败。
1，「跳过」通常就是之前已经开通过的人，属正常，不用处理。
2，「失败」要单独看——常见原因是网关服务这一刻连不上。等服务恢复后重跑一次即可，已成功的那批会走「跳过」，不会被做第二遍。
批量开通只管「开没开通」
余额是另一件事。批量开通不逐人分配额度，需要区别对待的人仍在用户管理页里单独设。
三、API 密钥：发给谁、还能不能用
菜单位置：AI网关 → API密钥
一个网盘用户名下可以有多把密钥，便于按用途分开——比如「教学环境用」「学生自己的开发环境用」，出问题时只停掉其中一把，不影响另一把。
可做的操作：
| 操作 | 说明 |
|---|---|
| 新建 | 为指定的网盘用户签发一把新密钥 |
| 重命名 | 改这把密钥的名字，便于分辨用途 |
| 启用 / 停用 | 临时封停某一把，不删除，随时可恢复 |
| 改分组 | 调整这把密钥所属的网关分组 |
| 删除 | 作废这把密钥 |
完整密钥只在新建那一刻显示一次
新建成功时返回的完整密钥只出现这一次，页面关掉就再也调不出来了（列表里一律是脱敏显示）。请当场复制保存好再关窗口。忘了记就只能删掉重发一把。
删除密钥收不回来
删除属于不可恢复的操作：这把密钥立刻作废，正在用它的桌面、脚本、开发工具会当场调不通。只是想临时断一下，请用停用而不是删除。同理，由 AI 助手 代为执行删除密钥时，会先弹出待确认卡片，必须管理员点头才真正执行。
终端用户自己怎么拿到密钥
除了管理员在控制台发，用户也可以在客户端自助查看自己的密钥与用量，不必找管理员要。
客户端登录那一刻会换发密钥
用户在客户端登录时会换发一把新密钥，旧的同时作废。所以：抄在别处、写死在脚本或桌面模板里的旧密钥，会在这个人下次登录客户端后失效。日常刷新页面、来回切页不会触发换发，也不会打断正在进行的会话——只有登录那一下会换。
四、分组同步
菜单位置：AI网关 → 分组管理
网关侧的分组同样不单独维护，而是把网盘分组映射成网关分组。网盘那边新建或调整了分组之后，可以在这里按单个分组重新同步一次，让网关侧跟上。
分组对不上时先想想是哪一边改的
分组的源头永远在个人网盘。发现网关侧分组不对，正确顺序是先到 个人网盘 → 网盘用户 的分组树上确认组本身是对的，再回来重新同步这一个组，而不是在网关侧硬改。
五、使用记录
菜单位置：AI网关 → 用户管理 / 使用记录
按人翻阅调用明细：既可以从「用户管理」里某个人进去看他的记录，也可以从「使用记录」页打开。用户管理列表上的当月用量是汇总数字，明细就在这里。
有人反馈额度掉得快、或者怀疑密钥外泄时，先来这里按人对一遍调用明细。具体的字段与筛选条件以您实机这一版为准。
六、网关的其余管理页
AI网关 菜单下还有一批页面，来自 Sub2API 服务自身，属于服务运营与运维侧的配置，与「把网盘用户开通成网关用户」这条主线不是一回事：
| 页面 |
|---|
| 仪表盘 |
| 运维概览 |
| 订阅套餐 |
| 上游账号 |
| 风控 |
| 代理 |
| 公告 |
| 备份恢复 |
| 渠道管理与监控 |
| 系统设置 |
这几页本手册暂不逐页展开
它们涉及上游订阅、渠道与风控等运营配置，页面构成随 Sub2API 版本变化，请以您实机上的页面与提示为准；把握不准的项目建议先联系服务提供方，不要在生产现场试改——上游账号与渠道配置改错会直接导致全场调不通模型。
七、和网盘那一侧的两种「配额」
标题里的「网盘配额」容易和网关余额混在一起，这里分清楚：
| 说的是什么 | 在哪儿定 | 说明 |
|---|---|---|
| 网关额度（余额） | AI网关 → 用户管理 | 这个人还能调多少模型，覆盖式设定 |
| 网盘容量 | 个人网盘 → 网盘设置 → 数据模板 | 用户那块虚拟磁盘多大，建模板时指定，默认 20480 MB |
两者都按同一份网盘用户记账，但互不影响：把网盘容量调大不会让网关额度变多，网关余额用完也不影响用户继续用自己的网盘。
人从网盘删掉之后，记得回头看一眼密钥
删除网盘用户属于不可恢复操作，操作前请确认。人删掉之后建议回 AI网关 → API密钥 核对一遍，把他名下还留着的密钥停用或删除，免得出现「人已经走了、密钥还在调」的情况。
八、这套网关给谁用
1，云桌面里的 AI 开发 / 教学环境。 桌面市场里的 AI 开发环境、AI 教学环境即依赖本网关，内置 KEY 需签订相应订购合同后才可启用，见 如何用桌面市场部署桌面。
2，开发工具直连。 网关另有一条直连通路，供 claude code、codex 一类工具直接使用：鉴权由 API 密钥本身完成，不需要管理台登录态，请求头原样透传，并支持流式输出。
直连通路不校验控制台登录，是设计如此
这条通路本来就是给带密钥的程序用的，密钥即身份，因此不走管理台的登录校验——这不是漏洞。真正需要管理员身份的是本页讲的这些管理页面，它们必须有登录态和用户管理权限才打得开。也正因为密钥即身份，密钥泄漏等同于额度被人白用，请按第三节的办法及时停用或重发。
九、常见问题
左侧根本没有「AI网关」这个菜单
按第一节的两道门排查：先看授权位有没有开通这一项，再确认本机装没装 Sub2API 组件。两者都具备时，还要看当前账号的角色有没有勾上对应的菜单权限。
菜单在，但页面数据是空的 / 打不开
多半是网关服务连不上。判定「已安装」要求管理密钥已配置且服务端能连上，只配不通就是这个表现。先确认本机 Sub2API 服务在跑，再看配置。
某个网盘用户在网关列表里找不到
用户管理页以网盘用户分页，找不到人说明网盘那边就没有这个人。请先到 个人网盘 → 网盘用户 里建好或导入，再回来开通。
开通了、也发了密钥，桌面里还是调不通
1，确认那把密钥是不是已停用或已被删除。
2，确认用户有没有在客户端重新登录过——登录会换发密钥，写死在模板或脚本里的旧密钥会失效。
3，看余额是不是被覆盖成了很小的数（余额设定是覆盖不是增减）。
4，以上都正常时，到「使用记录」里看这个人最近有没有调用记录，据此判断请求是压根没到网关，还是到了网关但被拒。
余额越设越小
这是覆盖式设定的典型误用：填进去的数字就是最终余额。加额度请先看当前值再算好总数填入。
十、配套阅读
- 个人网盘 —— 网关的人员底册与网盘容量都在这里定
- 如何用桌面市场部署桌面 —— AI 开发 / 教学环境的部署
- AI 助手 —— 与网关余额无关的另一套云端点数计费
- 上机认证实名记录 —— 上机人员与网盘用户的双向同步