---
title: 安装错误
description: NexCMP 安装程序可能打印的每个错误消息、其原因及修复方法 — 包含系统要求、许可证激活、下载验证、服务以及 nginx/TLS。
url: https://nexcmp.com/zh-cn/docs/troubleshooting/installation-errors/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 安装错误 {#installation-errors}

安装程序在遇到第一个致命问题时会停止，并打印以 `✗` 开头的红线。请修复原因并**再次运行相同命令** — 安装程序可安全重复执行。信息性行以 `•` 开头，成功步骤以 `✓` 开头。

## 机器检查 {#machine-checks}

| 消息 | 原因 | 解决办法 |
|---|---|---|
| `must be run as root (sudo)` | 未以 root 身份运行 | 在命令前加 `sudo`，或以 root 身份运行。 |
| `only Ubuntu 22.04/24.04 is supported (this host: …)` | 其他发行版或版本 | 请使用 Ubuntu 22.04 或 24.04 服务器。 |
| `only x86_64 is supported` | ARM 或其他 CPU | 请使用 x86_64 服务器。 |
| `requires ≥ 2 GB RAM (host has … MB)` | 内存过少 | 请添加内存。 |
| `requires ≥ 8 GB free disk space on / (… GB available)` | 根文件系统将满 | 请释放空间或扩容 `/`。 |
| `missing --license` / `missing --domain` | 首次安装时未带这些参数 | 请同时传入两者 — 参见 [Installation](https://nexcmp.com/zh-cn/docs/getting-started/installation/#parameters)。 |
| `unknown argument: …` | 参数拼写错误 | 请检查拼写；使用 `--help` 重新运行。 |
| `apt-get failed (another apt/dpkg process, e.g. unattended-upgrades, may still be running)` | 包管理器被锁定 | 等待几分钟（全新Ubuntu在启动后会自动运行更新）并重新运行。 |
| `… is a symlink — aborting` | `/opt/nexcmp` 或 `/etc/nexcmp` 是符号链接 | 请将其替换为真实的目录——安装程序出于安全考虑拒绝使用符号链接。 |

## 许可证激活 {#license-activation}

| 消息 | 原因 | 解决办法 |
|---|---|---|
| `cannot connect to https://nexcmp.com` | 服务器无通往许可证服务器的出站HTTPS | 检查服务器上的DNS、防火墙和代理：`curl -I https://nexcmp.com`。 |
| `license activation failed (HTTP …): <message>` | 许可证服务器拒绝了此密钥 | 阅读提示信息：密钥错误、域名与许可证不符、许可证已被暂停或撤销。请访问 [nexcmp.com/licenses](https://nexcmp.com/licenses) 检查许可证页面。 |
| `no release available for this license yet` | 该许可证没有可下载的版本 | 联系销售；参见 [Support](https://nexcmp.com/zh-cn/docs/troubleshooting/support/)。 |

## 下载与验证 {#download-and-verification}

| 消息 | 原因 | 解决办法 |
|---|---|---|
| `failed to download release X` | 下载时发生网络问题 | 重新运行。 |
| `sha256 mismatch (… ≠ …)` | 文件下载损坏或被篡改 | 重新运行；若问题依旧，可能是代理篡改了下载内容——请尝试换一个网络环境。 |
| `release X is unsigned — refusing to install` | 服务器未返回签名 | 切勿绕过；请联系支持团队。 |
| `INVALID SIGNATURE for version X — aborting` | Ed25519 签名验证失败 | 请**不要**安装。请联系支持团队——这表示该文件并非官方版本。 |
| `openssl failed to read public key` | OpenSSL 版本过旧或损坏 | 更新 `openssl` 软件包。 |
| `invalid version: …` | 来自服务器的意外数据 | 重新运行；若问题持续存在，请联系支持团队。 |

## 服务启动 {#service-start}

| 消息 | 原因 | 解决办法 |
|---|---|---|
| `service failed to start — check: journalctl -u nexcmp -n 50` | 面板未在3分钟内响应 `/healthz` | 查看日志。常见原因：端口（默认3000）已被占用（`ss -ltnp | grep 3000`）——请使用 `--port` 重新安装；`/var/lib/nexcmp` 中的文件属于 root 用户——请运行 `sudo nexcmp fix-owner`。 |

## nginx 与 TLS {#nginx-and-tls}

| 消息 | 原因 | 解决办法 |
|---|---|---|
| `DNS <domain> does not point to <IP> (nor to Cloudflare) — skipping nginx/TLS` | A/AAAA记录缺失或错误 | 参见 [DNS and Cloudflare](https://nexcmp.com/zh-cn/docs/getting-started/dns-and-cloudflare/)，然后重新运行。 |
| `certbot could not get a certificate yet — re-run the installer once DNS has settled` | Let's Encrypt 验证失败（80端口被阻断、DNS未生效、达到速率限制） | 开放80端口，等待DNS生效，然后重新运行。检查 `/var/log/letsencrypt/letsencrypt.log`。 |
| `certbot could not renew now — keeping the existing certificate` | 临时续签失败 | 不影响正常使用；稍后重新运行即可。 |
| `nginx rejected the HTTPS configuration — kept the previous one (check: nginx -t)` | 与其他 nginx 站点冲突（相同的 `server_name`，重复的设置） | 运行 `sudo nginx -t` 并解决冲突，然后重新运行。 |
| `apt-get could not install nginx` / `certbot` 或 `E: Failed to fetch … 404 Not Found` | 包管理器被锁定，或者服务器的软件包索引过期（在长时间未更新的模板镜像上很常见） | 运行 `sudo apt-get update`，等待其他 apt 进程结束，然后重新运行安装程序。 |
| `openssl could not create the self-signed certificate` | OpenSSL 问题 | 更新 `openssl`；然后重新运行。 |

## 安装之后 {#after-installation}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| 浏览器无法打开 `https://<domain>` | DNS 或 TLS 尚未准备就绪 | `sudo nexcmp status`；请使用 [emergency access](https://nexcmp.com/zh-cn/docs/getting-started/cli-reference/#emergency-access)。 |
| `ERR_TOO_MANY_REDIRECTS` | Cloudflare SSL 模式为 **Flexible** | 设置**Full (strict)** — [详情](https://nexcmp.com/zh-cn/docs/getting-started/dns-and-cloudflare/)。 |
| 向导提示“安装代码”错误 | 输入错误或使用了早期安装的代码 | 运行`sudo nexcmp status`并复制当前代码。 |
| 许可证显示 HTTP 421 | `/var/lib/nexcmp`中的文件所有者为 root | `sudo nexcmp fix-owner`，然后`sudo systemctl restart nexcmp`。 |