产品手册

AlphaTrust 客户端与网关的能力说明，以版本说明为准。

项目	说明
产品	AlphaTrust Gateway
适用版本	1.1.2
更新日期	2026/9/16
适用对象	平台管理员、普通用户、交付与运维人员

1. 产品简介

AlphaTrust Gateway 是面向企业大模型使用场景的统一接入、授权、路由、防护、计量和审计平台。企业可以将不同模型服务商、不同业务系统和不同用户的模型调用统一接入 Gateway，由平台集中完成以下工作：

统一管理上游模型服务商、协议地址、上游密钥和模型可用状态。
向下游业务系统或用户发放 AlphaTrust API Key，避免直接暴露上游密钥。
按用户、用户组、API Key、固定模型或智能路由模型控制访问范围。
对请求和响应执行关键词、语义、向量等安全检测。
记录模型调用、平台操作、运行状态、安全告警和智能路由决策。
统计请求数、Token、CNY 消耗、模型费用和系统资源趋势。
通过机器绑定 License 控制功能、资源上限和附加模块。 AlphaTrust 适合多模型统一入口、企业内部模型授权、AI 应用安全治理、模型费用分析和客户侧私有化交付等场景。

2. 用户、授权与导航

2.1 用户角色

角色	主要权限
管理员	管理服务商、模型、用户、用户组、额度、限流、安全策略、License、更新和全局审计数据。
普通用户	查看个人数据看板，管理自己的授权密钥，使用已授权的固定模型或智能路由模型，修改个人密码。

普通用户只能访问与本人相关的数据和资源；管理员可以访问平台级管理页面。具体可见范围还会受到 License 能力控制。

2.2 License 能力与附加模块

Gateway 使用机器绑定的 license.dat 。License 决定版本类型、功能能力、资源上限和附加模块。常见控制项如下：

功能	授权条件
系统资源	system_monitoring
智能路由	smart_routing
会话防护、调用分析和高级检测页签	advanced_security
统一登录	enterprise_sso
操作日志和运行日志	audit_export
浮动网关助手	gateway_chat
用户额度和 API Key 额度	user_quota、api_key_quota
客户端下载	standard_client 附加模块
在线安装更新	online_update 附加模块

当 License 无效、过期、机器不匹配或资源超限时，系统会显示授权异常信息，并限制相应功能或资源扩展。复制机器码和导入新 license.dat 的入口仍会保留，便于恢复授权。

2.3 当前导航

模块	页面	可见范围
首页	数据看板	管理员和普通用户
首页	安全总览	管理员
首页	系统资源	管理员，且需系统监控能力
管控	模型超市	管理员
管控	授权密钥	管理员和普通用户
管控	用户管理	管理员
管控	流量控制	管理员
管控	智能路由	管理员，且需智能路由能力
管控	模型价格	管理员
防护	实时防护	管理员
防护	会话防护、调用分析	管理员，且需高级安全能力
防护	安全设置	管理员；高级页签受 License 控制
审计	模型日志	管理员
审计	操作日志、运行日志	管理员，且需审计能力
设置	基础设置	管理员和普通用户
设置	统一登录	管理员，且需企业统一登录能力
设置	系统信息	管理员
设置	快速上手	管理员和普通用户

页面顶部还可能显示「客户端下载」「帮助与支持」和浮动网关助手。这些入口不属于左侧导航，并分别受附加模块、管理员角色或 License 能力控制。

3. 首次使用

3.1 部署与访问

Gateway 可以作为独立服务或容器化服务部署，也可以由桌面客户端连接远程 Gateway。交付包可能已预置服务地址和管理员账号；未完成本地或远程连接配置时，客户端会进入初始设置向导。常见访问方式：

场景	地址说明
直接运行后端	代理端口默认 18080，管理端口默认 18081
当前容器化交付	Nginx 对外监听 80；/api/ 和 /health 转发到管理端口，/v1/ 和 /anthropic/ 转发到代理端口
远程客户端	填写交付人员提供的 Gateway 管理地址

