企业管控面（管理后台）

管理后台（admin console）是企业服务端的控制面，不是客户端的一部分：它随服务端镜像一起下发， 用浏览器打开 /admin/ 即可使用。账号、部门、登录方式、模型网关、计量计费、能力中心与应用中心的 审批与授权、连接器目录、审计——所有管控决策都在这里收口。

员工侧看到的一切（登录页、客户端界面、门户页）都不经过后台；后台也不提供任何”给员工看”的内容。 管理员访问入口只有两个：直接访问 /admin/，或门户页页脚那行低对比度文字链接（首屏刻意不放管理入口， 避免员工点进去看到自己无法使用的登录页）。

定位：为什么它是服务端控制面

设计选择	原因
内嵌在服务端镜像里（随二进制分发，/admin/ 路径）	后台与它管控的对象（数据库、网关密钥、计费账本）在同一台机器、同一个进程边界内，不存在”客户端版本与服务端能力不匹配”的中间态
员工拿不到	管控动作的权限点只发给 super_admin / auditor；普通员工即使打开 /admin/ 也无法登录（非管理员账号被拒），更拿不到任何管理接口
侧栏按账号的 RBAC 权限点渲染	同一个后台对不同管理员呈现不同界面：super_admin 全量，auditor 只有只读三页。前端只做体验层，服务端 RequirePermission 才是护栏
品牌与文案不在后台编辑	名称、标语、欢迎语、标识、主题色来自构建期注入的渠道内容，见渠道与白标。改品牌 = 重新构建镜像，这样内容可审计、可复现

后台是内嵌进二进制的单页应用，自带内容安全策略；/admin 会 302 到 /admin/。

边界与失败行为

• 二进制里没有构建进管理端产物（例如本地直接跑未经打包的二进制）时，访问 /admin/ 返回 JSON 信封 404 NOT_FOUND「webadmin 未构建」，不会返回空白页。
• 管理接口的错误一律是统一信封 {"error":{"code":"…","message":"…"}}，健康探针是 /healthz。
• 后台不写业务数据以外的任何”外观”配置：它没有任何品牌字段，也没有”上传 logo”入口。

权限与导航

侧栏分三个分区，条目按当前账号下发的权限点显示（super_admin 是全部权限点，auditor 只有审计只读那三个）：

分区	页面	路径	职责	读权限点
管理	用户	/users	账号、角色、状态、余额、重置密码 / 重置 MFA、登录令牌	user:read
管理	部门	/departments	部门树、主管、成员（支持多部门）	dept:read
管理	认证	/auth	本地 / LDAP / OIDC 登录方式配置与目录同步	auth:read
运维	网关	/gateway	上游供应商、模型与定价、默认模型、限流、峰谷时段、网关防护	gateway:read
运维	网关文件	/gateway-files	上游 Files 归属台账：按员工看占用、搜索排序与过期清理	gateway:read
运维	错误监控	/error-monitoring	客户端错误上报开关与上报状态、错误追踪连接器预填	server-info:read
运维	用量中心	/usage	总览、部门、成员、模型、请求明细、余额、报表订阅	usage:read 等，见下
运维	能力中心	/capabilities	技能 / 智能体 / 审批 / 平台内置四个 Tab	market:read、capability:read
运维	应用中心	/app-center	员工自建应用：发布处置、版本审批、运营看板、限制项	capability:read
运维	连接器	/connectors	连接器目录定义与下发开关	connector:read
运维	服务器信息	/server-info	版本与更新提示、运行时与数据库、并发、审计链结论	server-info:read
审计	审计日志	/audit	敏感操作留痕与保留策略	audit:read

写面权限点按资源类别划分：user:write、dept:write、auth:write、gateway:write、 capability:write（能力中心与应用中心共用）、connector:write、market:write、 audit:retention:write（仅 super_admin，审计保留策略）。任何一个管理接口都必须显式申报权限点， 没有申报的路由在服务端启动时就会失败。

auditor 是只读角色：它只有 audit:read、usage:read、user:read 三个点，侧栏只显示它读得到的页面， 页面内的写入口（保存、删除、审批、调整）在其上都会失败。报表订阅列表刻意不发给 auditor—— 推送地址本身是凭据。

