Nginx UI 命令行接口（nginx-ui ctl）实战指南：服务令牌、远程运维与自动化

后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载nginx-ui ctl是 Nginx UI 内置的命令行管理工具通过调用管理 API 对正在运行的 Nginx UI 实例进行远程操作专为基础设施即代码IaC、配置即代码CaC、部署自动化和远程运维场景设计。本文基于 docs/zh_CN/guide/cli.md 展开并结合仓库内 internal/cmd/ctl.go、internal/middleware/middleware.go、internal/mcp/service_token.go 等源码完整讲解令牌创建、客户端配置、常见操作、通用 API 调用与服务令牌生命周期管理帮助你用一条命令行安全地自动化管理 Nginx UI。概述ctl 子命令与管理 API在 Nginx UI 的二进制入口中ctl与serve、reset-password、cert、host setup等并列注册为顶层子命令见 internal/cmd/main.go其完整定义为命令名ctl用途Manage a running Nginx UI instance through its API通过 API 管理正在运行的 Nginx UI 实例全局参数--endpoint、--token-file、--token-stdin、--ca-file、--node-id、--timeout子命令api、users、certificates、nginx、tokens见 internal/cmd/ctl.go从架构上看nginx-ui ctl并不是直接读写配置文件或数据库的本地工具而是一个管理 API 客户端它把命令行参数组装成 HTTP 请求携带Authorization: Bearer token头发送给运行中的 Nginx UI 服务端再由服务端中间件完成令牌校验与权限判定见 internal/middleware/middleware.go。这意味着目标实例必须处于运行状态且管理 API 可达一切操作都以令牌服务令牌或交互式管理员令牌为身份凭证只要网络可达你可以在任意机器上远程执行管理操作非常适合 CI/CD 流水线与自动化运维。第一步创建访问令牌nginx-ui ctl的所有操作都以令牌为凭证因此使用前必须先创建访问令牌。官方文档给出的步骤为以管理员身份登录 Nginx UI。打开Preferences Access Tokens前端实现见 app/src/views/preference/tabs/AccessTokens.vue。按最小权限原则创建令牌并设置过期时间。立即复制令牌——Nginx UI 不会再次显示该令牌。API 权限范围管理 API 相关的服务令牌权限范围如下Scope访问权限api:read管理 API 的GET、HEAD、OPTIONS请求api:write管理 API 的变更请求同时包含 API 读权限该权限模型在源码中有对应实现常量定义在 model/mcp_service_token.goAPITokenScopeRead api:read、APITokenScopeWrite api:write另有 MCP 侧的mcp:read、mcp:write。中间件apiScopeForRequest按 HTTP 方法映射所需 scopeGET/HEAD/OPTIONS请求要求api:read其余方法一律要求api:write见 internal/middleware/middleware.go。HasScope实现中api:write隐含api:readmcp:write同样隐含mcp:read因此只需授予高一级权限即可同时获得读权限见 internal/mcp/service_token.go。权限隔离与服务令牌限制MCP 权限与 API 权限彼此独立授予mcp:write不会获得管理 API 访问权限授予api:write也不会获得 MCP 访问权限。服务令牌无法执行交互式账户安全操作、创建或修改交互式用户、查看受保护设置、管理其他服务令牌、打开 Web 终端。api:read权限可以列出和查看用户但用户的创建、修改、删除和恢复必须使用已认证的交互式管理员会话。这些限制在代码中有两处保障一是serviceTokenInteractiveRoutes/serviceTokenInteractivePaths白名单表凡命中即拒绝服务令牌见 internal/middleware/middleware.go二是requireInteractiveAdministratorToken在客户端本地直接识别nui_pat_前缀并拒绝执行用户管理类操作见 internal/cmd/ctl.go。服务令牌的形态服务令牌的格式为nui_pat_publicID_secret其中 publicID 为 12 字节随机数、secret 为 32 字节随机数的 URL-safe Base64 编码数据库只保存基于 HKDF-SHA256 派生的 HMAC 校验值服务端无法反向还原明文令牌见 internal/mcp/service_token.go。这也是令牌只显示一次的底层原因。配置 ctl 客户端推荐做法是把端点写入环境变量把令牌保存在仅自动化账号可读的密钥文件中export NGINX_UI_CTL_ENDPOINThttps://nginx-ui.example.com nginx-ui ctl --token-file /run/secrets/nginx-ui-token users list端点的提供方式端点可通过--endpoint或环境变量NGINX_UI_CTL_ENDPOINT提供。源码中的解析逻辑见 internal/cmd/ctl.go还会做严格校验必须是http或https协议且必须包含主机名端点 URL 不得包含用户信息如https://user:passhost查询串与片段会被清空防止意外附加参数。令牌的提供方式令牌可通过NGINX_UI_CTL_TOKEN环境变量、--token-file或--token-stdin三种方式提供见 internal/cmd/ctl.go。官方建议优先使用密钥文件或标准输入避免令牌出现在命令历史或进程参数中。需要注意--token-stdin与--token-file互斥同时使用会直接报错令牌与请求体输入都有16 MiB16 20的大小上限超出即拒绝maxCLIInputSize常量见 internal/cmd/ctl.go。私有 CA 与集群节点路由如果服务端使用私有 CA 证书请通过--ca-file传入 PEM 证书链客户端会将其追加到系统根证书池且强制 TLS 最低版本为 1.2见 internal/cmd/ctl.go。使用--node-id可将支持的请求路由到指定集群节点该值会以X-Node-ID请求头发送到服务端由集群代理中间件解析并转发见 internal/cmd/ctl.go。--node-id必须是合法的无符号整数parseNodeID见 internal/cmd/ctl.go。客户端默认请求超时为30 秒可通过--timeout调整见 internal/cmd/ctl.go。客户端安全行为源码级ctl客户端在安全上有几处精心设计均有 internal/cmd/ctl_test.go 中的测试覆盖不跟随重定向CheckRedirect直接返回http.ErrUseLastResponse防止令牌在 302 场景下被转发到攻击者主机拒绝绝对 URLapi子命令的路径必须是相对路径绝对 URL 或//开头的路径一律报错TestCtlClientBuildsSafeAPIURL错误响应有界读取HTTP 错误会把状态码与响应体封装为ctlHTTPError输出便于排查TestCtlClientReturnsBoundedHTTPError。常见操作实战用户管理使用api:read服务令牌列出用户nginx-ui ctl --token-file /run/secrets/nginx-ui-token users list使用交互式管理员令牌创建用户nginx-ui ctl --token-file /run/secrets/admin-session-token users create \ --name deploy-user --password-file /run/secrets/deploy-user-passwordusers create的实现细节见 internal/cmd/ctl.go--name为必填密码必须通过--password-file或--password-stdin提供二者互斥且不能与--token-stdin同时使用密码长度上限为20 个字符按 Unicode 字符数统计见normalizeCtlPassword与 internal/cmd/ctl_test.go 中的中文密码测试该操作走executeInteractiveCtlRequest会先调用requireInteractiveAdministratorToken服务令牌nui_pat_前缀会被本地直接拒绝TestUserCreationRejectsServiceTokenLocally。文档同时提醒两点部署经验在跳过安装流程的部署中预置用户环境变量仍可用于初始化首个用户安装完成后请通过 Web 界面或使用交互式管理员令牌执行ctl users create来新增用户已启用双因素认证2FA的管理员应使用 Web 界面创建用户以便完成安全会话验证。证书管理列出证书并注册 Nginx UI 服务器上已存在的证书文件nginx-ui ctl --token-file /run/secrets/nginx-ui-token certificates list nginx-ui ctl --token-file /run/secrets/nginx-ui-token certificates import \ --name example.com \ --cert /etc/nginx/ssl/example.com/fullchain.pem \ --key /etc/nginx/ssl/example.com/privkey.pem源码细节见 internal/cmd/ctl.go子命令certificates有别名certslist对应管理 API 的GET /api/certsimport对应POST /api/cert_import后端路由见 api/certificate/router.goimport的--cert与--key为必填参数分别指服务器上的证书文件路径与私钥文件路径另有可选的--key-type覆盖私钥类型证书命令通过executeCtlRequestRedactingFields执行会从输出中递归移除ssl_certificate与ssl_certificate_key字段的 PEM 内容避免 CI 日志泄露密钥材料脱敏实现redactJSONFields见 internal/cmd/ctl.go测试见TestRedactJSONFieldsRecursivelyRemovesCertificateMaterial。查看和控制 Nginxnginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx status nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx test nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx reload nginx-ui ctl --token-file /run/secrets/nginx-ui-token nginx restart这四个子命令由同一个循环模板生成见 internal/cmd/ctl.go分别映射到管理 API 的子命令HTTP 方法API 路径nginx statusGETnginx/statusnginx testPOSTnginx/testnginx reloadPOSTnginx/reloadnginx restartPOSTnginx/restart其中test用于校验 nginx 配置等价于nginx -treload与restart会触发服务端对 nginx 进程的控制操作执行变更类操作需要令牌具备api:write权限。调用任意管理 API通用api子命令可覆盖尚未提供专用命令的管理操作nginx-ui ctl --token-file /run/secrets/nginx-ui-token api sites?page1 nginx-ui ctl --token-file /run/secrets/nginx-ui-token api \ --method POST --data-file site.json sites实现与约束见 internal/cmd/ctl.go 与apiURL的路径解析逻辑 internal/cmd/ctl.go路径解析到/api之下如果路径未以/api开头会自动拼接为endpoint/api/path如果路径已经以/api开头则原样使用因此api nginx/status与api /api/nginx/status等价查询字符串会被保留如api sites?page1中的?page1会原样传给服务端拒绝绝对 URLhttps://attacker.test/...这类绝对地址会被拒绝防止凭据被重定向到其他主机测试见TestCtlClientBuildsSafeAPIURL中apiURL(https://attacker.test/api/users)的用例--method默认GET可指定任意 HTTP 方法并自动转大写--data与--data-file二选一提供 JSON 请求体且请求体必须是合法 JSON请求体和响应体大小限制为 16 MiB超出即报错避免大流量打爆客户端内存。服务令牌生命周期管理创建、轮换和吊销服务令牌需要交互式管理员令牌包括所需的二次验证nginx-ui ctl --token-file /run/secrets/admin-session-token tokens list nginx-ui ctl --token-file /run/secrets/admin-session-token tokens create \ --name ci --scope api:write --expires-at 2027-01-01T00:00:00Z nginx-ui ctl --token-file /run/secrets/admin-session-token tokens rotate TOKEN_ID nginx-ui ctl --token-file /run/secrets/admin-session-token tokens revoke TOKEN_ID实现细节见 internal/cmd/ctl.gotokens list对应GET /api/service_tokenscreate对应POST /api/service_tokensrotate对应POST /api/service_tokens/:id/rotaterevoke对应DELETE /api/service_tokens/:id。--scope为必填且可重复传入多个 scope 用多个--scope参数目前仅接受api:read、api:write、mcp:read、mcp:write四个取值scope 规范化见 internal/mcp/service_token.go。--expires-at接受RFC3339 格式如2027-01-01T00:00:00Z的过期时间服务端会校验过期时间必须在未来见 internal/mcp/service_token.go。令牌名不得超过 64 个字符。管理端路由见 mcp/service_tokens.go叠加了三层保护RequireInteractiveUser()拒绝服务令牌自我管理RequireSecureSession()创建/轮换/吊销等变更操作要求安全会话即已完成二次验证的会话RejectInDemo()演示模式禁止签发新令牌防止访客获得绕过浏览器会话的凭证。生命周期语义轮换rotate会立即使旧令牌失效实现上只更新数据库中的 verifier 字段同时清空last_used_at见 internal/mcp/service_token.go旧密钥即刻作废无需等待过期吊销revoke为永久操作写入revoked_at时间戳不可恢复见 internal/mcp/service_token.go每次成功使用令牌都会更新last_used_at字段见 internal/mcp/service_token.go可用于审计与排查异常使用。安全设计要点小结将上述内容汇总nginx-ui ctl的安全模型可以概括为六条最小权限按操作类型授予api:read或api:writeapi:write隐含读权限MCP 与 API 权限域完全隔离令牌不可逆存储服务令牌明文只在创建时出现一次数据库仅保存 HMAC 校验值交互式边界用户管理、令牌管理、受保护设置、Web 终端等高敏操作强制要求交互式管理员会话敏感输出脱敏证书 PEM 内容在 CLI 输出前被递归移除避免 CI 日志泄露客户端硬化强制 TLS 1.2、不跟随重定向、拒绝绝对 URL 与带用户信息的端点、16 MiB 输入输出上限密钥不落命令行官方推荐通过--token-file或--token-stdin提供令牌避免进入命令历史与进程参数。如需进一步了解令牌相关的完整配置项如 crypto 密钥与节点实例 ID 对令牌派生 key 的影响、集群节点路由或 MCP 令牌在 AI 工具场景下的用法可继续阅读仓库内的 docs/guide/mcp.md、docs/guide/config-auth.md 与 docs/guide/config-cluster.md英文版对应 docs/guide/cli.md。结合 internal/cmd/ctl_test.go 中的测试用例你可以快速验证客户端在 URL 构造、重定向、Bearer 头、脱敏与密码边界等场景下的行为是否符合预期。赞分享后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载相关推荐专业终端视觉优化指南iTerm2主题定制与美学实践专业终端视觉优化指南iTerm2主题定制与美学实践 在当今开发工作流中终端界面已成为程序员日常交互的核心环境。然而长时间面对单调的默认配色不仅会导致视觉疲开发工具告别命令行Nginx-UI让服务器管理效率翻倍的秘诀告别命令行Nginx UI让服务器管理效率翻倍的秘诀 还在为复杂的Nginx配置命令而头疼吗每天面对密密麻麻的配置文件是不是感觉运维工作变得异常繁琐现在后端前端运维MCP 服务3 条命令把语音转成文字命令行跑通 Moonshine 本地语音识别3 条命令把语音转成文字命令行跑通 Moonshine 本地语音识别 不做云端语音识别能不能跑Moonshine 是面向边缘设备的语音识别ASR引擎人工智能语音音频AI 应用本地部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考