Nginx UI App 配置详解：PageSize 分页大小与 JwtSecret 签名密钥

后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载Nginx UI 的[app]配置段承载着两个影响全局行为的关键参数控制列表分页大小的PageSize以及用于签发与校验用户身份令牌的JwtSecret。本篇以官方文档 config-app.md 为主体结合仓库源码深入讲解这两个配置项的类型、默认值、生效版本、底层实现与安全注意事项帮助你正确配置并理解其背后的运行机制。概述Nginx UI 的[app]配置段Nginx UIYet another WebUI for Nginx使用 INI 格式的配置文件app.ini保存全部服务端设置。从v2.0.0-beta.37起应用级参数被统一收敛到[app]段。当前该段包含两个核心选项配置项类型默认值最低版本PageSizeint10v2.0.0-beta.37JwtSecretstring安装时自动生成v2.0.0-beta.37在源码层面app段通过 settings/settings.go 中的sections有序映射注册到配置系统并通过envPrefixMap将段名APP映射为环境变量前缀NGINX_UI_APP_。这意味着这两个配置项既可以在app.ini中书写也可以通过环境变量注入二者效果等价。PageSize控制列表分页大小配置参数类型int默认值10适用版本 v2.0.0-beta.37该选项用于设置 Nginx UI 中列表分页的每页条目数。调整分页大小有助于更高效地管理大量数据但过大的数值会增加服务器负载。前端默认值溯源在前端系统设置仓库中page_size的初始值同样被定义为10与后端默认值保持一致const data refSettings({ app: { page_size: 10, jwt_secret: , }, // ... })代码位置app/src/views/preference/store/index.ts。后端类型定义与测试验证后端AppSettings.PageSize被声明为int类型并在 v1 配置迁移逻辑中完成赋值迁移PageSize int json:page_size protected:true代码位置settings/server_v1.go。对应迁移逻辑v2.App.PageSize v1.PageSize代码位置settings/server_v1.go。在 settings/settings_test.go 中测试断言迁移后PageSize为20在 api/settings/settings_test.go 中测试将PageSize设为50并验证设置接口的保存与读取行为。这印证了该配置项同时支持通过配置文件与 Web 设置接口SettingsAPI修改。配置方式方式一编辑app.ini配置文件[app] PageSize 10方式二设置环境变量export NGINX_UI_APP_PAGE_SIZE10两种方式可参考 docs/guide/env.md 中的环境变量映射表Nginx UI 支持NGINX_UI_前缀的环境变量覆盖配置文件。方式三通过 Web 界面登录 Nginx UI 后进入系统设置System Settings在 App 区域修改 Page Size 并保存。保存动作最终通过settings.Update/settings.Save调用持久化到配置文件相关实现见 settings/settings.go。注意事项分页参数对列表接口的负载有直接影响每页条目数越大单次查询返回的数据量越大数据库与传输层的开销也随之增加。对于动辄数百上千条站点、证书或日志条目的部署环境建议保持较小的分页值如默认的1050必要时结合筛选条件缩小结果集。JwtSecretJWT 签名密钥配置参数类型string适用版本 v2.0.0-beta.37该选项用于配置 Nginx UI 服务端生成 JWTJSON Web Token所使用的密钥。JWT 是验证用户身份的标准机制用户登录后服务端签发一个 token后续请求携带该 token 即可完成身份验证。密钥的生成时机一键安装脚本自动生成如果使用官方一键安装脚本部署 Nginx UI脚本会生成一个 UUID 值并写入该选项。对应后端安装流程中安装接口同样使用 UUID 作为密钥来源err : settings.Update(func() { cSettings.AppSettings.JwtSecret uuid.New().String() settings.NodeSettings.Secret uuid.New().String() settings.CertSettings.Email json.Email })代码位置api/system/install.go。安装跳过时的兜底生成当配置了跳过安装SkipInstallation且JwtSecret为空时内核初始化逻辑也会自动生成 UUID 填入if cSettings.AppSettings.JwtSecret { cSettings.AppSettings.JwtSecret uuid.New().String() }代码位置internal/kernel/skip_install.go。底层实现签发与校验JWT 的签发与校验均位于 internal/user/user.go可直接观察到JwtSecret的实际用途。签发HS256 对称签名登录成功后服务端以JwtSecret作为 HS256 签名密钥将用户名、用户 ID、过期时间等声明编码为 tokenunsignedToken : jwt.NewWithClaims(jwt.SigningMethodHS256, claims) signedToken, err : unsignedToken.SignedString([]byte(cSettings.AppSettings.JwtSecret))代码位置internal/user/user.go。JWT claims 中包含了Issuer: Nginx UI、Subject、ExpiresAt等标准字段internal/user/user.go。校验验签与解析后续请求携带 token 时ValidateJWT使用同一个密钥解析并验证签名token, err : jwt.ParseWithClaims(tokenStr, JWTClaims{}, func(token *jwt.Token) (interface{}, error) { return []byte(cSettings.AppSettings.JwtSecret), nil })代码位置internal/user/user.go。为什么 JwtSecret 至关重要JwtSecret是整个认证体系的信任根任何能够读取该密钥的人都可以伪造合法的登录 token。仓库中的安全测试也反复验证了这一点多个模块的security_test.go在测试前会临时替换JwtSecret为测试值以隔离环境并验证受保护接口在无有效 token 时拒绝访问例如 api/user/security_test.go、api/sites/security_test.go、api/streams/security_test.go 以及 api/backup/security_test.go。这说明 Nginx UI 的配置、站点、备份、流媒体等敏感接口全部由基于JwtSecret的 JWT 鉴权中间件保护。配置方式方式一编辑app.ini配置文件[app] JwtSecret 至少 32 位的随机字符串方式二设置环境变量export NGINX_UI_APP_JWT_SECRET至少 32 位的随机字符串方式三通过 Web 界面系统设置 → App → JWT Secret 可直接修改并保存。安全建议请勿使用弱密钥或在多台实例间复用同一密钥修改JwtSecret后所有已签发的 token 将立即失效所有用户需要重新登录。从旧版本迁移[server]段 →[app]段在引入[app]段之前这两个选项位于[server]段字段名为JwtSecret、PageSize。Nginx UI 提供了自动迁移能力详见 settings/server_v1.go读取旧配置中的[server]段若检测到jwt_secret非空判定为 v1 配置通过migrateToV2将旧字段映射到新段如v1.JwtSecret→v2.App.JwtSecret、v1.PageSize→v2.App.PageSize合并用户已有配置后原子写回app.ini先写.tmp文件再os.Rename见 settings/settings.go。对应的旧环境变量也会被自动迁移例如SERVER_JWT_SECRET→APP_JWT_SECRET、SERVER_PAGE_SIZE→APP_PAGE_SIZEsettings/server_v1.go。迁移时会在日志中提示用户尽快更新环境变量因为自动迁移可能在后续版本中移除。在恢复备份时也有对应处理JwtSecret属于需要特殊保护的敏感字段恢复流程会单独判断是否沿用当前值还是采用备份值相关逻辑见 settings/restore.go 及其测试 settings/restore_test.go。配置生效与文件位置默认配置文件路径为app.ini可通过启动参数--config指定其他路径见 internal/cmd/main.go。设置接口返回的 App 配置结构中已包含JwtSecret与PageSize见 api/settings/settings.go 与 api/settings/settings.go。环境变量统一使用NGINX_UI_前缀settings/settings.go解析逻辑基于env.ParseWithOptionssettings/settings.go完整映射表见 docs/guide/env.md。小结[app]配置段虽然只有两个选项却是 Nginx UI 正常运转的基础PageSize决定了大量数据场景下的列表展示效率与服务器负载平衡JwtSecret则是一切身份认证与接口安全的前提。两者均支持app.ini配置、NGINX_UI_APP_*环境变量和 Web 设置界面三种修改途径且对旧版[server]段配置具备自动迁移能力。部署完成后建议立即检查JwtSecret是否为安装脚本自动生成的强随机值避免使用默认或弱密钥带来的安全风险。赞分享后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载相关推荐Nginx UI App 配置段详解PageSize 分页大小与 JwtSecret 密钥的完整配置指南Nginx UI App 配置段详解PageSize 分页大小与 JwtSecret 密钥的完整配置指南 导读 本文以 Nginx UI 官方配置文档 doc后端前端运维MCP 服务Nginx UI 应用级配置详解PageSize 列表分页与 JwtSecret 令牌签名Nginx UI 应用级配置详解PageSize 列表分页与 JwtSecret 令牌签名 本指南围绕 Nginx UI 配置文件中 app 段下的两个核心配后端前端运维MCP 服务ESP32物联网开发实战Arduino-ESP32从零构建智能设备ESP32物联网开发实战Arduino ESP32从零构建智能设备 Arduino ESP32是Espressif官方支持的ESP32系列SoC的Arduin嵌入式物联网驱动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考