边界与失败行为

• 权限点缺失时服务端返回 403 FORBIDDEN；前端隐藏入口只是体验（服务端才是护栏），因此手敲 URL 也拿不到数据。
• 前端在服务端没有下发权限集时（旧版本、异常响应）退回角色判定，且不放大可见面：只有 super_admin 全量，auditor 仅审计分区。
• 新页面如果忘记声明权限点，侧栏对该页 fail-closed（只有 super_admin 可见），不会默默对所有管理员开放。
• 读接口失败时页面不保留上一份数据继续渲染（避免把旧筛选结果冒充成本次结果），只显示失败态与重试入口。

认证与凭据生命周期

登录方式在「认证」页配置，员工面与管理面不是同一套：

• 员工面：本地账号 / LDAP / OIDC（含 OpenID 变体）。勾选哪些方式，客户端登录页就出现哪些； local 恒启用，可用「隐藏客户端本地登录入口」把它从客户端隐藏。
• 管理面：只认本地账号，且只有 super_admin / auditor 能登录。目录账号（LDAP/OIDC） 一律进不了后台——SSO 与 LDAP 只服务员工面。

登录方式配置

方式	必填项	说明
LDAP	服务器地址、bind DN、base DN	另有用户过滤器（默认 (uid=%s)）、用户名字段（默认 uid）、组过滤器、组属性（默认 cn）
OIDC / OpenID	issuer、client_id、secret、redirect URL	redirect URL 必须是 https 或 http 回环

• 用户名字段必须与目录实际属性一致：AD 常用 sAMAccountName，部分目录只有 cn/mail。 填错时单个人工登录仍可能成功（登录会回退到输入的用户名），但全量同步会因为取不到该属性而跳过全部用户。 「测试连接」返回的用户样例里 username 为空，就是这个字段没配对。
• 测试连接：LDAP 返回目录统计（匹配到的用户数、组数、前 5 个用户样例），保存前即可确认过滤器正确性； 密码留空或填 *** 表示”用已保存的密码测试”，不会因为密码框为空而失败。OIDC/OpenID 会拉取发现文档校验 issuer。
• 密码/密钥保持：已配置的密钥不回显（显示「已配置」）。留空保存 = 保持原值；要清除必须用显式的清空操作， 它会把空串的密文写回，覆盖已存密钥。
• 同一页还配置本地账号的密码最小长度（默认 10 位，可配 8–64 位），它约束新建用户、重置密码与自助改密三处。

LDAP 目录同步

保存配置后立即同步一轮，此后每 1 小时全量对账：

• 目录中的用户自动创建 / 更新（显示名、邮箱、组；组全量替换）；
• 目录中消失的用户自动停用并吊销全部令牌（离职立即失效）；
• LDAP 自动同步是单向的：曾被停用不会因为重新出现在目录里而自动启用——目录同步只自动停用、永不自动启用，重新启用一律由管理员显式执行（每轮被跳过的账号记一条 directory_enable_skipped 审计）；
• 目录扫描结果为 0 用户时拒绝执行本轮同步（防过滤器写错把全部外部用户停用掉）。

OIDC 的组同步只发生在登录时（IdP 的 groups claim），组变更要等用户重新登录才生效；需要及时离职处理就用 LDAP。

管理员 MFA（TOTP）

• 开启：先用主密码验证身份 → 得到密钥（二维码 + 文本两种呈现）→ 输入动态码完成绑定。开启成功后， 该账号的其他管理会话全部被吊销（防止”开启前就已存在的登录”绕过第二因子）。
• 关闭：主密码 + 当前动态码双验。关闭同样会吊销其他会话。
• 已开启时再次走”开启”流程会被拒绝（409 MFA_ALREADY_ENABLED）：更换验证器必须先关闭再开启， 不能让更弱的闸门（只凭主密码）替换更强的第二因子。
• 动态码一次性消费（同一步长内重放会被判为错误），登录挑战票据有有效期与尝试次数上限。
• 没有恢复码。丢失验证器的兜底是：另一位 super_admin 在用户页重置该账号的 MFA（会同时吊销其全部会话）， 或运维用服务端 CLI 的 --reset-mfa 模式重置。

