next-ai-draw-io 管理面板详解通过 Web 界面管理服务端模型、配额与可观测性配置【免费下载链接】next-ai-draw-ioA next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.项目地址: https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io本文基于仓库文档 docs/cn/admin-panel.md 展开讲解 next-ai-draw-io 的 Web 管理面板/admin如何用ADMIN_PASSWORD启用面板、在面板中配置 AI 提供商与通用设置、设置如何写入data/settings.json并以「面板 环境变量 内置默认值」的优先级覆盖process.env以及密钥掩码、只读降级、可写性检查等安全机制的源码实现帮助你在不改动部署环境变量的前提下完成服务端配置管理。启用面板ADMIN_PASSWORD 与认证机制启用方式非常简单对应文档中的「启用面板」一节设置ADMIN_PASSWORD环境变量不设置则面板禁用访问/admin并登录。在 env.example 中可以看到这两个相关的引导变量# ADMIN_PASSWORDyour-admin-password # SETTINGS_FILE./data/settings.json # Optional: custom settings file location认证逻辑集中在 lib/admin/auth.ts 的checkAdminAuth中所有/api/admin/*路由设置读写、提供商读写、模型测试都先调用它ADMIN_PASSWORD未设置时直接返回 403提示 Admin panel is disabled——即不设置密码 面板整体禁用而不是回退到公开访问请求需携带x-admin-password请求头前端封装在 admin-shared.ts 的adminFetch中比较使用crypto.timingSafeEqual做恒定时间比对避免时序侧信道。前端登录页位于 app/[lang]/admin/page.tsx登录成功后密码保存在浏览器sessionStorage键名next-ai-draw-io-admin-password刷新页面时自动恢复会话未保存修改时通过beforeunload弹出离开警告。可配置内容一Models模型与提供商面板第一个区块是Models。你可以像使用应用内的模型设置对话框一样添加提供商、填写 API Key / Base URL、勾选模型列表并指定默认模型。其数据来源与保存机制值得展开面板模型与环境配置合并而非覆盖面板保存的提供商以ADMIN_PROVIDERS键存入data/settings.json见 lib/admin/providers.ts 的ADMIN_PROVIDERS_KEY。关键点在于面板不修改AI_MODELS_CONFIG环境变量或ai-models.json文件二者的合并发生在读取时——由 lib/server-model-config.ts 的loadRawServerModelsConfig()在每次请求时把环境基线与面板提供商做 union。因此环境中定义的提供商在面板里只读展示providers 路由 的payload()会同时返回providers面板、可编辑与envProviders环境、只读若面板设置了默认提供商环境侧的「星号默认」标记会在面板中让位adminHasDefault逻辑与运行时合并行为保持一致。凭据写入 ADMIN_ 前缀环境变量面板保存时deriveEnvUpdateslib/admin/providers.ts把凭据派生为带ADMIN_前缀的环境变量名再写回设置文件例如第一个 OpenAI 实例写入ADMIN_OPENAI_API_KEY/ADMIN_OPENAI_BASE_URL同提供商的第二实例追加_2后缀。这样设计是为了不遮蔽标准变量如OPENAI_API_KEY——环境侧的模型条目仍依赖这些标准变量取凭据。个别提供商有例外映射bedrock→AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGIONvertexai→GOOGLE_VERTEX_API_KEY/GOOGLE_VERTEX_BASE_URLollama→OLLAMA_API_KEY/OLLAMA_BASE_URL如果某个提供商被标记为默认isDefault且模型列表非空面板还会同步写入AI_PROVIDER与AI_MODEL使其成为服务端的全局默认模型取消默认则删除这两个键回退到环境配置的默认。保存前的合法性校验PUT /api/admin/providers 的执行顺序是Zod 校验请求体 →mergeSecrets解析密钥占位标记 →validateAdminProviders业务校验 →saveSettings落盘。业务规则包括固定凭据类提供商FIXED_CRED_PROVIDERS以及edgeone只允许一个实例且不能与环境侧已配置的同名提供商共存因为二者共享全局凭据显示名必须唯一且不能与AI_MODELS_CONFIG/ai-models.json中的名称冲突全局只允许一个默认提供商。模型连通性测试保存前可用 app/api/admin/test-model/route.ts 测试当前甚至尚未保存的提供商状态。该端点复用/api/validate-model的逻辑但有一个关键安全约束L35-L48存储的密钥只在{isSet}占位标记被解析时才与已存条目比对——仅当 provider、baseUrl、awsRegion 完全一致时才允许复用已存密钥否则必须重新明文输入防止篡改 baseUrl 把存储的 Key 外带到任意主机。可配置内容二通用设置区注册表驱动面板其余区块由 lib/admin/settings-registry.ts 中的声明式注册表驱动服务端校验与前端渲染共用同一份定义键名与真实环境变量名完全一致。当前注册的五个分组如下完整字段定义见 settings-registry.ts分组键环境变量名类型 / 约束说明GenerationTEMPERATUREnumber0–2留空可兼容拒绝 temperature 的推理模型GenerationMAX_OUTPUT_TOKENSnumber≥1输出 token 上限Access ControlACCESS_CODE_LISTstring逗号分隔访问码空 开放访问FeaturesENABLE_VLM_VALIDATIONboolean用视觉模型校验生成的图表FeaturesVALIDATION_MODELstring为空时回退默认 AI 模型FeaturesVALIDATION_TIMEOUTnumber≥1000ms校验超时FeaturesENABLE_HISTORY_XML_REPLACEboolean将历史中的旧图表 XML 替换为占位符FeaturesALLOW_PRIVATE_URLSboolean默认true关闭即启用 SSRF 防护lib/ssrf-protection.ts 中! false即放行故未设置等价于允许ObservabilityLANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY/LANGFUSE_BASEURLstring / secret / string需要重启见下文Quota Rate LimitsDAILY_REQUEST_LIMIT/DAILY_TOKEN_LIMIT/TPM_LIMITnumber≥1每 IP 的每日请求数、每日 token 数、每分钟 token 数Quota Rate LimitsDYNAMODB_QUOTA_TABLE/DYNAMODB_REGION/QUOTA_TIMEZONEstring需要重启表名为空时配额强制不生效两个分组Observability、Quota带有总开关toggleable: true关闭开关会把该组内「已设置」的键暂存为删除项保存后功能即真正关闭打开则恢复编辑。这与面板中「保存后立即生效」的语义闭环。为什么部分项标记需要重启注册表字段restartRequired的注释写明「Value is only picked up at process start (module-load readers)」。面板保存本身会立即刷新process.env见下一节但 Langfuse 在进程启动时的 instrumentation.ts 中初始化DynamoDB 配额管理的表名/区域/时区也是模块加载期读取——这类值必须重启进程才能被拾取。持久化与优先级data/settings.json 如何覆盖环境变量文档中的「优先级」一节——面板 环境变量 内置默认值删除已保存的值回退到环境变量——由 lib/admin/settings.ts 实现核心机制有四点文件格式与路径。默认路径为process.cwd()/data/settings.json可用SETTINGS_FILE环境变量覆盖getSettingsPath。文件格式为{ version: 1, values: { KEY: value, ... } }加载时只保留字符串值手改出的 null/数组/对象会被丢弃避免污染process.env测试覆盖见 tests/unit/admin-settings.test.ts 的 drops non-string values from a corrupted file。启动时覆盖。instrumentation.ts 在 nodejs runtime 下于一切配置读取之前调用applyToEnv()把文件值叠加到process.env同时originalEnv快照记录了首次覆盖前的原始值。删除即回退。saveSettings收到null时删除对应键并重新执行applyToEnv()对已覆盖但本次消失的键恢复originalEnv中的原始值原来未设置则真正删除。因此面板里清空一个输入并保存效果就是「回退到环境变量」。原子写与文件权限。saveSettings 先写${filePath}.tmpmode: 0o600再rename对应文档「文件权限 600」的要求防止并发写坏文件。每个键的当前值来源被getValueSource归类为file/env/default三态并随 GET /api/admin/settings 返回前端据此展示「当前生效的是文件值还是环境值」编辑界面也可识别「改回环境值」这类无操作并自动取消脏标记。安全细节密钥只写与掩码密钥类字段type: secret如LANGFUSE_SECRET_KEY在 API 响应中经 maskSecret 掩码为{ isSet: true, hint: …末4位 }——API 永不回传明文密钥前端把它当作只读标记原样回传服务端再用mergeSecrets解析为存储值面板中提供商的apiKey/awsAccessKeyId/awsSecretAccessKey/vertexApiKey四个字段同样走掩码流程maskAdminProviders但请注意文档「注意事项」中的提醒这些密钥以明文形式存储在data/settings.json中文件权限 600 只是底线备份、镜像、共享主机时务必妥善保管该文件。平台限制与注意事项文档「注意事项」一节逐条都有源码依据无服务器平台只读。isSettingsWritable()lib/admin/settings.ts探测设置文件目录是否可写在 Vercel、Cloudflare Workers 等没有持久化磁盘的平台上GET返回writable: false页面顶部显示黄色只读横幅page.tsxPUT直接返回 503 并提示「改用环境变量配置」。Docker 持久化。docker-compose.yml 通过- ./data:/app/data卷持久化data/settings.json容器重建后配置不丢失。NEXT_PUBLIC_*不可在面板修改。这些变量在构建时固化进客户端 bundle注册表也明确将其排除settings-registry.ts 头部注释PUT 会因 Unknown setting 被拒绝。引导变量仅环境可用。ADMIN_PASSWORD与SETTINGS_FILE属于 bootstrap 值刻意不进入注册表避免「通过面板改掉自己的入口密码」造成锁死。数值/布尔字段的服务端校验min/max、true/false、枚举白名单见 settings 路由非法值以{ errors: {...} }返回前端会聚焦到第一个出错的字段。如何验证相关测试如果你需要确认这套机制的行为可以查看仓库内两个单元测试文件tests/unit/admin-settings.test.ts覆盖文件不存在/损坏、applyToEnv覆盖与恢复、保存与删除键后的环境变量回退、可写性判断等tests/unit/admin-providers.test.ts覆盖deriveEnvUpdates的ADMIN_前缀派生、默认模型写入AI_PROVIDER/AI_MODEL、凭据清理等。小结管理面板把「改.env再重新部署」简化为「浏览器里保存一下」模型配置以ADMIN_PROVIDERS与ADMIN_前缀环境变量落盘、与环境基线在读取时合并通用设置以「文件覆盖 env」的 dotenv 式叠加生效并保留完整回退语义密钥全程只写、掩码回显在不可写的服务器上自动降级为只读并提示走环境变量。理解 lib/admin/ 目录下的四个文件auth.ts、settings.ts、settings-registry.ts、providers.ts与 instrumentation.ts 的启动时序就掌握了整个面板的全部实现要点。【免费下载链接】next-ai-draw-ioA next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.项目地址: https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
next-ai-draw-io 管理面板详解：通过 Web 界面管理服务端模型、配额与可观测性配置
next-ai-draw-io 管理面板详解通过 Web 界面管理服务端模型、配额与可观测性配置【免费下载链接】next-ai-draw-ioA next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.项目地址: https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io本文基于仓库文档 docs/cn/admin-panel.md 展开讲解 next-ai-draw-io 的 Web 管理面板/admin如何用ADMIN_PASSWORD启用面板、在面板中配置 AI 提供商与通用设置、设置如何写入data/settings.json并以「面板 环境变量 内置默认值」的优先级覆盖process.env以及密钥掩码、只读降级、可写性检查等安全机制的源码实现帮助你在不改动部署环境变量的前提下完成服务端配置管理。启用面板ADMIN_PASSWORD 与认证机制启用方式非常简单对应文档中的「启用面板」一节设置ADMIN_PASSWORD环境变量不设置则面板禁用访问/admin并登录。在 env.example 中可以看到这两个相关的引导变量# ADMIN_PASSWORDyour-admin-password # SETTINGS_FILE./data/settings.json # Optional: custom settings file location认证逻辑集中在 lib/admin/auth.ts 的checkAdminAuth中所有/api/admin/*路由设置读写、提供商读写、模型测试都先调用它ADMIN_PASSWORD未设置时直接返回 403提示 Admin panel is disabled——即不设置密码 面板整体禁用而不是回退到公开访问请求需携带x-admin-password请求头前端封装在 admin-shared.ts 的adminFetch中比较使用crypto.timingSafeEqual做恒定时间比对避免时序侧信道。前端登录页位于 app/[lang]/admin/page.tsx登录成功后密码保存在浏览器sessionStorage键名next-ai-draw-io-admin-password刷新页面时自动恢复会话未保存修改时通过beforeunload弹出离开警告。可配置内容一Models模型与提供商面板第一个区块是Models。你可以像使用应用内的模型设置对话框一样添加提供商、填写 API Key / Base URL、勾选模型列表并指定默认模型。其数据来源与保存机制值得展开面板模型与环境配置合并而非覆盖面板保存的提供商以ADMIN_PROVIDERS键存入data/settings.json见 lib/admin/providers.ts 的ADMIN_PROVIDERS_KEY。关键点在于面板不修改AI_MODELS_CONFIG环境变量或ai-models.json文件二者的合并发生在读取时——由 lib/server-model-config.ts 的loadRawServerModelsConfig()在每次请求时把环境基线与面板提供商做 union。因此环境中定义的提供商在面板里只读展示providers 路由 的payload()会同时返回providers面板、可编辑与envProviders环境、只读若面板设置了默认提供商环境侧的「星号默认」标记会在面板中让位adminHasDefault逻辑与运行时合并行为保持一致。凭据写入 ADMIN_ 前缀环境变量面板保存时deriveEnvUpdateslib/admin/providers.ts把凭据派生为带ADMIN_前缀的环境变量名再写回设置文件例如第一个 OpenAI 实例写入ADMIN_OPENAI_API_KEY/ADMIN_OPENAI_BASE_URL同提供商的第二实例追加_2后缀。这样设计是为了不遮蔽标准变量如OPENAI_API_KEY——环境侧的模型条目仍依赖这些标准变量取凭据。个别提供商有例外映射bedrock→AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGIONvertexai→GOOGLE_VERTEX_API_KEY/GOOGLE_VERTEX_BASE_URLollama→OLLAMA_API_KEY/OLLAMA_BASE_URL如果某个提供商被标记为默认isDefault且模型列表非空面板还会同步写入AI_PROVIDER与AI_MODEL使其成为服务端的全局默认模型取消默认则删除这两个键回退到环境配置的默认。保存前的合法性校验PUT /api/admin/providers 的执行顺序是Zod 校验请求体 →mergeSecrets解析密钥占位标记 →validateAdminProviders业务校验 →saveSettings落盘。业务规则包括固定凭据类提供商FIXED_CRED_PROVIDERS以及edgeone只允许一个实例且不能与环境侧已配置的同名提供商共存因为二者共享全局凭据显示名必须唯一且不能与AI_MODELS_CONFIG/ai-models.json中的名称冲突全局只允许一个默认提供商。模型连通性测试保存前可用 app/api/admin/test-model/route.ts 测试当前甚至尚未保存的提供商状态。该端点复用/api/validate-model的逻辑但有一个关键安全约束L35-L48存储的密钥只在{isSet}占位标记被解析时才与已存条目比对——仅当 provider、baseUrl、awsRegion 完全一致时才允许复用已存密钥否则必须重新明文输入防止篡改 baseUrl 把存储的 Key 外带到任意主机。可配置内容二通用设置区注册表驱动面板其余区块由 lib/admin/settings-registry.ts 中的声明式注册表驱动服务端校验与前端渲染共用同一份定义键名与真实环境变量名完全一致。当前注册的五个分组如下完整字段定义见 settings-registry.ts分组键环境变量名类型 / 约束说明GenerationTEMPERATUREnumber0–2留空可兼容拒绝 temperature 的推理模型GenerationMAX_OUTPUT_TOKENSnumber≥1输出 token 上限Access ControlACCESS_CODE_LISTstring逗号分隔访问码空 开放访问FeaturesENABLE_VLM_VALIDATIONboolean用视觉模型校验生成的图表FeaturesVALIDATION_MODELstring为空时回退默认 AI 模型FeaturesVALIDATION_TIMEOUTnumber≥1000ms校验超时FeaturesENABLE_HISTORY_XML_REPLACEboolean将历史中的旧图表 XML 替换为占位符FeaturesALLOW_PRIVATE_URLSboolean默认true关闭即启用 SSRF 防护lib/ssrf-protection.ts 中! false即放行故未设置等价于允许ObservabilityLANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY/LANGFUSE_BASEURLstring / secret / string需要重启见下文Quota Rate LimitsDAILY_REQUEST_LIMIT/DAILY_TOKEN_LIMIT/TPM_LIMITnumber≥1每 IP 的每日请求数、每日 token 数、每分钟 token 数Quota Rate LimitsDYNAMODB_QUOTA_TABLE/DYNAMODB_REGION/QUOTA_TIMEZONEstring需要重启表名为空时配额强制不生效两个分组Observability、Quota带有总开关toggleable: true关闭开关会把该组内「已设置」的键暂存为删除项保存后功能即真正关闭打开则恢复编辑。这与面板中「保存后立即生效」的语义闭环。为什么部分项标记需要重启注册表字段restartRequired的注释写明「Value is only picked up at process start (module-load readers)」。面板保存本身会立即刷新process.env见下一节但 Langfuse 在进程启动时的 instrumentation.ts 中初始化DynamoDB 配额管理的表名/区域/时区也是模块加载期读取——这类值必须重启进程才能被拾取。持久化与优先级data/settings.json 如何覆盖环境变量文档中的「优先级」一节——面板 环境变量 内置默认值删除已保存的值回退到环境变量——由 lib/admin/settings.ts 实现核心机制有四点文件格式与路径。默认路径为process.cwd()/data/settings.json可用SETTINGS_FILE环境变量覆盖getSettingsPath。文件格式为{ version: 1, values: { KEY: value, ... } }加载时只保留字符串值手改出的 null/数组/对象会被丢弃避免污染process.env测试覆盖见 tests/unit/admin-settings.test.ts 的 drops non-string values from a corrupted file。启动时覆盖。instrumentation.ts 在 nodejs runtime 下于一切配置读取之前调用applyToEnv()把文件值叠加到process.env同时originalEnv快照记录了首次覆盖前的原始值。删除即回退。saveSettings收到null时删除对应键并重新执行applyToEnv()对已覆盖但本次消失的键恢复originalEnv中的原始值原来未设置则真正删除。因此面板里清空一个输入并保存效果就是「回退到环境变量」。原子写与文件权限。saveSettings 先写${filePath}.tmpmode: 0o600再rename对应文档「文件权限 600」的要求防止并发写坏文件。每个键的当前值来源被getValueSource归类为file/env/default三态并随 GET /api/admin/settings 返回前端据此展示「当前生效的是文件值还是环境值」编辑界面也可识别「改回环境值」这类无操作并自动取消脏标记。安全细节密钥只写与掩码密钥类字段type: secret如LANGFUSE_SECRET_KEY在 API 响应中经 maskSecret 掩码为{ isSet: true, hint: …末4位 }——API 永不回传明文密钥前端把它当作只读标记原样回传服务端再用mergeSecrets解析为存储值面板中提供商的apiKey/awsAccessKeyId/awsSecretAccessKey/vertexApiKey四个字段同样走掩码流程maskAdminProviders但请注意文档「注意事项」中的提醒这些密钥以明文形式存储在data/settings.json中文件权限 600 只是底线备份、镜像、共享主机时务必妥善保管该文件。平台限制与注意事项文档「注意事项」一节逐条都有源码依据无服务器平台只读。isSettingsWritable()lib/admin/settings.ts探测设置文件目录是否可写在 Vercel、Cloudflare Workers 等没有持久化磁盘的平台上GET返回writable: false页面顶部显示黄色只读横幅page.tsxPUT直接返回 503 并提示「改用环境变量配置」。Docker 持久化。docker-compose.yml 通过- ./data:/app/data卷持久化data/settings.json容器重建后配置不丢失。NEXT_PUBLIC_*不可在面板修改。这些变量在构建时固化进客户端 bundle注册表也明确将其排除settings-registry.ts 头部注释PUT 会因 Unknown setting 被拒绝。引导变量仅环境可用。ADMIN_PASSWORD与SETTINGS_FILE属于 bootstrap 值刻意不进入注册表避免「通过面板改掉自己的入口密码」造成锁死。数值/布尔字段的服务端校验min/max、true/false、枚举白名单见 settings 路由非法值以{ errors: {...} }返回前端会聚焦到第一个出错的字段。如何验证相关测试如果你需要确认这套机制的行为可以查看仓库内两个单元测试文件tests/unit/admin-settings.test.ts覆盖文件不存在/损坏、applyToEnv覆盖与恢复、保存与删除键后的环境变量回退、可写性判断等tests/unit/admin-providers.test.ts覆盖deriveEnvUpdates的ADMIN_前缀派生、默认模型写入AI_PROVIDER/AI_MODEL、凭据清理等。小结管理面板把「改.env再重新部署」简化为「浏览器里保存一下」模型配置以ADMIN_PROVIDERS与ADMIN_前缀环境变量落盘、与环境基线在读取时合并通用设置以「文件覆盖 env」的 dotenv 式叠加生效并保留完整回退语义密钥全程只写、掩码回显在不可写的服务器上自动降级为只读并提示走环境变量。理解 lib/admin/ 目录下的四个文件auth.ts、settings.ts、settings-registry.ts、providers.ts与 instrumentation.ts 的启动时序就掌握了整个面板的全部实现要点。【免费下载链接】next-ai-draw-ioA next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.项目地址: https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
