---
title: 安裝錯誤
description: NexCMP 安裝程式可能列印的每個錯誤訊息、成因與修復方法 — 包含系統需求、授權啟用、下載驗證、服務以及 nginx/TLS。
url: https://nexcmp.com/zh-tw/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)` | 記憶體不足 | 請增加 RAM。 |
| `requires ≥ 8 GB free disk space on / (… GB available)` | 根檔案系統幾近全滿 | 釋放空間或擴充 `/`。 |
| `missing --license` / `missing --domain` | 首次安裝時未使用這些參數 | 請同時傳入二者 — 請參閱 [Installation](https://nexcmp.com/zh-tw/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、防火牆與proxy：`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-tw/docs/troubleshooting/support/)。 |

## 下載與驗證 {#download-and-verification}

| 訊息 | 原因 | 修正方式 |
|---|---|---|
| `failed to download release X` | 下載期間發生網路問題 | 再次執行。 |
| `sha256 mismatch (… ≠ …)` | 檔案到達時受損或遭到竄改 | 再次執行；若重複發生，可能是proxy正在重寫下載內容——請嘗試從其他網路執行。 |
| `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-tw/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-tw/docs/getting-started/cli-reference/#emergency-access)。 |
| `ERR_TOO_MANY_REDIRECTS` | Cloudflare SSL模式為**Flexible** | 設定 **Full (strict)** — [details](https://nexcmp.com/zh-tw/docs/getting-started/dns-and-cloudflare/)。 |
| 精靈顯示「安裝代碼」錯誤 | 拼字錯誤或來自早期安裝的代碼 | 執行 `sudo nexcmp status` 並複製目前的代碼。 |
| 授權顯示 HTTP 421 | `/var/lib/nexcmp` 中的檔案擁有者為 root | `sudo nexcmp fix-owner`，然後 `sudo systemctl restart nexcmp`。 |