server-helper

安全地准备 macOS / Linux 主机，并把域名与 HTTPS 接到本机服务端口。

快速开始 · 使用指南 · 部署指南 · 参数参考 · 常用命令 · 排查

@xenonbyte/server-helper 是一个在目标主机本地运行的接入工具。它准备 Docker、Nginx、ACME 与证书续期环境，校验域名和端口，并把每个精确域名代理到独立的 loopback 服务端口。

它不构建或发布业务项目，也不管理数据库、内部 DNS、业务 A/AAAA 记录、防火墙、云安全组或负载均衡器。DNS-01 场景下，它只使用操作员配置的 provider 凭据自动维护 ACME challenge TXT 记录。

[!IMPORTANT] 所有修改命令默认都是 dry-run。只有显式添加 --apply 才会修改主机。

部署 Cipher Server：从 Cipher 部署指南 开始，默认 API / Admin 端口为 5000 / 5001。本页的 8080 / 9090 是通用示例；遇到问题直接查 故障排查手册。

工作原理

客户端
  │ HTTPS :443
  ▼
Nginx（server-helper 管理）
  ├── api.example.com   ──► http://127.0.0.1:8080
  └── admin.example.com ──► http://127.0.0.1:9090

| 责任方 | 负责 | 不负责 | |---|---|---| | 项目 | 镜像、Compose、依赖、迁移、业务密钥、健康检查、业务回滚、稳定 loopback 端口 | Nginx、80/443、证书、ACME、server-helper 状态 | | server-helper | Docker/Nginx/ACME 主机接入、DNS-01 profile 与 challenge TXT、TLS、证书续期、域名到本地端口的映射 | 项目构建、数据库、内部 DNS、业务 A/AAAA、防火墙、云基础设施 | | 运维或云平台 | DNS zone 与 API 凭据授权、内部 DNS、业务 A/AAAA、NAT、负载均衡入口、防火墙、云安全组 | 项目镜像和 server-helper 的受管文件 |

[!NOTE] TLS 由接入层处理，不代表项目可以忽略公开地址。PUBLIC_URL、CORS、OAuth redirect URI 和 Cookie 策略仍属于业务配置。

环境要求

支持矩阵版本：2026-07-29。

| 系统 | 版本 | 环境 | |---|---|---| | macOS | 13.3+、14、15、26 | 仅 test | | Ubuntu | 22.04、24.04、26.04 | test、prod | | Debian | 12、13 | test、prod | | CentOS Stream | 9、10 | test、prod |

支持 amd64 和 arm64。Linux 必须使用 systemd，且不能在容器内执行宿主机准备。

• 目标主机已经安装 Node.js 和 npm；本工具不安装它们，也不声明额外的最低 Node.js 版本。
• Linux 的 CLI 使用 /usr 或 /opt 下的系统级全局 npm prefix，例如 /usr/local；macOS 还支持当前登录用户的标准 nvm prefix，例如 ~/.nvm/versions/node/v24.13.0。
• 项目长期提供一个稳定的 loopback 服务端点；推荐 127.0.0.1:<port>，也支持 ::1。
• Linux Docker Engine 服务端 ≥ 28.0.0；CLI 版本不代表服务端版本。本机 Docker 必须可访问，已有旧版需操作员明确升级。
• 本机 TCP 80 和 443 可交给受管 Nginx；DNS-01 也要求这两个本机端口没有冲突。
• 你能控制目标域名，并已准备所需的 DNS、入口网络和 ACME 条件。
• 交互操作可以使用 sudo；需要提权的非交互操作必须具备 passwordless sudo。

[!WARNING] 项目本地安装和 npx 不适用于持久主机操作。Linux 拒绝用户目录下的 npm prefix，且全局 prefix、CLI 入口和包文件必须由 root 拥有并禁止 group/other 写入。macOS 只额外接受当前登录用户拥有、禁止 group/other 写入的标准 nvm 版本目录；持久任务会固定到该 Node 版本，移除它前必须在新版本中安装 CLI 并重新执行 host prepare --apply。

主机准备会安装或校验所需组件：Linux 使用系统 Nginx、Docker Engine / Compose 和 systemd 续期任务；macOS 使用 Docker Desktop、受管 Nginx 容器和用户 LaunchAgent。满足版本要求的已有 Docker 与 Compose 会被保留，无法安全补齐依赖时明确失败。

