企业官网建设流程全解析

• 后端
• 前端
• 运维
• MCP 服务

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 界面中创建

1. 以管理员身份登录 Nginx UI。
2. 打开Preferences > Access Tokens（对应前端页面 app/src/views/preference/tabs/AccessTokens.vue）。
3. 按最小权限原则创建令牌：只授予任务所需的最小 scope，并设置过期时间。
4. 立即复制令牌。Nginx UI 不会再次显示它——数据库里只保存验证器（verifier），不保存明文令牌。

API 权限范围（Scope）

在源码中，scope 常量定义于 model/mcp_service_token.go，除 API scope 外还有独立的 MCP scope：

MCPTokenScopeRead = "mcp:read" MCPTokenScopeWrite = "mcp:write" APITokenScopeRead = "api:read" APITokenScopeWrite = "api:write"

scope 的包含关系由 internal/mcp/service_token.go 中的HasScope实现：api:write隐式包含api:read，mcp: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_ENDPOINT=https://nginx-ui.example.com nginx-ui ctl --token-file /run/secrets/nginx-ui-token users list

端点与令牌的提供方式如下表：

从源码看（internal/cmd/ctl.go），newCtlClient会先取--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 证书链。源码会在系统证书池基础上追加该 CA（internal/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-password

users 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.pem

certificates（别名certs）子命令的实现见 internal/cmd/ctl.go：

• import的--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.go）：status走GET /api/nginx/status，test、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?page=1 nginx-ui ctl --token-file /run/secrets/nginx-ui-token api \ --method POST --data-file site.json sites

api子命令的参数（internal/cmd/ctl.go）：

路径解析与安全边界

路径会解析到/api之下（internal/cmd/ctl.go），具体规则：

• 相对路径如sites?page=1会拼接为<endpoint>/api/sites?page=1；
• 若路径本身已以/api开头（如/api/nginx/status），则按原样使用，不重复拼接；
• 查询字符串被保留；
• 拒绝绝对 URL（如https://attacker.test/api/users），防止凭据被重定向到其他主机；
• 客户端还禁用了自动重定向（CheckRedirect返回ErrUseLastResponse，见 internal/cmd/ctl.go），相关行为有测试TestCtlClientDoesNotFollowRedirects佐证（internal/cmd/ctl_test.go）。

请求/响应大小限制

请求体和响应体均限制为16 MiB（maxCLIInputSize = 16 << 20，见 internal/cmd/ctl.go）。超限的文件、令牌输入或 API 响应都会返回明确的错误，避免内存被异常数据撑爆。同时，--data/--data-file提供的内容必须是合法 JSON（internal/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）：

令牌的底层形态

令牌格式为nui_pat_<publicID>_<secret>：publicID 为 12 字节随机数（Base64 URL 编码后 16 字符），secret 为 32 字节随机数（43 字符），见 internal/mcp/service_token.go 与解析逻辑（L187-L203）。数据库只保存由 HKDF 派生的 HMAC-SHA256 验证器（L221-L237），验证时使用常量时间比较（subtle.ConstantTimeCompare，L156），有效防御时序侧信道。此外：

• 令牌验证时同步刷新last_used_at字段，便于审计与闲置清理；
• 管理端路由同时保留/api/mcp/tokens作为兼容别名（mcp/service_tokens.go）；
• 服务令牌的创建、轮换、吊销接口除RequireInteractiveUser外，还叠加了RequireSecureSession（2FA 验证）与RejectInDemo（演示模式拒绝签发，防止演示访问者滥用凭据）两道中间件（mcp/service_tokens.go）。

安全设计要点小结

综合官方文档与源码，nginx-ui ctl在安全上做了多层设计，在自动化脚本中应保持这些默认行为：

1. 令牌最小化：按需授予api:read/api:write，设置过期时间；服务令牌与交互式会话严格隔离。
2. 凭据不入参数：优先--token-file/--token-stdin/环境变量，避免出现在进程参数与 shell 历史中。
3. 防凭据外泄：拒绝绝对 URL、禁用重定向跟随、证书输出递归脱敏、16 MiB 大小上限。
4. 强 TLS 基线：默认最低 TLS 1.2，支持--ca-file对接私有 CA。
5. 敏感操作要求交互式会话：用户管理、令牌生命周期管理强制交互式管理员令牌，并叠加安全会话（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 服务