密码与吊销语义

• 密码最小长度在「认证」页配置（默认 10 位，可配 8–64 位）；super_admin 不能重置自己的 MFA （要在右上角账号菜单的「安全设置」里关闭）。
• 重置密码 = 强制改密：重置后的账号进入 password_must_change 状态，除改密、读取自身信息、登出之外的 业务接口一律 403 PASSWORD_CHANGE_REQUIRED（客户端在完成改密前拿不到任何业务数据）。
• 改密即吊销：密码变更与”删除该用户全部 API 令牌 + 全部管理会话”在同一个事务里完成，含当前会话—— 改密后必须重新登录。禁用用户走同一条吊销路径。
• 删除用户 = 抹除：同一事务里清除其 API 令牌、用量明细与日/月汇总、余额流水与发放记录、管理会话、 部门归属与用户级授权。被抹除的金额记进 user_delete 审计条目——“删即消失”语义下，金额只能靠审计追溯。
• LDAP/OIDC 用户的密码由企业 IdP 管理，后台不提供改密（用户页只对本地账号显示重置入口）。

边界与失败行为

• 认证配置未加载成功时保存被锁定：否则一次读失败会把空配置当成新配置提交，覆盖现有登录方式与已存密钥。 失败提示会明确写出这一点并给出「重新加载配置」。
• 保存认证配置会立即同步一次目录；同步失败不会回滚配置，但会在页面上报错，管理员可稍后重试。
• 密码校验有并发闸门（argon2 内存开销较大），过载时返回 429 RATE_LIMITED 而不是排队堆积。
• 登录失败统一返回 401 AUTH_FAILED「用户名或密码错误或非管理员」，不区分”用户不存在”与”密码错”， 也不区分”不是管理员”。

令牌与会话模型

后台管理的是两类凭证，规则完全不同：

	员工 API 令牌	管理端会话
存放	数据库只存 SHA-256 哈希，原文只在签发那一刻返回	只存哈希（会话主键不入库为明文）
有效期	90 天固定过期	12 小时硬上限 + 60 分钟空闲滑动，任一到期即失效
载体	Authorization: Bearer	HttpOnly + SameSite=Lax 的会话 cookie（Secure 按部署判定）
防伪	—	CSRF token 与会话绑定（HMAC），管理写操作必须携带
吊销	用户页可逐个撤销；改密 / 禁用 / 删除连带全撤	改密、重置 MFA、开启或关闭 MFA 时连带撤销（保留发起动作的当前会话）

• 签发令牌时会顺带清理一批已过期的令牌行（有界、走过期索引），登录频率驱动增长，也由登录驱动回收。
• 登录限流只对失败计数（5 分钟滑动窗口，成功即清空）：账号维度 10 次（可用环境变量调整上限）、 来源 IP 维度 60 次。账号维度的失败预算与客户端登录共用同一份——在客户端试错 10 次之后， 同一个账号在后台也被拦住。
• 来源 IP 按”信任边界解析出的真实客户端 IP”计（只有请求确实来自受信反代时才采信转发头）， 否则反向代理会把所有请求算成同一个 IP，60 次失败就能锁死全组织登录。
• 管理会话的 CSRF token 与会话同寿命；页面刷新后可从「读取自身信息」接口取回，不需要重新登录。

边界与失败行为

• 凭证被拒 ≠ 依赖故障：令牌不存在 / 已吊销 / 已过期 / 用户不存在 / 用户已停用 → 401（客户端据此清会话）； 数据库抖动、连接池耗尽、语句超时 → 5xx（客户端保留令牌重试）。把后者也压成 401 会让一次数据库抖动 等同”全体在线员工被登出”，因此两者在服务端是显式分类的。
• 会话过期或被吊销后，管理接口返回 401 AUTH_REQUIRED，前端回到登录页；写操作缺 CSRF token 时被拒。
• 限额触发时返回 429 RATE_LIMITED；MFA 第二步有独立的 IP / 账号两个失败桶，避免动态码被爆破。

页面职责

管理分区

用户 /users（读 user:read，写 user:write）