容器化交付默认不启用 HTTPS 或 443 。如客户环境要求 HTTPS，应由交付或运维结合正式域名、证书和网络边界统一配置，不应使用临时自签名方案替代正式部署。

3.2 登录方式

默认使用本地用户名和密码登录。启用企业统一登录后，登录页可以显示飞书或钉钉认证入口。管理员还可以根据部署条件配置硬件安全密钥，并选择以下本地管理员登录策略：

仅密码登录。
仅硬件安全密钥登录。
密码或硬件安全密钥登录。硬件安全密钥在非本机交付环境中需要固定域名和 HTTPS 支持。

3.3 推荐配置顺序

在「设置 -> 系统信息」确认 License 状态和资源上限。
在「管控 -> 模型超市」添加或检查模型服务商。
同步模型列表，启用允许进入 Gateway 的模型。
在「管控 -> 模型价格」同步价格并检查未计价模型。
在「管控 -> 用户管理」创建用户并分配模型、组织或额度。
在「管控 -> 授权密钥」创建下游 API Key。
在「设置 -> 快速上手」复制 API 地址、API Key 和模型名称。
发起测试调用后，在「审计 -> 模型日志」核对结果。
按需配置安全防护、智能路由、统一登录和在线更新。

4. 核心概念

4.1 服务商实例

服务商实例是对一个上游模型平台或企业自建模型接口的配置。配置内容通常包括：

服务商名称和协议类型。
上游基础地址和各协议端点。
一个或多个上游 API Key。
已同步模型、模型启停状态和可用性。
可选的手工额度、账户余额和协议端点覆盖配置。服务商名称是固定模型 ID 的组成部分。例如服务商名称为 deepseek1 ，模型为 deepseek-chat ，完整模型 ID 为： deepseek1:deepseek-chat AlphaTrust 内置服务商由产品维护，页面不会提供删除入口；客户添加的服务商可按权限编辑、排序或删除。

4.2 模型 ID 与模型别名

固定模型通常使用服务商名称:模型名。Gateway 兼容读取历史的斜杠写法，但新增配置和外部工具应统一使用冒号形式。模型别名可以为真实模型提供稳定、简洁的外部名称。下游通过别名调用时，Gateway 在内部解析真实目标；模型列表也会优先返回别名，减少真实模型拓扑暴露。别名权限与真实模型权限仍由 Gateway 统一校验。

4.3 授权密钥

授权密钥是 Gateway 发给下游业务系统或用户工具的调用凭证，格式为 sk-... 。下游应用只保存 AlphaTrust API Key，不直接持有上游服务商密钥。授权密钥支持：

创建、查看、搜索、筛选、启用、禁用和删除。
绑定允许调用的固定模型和智能路由虚拟模型。
由管理员查看全局密钥，普通用户管理自己的密钥。
在 License 允许时配置有限或无限 CNY 额度，并查看已用、预留和剩余额度。
在标准客户端模块可用时，生成客户端启动配置。请在创建后立即妥善保存密钥，不要在文档、聊天记录、代码仓库或工单中粘贴真实密钥。

4.4 模型权限

模型权限会在多个层级共同生效：

服务商和模型必须处于启用状态。
用户可以继承用户组模型，也可以配置额外模型。
API Key 可以在用户可用范围内进一步收窄模型。
智能路由虚拟模型需要单独授权，不会因为固定模型通配权限而自动获得。企业版可在「用户管理」中维护组织、用户组、用户组默认模型和额度组策略；基础版会隐藏未授权的组织能力，但保留本地用户管理。

4.5 固定模型与智能路由

固定模型调用由下游明确指定服务商名称:模型名。智能路由调用使用虚拟模型，由 Gateway 根据请求偏好、模型能力、价格和运行指标选择实际模型。当前虚拟模型包括：

模型 ID	路由偏好
auto	均衡
auto-quality	任务适配度优先
auto-cost	成本优先
auto-latency	延迟优先

只有处于活动状态并已分配权限的虚拟模型可以用于新授权。被停用的历史虚拟模型不会自动加入新权限，但原有配置会保留，便于管理员处理存量关系。

