ngc（NginxConfigControl）安装与使用说明 ======================================= ngc 是运行在 Nginx 服务器上的命令行配置管理工具，用于管理配置根目录 （默认 /etc/nginx）下的配置文件：列表、交互式批量启停、字段级编辑、 永久删除、校验、重载与自更新。 一、依赖 -------- 1. bash 或 zsh、nginx。 2. coreutils、awk/sed/grep/find、flock。 3. 在线安装与自更新需要 curl 或 wget，以及 sha256sum、shasum 或 openssl 之一。 二、安装 -------- 本项目仅发布 unix 制品。macOS 会明确报错（依赖 flock 与 sort -V）。 1. 在线安装（发布版，推荐）： curl -fsSL <基地址>/nginx-config-control/unix/install.sh | bash curl -fsSL <基地址>/nginx-config-control/unix/install.sh | zsh 管道执行下不会出现任何交互提示，安装完成后按输出提示执行 source ~/.bashrc 或 source ~/.zshrc。 可选参数（管道执行时用 bash -s -- 或 zsh -s -- 传入）： --base-url URL 覆盖下载基地址 --prefix DIR 安装前缀，默认 $HOME/.local --shell bash|zsh 指定目标 shell，缺省自动识别 --reinstall 同版本已安装时也重新安装 --force 允许降级、覆盖异常现场 --insecure 跳过 TLS 校验（自签/私有 CA 服务器） -h, --help 显示帮助 示例： curl -fsSL <基地址>/nginx-config-control/unix/install.sh | bash -s -- --prefix "$HOME/.local" 基地址解析优先级（命中即用，四者皆空则报错退出）： 1) 命令行 --base-url URL 2) 环境变量 NGINX_CONFIG_CONTROL_BASE_URL 3) 用户安装配置 ~/.config/nginx-config-control/install.conf 中的 base_url= 行 4) 发布时注入的默认基地址 2. 离线安装： 从发布目录 unix/ 下载 nginx-config-control-unix-<版本>.tar.gz，解压后执行包内 install.sh： tar -xzf nginx-config-control-unix-<版本>.tar.gz -C ngc-unix cd ngc-unix bash install.sh --prefix "$HOME/.local" 包内脚本与在线安装共用同一实现，支持同样的 --prefix/--shell/--reinstall/--force。 3. 从源码目录安装（开发版）： bash install-dev.sh zsh install-dev.sh 4. 安装布局（全部相对安装前缀，默认 $HOME/.local）： <前缀>/bin/ngc <前缀>/share/bash-completion/completions/ngc <前缀>/share/zsh/site-functions/_ngc <前缀>/share/nginx-config-control/install-record 安装器会同时安装 bash 与 zsh 补全（与当前 shell 无关），并写入安装记录。 安装记录首行为 # version: vX.Y.Z，其后为已安装文件的绝对路径。 rc 受管块标记为 # >>> nginx-config-control >>>，只写入当前 shell 对应的 rc 文件（zsh 尊重 ZDOTDIR），重复安装后始终只有一块。 同版本已安装且未指定 --reinstall 时直接以 0 退出；升级会读取旧版 ~/.local/share/ngc/files.list 清理旧补全、旧状态文件与旧 # >>> ngc >>> 块， 但保留用户配置与用户数据。 从 v0.2.1 及更早版本升级（重要）：下载根为 <基地址>/nginx-config-control/unix/， 入口脚本也位于该平台目录内（v1.0.0 曾短暂使用扁平根，v1.0.1 起恢复平台层）。 旧客户端执行 ngc update 会遇到 404，请手动执行一次新版在线安装完成迁移： curl -fsSL <基地址>/nginx-config-control/unix/install.sh | bash 安装过程会写入 update_base_url，之后 ngc update 恢复正常。 旧配置 ~/.config/ngc/config 保留不删，确认无误后可自行移除。 配置模板：发布目录中的 config-templates.zip 含 config.example。 解压后可复制为 ~/.config/nginx-config-control/config 后修改， 首次安装也会自动生成该配置文件；安装时能解析到基地址则直接写入 update_base_url，否则留空待填。 三、快速开始 ------------ 所有配置管理命令需要 root 权限，例如： sudo ngc list 安装完成后先查看列表，确认配置根目录与扫描结果正确，再执行变更。 四、子命令 ---------- ngc list 树形列出配置文件、启用状态与类型 ngc toggle [--force] 交互式批量启用/禁用配置 ngc edit 交互式修改内置字段 ngc delete [--force] 永久删除配置文件 ngc check 执行 nginx -t ngc reload 校验后重载 Nginx ngc update [选项] 自更新 ngc version 显示版本 ngc help 显示帮助 常用示例： sudo ngc list sudo ngc toggle sudo ngc edit sites-available/example.com.conf sudo ngc delete conf.d/legacy.conf --force sudo ngc check sudo ngc reload 五、全局参数 ------------ --root DIR 配置根目录，默认 /etc/nginx --nginx PATH nginx 可执行文件，默认 nginx --conf PATH 校验入口配置，默认 /nginx.conf --force, --yes 覆盖冲突、跳过删除确认、允许核心文件操作 -h, --help 显示帮助 -V, --version 显示版本 参数可放在子命令前，例如： sudo ngc --root /etc/nginx list 六、list 与 toggle ------------------ 1. 列表按相对路径树形分组展示：目录标题以 / 结尾，叶子只显示文件名， 同级目录在前、文件在后，两空格缩进体现层级，不展示空目录。 2. list 输出 NAME / STATUS / TYPE 三列；类型包括站点（site）、 conf.d（confd）、核心（core）与其他（other）。 3. conf.d 下的 .conf.disabled 按逻辑配置合并展示，隐藏 .disabled 后缀。 4. toggle 中已启用为 [x]、未启用为 [ ]，光标只在叶子间移动： - 空格：切换当前项； - Enter：应用全部改动； - Esc 或 q：取消全部改动； - Ctrl-C：取消退出。 5. 应用规则： - 站点配置：在 sites-enabled 建立/删除指向 sites-available 源文件的软链； - conf.d 配置：.conf 与 .conf.disabled 相互重命名。 6. 批量应用后统一执行一次 nginx -t：失败则逆序回滚本次全部变更。 冲突（软链指向错误、目标已存在等）默认整批中止且不产生变更； --force 允许重建/覆盖并保留回滚备份。 7. core、other 及异常条目（断链、越界软链等）不进入复选列表，退出时提示。 8. 无改动时按 Enter 提示无变更；stdin 不是终端时拒绝执行。 七、edit 编辑字段 ----------------- 支持的内置字段（按指令名定位，仅替换指令值，保留缩进与行尾分号）： server_name、listen、root、proxy_pass、ssl_certificate、 ssl_certificate_key、client_max_body_size、index、access_log、error_log 1. 选择字段后输入新值，空输入视为取消本次修改。 2. 同一文件多处匹配时列出全部匹配（含行号与上下文），逐处选择修改。 3. 每次修改后执行 nginx -t 并显示结果；编辑模式退出时再汇总一次。 4. 编辑不回滚：校验失败由用户决定后续处理。 八、delete 删除 --------------- 1. 永久删除，不移动到归档目录；默认交互确认（y/N）。 2. --force 跳过确认；删除核心配置（如 nginx.conf、mime.types）必须显式 --force。 3. 删除后执行 nginx -t 并报告结果，失败不回滚但会明确警告。 4. 不允许删除配置根目录自身及目录。 九、check 与 reload ------------------- ngc check 执行 nginx -t，透传错误信息，按结果返回退出码。 ngc reload 先执行 nginx -t，校验通过后才重载 Nginx。 启用/禁用、编辑、删除都不会自动重载 Nginx，需要时显式执行 ngc reload。 十、自更新 ---------- ngc update --check 检查是否有新版本 ngc update -y 确认并更新到最新版本 更新基地址取自用户配置 update_base_url，也可用 --base-url 临时覆盖： ~/.config/nginx-config-control/config update_base_url=https://files.example.com 更新流程：下载 /nginx-config-control/unix/update-manifest.json， 远端版本更高时先展示更新说明（来自发布方的更新记录），再下载清单指定的 nginx-config-control-unix-<版本>.tar.gz、校验 sha256、解压并用包内安装脚本完成更新。 本地版本取自 <前缀>/share/nginx-config-control/install-record 首行； 前缀由 ngc 实际安装位置推导，也可用 --prefix 覆盖。 --shell 取值为 bash|zsh|auto，缺省自动识别当前 shell。 更新会以新清单 files 为准：旧记录中位于安装前缀内、且不在新清单中的文件会被删除； 前缀之外的路径只提示、不自动删除。用户配置 （~/.config/nginx-config-control/config）不会被更新覆盖或删除。 十一、卸载 ---------- curl -fsSL <基地址>/nginx-config-control/unix/uninstall.sh | bash curl -fsSL <基地址>/nginx-config-control/unix/uninstall.sh | zsh 也可使用离线归档内的 uninstall.sh： bash uninstall.sh --prefix "$HOME/.local" 可选参数： --prefix DIR 安装前缀，默认 $HOME/.local --shell bash|zsh 决定 rc 清理目标，缺省自动识别 --force 无安装记录时按默认布局清理残留文件 --base-url URL 兼容参数，卸载不联网，不生效 --reinstall 兼容参数，卸载忽略 --insecure 兼容参数，卸载不联网，不生效 卸载只删除 <前缀>/share/nginx-config-control/install-record 中记录的文件与 空目录，并从 rc 移除受管块；安装记录不存在时提示“未在该前缀下发现安装记录” 并以 0 退出。不会删除用户配置、旧配置 ~/.config/ngc/config、用户数据或 /etc/nginx 下的任何内容。 十二、注意事项 -------------- 1. 变更前建议先备份配置；工具不自动修改 nginx.conf 中的 include 语句。 2. 路径必须位于配置根目录内；越界路径与指向根目录外的软链会被拒绝。 3. 错误信息输出到 stderr，常规结果输出到 stdout。 4. <基地址> 指发布时配置的下载根，例如 https://files.example.com； 每平台目录固定为 <基地址>/nginx-config-control/<平台>/（本项目为 unix/）， install.sh、uninstall.sh、归档、sha256sums 与 update-manifest.json 均在其中。 5. 从 v0.2.1 及更早版本升级须先手动执行一次新版在线安装（见“二、安装”）。 6. 安装记录被误删时卸载无法定位文件；可加 --force 按默认布局清理残留。