运维配置
Root 配置系统模式、模型性能指标、邮件发送（SMTP / Resend）与余额提醒、Worker、日志维护、性能保护和版本检查。
运维配置位于 /system-settings/operations，仅 Root 可访问。
运维配置简介
该工作区包含「系统行为」「模型性能指标」「邮件与通知」「Worker 代理」「日志维护」「性能」和「系统维护」七个分区。用于配置系统模式、模型性能指标、邮件发送与余额提醒、Worker、日志维护、性能保护和版本检查。
| 分区 | 入口 | 主要用途 |
|---|---|---|
| 系统行为 | /system-settings/operations/behavior | 侧边栏默认偏好、演示站与自用模式。 |
| 模型性能指标 | /system-settings/operations/alerts | 模型性能指标的记录、刷库与保留。 |
| 邮件与通知 | /system-settings/operations/email | 邮件发送方式（SMTP / Resend）与余额不足提醒。 |
| Worker 代理 | /system-settings/operations/worker | 指定下载与通知链路的外部代理。 |
| 日志维护 | /system-settings/operations/logs | 消费日志开关、用户日志导出与查询范围、数据库日志与服务器文件清理。 |
| 性能 | /system-settings/operations/performance | 请求体缓存、资源保护和进程统计。 |
| 系统维护 | /system-settings/operations/update-checker | 版本信息与更新检查。 |
注意
日志删除、缓存清理和强制 GC 都是即时运维操作，不属于可撤销的表单草稿。执行前先确认目标、影响范围和恢复方案，并避免在高峰期反复操作。
配置分区
运维域下有七个独立分区：
系统行为
- 运维-系统行为配置
系统行为分区包含三个开关：
| 页面字段 | 配置键 | 默认值 | 实际作用与边界 |
|---|---|---|---|
| 默认折叠侧边栏 | DefaultCollapseSidebar | false | 界面说明为「默认情况下为新用户折叠侧边栏」。 |
| 演示站点模式 | DemoSiteEnabled | false | 界面说明为「启用功能受限的演示模式」。 |
| 自用模式 | SelfUseModeEnabled | false | 未设置价格的模型按默认倍率 37.5 计费并出现在模型列表中，不再因未定价被拒绝；登录页隐藏「注册」链接，但不关闭注册接口。 |
模型性能指标
- 运维-模型性能指标配置
模型性能指标从 Relay 请求完成和计费链路收集模型、分组、请求耗时、首 Token 时间、成功率、输出 Token 和生成耗时，用于模型广场等性能展示。
| 页面字段 | 配置键 | 默认值 | 行为与边界 |
|---|---|---|---|
| 启用模型性能指标 | perf_metrics_setting.enabled | true | 控制是否继续记录 Relay 性能样本。关闭后不会新增样本，刷库循环也会跳过写库和过期清理；已有数据库记录与关闭前的内存聚合桶不会立即清空。 |
| 刷库间隔（分钟） | perf_metrics_setting.flush_interval | 5 | 最小值为 1，控制把已完成的内存聚合桶写入数据库以及执行过期数据清理的循环周期，不是前端图表刷新频率。 |
| 聚合时间桶 | perf_metrics_setting.bucket_time | hour | 可选 1 分钟、5 分钟和 1 小时；修改后只影响后续样本的分桶。 |
| 保留天数 | perf_metrics_setting.retention_days | 0 | 0 表示永久保留；正数会在刷库循环中清理更早的性能指标。 |
操作流程：
- 按数据量选择是否记录模型性能指标、刷库间隔、聚合时间桶与保留天数，然后保存。
- 检查性能指标时注意：处理本次查询的节点会直接合并其内存中尚未刷库的数据，但多实例部署时，其他节点的样本要等其刷库后才可见，模型广场还会缓存约 1 分钟；不能用保存后的即时空图判断失败。
提示
选择较细的桶或较短的刷库间隔会增加内存、数据库和后台写入负载，应结合模型数量、分组数量和请求量评估。
邮件与通知
- 运维-邮件与通知配置
系统邮件用于注册验证码、密码重置、用户通知和其他系统邮件，可通过 SMTP 或 Resend API 发送；本分区还包含余额不足提醒。
- 邮件发送方式
「邮件发送方式」（EmailProvider，默认 smtp）可选 SMTP 或 Resend API。只用所选方式发送邮件，另一种方式的配置会保留；所选方式发送失败时不会改用另一种。页面只显示所选方式的字段，保存时最后才写入发送方式，同一次保存中其他配置写入失败时不会切换。
- SMTP
选择 SMTP 时，主要配置键如下：
| 页面字段 | 配置键 | 默认值或格式 | 说明 |
|---|---|---|---|
| SMTP 主机 | SMTPServer | 空 | SMTP 提供商的主机名或 IP。 |
| 端口 | SMTPPort | 587 | 常用端口包括 25、465 和 587。 |
| 跳过 SMTP TLS 证书验证 | SMTPInsecureSkipVerify | false | 允许自签名或主机名不匹配的 SMTP 证书。 |
| 用户名 | SMTPAccount | 空 | 用于与 SMTP 服务器进行身份验证的账户。 |
| 密码 / 访问令牌 | SMTPToken | 不回显 | 留空以保留现有凭证。 |
| SMTP 加密方式 | SMTPSSLEnabled、SMTPStartTLSEnabled | 均关闭 | 选择一种 SMTP 传输加密方式；可选'无加密'、'SSL/TLS'、'STARTTLS'。 |
| 强制 AUTH LOGIN | SMTPForceAuthLogin | false | 强制使用 AUTH LOGIN 方法进行 SMTP 认证。 |
| 发件地址 | SMTPFrom | 空；只能是邮箱地址或留空 | 只填纯邮箱地址，例如 noreply@example.com；留空时使用「用户名」。收件人看到的发件人名称固定为系统名称，不能在此设置。 |
- 传输加密模式
| 模式 | 行为与建议 |
|---|---|
| 无加密 | 通常建立明文 SMTP 连接；端口 465 且未启用 STARTTLS 时仍按下述兼容规则使用隐式 TLS。明文连接只适合受控内网或明确要求该模式的服务。 |
| SSL/TLS | 建立隐式 TLS 连接。即使没有显式选择，端口为 465 且未启用 STARTTLS 时，当前后端也会使用隐式 TLS。 |
| STARTTLS | 先建立普通 SMTP 连接，再要求服务器支持并升级到 STARTTLS；服务器未声明 STARTTLS 时发信失败。 |
- Resend API
选择 Resend API 时显示以下字段：
| 页面字段 | 配置键 | 默认值或格式 | 说明 |
|---|---|---|---|
| 发件邮箱地址 | ResendFrom（地址部分） | 空；必须是有效邮箱 | 域名须已在 Resend 完成验证。 |
| 发件人名称 | ResendFrom（名称部分） | 空 | 收件人看到的发件人名称，留空时使用「系统名称」；不能包含换行。保存时与地址合并为 "名称" <地址> 存入 ResendFrom。 |
| Resend API 密钥 | ResendApiKey | 不回显 | 留空以保留现有密钥；从未配置过密钥时必须填写，否则提示「请先配置 Resend API 密钥，再启用 Resend」。 |
Resend 为当前发送方式时，后端会拒绝把密钥或发件地址改成无效值。
提示
SMTP 连接和 Resend 请求（https://api.resend.com/emails）都由后端直接发出，不经过 Worker 代理或 URL SSRF 校验；Resend 拒绝发送时，具体原因只写入服务端日志。生产环境应确认 DNS、端口、证书、认证、SPF、DKIM、DMARC 和发件人策略。
- 配置流程
- 选择发送方式。SMTP 需从邮件服务商获取主机、端口、认证账号和授权码或密码，不要把 Web 邮箱登录地址填入主机字段；Resend 需准备已在 Resend 完成验证的发件域名和 API 密钥。
- 使用 SMTP 时，按服务商要求选择 SSL/TLS 或 STARTTLS，填写纯邮箱发件地址。除已评估的内部场景外，不启用跳过证书验证。
- 填写新 Token 并保存；不轮换凭证时保留输入框为空。
- 余额不足提醒
| 页面字段 | 配置键 | 默认值 | 说明 |
|---|---|---|---|
| 余额不足提醒 | QuotaRemindEnabled | true | 界面说明为「用户余额低于阈值时，通过其选择的通知方式提醒」，实际只在一次扣费跨过阈值时提醒（见下文）。关闭后全站不发送余额提醒。 |
| 默认提醒阈值 (USD) | QuotaRemindThreshold | 1000（内部 quota） | 仅在开关开启时显示。括号内随「显示模式」变为 USD、CNY、自定义符号或 Tokens；按显示金额输入，保存时换算为内部 quota 单位。例如默认值 1000 quota 在 USD 显示下为 0.002。 |
Relay 结算链路会分别检查钱包和订阅额度：钱包按 UserQuota - (quota + preConsumedQuota) 比较，订阅按订阅总额减已使用量比较。只有本次扣费使余额从阈值及以上降到阈值以下时才提醒一次；余额已低于阈值时不再重复提醒，充值回到阈值及以上后才可能再次提醒。
操作流程：
- 根据计费与支付配置中的「显示模式」设置默认提醒阈值。
提示
- 异步发送余额不足通知。用户在个人资料中关闭「余额不足提醒」时不发送；用户设置的非零提醒阈值优先于此全局值。
- 通知方式由用户设置决定，可以是邮件、Webhook、Bark 或 Gotify；未选择时默认使用邮件。通知失败会写入系统错误日志。
Worker 代理
- 运维-Worker 代理配置
Worker 代理用于源码中明确接入的服务端外部请求链路，例如远程文件或图片下载、用户 Webhook，以及 Bark 和 Gotify 通知。它不是渠道 Relay、支付、OAuth 或所有出站流量的通用代理。
| 页面字段 | 配置键 | 默认值或校验 | 行为 |
|---|---|---|---|
| Worker URL | WorkerUrl | 空；非空时必须以 http:// 或 https:// 开头 | 保存时移除末尾 /；非空时请求将被转发到此 Worker。 |
| Worker 访问密钥 | WorkerValidKey | 不回显 | 随 Worker 请求发送，用于与 Worker 进行身份验证。留空以保留现有密钥。 |
| 允许 HTTP 图像请求 | WorkerAllowHttpImageRequestEnabled | false | 界面说明为「当代理通过 HTTP 获取图像的 worker 时启用」。 |
- 配置与停用
- 准备受控的 Worker 服务，确认其接受 New API 的请求格式并校验访问密钥，再填写 URL 与密钥。
- 按目标资源的协议决定是否允许 HTTP，点击「保存 Worker 设置」。
- 停用时清空 Worker URL 并保存，已保存的访问密钥会一并清除；若同时在密钥框输入了新值，则保存为该新值。仅清空密钥输入框但保留 URL，不会清除旧密钥。
提示
- Worker 负载可能携带目标 URL、请求头、通知内容和认证信息。
WorkerValidKey作为请求 JSON 的key字段发送，是否校验由 Worker 实现决定；New API 不使用它验证 Worker 响应，也不能用它替代目标 URL 的访问控制。- 普通下载、Webhook 和通知链路仍会在进入 Worker 前使用相应的 SSRF 校验，但 Worker URL 本身是 Root 配置的外部信任边界。
注意
只使用由你控制并能审计日志的 Worker。启用 Worker 后，敏感通知或远程资源请求可能经过该服务；确认其 TLS、密钥验证、日志脱敏、超时、目标过滤和数据保留策略。
日志维护
- 运维-日志维护配置
日志维护分为记录配额使用量、日志查询与导出、清理历史日志和服务器日志管理。两种清理影响不同的数据源。
- 记录配额使用量
- 「记录配额使用量」对应
LogConsumeEnabled，默认开启。 - 它控制是否创建逐请求的消费日志，包括普通 Relay 和异步任务结算产生的消费记录。
- 关闭后会减少数据库写入，但使用日志、消费统计、数据看板统计和依赖这些记录的分析将缺少新数据。
- 调整开关后点击「保存日志设置」。
提示
该开关只控制消费日志：不会停止错误、充值、系统或退款日志，不影响审计日志，也不会关闭服务器文本日志、Midjourney 任务表或异步任务表。
- 日志查询与导出
| 页面字段 | 配置键 | 默认值或校验 | 行为与边界 |
|---|---|---|---|
| 允许用户导出日志 | log_setting.user_export_enabled | true | 用户可以在使用日志页面下载自己的日志。管理员始终可以导出。关闭后普通用户的导出请求会被拒绝。 |
| 日志最长时间范围（天） | log_setting.max_range_days | 365；整数，最小 1 | 用户在日志和数据看板中一次最多能查看的时间范围，也是每次导出的最长时间范围。未指定开始时间时按该范围回溯，超出时报错。每次导出都受此限制，管理员查询日志不受限。 |
两项与「记录配额使用量」共用「保存日志设置」按钮。
- 清理历史日志
清理作用于执行节点连接的 LOG_DB，移除所选时间戳之前创建的所有日志条目。
- 先归档必要数据，在日期与时间控件中选择截止时间，或使用「24 小时前」「7 天前」「30 天前」快捷项。
- 点击「清理日志」，在确认框中确认删除；系统会创建 log_cleanup 系统任务。
- 观察进度与已处理数量。任务处于待执行或运行中时，页面不会再发起同类任务；关闭页面不等于取消后台清理。
- 成功时显示删除数量或“没有匹配日志”的提示；失败时查看任务错误。
| 任务状态 | 含义与处理 |
|---|---|
pending | 等待运行器领取；长期等待时检查 Master 实例和系统任务运行器。 |
running | 正在清理并更新进度，不要重复发起。 |
succeeded | 本次任务完成。 |
failed | 查看错误并检查日志库与运行器；已完成的删除不会自动恢复。 |
提示
- 此操作不会清理
quota_data聚合数据、性能指标、审计日志、绘图与异步任务记录，也不会删除服务器上的日志文件。 - 多个节点共享日志库时，删除会影响共同的日志历史，不能把它当作只清理某一个节点的日志。
- 服务器日志管理
服务器日志管理只在配置了日志目录时可用，并且只扫描该目录下名称匹配 oneapi-*.log 的文件。
可查看服务器日志目录、日志文件数、日志总大小和时间范围；服务器日志提供两种清理方式：
- 按数量：按文件名（含时间戳）从新到旧保留最近 N 个文件，删除其余日志文件。
- 按天数：保留最近 N 天，删除修改时间早于 N 天前的日志文件。
注意
数据库日志和服务器日志文件的删除不可恢复。清理前确认审计、争议处理、支付、合规和故障排查所需的留存周期，并完成必要的数据库或日志归档。
性能
- 运维-性能配置
性能分区同时管理请求体磁盘缓存、请求体内存缓存和系统性能监控。
- 请求体磁盘缓存
启用后，达到阈值且未超过当前缓存容量边界的大请求体或文件数据会临时存到磁盘，以减少内存占用；不满足条件时继续使用内存。
| 页面字段 | 配置键 | 默认值或校验 | 行为与边界 |
|---|---|---|---|
| 启用磁盘缓存 | performance_setting.disk_cache_enabled | false | 启用磁盘缓存后，大请求体将临时存储到磁盘而非内存，可显著降低内存占用。建议在 SSD 环境下使用。 |
| 磁盘缓存阈值 (MB) | performance_setting.disk_cache_threshold_mb | 10 MB；最小 1 MB | 请求体超过此大小时使用磁盘缓存 |
| 磁盘缓存最大总量 (MB) | performance_setting.disk_cache_max_size_mb | 1024 MB；最小 100 MB | 按当前进程统计判断“现有用量 + 新请求大小”是否超过该值；它不是操作系统磁盘配额。 |
| 缓存目录 | performance_setting.disk_cache_path | 空 | 留空使用系统临时目录下的 new-api-body-cache；非容器环境可编辑，容器环境不显示此字段，应通过挂载和容器存储策略管理。 |
- 系统性能监控
系统性能监控默认开启。后台约每 5 秒采集 CPU、内存和缓存目录所在磁盘的使用率；CPU 和内存优先按容器 cgroup 配额计算，取不到时使用宿主机数值。当某个阈值大于 0，且连续 3 次采样（约 15 秒）的整数使用率都严格高于阈值时，新 Relay 请求会被拒绝并返回 HTTP 503；任一次采样回落即恢复。关闭监控或调高阈值后立即放行，采样超过 30 秒未更新时也不拒绝。
| 页面字段 | 配置键 | 默认值或校验 |
|---|---|---|
| 启用性能监控 | performance_setting.monitor_enabled | true |
| CPU 阈值 (%) | performance_setting.monitor_cpu_threshold | 90；前端最小值 0，没有前端最大值限制 |
| 内存阈值 (%) | performance_setting.monitor_memory_threshold | 90；0–100 |
| 磁盘阈值 (%) | performance_setting.monitor_disk_threshold | 95；0–100 |
提示
- 资源保护使用周期性快照，不是排队或自动扩容系统。启用后通常每 5 秒更新一次；
- 资源保护中间件挂载在 Playground、
/v1（含视频生成）、Gemini（/v1beta）、Midjourney 和任务插件等 Relay 路径，不影响登录、普通管理 API 或全部后台任务。
- 性能统计与操作
页面显示处理该请求的节点上的磁盘／内存缓存用量和命中次数、活动缓存数量、缓存目录文件、磁盘空间、Go 内存以及 Goroutine 数量，并提供以下操作：
| 操作 | 实际影响 |
|---|---|
| 刷新统计 | 重新获取处理该请求的节点的统计信息。 |
| 清理不活跃缓存 | 删除缓存目录中修改时间超过 10 分钟的普通文件。实现只按文件修改时间判断，没有额外核对文件是否仍被请求引用；高峰期或存在长时间请求时应谨慎执行。 |
| 重置统计 | 只清零磁盘和内存缓存命中次数，不清空活动缓存、当前用量或目录文件。 |
| 执行 GC | 在处理该请求的节点上立即调用垃圾回收，可能造成短暂延迟抖动。 |
提示
这些统计和操作只作用于处理该请求的节点，不会自动遍历其他节点。
- 配置与操作顺序
- 根据实例的磁盘空间和请求体大小设置缓存阈值与最大总量；不要把最大缓存值当作已经预留的磁盘空间。
- 设置资源保护阈值并保存；按每个维度的单位和范围填写，不把 CPU 校验范围套用到内存或磁盘。
- 先使用「刷新统计」观察用量，再按需要单独执行「清理不活跃缓存」「重置统计」或「执行 GC」。
- 多实例部署要分别检查目标节点。缓存清理不可恢复，重置命中次数也不能代替释放缓存或清理日志。
系统维护
- 运维-系统维护配置
系统维护分区展示 /api/status 返回的当前版本和进程启动时间，并允许浏览器检查 GitHub Release。
点击「检查更新」打开「系统更新」对话框，浏览器直接请求：
https://api.github.com/repos/QuantumNous/new-api/releases?per_page=100请求超时为 10 秒。页面忽略草稿和无法解析版本号的标签，按版本号（同一版本号下从低到高依次为 alpha、beta、rc、正式版、patch）选出最新的一个，预发布版也参与比较并标注「预发布版」；只有最新版本高于当前版本、且该版本未被忽略时，才显示「可更新」。对话框可「重新检查」「忽略该版本提醒」（只记录在当前浏览器）或「前往 GitHub」。Admin 及以上角色登录后，页头的版本号也是同一入口，页面可见且在线时浏览器每小时自动检查一次。
注意
更新检查不会下载代码、验证升级兼容性、替换二进制、拉取镜像、迁移数据库、重建容器、重启服务或自动回滚。查看 Release 后，应按照实际部署方式制定备份、测试、升级和恢复流程。
保存与生效
保存方式见系统设置概览，生效与多实例同步规则见生效范围与多实例同步，浏览器何时显示新值见前端显示与缓存。未特别说明时，保存后处理该请求的节点立即使用新值，其他节点随系统设置同步（默认 60 秒）；各配置项读取新值的时机如下：
系统行为与性能指标
| 配置项 | 保存方式 | 生效时机 |
|---|---|---|
| 默认折叠侧边栏 | 页头「保存更改」 | — |
| 演示站点模式 | 页头「保存更改」 | 用户界面刷新页面后按新设置显示。 |
| 自用模式 | 页头「保存更改」 | 下一次请求起，未设置价格的模型按默认倍率计费并出现在模型列表中；登录页的「注册」链接刷新页面后变化。 |
| 启用模型性能指标 | 页头「保存更改」 | 下一个请求起开始或停止记录样本；关闭后，刷库循环从下一轮起跳过写库和过期清理。 |
| 刷库间隔（分钟） | 页头「保存更改」 | 当前这一轮等待结束后，才按新间隔执行。 |
| 聚合时间桶 | 页头「保存更改」 | 只影响之后记录的样本，已有数据的分桶不变。 |
| 保留天数 | 页头「保存更改」 | 下一轮刷库时按新天数清理过期数据。 |
邮件、通知与 Worker
| 配置项 | 保存方式 | 生效时机 |
|---|---|---|
| 邮件发送方式、SMTP 和 Resend 配置 | 页头「保存更改」 | 下一封邮件发送时读取。 |
| 余额不足提醒、默认提醒阈值 (USD) | 页头「保存更改」 | 下一次扣费结算时判断，用户个人设置的阈值优先；个人设置页显示的默认值刷新页面后更新。 |
| Worker URL、Worker 访问密钥、允许 HTTP 图像请求 | 「保存 Worker 设置」 | 下一次远程文件下载、Webhook、Bark 和 Gotify 通知请求起。 |
日志与清理
| 配置项 | 保存方式 | 生效时机 |
|---|---|---|
| 记录配额使用量 | 「保存日志设置」 | 关闭后，之后的请求不再写入消费日志，已有日志不变。 |
| 允许用户导出日志、日志最长时间范围（天） | 「保存日志设置」 | 服务端在每次导出和查询时按新设置校验；用户界面的导出按钮和默认范围刷新页面后更新。 |
| 清理日志 | 确认后创建系统任务，不经过保存按钮 | 由 Master 实例执行：处理该请求的节点是 Master 实例时立即开始，否则约 15 秒内开始；清理执行节点连接的日志库。 |
| 服务器日志清理 | 确认后立即执行 | 只作用于处理该请求的节点的日志目录。 |
性能与资源保护
| 配置项 | 保存方式 | 生效时机 |
|---|---|---|
| 磁盘缓存的开关、阈值、最大总量和目录 | 页头「保存更改」 | 保存后立即应用到运行配置，之后缓存的请求体按新设置处理。 |
| 性能监控的开关和阈值 | 页头「保存更改」 | 关闭监控或调高阈值后，下一个请求起即放行；开启监控或调低阈值后，需连续 3 次采样（约 15 秒）都超过阈值，才开始拒绝新的 Relay 请求。 |
| 清理不活跃缓存、重置统计、执行 GC | 确认后立即执行，不经过保存按钮 | 只作用于处理该请求的节点。 |
补充说明
- 没有改动：模型性能指标和性能没有改动时提示「没有需要保存的更改」。
- 系统维护：没有保存按钮，只显示当前版本、启动时间和更新检查。
注意事项
- 即时运维操作不可撤销：日志清理、服务器日志清理、缓存清理、重置统计和执行 GC 都没有可撤销的草稿，见日志维护和性能。
- 日志清理影响共享的日志库：清理作用于执行节点连接的日志库，多个节点共享日志库时影响各节点的日志历史，见日志维护。
- 资源保护会拒绝新的 Relay 请求：阈值被连续采样超过时，新的 Relay 请求返回 HTTP
503，登录和普通管理接口不受影响；阈值过低会拒绝正常请求，见性能。 - 保存成功不代表连接成功：保存邮件配置时不测试连接，见邮件与通知。
- SMTP 和 Resend 不经 Worker：两者都由后端直接发出，不经过 Worker 代理或 URL SSRF 校验，见邮件与通知。
- 余额不足提醒失败不影响扣费：提醒在结算后异步发送，发送失败只写入系统错误日志，见邮件与通知。
常见问题
相关文档
这篇文档对您有帮助吗？
最后更新于