主控安装
在授权中心生成安装命令、一条命令安装 cdnca 主控、首次登录，网关端口与防火墙，以及按失败步骤处理。
装完就能用：社区版免激活，不必先去授权中心登记。一键命令与制品见下载页；节点可自建或从节点平台订阅，市场能力随版本开放。下方正文保留商业授权场景步骤（含授权 IP），社区版可跳过激活相关项。 打开下载页
主控是你自己的 CDN 管理后台。安装由主控管理员在一台全新的服务器上完成，命令从授权中心生成。安装过程中会同时创建首个管理员，装完直接登录，不需要再做“首次初始化”。
准备
- 一台全新安装系统的 x86_64 服务器和它的 root 权限，系统与配置见系统要求。不要预装 Web 服务、数据库等环境。
- 一份可用的主控授权，授权 IP 与这台服务器的公网 IP 一致。
- 打算用域名访问时，先把管理域名（例如 console.cdnca.com）解析到这台服务器，并确保 TCP 80 能从公网访问（用于申请 HTTPS 证书）。
- 一个能收信的邮箱，用于证书申请联系。
第一步：在授权中心生成安装命令
- 登录授权中心，打开左侧“我的授权”，点击本次使用的授权进入详情。
- 在“授权详情”核对“授权 IP”与服务器公网 IP 一致。不一致时先回列表修改主控 IP；未登记的 IP 下载安装脚本会返回 403。
- 在右侧“安装说明”点击“一键安装脚本”→“生成安装命令”→“复制”。命令里带一次性激活凭据，24 小时内有效，只显示这一次。
命令只用于自己的服务器，不要发给他人或贴到公开工单。授权已经装过主控时，详情页不再生成首装命令，迁移请看迁移到新服务器。
命令的样子如下（实际以授权中心复制的为准，激活凭据由页面自动带上）：
(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')第二步：在服务器上执行
以 root 登录服务器，粘贴整条命令执行。不需要另外拼接下载地址或激活参数。安装器会逐步显示当前步骤、整体进度和预计剩余时间，完整输出写入 /var/log/cdnca-install-control-*.log。
按提示填写：
| 提示 | 怎么填 |
|---|---|
| 管理端公网域名或 IP | 管理员和用户访问后台用的地址，例如 console.cdnca.com；用域名时先确认解析正确 |
| HTTPS 端口 | 默认 443；用其他端口时，之后的访问地址都要带上这个端口 |
| 证书联系邮箱 | 能收信的邮箱，用于 HTTPS 证书申请；它不是管理员登录名 |
| 管理员用户名 | 自己设置，没有通用默认账号；小写字母开头，3–128 位，可用小写字母、数字、下划线、点和连字符 |
| 管理员密码 | 自己设置，8–1024 位，至少包含大写字母、小写字母、数字、符号中的两种，不能含空格或中文；输入时屏幕不显示字符，按提示再输一次 |
预检结果分两种：“不通过”是硬性条件（系统版本、架构、内存、端口占用等），必须处理后才能继续；“警告”可以确认后继续，也可以在命令末尾加 --yes 跳过确认。
也可以用参数直接给出这些值，适合批量或无人值守安装：
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.com已有可信的公网证书时，用 --public-cert-file 和 --public-key-file 指定证书与私钥文件，安装器就不再申请证书。
第三步：确认安装完成并登录
- 等终端出现 control-api installed, activated and ready。只看到下载完成或解压完成时不要关闭终端。
- 在浏览器打开 https://console.cdnca.com/dashboard/login。端口不是 443 时写成 https://console.cdnca.com:端口/dashboard/login。终端里打印的 Control plane URL 不带端口，以你填的端口为准。
- 用刚设置的管理员用户名和密码登录，检查右上角账号、授权状态和到期时间。
也可以在服务器上确认服务状态，四项都应为 active：
systemctl is-active cdnca-control-api cdnca-agent-gateway cdnca-control-nats cdnca-control-web回到授权中心的授权详情，“授权 IP”“授权域名”应显示这台主控上报的值。
网关端口、防火墙与证书
- 安装结束时会告知两个网关端口（节点注册、节点通道）。不指定时在 20000–29999 随机选两个空闲端口，也可以用 --gateway-ports 注册,通道 指定。不要照抄旧教程里的固定端口。
- 在主机防火墙和云安全组放行 TCP 443、80 以及这两个网关端口。不要整体关闭防火墙。
- 用域名安装时，证书申请需要域名解析正确且 TCP 80 可从公网访问。
- 直接用 IP 安装时，主控使用本机私有 CA 证书，浏览器会提示不受信任；先核对服务器地址无误再继续。
- 管理后台前面套 CDN 时，CDN 对外 443，回源端口填管理端 HTTPS 端口（默认 443，即安装时 --master-port 填的端口）。节点经 CDN 连网关时另行配置，回源端口填网关注册端口，按安装结束时的提示或“网关管理”页操作。
安装失败时
命令返回安装器自己的退出码；下载失败、下载内容为空或不完整时，不会执行任何安装步骤。终端最后会标出失败的步骤（“✗ [第几步/共几步] … 失败”）、版本和日志位置，上方的 error 行是原因。完整输出（含失败子命令的输出）在 /var/log/cdnca-install-control-*.log。按失败的步骤处理：
| 失败在哪一步 | 本机状态 | 怎么处理 |
|---|---|---|
| 第 1–4 步：环境预检、基础工具、激活凭据与管理员、下载并校验安装包 | 还没写入主控状态，激活凭据未使用 | 按 error 行处理（登记出口 IP、放行端口、换可用的下载源等），然后重新执行同一条命令；凭据过期就回授权中心重新生成 |
| 第 5–8 步：安装依赖、生成身份与证书、下载节点组件、初始化数据库 | 已写入部分状态 | 按 error 行修复后重新执行同一条命令。安装器提示 existing control installation state 或 existing_state_requires_review 时，不要手工删目录凑成“全新”，把日志与失败步骤交技术支持，或换一台干净的服务器 |
| 第 9 步（激活授权）及以后 | 授权端可能已记录本次安装 | 不要重复全新安装；保留日志，按 error 行和日志里对应的“>>> …（失败输出）”段排查。要换服务器，先在授权中心把主控 IP 改成新服务器的出口 IP（旧服务器的主控随之停止获取授权），再整机迁移（见迁移到新服务器）或在新服务器全新安装 |
常见原因：
- 下载返回 403：授权 IP 与服务器出口 IP 不一致，在授权中心改成正确的 IP 后重试。
- 激活凭据过期：回授权详情重新生成安装命令。
- 域名打不开：核对解析、公网 IP、实际端口和云安全组；修改 DNS 后等待生效。
- 密码输入时没有字符：这是隐藏输入，输完回车，再按提示确认。
- 装完不能登录：核对用户名、完整访问地址（含端口）和服务状态。忘记密码见问题处理。