4.6 模型价格与 CNY 额度

「模型价格」中的价格用于 Gateway 内部消耗计算，可能与服务商官方网站显示的价格不同。AlphaTrust 内置模型价格从 Center 同步；客户自定义服务商只有配置了对应精确价格时才参与 CNY 计费。价格状态包括已计价、Center 缺失、价格异常和未计价。未计价模型仍可调用，但不冻结、不扣减 CNY 额度，日志和统计会保留“未计价”事实，避免将缺价误显示为零成本。

5. 首页

5.1 数据看板

「首页 -> 数据看板」面向业务使用统计。页面支持切换时间范围、Token 视图和内部消费额度视图，展示：

请求数、Token 消耗、活跃用户和活跃模型。
用户、模型和部门维度的趋势及排行。
管理员范围的用户消耗排行和疑似非业务调用线索。
普通用户自己的调用和消耗数据。未计价请求不会被伪装为 CNY 消耗；需要结合模型价格覆盖情况理解额度统计。

5.2 安全总览

「首页 -> 安全总览」用于管理员查看平台安全态势，包括：

请求和告警趋势。
告警等级分布。
高风险调用方。
安全检测 Token 消耗和类型分布。
管理员自己的额度状态。

5.3 系统资源

「首页 -> 系统资源」用于查看 Gateway 所在宿主机的运行资源，包括 CPU、内存、数据磁盘摘要、资源趋势和异常记录。GPU 事件采用持续超阈值和持续恢复判断，短时推理峰值不会直接生成异常事件。该页面需要系统监控能力，且依赖宿主机能够提供相应资源数据。

6. 管控

6.1 模型超市

「管控 -> 模型超市」用于管理服务商、模型和模型别名。服务商视图支持：

添加、搜索、排序、编辑和删除客户服务商。
同步上游模型并批量启用或禁用。
查看服务商启停状态、模型数量、上游 Key 数量和可选余额信息。
查看或调整服务商协议端点。
对单个模型执行启用、禁用和可用性检查。模型别名视图用于创建外部稳定名称并绑定真实模型。修改别名前，应确认下游业务是否已经依赖原名称。

6.2 授权密钥

「管控 -> 授权密钥」用于管理下游调用凭证。管理员可以查看平台密钥，普通用户只管理自己的密钥。创建密钥时需要填写名称，并在当前用户可用范围内选择模型。若启用 API Key 额度能力，还可以配置有限或无限额度。页面支持按名称、状态和模型授权范围筛选，并可批量处理选中的密钥。启用标准客户端模块后，用户可以从页面准备客户端配置；真实 API Key 只应交给明确授权的使用者。

6.3 用户管理

「管控 -> 用户管理」统一承载用户和用户组管理，不再提供独立的左侧「用户组管理」入口。用户管理支持：

新建、搜索、查看、编辑和删除用户。
修改显示名称、组织归属和状态。
重置用户密码。
配置固定模型和智能路由模型权限。
在授权允许时配置用户无限额度、初始额度、增加额度或收回额度。
在企业组织能力可用时维护用户组、组默认模型和额度组优先级。用户额度、API Key 额度和额度组共同参与请求前的额度判断。调整额度前应确认当前已用、预留和剩余金额。

6.4 流量控制

「管控 -> 流量控制」用于设置请求速率限制，防止单个调用方或异常流量占满上游资源。支持的限流维度包括：

全局 RPM。
API Key RPM。
模型 RPM。
服务商 RPM。 License 可以设置这些维度的硬上限。页面保存值不能超过授权上限；请求超过生效限制后，客户端应按响应提示退避重试。

6.5 智能路由

「管控 -> 智能路由」展示 AlphaTrust 内置模型的 Auto 候选状态和路由效果。页面包括：

智能路由请求数、平均延迟、首 Token 时间、实际模型费用、净节省费用和缓存命中率。
候选模型的能力、价格、健康状态、调用样本和 Auto 资格。
对异常模型执行带原因审计的紧急停用或恢复。
最近路由记录中的虚拟模型、实际选择模型、路由依据、性能、Token 和费用。 Auto 候选以 AlphaTrust 内置模型目录、Center 价格和 Gateway 实际运行数据为准。紧急停用只改变临时可用性，不修改模型能力事实、价格或历史记录。