macOS 还需：

• Docker Desktop 开启 Settings → Resources → Network → Enable host networking，关闭 Enhanced Container Isolation。
• macOS 13 使用 Docker Desktop 4.34–4.48.x；macOS 14+ 使用 4.34+。
• 以当前登录用户运行 CLI，不要在命令前加 sudo；删除 nvm 版本前先迁移全局 CLI 并重新准备主机。
• ACME 路径、下载或迁移失败按 故障排查手册 处理，不手工合并账户目录。

找到你的部署场景

先按实际网络选择。下面快速开始采用「公网直连 + HTTP-01」；其他场景的完整流程见 不同环境部署指南：

| 你的情况 | 证书模式 | 关键参数 | |---|---|---| | Linux 有公网 IP，域名直接解析到它 | HTTP-01（自动） | 无 | | Linux 在 NAT、云负载均衡或前置代理之后 | HTTP-01（自动） | 可重复的 --expected-ip IP | | 公网入站 TCP 80 不可达，本机 80/443 可用 | DNS-01（显式） | --cert-mode dns-01 --dns-profile NAME | | 域名只在内网解析（Linux 或 macOS 测试机） | DNS-01（自动强制） | --exposure lan --dns-profile NAME | | 一台主机接多个域名 | 各站点独立 | 每个域名一个稳定 loopback 端口 | | 项目自己已经是 HTTPS | 不变 | --upstream-scheme https + TLS name + 可信 CA |

[!IMPORTANT] server-helper 只校验内部 DNS、业务 A/AAAA、CAA、防火墙、云安全组、NAT 和负载均衡配置，不会创建或修改它们。DNS-01 签发和续期仅临时维护 challenge TXT。请先完成外部配置，并确认目标主机和预期客户端的实际 DNS 解析结果正确。

接入任何域名前，先从目标主机确认解析结果符合预期：

dig +short A api.example.com
dig +short AAAA api.example.com

.local、仅写入 /etc/hosts 或无法公开验证的内部名称不能申请 Let's Encrypt 证书；局域网测试域名也必须属于你真实控制的公网域名。路由器不能下发自定义 DNS、需要使用 dnsmasq/NAS、Android 无法修改 hosts，或遇到代理 Fake-IP 198.18.x.x 时，请按 局域网 DNS 与 site add 接入指南 逐项配置并验证。

快速开始

1. 安装 CLI

以下命令在目标主机执行。先安装系统受信的 Node.js / npm，然后按平台选择：

Linux（示例使用 /usr/local 系统 prefix）：

command -v node
command -v npm
sudo npm install --global --prefix /usr/local @xenonbyte/server-helper
/usr/local/bin/server-helper --version

将 /usr/local/bin 放入发布用户 PATH，确保 command -v server-helper 指向此安装。若 Node/npm 来自用户 nvm 目录，先准备系统级 Node/npm，不能把用户可写的包登记给 root 续期任务。

macOS（当前登录用户，可使用标准 nvm）：

npm install --global @xenonbyte/server-helper
server-helper --version

Linux 每台主机只保留一个系统级全局安装。macOS 可以直接使用当前 nvm Node 版本中的全局安装；host prepare 会提示并记录精确路径，但不会安装或替换 CLI。

2. 准备主机

先预览计划，确认后用相同参数重新校验并应用：

server-helper host prepare
server-helper host prepare --apply

Linux 首次准备默认使用 sudo-only Docker 访问方式，后续省略该参数时沿用已有设置。如果明确接受 docker 组等同 root 的安全风险，可改用 --docker-access group --apply；工具只会撤销由自己添加的组成员关系。

Cipher 的 Linux 发布用户需要直接运行 Compose，因此两次准备命令均加 --docker-access group，应用后重新登录，再运行 docker ps 验证。macOS 使用当前用户 Docker Desktop，不设 Linux 组模式。

3. 让项目只监听 loopback

services:
  api:
    ports:
      - "127.0.0.1:8080:8080"

容器内应用可以监听 0.0.0.0:8080，但上例发布到宿主机的端口必须绑定到 127.0.0.1；直接运行的服务也可以绑定到 ::1。