• 列表与搜索：按用户名子串搜索（纯子串匹配，% / _ 不当通配符），显示角色、状态、部门、余额、本月消费、创建时间、上次改密。
• 新建用户：用户名 + 密码（长度下限在「认证」页配置，默认 10 位）+ 角色（super_admin / auditor / user）。角色是权限的唯一真源； 角色变更立即生效并写审计，且系统必须保留至少一名管理员。
• 设置部门：多选（checkbox 树），提交部门 ID 数组；也提供「清空全部归属」。
• 启用 / 禁用：禁用需二次确认，明示”将立即吊销该用户全部 API 令牌，客户端需重新登录”。
• 删除：二次确认，明示会同时抹除全部 API 令牌、用量记录（明细与日/月汇总）、余额流水、会话与组归属，不可恢复。
• 重置密码：为本地用户设置新密码，重置即吊销其全部会话，对方下次登录必须先改密。 外部认证用户的密码由企业 IdP 管理，此入口不适用。
• 重置 MFA：关闭该用户的动态码并吊销其全部会话；不能对自己操作。
• 登录令牌：分页列出该用户的令牌（名称、创建时间、过期时间、状态：正常 / 已过期 / 已撤销），可逐个撤销。

部门 /departments（读 dept:read，写 dept:write）

• 部门树可任意嵌套：新建 / 编辑部门（名称、上级部门、部门主管、描述）、查看成员、删除部门。
• 删除有关联（成员、子部门、授权引用）的部门会被拒绝，需要先处理关联。
• 组织语义：部门树 → 部门主管 → 员工；授权给部门覆盖其子部门成员，主管自动继承本部门及下级授权。
• 用户可属于多个部门（本地账号与目录账号都是），所属部门全部生效。

认证 /auth（读 auth:read，写 auth:write）——见上文「认证与凭据生命周期」。

运维分区

网关 /gateway（读 gateway:read，写 gateway:write）

• 上游供应商：渠道型（选渠道，如 deepseek）或手动型；名称、对外访问地址、API Key（加密存储、永不回显）、 协议（openai 默认 / anthropic / both——both 表示同一个 key 同时服务两套端点）、启用开关。 停用后不参与模型路由，但模型仍可在管理面查看与编辑。
• 模型：名称、显示名、所属上游、上下文窗口、默认思考强度、输入模态（仅文字 / 文字 + 图片， 客户端据此决定是否允许上传图片）、输入价、输出价、缓存命中输入价、低谷折扣率、并发目标。 模型列表可「立即同步」从上游拉取；同步不会覆盖管理员配过的输入模态。
• 默认模型：客户端登录后默认使用的模型；随启动配置下发给员工，员工可在模型选择器里单独调整。
• 全局设置：每用户限流（次/分钟，0 = 不限制）、高峰时段、未定价模型策略、文件保留上限、 单请求文件引用上限、请求体加工内存预算、调用明细保留时长。
• 高峰时段：多段窗口，北京时间，按星期勾选生效日，半开区间 [start, end)； 未配置任何窗口 = 全天标准价；留空或填 1 的低谷折扣 = 无峰谷价。

网关文件 /gateway-files（读 gateway:read；删除、批量清理需 gateway:write）

• 上游 Files API 的归属台账：文件 ID、所属员工、大小、上传时间、过期时间、状态（有效 / 已过期）。
• 上游配额是按 API key 全组织共享的，所以这一页解决的问题是”谁占了额度”：可按员工汇总占用、 按占用字节或文件数排序、按 file_id 搜索、只看某个员工的全部文件。
• 单个删除：同时删除上游文件与台账记录。批量清理：必须指定条件（有效 / 已过期，或先填用户名）， 全组织范围只允许清理已过期文件，单次最多 500 条，需要输入「确认」二字，返回命中 / 删除 / 失败计数。
• 服务端另有每 5 分钟一轮的自动回收；文件保留上限在网关页配置（默认 7 天，可配 1–30 天）， 超期文件由服务端在上游删除。

错误监控 /error-monitoring（读 server-info:read）