6.6 模型价格

「管控 -> 模型价格」用于从 Center 同步并检查 Gateway 的模型价格目录。页面支持按价格状态筛选、搜索模型、查看输入输出类型以及输入输出价格。同步失败时，Gateway 会保留上次成功同步的价格，并显示同步异常。管理员应优先处理内置模型缺价和无效价格；自定义服务商模型若没有精确价格，会按未计价处理。

7. 防护

7.1 实时防护

「防护 -> 实时防护」用于查看请求链路中的实时安全告警、今日新增、威胁类型和安全引擎状态。管理员可以检索告警并查看命中详情。实时检测可覆盖输入和输出内容，具体执行规则由「安全设置」控制。

7.2 会话防护

「防护 -> 会话防护」用于从会话和调用行为角度识别高风险 API Key、异常用途或非业务调用。页面展示分析状态、高危威胁、会话数量、综合风险和历史记录。该页面需要高级安全能力。

7.3 调用分析

「防护 -> 调用分析」用于创建 API Key 行为分析任务。管理员可以选择 API Key、分析模型和日志范围，启动或停止任务，并查看风险等级、执行历史和结果。分析任务可能消耗模型 Token 和额度，创建周期任务前应确认分析模型、时间范围和执行频率。

7.4 安全设置

「防护 -> 安全设置」包含以下页签：

页签	说明
实时防护配置	控制输入检测、输出检测、放行或拦截方式。
关键词词库	管理风险关键词、分类和白名单。
语义检测	使用模型对内容进行语义安全分类。
向量样本库	维护恶意样本，通过 Embedding 相似度检测风险。
威胁分析配置	设置分析模型、时间范围、调度方式、频率和时区。

基础 License 只显示基础安全页签；语义、向量和威胁分析配置需要高级安全能力。

8. 审计

8.1 模型日志

「审计 -> 模型日志」用于查询模型调用记录。页面支持按时间、关键词、状态和调用类型筛选，并可导出 CSV。展开日志后可以查看请求路径、状态码、调用身份、模型、服务商、Token、价格状态、路由信息以及按权限返回的请求和响应详情。日志适合用于：

排查调用失败或协议兼容问题。
确认 API Key、用户和模型权限是否生效。
核对固定模型或智能路由的实际目标。
区分已计价和未计价请求。
复盘安全告警和异常调用。

8.2 操作日志

「审计 -> 操作日志」记录平台内的重要管理动作，例如用户、API Key、服务商、模型和配置变更。管理员可据此追踪谁在何时修改了什么资源。

8.3 运行日志

「审计 -> 运行日志」展示 Gateway 运行过程中的日志，支持按日志级别查看，主要用于运维排查。运行日志可能包含系统路径、错误上下文等内部信息，不应直接对外公开。

9. 设置

9.1 基础设置

「设置 -> 基础设置」分为「配置」和「账户」页签。管理员可以：

调整日志级别。
保存、切换、重命名和删除配置方案。
导出或恢复 Provider、模型映射、系统、安全和限流配置。
重置平台配置。管理员和普通用户都可以在「账户」页签修改自己的密码。配置备份可能包含上游密钥等敏感信息，必须加密保存并限制访问。恢复配置会覆盖现有配置；端口、监听地址或 TLS 等部署级变更仍可能需要由交付人员重新部署后生效。

9.2 统一登录

「设置 -> 统一登录」用于配置飞书网页应用或钉钉 OAuth 登录。管理员可以设置组织根名称、客户端标识、客户端密钥、回调地址，并决定是否启用或显示在登录页。同一页面还管理本地管理员登录策略和硬件安全密钥。配置统一登录前，应在身份平台登记页面显示的回调地址，并确保外部访问地址与实际部署一致。

9.3 系统信息

「设置 -> 系统信息」集中展示部署激活、授权信息和系统更新。