4. 接入域名

域名应先解析到本机公网地址。首次执行时保留 dry-run，审查计划后再用相同参数追加 --apply：

先将示例域名和邮箱替换成实际值；example.com 不能直接申请证书。局域网环境请先按 场景 D 准备内部 DNS 与 DNS profile。

server-helper site add \
  --env prod \
  --domain api.example.com \
  --upstream-port 8080 \
  --acme-email [email protected]

server-helper site add \
  --env prod \
  --domain api.example.com \
  --upstream-port 8080 \
  --acme-email [email protected] \
  --apply

公网域名默认使用 HTTP-01，并要求外部 TCP 80 可达。工具会校验 DNS 和 CAA，但不会修改 DNS、防火墙、云安全组或 NAT。

5. 验证状态

server-helper doctor
server-helper doctor --domain api.example.com
server-helper site list

doctor 只读且不会修复主机。任何必需检查失败时退出码为 50；无法从本机证明的外部可达性会标记为 UNVERIFIED。

接下来的日常操作——改端口、开 WebSocket/SSE、暂停恢复、续期检查、诊断、升级卸载——见 使用指南。

常用命令

| 命令 | 用途 | |---|---| | server-helper host prepare | 预览或调和主机环境 | | server-helper host unprepare | 移除受管主机集成；不会删除 npm 包或 Linux 系统软件 | | server-helper dns profile configure | 创建或调和可复用 DNS profile，并安全存储凭据 | | server-helper dns profile rotate | 轮换受管 DNS 凭据 | | server-helper dns profile list / show | 只读查看 profile 元数据；永不返回秘密 | | server-helper dns profile remove | 删除未被站点使用的 profile、凭据和本地 ACME 数据 | | server-helper site add | 接入新域名 | | server-helper site update | 修改已有站点；域名本身不可重命名 | | server-helper site enable / disable | 恢复代理，或保留 HTTPS 并返回 503 | | server-helper site list | 列出站点 | | server-helper site status --domain DOMAIN | 运行主机和指定站点检查 | | server-helper site remove | 备份后删除指定站点；不会修改 DNS | | server-helper transaction recover --run-id RUN_ID | 验证并解除受支持的 incomplete 事务门禁 | | server-helper doctor | 严格只读诊断 |

# 修改端口
server-helper site update --domain api.example.com --upstream-port 8181 --apply

# 暂停和恢复
server-helper site disable --domain api.example.com --apply
server-helper site enable --domain api.example.com --apply

# 删除：先预览，再应用
server-helper site remove --domain api.example.com
server-helper site remove --domain api.example.com --apply

非交互删除还必须添加 --yes。site remove 保存的是人工恢复材料，不是自动恢复功能。

完整参数、默认值、退出码和自动化契约见 CLI 参数参考，或运行 server-helper <command> --help。

安全默认值

• 默认 dry-run、loopback 上游、HTTP 跳转 HTTPS；拒绝混合公私地址和无法确认的检查结果。
• 入口重建可信转发头，不拼接客户端提供的代理链；前置七层代理需单独核对回源和客户端 IP 策略。
• 秘密只经隐藏提示或受保护的凭据文件输入，不提供命令行 key / secret 参数。
• 修改使用写锁、事务、备份和回滚；未知事务会阻止后续写操作，不能通过删除收据绕过。

全部约束见 参数参考。自动化使用 --non-interactive --format json：stdout 恰好一个 JSON 对象，日志在 stderr，不要合并后解析。

项目日常部署

site add/update 是低频基础设施操作。日常发布只处理项目构建、Compose、数据库迁移、loopback 健康检查和项目自己的故障恢复策略。Cipher 当前使用本地构建和单实例替换，失败后人工修复并重新发布。

[!CAUTION] 项目发布脚本不得调用 host prepare/unprepare 或 site add/update，也不得修改 80/443、Nginx、证书、ACME 或 server-helper 状态。

完整责任矩阵和可选 Compose 发布示例见 项目部署指南。

排查

先在目标主机运行 server-helper doctor --domain api.example.com，再从实际客户端访问域名。两边的 DNS 和网络可能不同，主机检查成功不等于客户端可达。