• 开关 + DSN + 上报等级（debug / info / warning / error，默认 error）+ 启动时发送链路心跳。 这套配置随客户端启动配置下发，员工登录后自动启用，无需用户手动连接。
• 客户端上报状态：列出最近 100 台客户端回报的初始化结果（成功 / 失败与原因、DSN 主机、等级、版本）与最近一次上报时间。
• 「发送测试事件」直接验证链路是否连通，返回 HTTP 状态与事件 ID。
• 连接器预填：为错误追踪类连接器预填服务地址与组织，员工只需填自己的 API Token。

用量中心 /usage（子页各有权限点）

子页	路径	负责什么	权限点
总览	/usage	上游账户余额（供应商开放查询时）、本月 / 今日 / 区间费用与请求数、消耗趋势、模型 TOP 10	usage:read
部门用量	/usage/depts	按部门维度看消耗、成员排行、模型拆分	dept:read
成员用量	/usage/members	本月每人消耗、账户余额、状态；点击进入成员详情（按天趋势、模型构成、最近请求）	user:read
模型分析	/usage/models	单价、tokens、费用占比、渠道分布；未定价模型标注「未定价」	usage:read
请求日志	/usage/logs	每次模型调用的计量记录（不含对话内容），默认近 7 天、最长 90 天	usage:read
余额	/usage/balance	发放策略与闸门开关、单人调整、流水与对账	user:read
报表订阅	/usage/reports	每月自动生成上月汇总并推送到企业机器人 webhook	report:read

• 余额子页：顶部是发放策略（闸门开关、每人每月额度、发放方式「累加 / 覆盖」）与「立即补发本月」； 行内可对单人做「加到余额 / 从余额扣除 / 设为 / 清零」，备注会写进流水与审计；流水区显示类型、金额、 变动后余额、时间与备注。页面还会显示欠款人数与欠款总额——流式请求在正文交付后才结算， 并发的在途请求可以一起把小额账户打成负数，这个数字是唯一能在管理端看见它的地方。
• 报表订阅：订阅名称、推送地址（企业机器人 webhook）、启用开关；可「测试」推送、查看上次推送与 下次重试时间、欠投期号与最近错误。推送地址作为凭据不回显（显示「已配置」）。

能力中心 /capabilities（读 market:read / capability:read，写 capability:write / market:write）

四个 Tab：

1. 技能：市场技能列表（官方蓝标 / 员工上传）；上架（上传 .zip 压缩包或从 Git 源接入）、 上传新版、下架 / 重新上架、编辑展示元数据、规范化（按发布标准改写包内 SKILL.md）、授权、转移归属、锁定管理。
2. 智能体：与技能同构的组织侧市场（智能体自身的发布与审核面）。
3. 审批：员工上传的技能与智能体的统一审批队列，状态 Tab（待审核 / 已通过 / 已拒绝 / 全部）+ 类型筛选； 动作 = 通过 / 拒绝（理由必填、作者可见）/ 删除；质量标记 = 官方 / 精选（仅”已通过”可设，互斥）； 可查看归档内容预览后决定。
4. 平台内置：随服务端镜像分发的只读技能清单，含”未收录”的逐条原因。

应用中心 /app-center（读 capability:read，写 capability:write）

三个子页：

1. 应用：员工自建应用的列表与处置——上下架、冻结 / 解冻、转移归属（负责人）、删除、访问级别； 抽屉里可看版本、待审清单、表结构与数据行（只读，用于排障与合规）、运行诊断、公告模板。 更新审批开关是组织级开关：开启后员工发布的新版本停在「待审批」，线上继续运行当前生效版本。
2. 运营看板：打开次数（PV / UV）、按日趋势、按部门聚合；口径是”窗口内按用户去重”， 部门取打开时刻的主部门。应用维度 AI 用量与打开次数一同展示。
3. 限制项：平台级资源与时间预算（全局并发、单应用并发与队列、单用户并发、单实例内存上限、 模块缓存与空闲回收、应用库只读连接数与此缓存、guest / 干跑 / 宿主调用 / 端到端墙钟 / 单条 SQL / 编译各项预算）。 合法区间由服务端按项目之间的序关系推导，控制台显示的区间就是服务端会接受的区间。

连接器 /connectors（读 connector:read，写 connector:write）

