直接跳至正文内容
真机实测 · 优惠码同步
EU EUServerLab 欧服实验室
实操指南 更新于: · 10 分钟阅读

Netcup 新版 SCP REST API (OAuth2) 与 CCP DNS-01 自动化指南:自动快照、rDNS 与泛域名证书 (2026)

详解 2026 Netcup 新版 SCP OpenAPI v1(Keycloak OAuth2 离线令牌自动快照/rDNS)与 CCP DNS-01(acme.sh / Traefik 泛域名 SSL 防超时配置)。

作者:刘海 (Hai Liu · 系统与云成本测试工程师) · * 文内优惠码与下单直链含合作伙伴标识(rel="sponsored"),不增加任何购买费用。

核心要点

更新于: 2026-11-22

快速实操步骤清单

  1. 1
    通过 OAuth2 设备流获取 SCP 离线 Refresh Token

    请求 Keycloak /auth/device 接口(client_id=scp & scope='openid offline_access'),浏览器确认一次后将 refresh_token 存入 /etc/netcup-scp.env(权限 600)。

  2. 2
    编写定时脚本换取短期 Bearer 令牌并创建快照

    每次执行时先向 /token 接口换取 access_token,再调用 /scp-core/api/v1/servers/{id}/snapshots 创建零成本快照(x86 支持在线快照,ARM 需先关机)。

  3. 3
    在 CCP 生成 API 凭证并配置 600 秒 DNS 生效等待

    登录 CCP -> Master Data -> API(CloudDNS/新版 REST 用 API Key;传统 ACME 插件用 Legacy API Key + Legacy API Password),为 acme.sh 配置 --dnssleep 600 或为 Traefik 设置 NETCUP_PROPAGATION_TIMEOUT=900。

很多开发者在折腾 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 APIhttps://api.netcup.com(OpenAPI 3.1 REST API)API Key(在 CCP Master Data -> API 生成)新版 CloudDNS 区域管理与域名生命周期 REST 自动化
CCP 经典 Legacy APIhttps://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)
控机面板与终端配置路径示意 AS197540 · SCP
Server Control Panel (SCP) 控机台 · RS 1000 G12.5 核心功能视图
servercontrolpanel.de · KVM 救援终端 · 自挂 ISO · €0 免费快照 · 自助开 25 端口
💿 光驱挂载 (Custom ISO)
自助上传挂载 Proxmox VE / Debian 12 / Alpine 任意镜像
📸 免费快照 (CoW Snapshots)
€0 免费写时复制快照,改崩内核或数据库前快速无损回滚
🔓 SCP → Firewall 防火墙
无需工单,手动删除默认「netcup Mail block」规则即可放行 25/465/587 端口
🌐 双栈网络与 rDNS 反解
欧/美 2.5Gbps Fair-Use · IPv4 /22 与 IPv6 /64 支持自助 PTR 反解
新版 SCP OpenAPI v1 通过 OAuth2 令牌管理 KVM 生命周期、免费写时复制快照、防火墙策略与双栈 rDNS

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 时,你会看到两类凭证入口:

方案 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"
      - "[email protected]"
      - "--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 完成初始化、防火墙下发与快照巡检。

服务端实时码池 · 点击优惠码直接带入结算
切换同系机型优惠码:
#rs1

RS 1000 G12.5 独享核主力款

免 2 个月月费 · 新老用户通用(选 12 个月合同期生效)

EPYC 9645/9655 Zen 5 4 核独享 CPU 8GB DDR5 ECC 128GB NVMe · 欧/美 2.5G
★ 折扣差额对比:专属优惠码 vs 新人 €5 免税通用券 (#5e)
免税视图(0% VAT)下,使用 #rs1 首年实省 €36.52,相比 #5e 新人券(免税直减 €5.00)多省 €31.52,且新老账号通用。
正从 5 个可用码中随机抽取 1 个... 1/5 点击直接带码下单(自动生效)* →
* 推广合作链接(不增加购买费用)
自动带码跳官方购物车(?gutschein=)· 机型专属码新老用户通用。 查看完整用券规则与新老号边界 →

常见问题解答 (FAQ)

为什么网上老教程里的 Netcup SCP SOAP 脚本现在全部报错失效了? ▼

因为 Netcup 已将控机面板 SCP(servercontrolpanel.de)全面迁移至基于 Keycloak OpenID Connect(OAuth2)鉴权的 OpenAPI 3.1 REST 架构(https://www.servercontrolpanel.de/scp-core/api/v1,路径严格区分大小写且统一为全小写,并支持 IP/CIDR 白名单),不再接受旧版静态 SOAP 密码调用。

可以用 SCP 的 OAuth2 令牌去给域名添加 TXT 解析申请泛域名证书吗? ▼

不可以。域名与 DNS 解析归属在财务与域名面板 CCP(customercontrolpanel.de),需在 CCP 左侧「Master Data / Stammdaten -> API」按场景生成凭证:新版 netcup API(https://api.netcup.com,OpenAPI 3.1 REST 接口,用于 CloudDNS 与域名管理)使用标准 API Key;而传统域名 DNS 区域及现存 acme.sh(dns_netcup)/ Traefik 插件则使用 Legacy API Key 与 Legacy API Password 调用 ccp.netcup.net/run/webservice/servers/endpoint.php。

为什么 acme.sh 或 Traefik 用 Netcup DNS-01 申请证书经常报 NXDOMAIN 验证失败? ▼

这不是密钥填错,而是因为 Netcup 免费权威 DNS 服务器采用约 5–10 分钟一次的批量区域重载机制。在 acme.sh 中加上 --dnssleep 600,或在 Traefik/Lego 中设置 NETCUP_PROPAGATION_TIMEOUT=900 即可 100% 稳定签发。

开启了 2FA 两步验证的 SCP 账号怎么跑无人值守定时快照? ▼

首次在命令行发起带 scope='openid offline_access' 的 OAuth2 设备码授权(Device Flow),在浏览器完成一次登录与 2FA 确认即可拿到持久化 refresh_token;只要每 30 天内至少刷新调用一次即可长期免人工续期。

更多实操指南与机型评测

同级主机横向对比