| 卡在哪里 | 下一步 | |---|---| | CLI 安装、权限或 Docker 版本 | 主机准备 | | 80/443 或应用端口冲突 | 端口与上游 | | DNS、Fake-IP、AAAA、provider 或证书失败 | DNS 与证书 | | 502 / 504 / 413、CORS、客户端超时 | HTTPS 和客户端访问 | | 旧站点、续期或事务恢复 | 升级与续期、恢复 |

升级与卸载

npm 独占 CLI 包文件。升级或降级后，重新运行幂等的主机准备来调和续期任务和持久状态：

安装命令沿用第 1 步的平台和 prefix；Linux 示例中的 npm 安装需使用相同系统 prefix 和所需的 sudo 权限。

Linux 更新示例：

sudo npm install --global --prefix /usr/local @xenonbyte/server-helper@latest

macOS 更新示例：

npm install --global @xenonbyte/server-helper@latest

随后两种平台均执行：

server-helper host prepare
server-helper host prepare --apply

已有站点还需检查代理模板：host prepare 不会重写站点配置。运行 doctor，若出现 forwarded_headers 失败，按 旧站点升级步骤 用一个明确的现有配置值执行 site update。只传域名不会重建模板。请保留配置校验和门禁，不要手改 Nginx 或状态文件。

卸载顺序固定为：删除所有站点、移除主机集成、最后由 npm 删除 CLI。

server-helper site remove --domain api.example.com --apply
server-helper host unprepare --apply
npm uninstall --global @xenonbyte/server-helper

host unprepare 在仍有站点时会拒绝执行。它移除续期调度器、受管 Nginx 集成、host state 和仅由工具添加的 Docker 组成员关系；不会卸载 Linux 上的 Docker、Nginx、Git 等系统包，也不会删除 npm 包。

如需同时删除受管状态、证书历史、ACME 私有数据、日志和备份，用 --purge-data --yes 替代普通 host unprepare。数据清除支持中断后续跑；请把原始 DNS 凭据存放在受管数据根之外，purge 不会删除这些目录之外的文件。

受管数据

| 平台 | 主要受管路径 | |---|---| | Linux | /etc/server-helper、/var/lib/server-helper/{state,acme,certs,transactions,backups}、/var/lib/server-helper/acme-webroot、/var/log/server-helper、/var/log/nginx/server-helper、/run/server-helper | | macOS | ~/Library/Application Support/server-helper/{config,state,certs,transactions,backups,run,nginx/sites}、~/.local/share/server-helper/acme、~/Library/Logs/server-helper、~/Library/LaunchAgents/net.xstudio.server-helper.renew.plist |

Linux 还会管理 systemd renewal service/timer、Nginx include 和 logrotate 配置。CLI 文件位于 npm 全局 prefix（npm root --global），由 npm 独占管理。

开发验证

npm test
npm run test:package

测试在带安全标记的临时根目录中运行，不会安装真实主机软件或占用真实的 80/443。包验证会检查精确发布文件、可执行入口，以及隔离的全局和本地安装。

文档

| 文档 | 内容 | 什么时候看 | |---|---|---| | 使用指南 | 心智模型、计划输出怎么读、全部日常操作、续期与诊断 | 装好之后，想知道日常怎么用 | | 不同环境部署指南 | 公网直连、NAT/负载均衡、公网 80 不可达、局域网测试、多站点、HTTPS 上游 | 首次接入或环境变化 | | CLI 参数参考 | 全部命令的参数、默认值、约束、退出码与自动化契约 | 查某个参数到底怎么用 | | 局域网 DNS 与 site add 接入指南 | dnsmasq、NAS/DHCP、Android、代理 Fake-IP、DNS-01 与逐项验证 | 局域网客户端解析不到域名 | | 故障排查手册 | 按症状给出执行位置、检查命令、预期结果和处理方法 | 命令失败、访问不通或升级旧站点 | | 项目部署指南 | 责任边界、Cipher 发布方式和可选 Compose 脚本 | 写项目自己的发布流程 | | 维护者发布指南 | 版本同步、精确 tarball、npm 发布与发布后验证 | 发布本工具的新版本 |

命令行内置帮助随时可查：server-helper --help、server-helper site --help、server-helper dns profile --help、server-helper transaction --help、server-helper doctor --help。