Nginx UI 命令行接口（nginx-ui ctl）实战指南：基于管理 API 的自动化运维与配置即代码

后端前端运维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/guide/cli.md 为主线结合仓库内internal/cmd/ctl.go等核心源码完整讲解令牌体系、客户端配置、常用操作、通用 API 调用与令牌生命周期管理帮助你写出可审计、可复用、不泄露密钥的自动化脚本。ctl 命令在 Nginx UI 中的定位在 Nginx UI 的可执行文件中ctl是注册在顶层命令下的一个子命令见 internal/cmd/main.go与serve、reset-password、cert、host-setup等并列。它的完整定义位于 internal/cmd/ctl.go命令行为不需要与 Nginx UI 部署在同一台机器只要网络可达即可通过 HTTP(S) 调用管理 API认证采用Authorization: Bearer token头见 internal/cmd/ctl.go全部输出为格式化后的 JSON便于在 CI/CD 管道、脚本中继续解析。这意味着你可以在本地开发机、GitHub Actions Runner、Jenkins Agent 或 Kubernetes Job 中用同一套 CLI 管理远端 Nginx UI 实例而无需登录 Web 界面。第一步创建访问令牌在 Web 界面中创建以管理员身份登录 Nginx UI。打开Preferences Access Tokens对应前端页面 app/src/views/preference/tabs/AccessTokens.vue。按最小权限原则创建令牌只授予任务所需的最小 scope并设置过期时间。立即复制令牌。Nginx UI 不会再次显示它——数据库里只保存验证器verifier不保存明文令牌。API 权限范围ScopeScope访问权限api:read管理 API 的GET、HEAD、OPTIONS请求api:write管理 API 的变更请求同时包含 API 读权限在源码中scope 常量定义于 model/mcp_service_token.go除 API scope 外还有独立的 MCP scopeMCPTokenScopeRead mcp:read MCPTokenScopeWrite mcp:write APITokenScopeRead api:read APITokenScopeWrite api:writescope 的包含关系由 internal/mcp/service_token.go 中的HasScope实现api:write隐式包含api:readmcp:write隐式包含mcp:read但MCP 权限与 API 权限彼此独立。授予mcp:write不会获得管理 API 访问权限授予api:write也不会获得 MCP 访问权限。服务令牌的权限边界服务令牌service token即nui_pat_前缀的令牌无法执行以下操作访问交互式账户安全操作如双因素认证相关流程创建或修改交互式用户查看受保护设置对应管理 API 中的settings/protected接口管理其他服务令牌打开 Web 终端。api:read可以列出和查看用户但用户的创建、修改、删除和恢复必须使用已认证的交互式管理员会话。这一限制在客户端侧也有兜底requireInteractiveAdministratorToken会直接拒绝nui_pat_前缀的令牌执行用户管理类操作见 internal/cmd/ctl.go并有一一对应的单元测试见 internal/cmd/ctl_test.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命令行优先环境变量兜底令牌--token-file、--token-stdin或环境变量NGINX_UI_CTL_TOKEN建议优先使用密钥文件或标准输入从源码看internal/cmd/ctl.gonewCtlClient会先取--endpoint为空时回落到NGINX_UI_CTL_ENDPOINT端点必须是合法的http/httpsURL 且不能包含用户信息userinfo否则直接报错。令牌的读取逻辑见 internal/cmd/ctl.go--token-stdin与--token-file互斥都不提供时才读NGINX_UI_CTL_TOKEN且所有输入都会做 16 MiB 上限校验与首尾空白裁剪。安全建议优先使用密钥文件或标准输入避免令牌出现在命令历史或进程参数如ps中。在容器/CI 场景中/run/secrets/...或环境注入的密钥文件是常见做法。私有 CA 与集群节点路由如果 Nginx UI 使用私有 CA 签发 TLS 证书用--ca-file传入 PEM 格式的 CA 证书链。源码会在系统证书池基础上追加该 CAinternal/cmd/ctl.go并强制tls.Config.MinVersion tls.VersionTLS12拒绝低于 TLS 1.2 的握手。使用--node-id可将支持的请求路由到指定集群节点。客户端会把它转换为X-Node-ID请求头internal/cmd/ctl.go其值必须是合法的无符号整数internal/cmd/ctl.go。另外--timeout可设置请求超时时间默认 30 秒internal/cmd/ctl.go。常见操作用户管理使用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 字符计数见 internal/cmd/ctl.go超长会报password must not exceed 20 characters该规则有专门测试覆盖internal/cmd/ctl_test.go该操作内部走executeInteractiveCtlRequest即要求交互式管理员令牌。关于初始用户在跳过安装流程skip-installation的部署中预置用户环境变量仍可用于初始化首个用户。安装完成后新增用户应通过 Web 界面或使用交互式管理员令牌执行ctl users create。已启用双因素认证2FA的管理员应使用 Web 界面以便完成安全会话secure session验证——从源码看令牌管理与用户管理相关接口都挂在RequireSecureSession中间件之后见 mcp/service_tokens.go该中间件要求完成 2FA 校验才放行internal/middleware/secure_session.go。证书管理列出证书并注册 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.pemcertificates别名certs子命令的实现见 internal/cmd/ctl.goimport的--cert与--key为必填指向Nginx UI 服务器本地的文件路径不是在客户端机器上读取文件内容再上传可选的--key-type用于覆盖私钥类型专用证书命令会从输出中递归删除ssl_certificate与ssl_certificate_key字段避免 CI 日志捕获密钥材料。这是通过redactJSONFields实现的internal/cmd/ctl.go测试TestRedactJSONFieldsRecursivelyRemovesCertificateMaterial验证了即使在嵌套 JSON 中也能完整清除internal/cmd/ctl_test.go。Nginx 控制nginx-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.gostatus走GET /api/nginx/statustest、reload、restart分别走POST /api/nginx/test、/api/nginx/reload、/api/nginx/restart。由于api:write覆盖这些变更操作运行test/reload/restart需要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 sitesapi子命令的参数internal/cmd/ctl.go参数说明PATH位置参数必填。API 路径可携带查询字符串--methodHTTP 方法默认GET--data直接以字符串传入 JSON 请求体--data-file从文件读取 JSON 请求体与--data互斥路径解析与安全边界路径会解析到/api之下internal/cmd/ctl.go具体规则相对路径如sites?page1会拼接为endpoint/api/sites?page1若路径本身已以/api开头如/api/nginx/status则按原样使用不重复拼接查询字符串被保留拒绝绝对 URL如https://attacker.test/api/users防止凭据被重定向到其他主机客户端还禁用了自动重定向CheckRedirect返回ErrUseLastResponse见 internal/cmd/ctl.go相关行为有测试TestCtlClientDoesNotFollowRedirects佐证internal/cmd/ctl_test.go。请求/响应大小限制请求体和响应体均限制为16 MiBmaxCLIInputSize 16 20见 internal/cmd/ctl.go。超限的文件、令牌输入或 API 响应都会返回明确的错误避免内存被异常数据撑爆。同时--data/--data-file提供的内容必须是合法 JSONinternal/cmd/ctl.go非 JSON 请求体会在发送前被拦截。令牌生命周期管理创建、轮换和吊销服务令牌需要交互式管理员令牌包括所需的双因素验证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各子命令的行为与后端实现mcp/service_tokens.go、internal/mcp/service_token.go子命令后端接口行为说明tokens listGET /api/service_tokens列出全部服务令牌不含明文tokens createPOST /api/service_tokens必填--name≤64 字符与--scope可重复api:read/api:write/mcp:read/mcp:write--expires-at接受 RFC3339 时间必须是未来时间tokens rotate TOKEN_IDPOST /api/service_tokens/:id/rotate轮换会立即使旧令牌失效——后端用新的随机 secret 重写 verifier并清空last_used_attokens revoke TOKEN_IDDELETE /api/service_tokens/:id设置revoked_at时间戳吊销为永久操作不可逆令牌的底层形态令牌格式为nui_pat_publicID_secretpublicID 为 12 字节随机数Base64 URL 编码后 16 字符secret 为 32 字节随机数43 字符见 internal/mcp/service_token.go 与解析逻辑L187-L203。数据库只保存由 HKDF 派生的 HMAC-SHA256 验证器L221-L237验证时使用常量时间比较subtle.ConstantTimeCompareL156有效防御时序侧信道。此外令牌验证时同步刷新last_used_at字段便于审计与闲置清理管理端路由同时保留/api/mcp/tokens作为兼容别名mcp/service_tokens.go服务令牌的创建、轮换、吊销接口除RequireInteractiveUser外还叠加了RequireSecureSession2FA 验证与RejectInDemo演示模式拒绝签发防止演示访问者滥用凭据两道中间件mcp/service_tokens.go。安全设计要点小结综合官方文档与源码nginx-ui ctl在安全上做了多层设计在自动化脚本中应保持这些默认行为令牌最小化按需授予api:read/api:write设置过期时间服务令牌与交互式会话严格隔离。凭据不入参数优先--token-file/--token-stdin/环境变量避免出现在进程参数与 shell 历史中。防凭据外泄拒绝绝对 URL、禁用重定向跟随、证书输出递归脱敏、16 MiB 大小上限。强 TLS 基线默认最低 TLS 1.2支持--ca-file对接私有 CA。敏感操作要求交互式会话用户管理、令牌生命周期管理强制交互式管理员令牌并叠加安全会话2FA校验。将这些实践落实到 CI 流水线例如用nginx test校验配置后再nginx reload用certificates import注册既有证书用api子命令对接尚未有专用命令的接口即可把 Nginx UI 纳入标准的 GitOps / 配置即代码工作流。若需对照中文资料可参阅仓库内的 docs/zh_CN/guide/cli.md命令的完整实现与测试用例可深入阅读 internal/cmd/ctl.go 与 internal/cmd/ctl_test.go。赞分享后端前端运维MCP 服务【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址https://gitcode.com/gh_mirrors/ngi/nginx-ui点击查看免费下载相关推荐Nginx UI 命令行接口nginx-ui ctl实战指南服务令牌、远程运维与自动化Nginx UI 命令行接口nginx ui ctl实战指南服务令牌、远程运维与自动化 nginx ui ctl 是 Nginx UI 内置的命令行管理工后端前端运维MCP 服务专业终端视觉优化指南iTerm2主题定制与美学实践专业终端视觉优化指南iTerm2主题定制与美学实践 在当今开发工作流中终端界面已成为程序员日常交互的核心环境。然而长时间面对单调的默认配色不仅会导致视觉疲开发工具Nginx UI 的 MCP 模块为 AI Agent 提供 Nginx 配置管理与服务控制接口Nginx UI 的 MCP 模块为 AI Agent 提供 Nginx 配置管理与服务控制接口 MCPModel Context Protocol模型上后端前端运维MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考