授权信息

授权页支持：

复制本机机器码。
导入或替换机器专属 license.dat 。
查看客户、产品、授权版本、到期时间、License ID 和签发 Key。
查看能力、附加模块和用户/API Key/模型资源使用量。
查看并发、全局 RPM、API Key RPM、模型 RPM 和服务商 RPM 上限。
查看机器绑定摘要和授权文件摘要。

Gateway 部署激活

配置 Center 地址后，管理员可以激活当前 Gateway deployment，并查看 Deployment ID、设备 ID、客户归属和绑定状态。基础版和企业版都可以执行激活、心跳和检查更新；在线安装还需要 online_update 附加模块。

系统更新

系统更新页展示当前版本、更新通道、最新可用版本、更新准备状态和版本说明。安装按钮只有在以下条件满足时才可用：

Gateway 已配置并激活更新中心。
更新清单已通过签名校验。
宿主机 updater 已按文件任务模式准备完成。
License 包含在线更新附加模块。
当前没有待处理更新任务。更新由宿主机 updater 拉取镜像、切换服务并执行健康检查；失败时按交付配置回滚。数据库迁移不保证自动逆向回滚，涉及重要数据时应在更新前完成备份。 9.4 快速上手「设置 -> 快速上手」会根据当前账号和配置状态显示完成进度。管理员的必要步骤是添加服务商、创建授权密钥和复制接入配置；普通用户的必要步骤是确认可用模型、创建个人密钥和复制接入配置。页面会自动显示当前 Gateway 的 API 地址和一个可用模型示例。

10. 其他入口

10.1 网关助手

当 License 包含 gateway_chat 时，页面右下角显示浮动网关助手。它使用当前用户已授权模型，适合进行简单对话和连通性验证。旧版「能力 -> 对话聊天」路由已统一跳转到当前首页，不再作为独立导航模块。

10.2 客户端下载

当 License 包含 standard_client 附加模块时，页面顶部显示「客户端下载」。用户可以查看平台、架构、版本和校验信息，下载由 Center 发布的标准客户端。安装客户端后，可在授权密钥页面准备启动配置。下载文件后应核对页面提供的校验信息，不要使用来源不明的安装包。

10.3 帮助与支持

管理员可以通过页面顶部的「帮助与支持」提交系统问题或充值申请，并在「工单记录」中查看历史工单和详情。提交工单时不要附带真实 API Key、上游密钥、数据库密码、完整 license.dat 、私钥或其他敏感凭据。必要日志应先脱敏。

11. 外部系统接入

11.1 接入所需信息

大多数下游工具只需要三项配置：

配置项	示例
API 地址	http://gateway.example/v1
API Key	sk-...
模型名称	服务商名称:模型名、模型别名或已授权的智能路由虚拟模型

认证支持： Authorization: Bearer sk-... 部分 Anthropic 客户端也可以使用： x-api-key: sk-...

11.2 协议与路径

能力	路径
OpenAI Chat Completions	/v1/chat/completions
OpenAI Responses	/v1/responses
OpenAI Embeddings	/v1/embeddings
OpenAI 模型列表	/v1/models
Anthropic Messages	/v1/messages 或 /anthropic/v1/messages
图像生成	/v1/images/generations
视频生成与任务查询	/v1/videos/generations 及对应任务路径

模型列表会按当前 API Key 权限返回可用模型；配置别名时优先返回别名。图像、视频、Embedding、Responses、工具调用和流式输出是否可用，还取决于目标服务商协议和模型能力。

11.3 直接运行与容器地址示例

直接运行后端时： OpenAI Base URL: http://服务器IP:18080/v1 Anthropic Base URL: http://服务器IP:18080 管理页面: http://服务器IP:18081/admin/ 当前容器化交付通过 Nginx 统一暴露时： OpenAI Base URL: http://服务器地址/v1 Anthropic Base URL: http://服务器地址管理页面: http://服务器地址/ 实际地址以交付环境为准。不要在客户端中填写后端容器内部端口或数据库地址。

12. 部署、数据库与授权