• 这里维护的是目录定义（服务端下发、客户端登录后自动同步），凭据只存客户端本地，定义里不含任何密钥。
• 表单字段：编号（创建后不可改，客户端按它匹配本地凭证）、名称、描述、传输方式 （streamable-http 的端点 URL，或 stdio 的 command 与 args / env）、静态请求头、 认证方式（auto / oauth / device / token / server-side）、OAuth 相关端点与 clientId / scopes / 超时。
• 右侧实时生成定义 JSON；也可以直接粘贴一条标准 MCP 配置（type + url，或 command/args/env）导入。
• 每行有启停开关，控制该连接器是否随目录下发给客户端。

服务器信息 /server-info（读 server-info:read）

• 版本与更新提示、运行时长、Go 版本、CPU / GOMAXPROCS / goroutine 数、内存与磁盘占用、数据目录、 数据库引擎与各表行数、迁移版本。
• 模型并发：按模型展示「当前并发 / 90 天峰值 / 目标」与峰值利用率（目标是模型的并发目标参数）， 作为向上游申请扩容的量化依据。
• 审计链校验结论（是否完整、断链位置、校验执行者与次数、结论新鲜度）。
• 余额准入拒绝的累计次数与最近一条被拒记录（谁、依据是什么、差多少钱）。
• 错误监控、OIDC 流程等运行面健康摘要。

审计分区

审计日志 /audit（读 audit:read；保留策略写需 audit:retention:write，仅 super_admin）

• 记录内容：操作者、动作名、目标与明细、时间。覆盖用户与部门变更、角色变更、令牌签发与吊销、余额调整与发放、 网关配置与定价、峰谷窗口、技能与智能体审批/授权/质量标记、能力锁定、连接器、应用处置、 目录同步动作、管理员 MFA 开关、审计保留策略变更等。
• 筛选：动作类型、用户名、时间范围、分页；读取失败时不渲染上一页的行（否则会冒充本次筛选结果）； 导出 CSV 只在本次读取成功时可用。
• 留痕不可篡改：每条记录带 prev_hash 与本条 hash，链输入是 sha256(prev_hash | 操作者 | 动作 | 明细 | 时间)，写入时串行化以避免并发分叉。改动任何一行都会破坏其后所有链节。 服务端每小时校验一次链，结论与”是否新鲜”展示在服务器信息页——过期的校验结论不会被显示成实时结论。
• 保留策略：保留天数可配 1–3650，默认 180。保存时立即清理一次，其后由后台调度器每 6 小时执行一轮。

边界与失败行为

逐页汇总（服务端是唯一护栏，前端禁用只是体验）：

• 用户：不能取消自己的管理员权限、不能禁用自己；删除最后一名 super_admin 会被拒绝（并发场景下用行锁把该检查串行化）。部门树未加载成功时「设置部门」的保存被锁定——否则会用空归属覆盖该用户的全部部门。
• 部门：删除仍有关联（成员 / 子部门 / 授权引用）的部门被拒绝，须先处理关联。
• 认证：配置未加载成功时保存被锁定；用户名字段与目录实际属性不一致时，全量同步会跳过全部用户（单个人工登录仍可能成功，是最容易误判的一种失败）。
• 网关 / 网关文件：取值非法即 400 VALIDATION 且不落盘；高峰时段的存量值无法解析时拒绝保存；全局设置未加载成功时保存锁定；全组织范围的批量清理只允许「已过期」，且必须显式给出条件。
• 错误监控：开关打开而 DSN 为空时，客户端不会上报任何错误（保存前即提示）；配置未加载成功时保存锁定；客户端上报状态读不到时显示「没有数据」，不渲染成「一切正常」。
• 用量中心：发放策略加载失败时写面锁定；流水读取失败不显示旧流水；被余额闸门拒掉的请求不在用量明细里出现（它根本没有转发），只在服务器信息页与日志里留痕。
• 能力中心 / 应用中心：未授权对员工一律 404；「拒绝」与「删除」会释放归档字节且不可恢复，「下架」可恢复；与市场同名的审批被 409 阻断；对已下架应用的版本审批通过会被 409 拒绝，必须先上架。
• 连接器：编号创建后不可改（客户端按它匹配本地凭据）；定义必须能解析为 JSON 对象，否则保存被拒。
• 服务器信息：读不到的字段显示「未知」而不是 0；更新清单的渠道与本部署不一致时按「检查不可用」处理，不显示「已是最新」；审计链校验结论过期时显式标注。
• 审计日志：列表读失败时不保留上一页的行；保留策略读失败时保存按钮锁定；保留天数不是 1–3650 的整数时保存被拒；auditor 能看到日志，但看不到报表订阅（推送地址本身就是凭据）。

