Install the control plane
Generate the command in the licence centre, install the cdnca control plane, sign in, gateway ports and firewall, and what to do for each failed step.
Community edition needs no activation — you do not have to register at the licence centre first. See Downloads for the one-liner and packages. Host your own nodes or subscribe on the node platform; marketplace features open by version. The steps below still cover commercial licences (including licensed IP); community installs can skip activation items. Open Downloads
The control plane is your own CDN console. Your administrator installs it on a fresh server with a command generated in the licence centre. The installer also creates the first administrator, so you sign in straight after; there is no separate first-run setup.
Before you start
- A freshly installed x86_64 server with root access; see requirements. Do not pre-install web servers, databases or similar.
- A valid control-plane licence whose licensed IP matches the server's public IP.
- To use a domain, point the console domain (for example console.cdnca.com) at the server first and keep TCP 80 reachable from the internet (needed to issue the HTTPS certificate).
- An e-mail address that receives mail, used as the certificate contact.
Step 1: generate the install command
- Sign in to the licence centre, open "My licences" and click the licence you will use.
- In the licence details, check that the licensed IP matches the server's public IP. If not, change the control-plane IP in the list first; an unregistered IP gets 403 when downloading the installer.
- Under the install instructions, click "One-click install script" → "Generate install command" → "Copy". The command carries a one-time activation credential, valid for 24 hours and shown only once.
Use the command only on your own server; do not share it or paste it in public tickets. Once a licence has a control plane installed, the details page no longer generates a first-install command; to move servers see migrate to a new server.
The command looks like this (always use the one copied from the licence centre; it adds the credential for you):
(f=$(mktemp) || exit 1; trap 'rc=$?; rm -f "$f"; exit $rc' EXIT; trap 'exit 130' INT; trap 'exit 143' TERM; { curl --proto '=https' --proto-redir '=https' -fsSL -o "$f" 'https://auth.cdnca.com/downloads/install-control.sh'; } || { rc=$?; echo '[cdnca-control] error: 无法下载安装脚本' >&2; exit $rc; }; { [ "$(head -c 2 "$f")" = '#!' ] && [ "$(tail -n 1 "$f")" = 'main "$@"' ]; } || { echo '[cdnca-control] error: 下载的安装脚本为空或不完整' >&2; exit 1; }; bash "$f" --licensing-server 'https://auth.cdnca.com')Step 2: run it on the server
Sign in as root and paste the whole command. Do not add download URLs or activation flags yourself. The installer shows each step, overall progress and the estimated time left; the full output goes to /var/log/cdnca-install-control-*.log.
Answer the prompts:
| Prompt | What to enter |
|---|---|
| Console public domain or IP | The address admins and users open, for example console.cdnca.com; check DNS first when using a domain |
| HTTPS port | 443 by default; with another port, every console address must include it |
| Certificate contact e-mail | A working mailbox for HTTPS certificate requests; it is not the admin login |
| Admin username | Your choice, there is no default account; starts with a lowercase letter, 3–128 characters of lowercase letters, digits, underscore, dot and hyphen |
| Admin password | Your choice, 8–1024 characters with at least two of upper case, lower case, digits and symbols, no spaces or non-ASCII characters; nothing is echoed while typing, enter it twice |
The preflight reports two kinds of result: "failed" items (OS version, architecture, memory, ports in use and so on) must be fixed before you continue; "warning" items can be confirmed, or skipped with --yes at the end of the command.
You can also pass the values as flags for scripted installs:
bash install-control.sh --licensing-server 'https://auth.cdnca.com' --master-host console.cdnca.com --master-port 443 --certificate-email ops@cdnca.com --admin-username admin --admin-email ops@cdnca.comIf you already have a trusted public certificate, pass it with --public-cert-file and --public-key-file and the installer will not request one.
Step 3: confirm and sign in
- Wait for control-api installed, activated and ready in the terminal. Do not close it after "download complete" or "unpacked".
- Open https://console.cdnca.com/dashboard/login. With a port other than 443 use https://console.cdnca.com:PORT/dashboard/login. The "Control plane URL" printed in the terminal omits the port; use the port you entered.
- Sign in with the admin username and password you set and check the account, licence status and expiry.
On the server, all four services should be active:
systemctl is-active cdnca-control-api cdnca-agent-gateway cdnca-control-nats cdnca-control-webIn the licence centre, the licence details should now show the licensed IP and domain reported by this control plane.
Gateway ports, firewall and certificates
- The installer prints two gateway ports at the end (node enrollment and node channel). By default it picks two free ports in 20000–29999; set them with --gateway-ports enrollment,channel if needed. Do not copy fixed ports from old guides.
- Open TCP 443, 80 and both gateway ports in the host firewall and the cloud security group. Do not turn the firewall off.
- With a domain, issuing the certificate needs correct DNS and TCP 80 reachable from the internet.
- With an IP only, the control plane uses a private local CA and browsers warn that it is untrusted; check the server address before continuing.
- To put the console behind a CDN, keep 443 public and set the origin port to the management HTTPS port (443 by default, or the --master-port value). Nodes that reach the gateway through a CDN are set up separately: the origin port is the gateway enrollment port; follow the installer's closing notes or the Gateways page.
If the install fails
The command returns the installer's own exit code; a failed, empty or truncated download runs no install step. The last lines mark the failed step ("✗ [step/total] … 失败"), the version and the log; the error line above is the cause. The full output, including the failed sub-command's output, is in /var/log/cdnca-install-control-*.log. Act on the failed step:
| Failed step | State on the host | What to do |
|---|---|---|
| Steps 1–4: preflight, base tools, activation credential and admin, download and verify | No control-plane state written; credential unused | Fix what the error line says (register the egress IP, open ports, use a reachable download source) and run the same command again; generate a new command if the credential expired |
| Steps 5–8: dependencies, identity and certificates, node components, database | Some state written | Fix the cause and run the same command again. If the installer reports existing control installation state or existing_state_requires_review, do not delete directories to make the host look fresh; send the log and failed step to support, or use a clean server |
| Step 9 (activate) and later | The licence server may have recorded this installation | Do not rerun the fresh install; keep the log and follow the error line and the matching ">>> …（失败输出）" section. To move servers, first change the master IP to the new server's egress IP in the license center (the old server's control plane then stops receiving the licence), then move the whole server (see migrate to a new server) or install fresh on the new server |
Common causes:
- 403 on download: the licensed IP is not the server's egress IP; correct it in the licence centre and retry.
- Credential expired: generate a new install command in the licence details.
- Domain does not open: check DNS, public IP, the actual port and the security group; wait for DNS changes to apply.
- No characters while typing the password: input is hidden; press Enter and confirm.
- Cannot sign in after install: check the username, the full address including the port, and service status. For a lost password see troubleshooting.
More in troubleshooting. Next: install a node.