12.1 数据库

Gateway 支持以下数据库：

数据库	适用说明
SQLite	默认模式，适合单机、试用和轻量部署。数据文件位于 Gateway 持久化数据目录。
PostgreSQL	适合正式环境和独立数据库部署，由交付配置数据库类型和连接信息。

不要通过复制正在运行的 SQLite 文件或直接修改数据库表完成日常配置。数据库迁移、备份和恢复应使用经过验证的交付流程，并在执行前确认回滚方案。

12.2 持久化数据

容器部署必须持久化 /opt/alphatrust-gateway/data ，其中包含配置、数据库、设备身份、License 和其他运行数据。删除或错误覆盖该目录可能导致配置丢失、设备身份变化或 License 失效。

12.3 机器码与 license.dat

授权流程：

在「设置 -> 系统信息 -> 授权信息」复制机器码。
将机器码提交给授权签发方。
获取该机器专属的 license.dat 。
在授权页上传文件。
确认授权状态、到期时间、功能能力和资源上限。机器码依赖宿主机设备身份。容器部署必须复用宿主机持久化的设备身份文件，不得把临时容器 hostname、容器 ID 或 Docker 网卡当作正式设备身份。旧版明文 JSON License 上传入口已停用。新安装、换证和恢复授权均使用 license.dat ，不要向客户交付新的 alphatrust.license.json 。

12.4 在线更新安全边界

在线更新采用签名清单和宿主机 updater。Gateway 业务容器不直接获得 Docker 控制权限；镜像拉取、切换、健康检查和回滚由宿主机组件执行。更新前应确认：

License 有效且包含在线更新附加模块。
当前数据库和数据目录已完成必要备份。
更新源、验签公钥和镜像范围由交付配置，不在页面临时修改。
当前服务没有未完成的更新任务。

13. 常见使用路径

13.1 新增一个模型服务商

进入「管控 -> 模型超市」。
点击「添加服务商」。
选择协议类型，填写名称、上游地址和 API Key。
保存后同步模型。
启用需要开放的模型。
必要时配置协议端点或模型别名。
在「模型价格」确认计价状态。

13.2 给业务系统创建调用凭证

进入「管控 -> 授权密钥」。
点击创建密钥并填写用途明确的名称。
选择允许调用的固定模型或智能路由模型。
按需配置 API Key 额度。
创建后安全交付 sk-... 。
在模型日志中确认首次测试调用。

13.3 外部工具接入

在「设置 -> 快速上手」复制 API 地址。
使用授权密钥页面创建的 sk-... 。
模型填写服务商名称:模型名、模型别名或智能路由虚拟模型。
根据客户端选择 OpenAI 或 Anthropic Base URL。
发起调用并在数据看板、模型日志中确认记录。

13.4 排查调用失败

确认 API Key 处于启用状态且额度充足。
确认用户和 API Key 都拥有目标模型权限。
确认服务商和目标模型已启用。
在模型日志查看状态码、请求路径和错误详情。
检查是否命中流量限制或安全拦截。
智能路由调用还需确认虚拟模型权限和候选模型健康状态。

13.5 排查 License 异常

进入「设置 -> 系统信息 -> 授权信息」。
查看状态码、到期时间和机器绑定信息。
机器不匹配时，复制当前机器码重新签发。
授权过期或能力缺失时联系授权方换证。
资源超限时，先禁用或删除不再使用的用户、API Key 或模型。

14. 使用与安全建议

上游服务商密钥只在模型超市维护，不直接分发给业务系统。
不同业务、环境和团队使用独立 API Key，便于统计、限额和回收。
模型、智能路由和额度权限按最小必要范围开放。
配置安全拦截前，先在检测模式观察命中，再逐步启用阻断。
定期检查模型价格同步和未计价请求，避免额度统计口径被误解。
配置备份、数据库备份、License 和更新材料按敏感文件管理。
对外提供服务时使用正式域名和 HTTPS，并限制管理 API 的网络访问范围。
不在日志、工单、截图或代码仓库中泄露 API Key、数据库密码、授权文件和私钥。