模型网关与计费口径

用量与费用的计算

每次模型调用的费用在记录时按下式折算并落库：

cost =（未命中缓存的输入 token / 1e6 × 输入价
      + 缓存命中输入 token / 1e6 × 缓存价
      + 输出 token / 1e6 × 输出价）× 峰谷系数

• 单价单位是元 / 百万 token；缓存价未配置时回退到输入价。
• 峰谷系数按记录时刻判定：命中高峰窗口（北京时间，半开区间）即为 1；窗口外且模型配置了 低谷折扣率（0 < d < 1）时乘 d；没有配置窗口或折扣为 1 时恒为 1。
• token 计数在计费入口统一钳到非负：上游报负数不会产生负费用、也不会变成”费用向下修正”（那会让余额凭空增加）。
• 改价只影响之后产生的费用：历史费用按记录时的定价留存，不会被重算。

余额是唯一闸门

员工侧的额度只有账户余额一种（历史的三套并行额度机制已下线）。网关在转发之前做多层准入：

1. 闸门开关打开、账号已开通余额账户、且分位余额 ≤ 0 → 429 BALANCE_EXHAUSTED；
2. 最小计费额：按服务端自己的 prompt 估算口径算出”这一次最少要花多少”，余额盖不住就不放行；
3. 学到的下限：任何一次结算因余额不足失败，都会把该账号的准入下限抬到当时余额之上 （失败整笔回滚，余额不变，所以不会自我解除）；
4. 未定价模型默认拒绝：输入价为空或 ≤ 0 的模型返回 429 MODEL_NOT_PRICED。 这条默认必须存在——未定价模型成本恒为 0，会让上面三层同时失效。确实免费或自建的模型， 把「未定价模型」策略改成「允许使用」即可，那时费用才按 0 计。

• 管理员豁免，未开通余额账户的员工不适用闸门（存量部署开启闸门不会误拦全员）。
• 被拒的请求不转发给上游、不产生费用、不落账，因此不会留下”花了钱没记账”的中间态。
• 拒绝的可观测痕迹有三处：服务器信息页的累计次数与最近一条被拒记录、结构化日志（按用户节流，带抑制计数）、 以及结算侧的”下限抬升”日志。

账本与发放

• balance_ledger 是追加型流水，按微元记账；不变量是 账户余额 == 流水金额之和，因此每一笔都能对账。
• 单人调整（加 / 扣 / 设为 / 清零）与月度发放都会写流水；人工动作另写审计。
• 月度发放：配置闸门开关、每人每月额度与发放方式。「累加」是在现有余额上加；「覆盖」会清零结余与手工充值， 清零的差额记一条 reset 流水（可追溯）。发放的幂等锚是逐人·月，新入职、漏发、重新启用的员工会被下一轮自动补齐； 发放与闸门解耦（额度 > 0 就发，“拦不拦”由开关单独决定）。

边界与失败行为

• 余额查询失败 fail-closed：读不到余额配置时按”拒绝”处理，不会放行。
• 未定价模型被拒时，网关不会用一个笼统的余额错误顶替它——错误码与文案要能让管理员定位到”该给这个模型配价”。
• 保存网关配置时，服务端会校验取值（限流范围、价格非负、低谷折扣必须在 (0,1]、文件保留天数区间、 高峰时段 JSON 合法性等），非法即 400 VALIDATION 且不落盘。
• 高峰时段配置解析失败时拒绝保存：存量值不是本页认得的形状时，宁可拒绝也不静默清空计费口径。
• 全局设置未加载成功时保存锁定：否则一次读失败会把空值当成新配置提交（典型后果是清空默认模型与峰谷窗口）。
• 上游 4xx 只透传错误消息与类型/码，不透传上游原始响应体。

授权模型

能力中心、共享内容与组织内市场都走同一套授权语义：

