很多开发者在折腾 Netcup 自动化运维时容易踩两个坑:一是照搬早年博客里早已废弃的 SCP SOAP 接口,二是把 SCP 控机面板与 **CCP 账务/域名面板(含新版 REST netcup API 与经典 Legacy API)**的凭证混为一谈。2026 年现行双面板 API 架构分工如下:
| 归属面板 | 官方 API 端点前缀 | 鉴权与安全机制 | 支持自动化的核心能力 |
|---|---|---|---|
| SCP 控机面板 | https://www.servercontrolpanel.de/scp-core/api/v1(OpenAPI 3.1,全小写区分大小写) | Keycloak OAuth2(client_id=scp,offline_access 换 Bearer JWT;支持 IP/CIDR 白名单) | 开关机/硬重启、€0 免费快照(x86 在线 CoW / ARM 离线快照)、SCP 云端防火墙、IPv4/IPv6 PTR 反向解析、救援模式与挂载 ISO |
CCP 新版 netcup API | https://api.netcup.com(OpenAPI 3.1 REST API) | API Key(在 CCP Master Data -> API 生成) | 新版 CloudDNS 区域管理与域名生命周期 REST 自动化 |
CCP 经典 Legacy API | https://ccp.netcup.net/run/webservice/servers/endpoint.php(JSON / SOAP) | Legacy 会话(客户号 customernumber + Legacy API Key + Legacy API Password) | 经典权威 DNS 解析记录(A、AAAA、TXT、CAA)、现成 ACME DNS-01 泛域名自动续签插件(acme.sh / Traefik / 1Panel) |
1. 获取新版 SCP REST API v1 离线令牌(兼容 2FA 免浏览器续期)
由于 SCP 全面启用了 Keycloak 统一身份认证与 TOTP 两步验证,无人值守脚本需先通过 OAuth2 Device Authorization Flow(设备授权流) 获取一枚带 offline_access 权限的持久化 refresh_token:
# 第一步:发起设备码请求(务必包含 offline_access 以便定时任务离线换取令牌)
DEVICE_RESP=$(curl -sS -X POST \
"https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/auth/device" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=scp" \
-d "scope=openid offline_access")
echo "$DEVICE_RESP" | jq -r '"请在浏览器打开并确认授权: \(.verification_uri_complete)\n设备验证码: \(.user_code)"'
DEVICE_CODE=$(echo "$DEVICE_RESP" | jq -r '.device_code')
# 第二步:浏览器完成登录 + 2FA 点击同意后,执行以下命令保存持久化 refresh_token
TOKEN_RESP=$(curl -sS -X POST \
"https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
-d "client_id=scp" \
-d "device_code=${DEVICE_CODE}")
REFRESH_TOKEN=$(echo "$TOKEN_RESP" | jq -r '.refresh_token')
sudo install -m 600 /dev/null /etc/netcup-scp.env
echo "SCP_REFRESH_TOKEN=${REFRESH_TOKEN}" | sudo tee /etc/netcup-scp.env >/dev/null
官方 OpenAPI 3.1 文档、MCP 端点与 IP 白名单: SCP REST API 遵循 OpenAPI 3.1 规范,登录 SCP 后可直接访问
https://www.servercontrolpanel.de/scp-core/api/v1/openapi(以及 MCP 规范端点https://www.servercontrolpanel.de/scp-core/api/v1/openapi/mcp或面板右上角 Account → API)查阅完整字段定义。注意所有 REST 路径严格区分大小写且统一为全小写,生产环境建议在 SCP 设置中配置 IP / CIDR 访问白名单(Allowlist)。
2. 生产级自动写时复制(CoW)快照脚本
Netcup G12.5 x86 独享核 Root-Server 与常规 x86 VPS 在磁盘留有余量时,支持在 SCP 内创建 €0 免费本地在线写时复制(Copy-on-Write)快照(载荷中传入 "onlineSnapshot": true);需要注意 ARM64 机型(VPS ARM G12.5)仅支持离线快照(Offline Snapshots),调用快照接口前必须先将虚拟机正常关机停止。将以下脚本保存为 /usr/local/sbin/netcup-auto-snapshot.sh 并挂载到系统升级或数据库迁移前执行,即可实现秒级兜底回滚:
#!/usr/bin/env bash
set -euo pipefail
source /etc/netcup-scp.env
API_BASE="https://www.servercontrolpanel.de/scp-core/api/v1"
TOKEN_URL="https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token"
# 1. 使用离线 refresh_token 换取当前有效的短期 Bearer access_token
ACCESS_TOKEN=$(curl -fsS -X POST "$TOKEN_URL" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "client_id=scp" \
-d "refresh_token=${SCP_REFRESH_TOKEN}" | jq -r '.access_token')
# 2. 查询账号下第一台服务器的数字 ID(多台机器可按 name 过滤如 v2202611...)
SERVER_ID=$(curl -fsS -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"${API_BASE}/servers" | jq -r '.[0].id')
SNAP_NAME="auto-$(date -u +%Y%m%d-%H%M)"
# 3. 创建快照(x86 Root-Server / x86 VPS 支持 onlineSnapshot: true 在线无感快照;
# 若为 VPS ARM G12.5,仅支持离线快照,必须先关机停止实例并将 onlineSnapshot 设为 false)
curl -fsS -X POST "${API_BASE}/servers/${SERVER_ID}/snapshots" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"name\":\"${SNAP_NAME}\",\"description\":\"Automated pre-upgrade CoW snapshot\",\"onlineSnapshot\":true}"
echo "已成功为服务器 ${SERVER_ID} 创建免费快照: ${SNAP_NAME}"
同理,部署自建邮局时(详见《25 端口放行与双栈 PTR 邮局配置指南》),也可直接向 ${API_BASE}/rdns/ipv4 与 ${API_BASE}/rdns/ipv6 提交 JSON 自动绑定反向解析。
3. CCP DNS-01 泛域名 SSL 自动续签(解决 NXDOMAIN 超时核心技巧)
登录 CCP(customercontrolpanel.de)→ 左侧 Master Data / Stammdaten → API 时,你会看到两类凭证入口:
- 新版
netcup API(https://api.netcup.com,OpenAPI 3.1 REST API): 生成标准 API Key,适合管理 CloudDNS 与自研域名自动化脚本。 - 经典
Legacy API(https://ccp.netcup.net/run/webservice/servers/endpoint.php): 生成Legacy API Key与Legacy API Password,供传统免费权威 DNS 区域(如购买 建站虚拟主机 获赠的免费域名或单独注册的.de/.com)直接对接现成的acme.sh(dns_netcup)、Traefik/Lego 与 1Panel 插件。
方案 A:acme.sh 签发泛域名证书(必加 --dnssleep 600)
Netcup 权威 DNS 集群并非秒级实时刷新,而是每 5 至 10 分钟批量同步一次区域文件。不加等待参数会导致 Let’s Encrypt 提前查不到 _acme-challenge 记录而报错:
export NC_Apikey="你的_CCP_API_KEY"
export NC_Apipw="你的_CCP_API_PASSWORD"
export NC_CID="你的纯数字客户号_Kundennummer"
acme.sh --issue --dns dns_netcup \
--dnssleep 600 \
-d example.com -d '*.example.com' \
--keylength ec-256
方案 B:Traefik v3 / Coolify / 1Panel 容器网关配置
在 Coolify 或 Dokploy 中使用 Traefik 自动签发证书(含不暴露 80 端口的内网 WireGuard 面板域名):
services:
traefik:
image: traefik:v3.2
command:
- "--certificatesresolvers.le-netcup.acme.dnschallenge=true"
- "--certificatesresolvers.le-netcup.acme.dnschallenge.provider=netcup"
- "--certificatesresolvers.le-netcup.acme.dnschallenge.delaybeforecheck=600"
- "--certificatesresolvers.le-netcup.acme.dnschallenge.resolvers=46.38.225.230:53,1.1.1.1:53"
- "--certificatesresolvers.le-netcup.acme.email=ops@example.com"
- "--certificatesresolvers.le-netcup.acme.storage=/letsencrypt/acme.json"
environment:
NETCUP_CUSTOMER_NUMBER: "${NC_CID}"
NETCUP_API_KEY: "${NC_Apikey}"
NETCUP_API_PASSWORD: "${NC_Apipw}"
NETCUP_PROPAGATION_TIMEOUT: "900"
NETCUP_POLLING_INTERVAL: "30"
4. Terraform / OpenTofu 适用边界提示
如果你习惯用基础设施即代码(IaC)编排资源:DNS 解析记录可通过新版 https://api.netcup.com(CloudDNS REST 接口)或社区 netcup-dns Terraform Provider(对接 CCP Legacy API)自动化维护;而计算实例采用 1M / 12M / 24M 合同制且无 API 动态创建/销毁新服务器接口(注:x86 VPS 虽在帮助中心支持可选按小时计费模式,但不像 Hetzner Cloud 可用 Terraform 随时开删实例;合同期管理请使用符合 AGB § 6 规则的 提前 1 个月通知期退订工具),推荐在首次下单开通后,结合 SCP REST API v1 + Ansible 完成初始化、防火墙下发与快照巡检。
RS 1000 G12.5 独享核主力款
免 2 个月月费 · 新老用户通用(选 12 个月合同期生效)