• 授权对象 = 用户或部门（部门名大小写不敏感）。一个资源可以同时授权给多个用户与多个部门； 保存”部门授权”是整份覆盖（用户授权不受影响），这是一次显式决定，不是增量追加。
• 生效组是展开后的集合：归属部门 + 其祖先链（授权给上级部门覆盖下级成员）+ 主管的部门子树 （主管自动继承本部门及下级授权）+ 隐式的「全员」组。
• 双门制：先审批通过（内容本身可用），再授权（对具体的人可见可安装）。两门都过才出现在员工的目录里。
• 管理员（super_admin）恒全量，且不写授权表——管理端的可见性不受授权影响。
• 名称冲突：员工上传的内容与市场同名时，审批时用 409 阻断（需先处理市场侧或驳回），不会静默覆盖。
• 能力锁定：管理员可以把某个名称（技能或智能体）锁定，员工不能再用它发布；锁定理由对员工可见， 解除后员工可再次上传。

边界与失败行为

• 未授权一律 404，与”不存在”逐字节同形（对未授权者，“已下架”与”不存在”也是同一个响应）——不泄露资源存在性。
• 授权表读不出来（依赖故障）时返回 500，不得塌成 404：员工若把一次数据库抖动当成”这个技能没了”， 会把它当终态而不重试；且这一面必须与组织侧、市场侧的口径一致。
• 授权变更（授权 / 撤销 / 整份覆盖）都写审计。
• 授权对话框在授权列表读取失败时锁定保存：否则会用空列表覆盖现有授权；资源切换时授权列表必须在渲染期同步归零， 不能残留上一份资源的授权。

品牌与文案为什么不在管理端编辑

名称、标语、欢迎语、标识、主题色、数据根、深链 scheme 等属于渠道内容：它们在构建期由渠道包注入镜像， 随镜像只读下发，客户端登录页、客户端界面、门户页与后台侧栏都从这一份内容取值。

这样设计的原因：品牌是可审计、可复现的构建输入，而不是运行期可变状态——同一个镜像 tag 对应同一套渠道内容， 排障时”线上看到的是什么品牌”不依赖数据库里某个字段当时是多少。因此后台没有任何在线编辑品牌或门户文案的入口 （历史入口已删除）。改品牌 = 改渠道包并重新构建镜像，见渠道与白标。

边界与失败行为

• 后台不提供品牌相关的写接口；试图通过旧书签访问相关页面会落到 404 提示页。
• 渠道内容缺失时，客户端与服务端按内置的默认品牌渲染，不会因此启动失败。

失败排查速查

现象	先看哪里
员工调用模型被拒（429 / 403）	用量中心「请求日志」与「余额」；服务器信息页的”最近一条被拒记录”（谁、依据、差多少钱）；网关页的未定价模型策略与限流
员工登录失败	认证页的启用方式与目录配置；auditor/super_admin 之外的角色不能进后台；限流是”只对失败计数”，5 分钟后自动恢复
目录同步没有建出用户	认证页「用户名字段」是否与目录实际属性一致；测试连接返回的用户样例里 username 是否为空
员工看不到某个技能 / 智能体 / 应用	能力中心「审批」Tab 的状态与「授权」弹窗（未授权 = 员工侧 404）；应用中心的是否已下架 / 冻结
客户端不上报错误	错误监控页：开关是否打开、DSN 是否为空、上报等级；「客户端上报状态」里最近 100 台的初始化结果与原因；用「发送测试事件」验证链路
审计轨迹对不上	审计日志页的筛选与保留天数；服务器信息页的链校验结论是否”新鲜”（过期结论不代表当前状态）
后台某个页面进不去或空白	该账号的权限点（侧栏按权限渲染，服务端 403 才是最终判定）；/admin/ 是否返回”webadmin 未构建”

相关

• 部署与运维：镜像、升级与回滚、数据目录与备份；
• 渠道与白标：品牌与文案的唯一来源；
• 架构总览：三层拓扑与数据流；
• API 参考：管理面 /api/server/*、员工面 /api/client/v2/*、模型网关 /v1/*；
• 桌面客户端：员工侧看到的能力与边界；
• 常见问题。