# 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 防超时配置）。

- Canonical URL: https://euserverlab.com/zh/guides/netcup-scp-rest-api-dns-automation-guide/
- Language: zh-Hans
- Published: 2026-11-15 | Updated: 2026-11-22
- Publisher: EUServerLab (https://euserverlab.com/zh/methodology/)

## 核心结论摘要
- Netcup 自动化严格分为两套面板体系：新版 SCP OpenAPI 3.1 REST API v1（Keycloak OAuth2 令牌）负责开关机、免费快照、防火墙与 rDNS；客户面板 CCP 同时提供新版 netcup API（https://api.netcup.com，OpenAPI 3.1 REST 架构，用 API Key 管理 CloudDNS 与域名）以及经典 Legacy API（endpoint.php，用 Legacy API Key + Legacy API Password 对接传统 DNS 与现存 ACME 插件）。
- 旧版 SCP SOAP 接口已下线——在终端跑一次 OAuth2 Device Flow（client_id=scp，带上 offline_access）即可拿到长期离线 Refresh Token 供定时脚本调用，且可在 SCP 设置 IP/CIDR 访问白名单。
- 使用 acme.sh（dns_netcup）或 Traefik 申请 Let's Encrypt 泛域名证书时，务必设置 600–900 秒等待时间（--dnssleep 600），因为官方权威 DNS 每 5–10 分钟批量重载一次解析。
- 配合每日/升级前 SCP 免费自动快照脚本（x86 Root-Server 与 x86 VPS 支持在线无感 CoW 快照；VPS ARM G12.5 仅支持关机离线快照），可在零附加存储月费下实现生产回滚保护。

## 关键步骤清单
1. **通过 OAuth2 设备流获取 SCP 离线 Refresh Token**: 请求 Keycloak /auth/device 接口（client_id=scp & scope='openid offline_access'），浏览器确认一次后将 refresh_token 存入 /etc/netcup-scp.env（权限 600）。
2. **编写定时脚本换取短期 Bearer 令牌并创建快照**: 每次执行时先向 /token 接口换取 access_token，再调用 /scp-core/api/v1/servers/{id}/snapshots 创建零成本快照（x86 支持在线快照，ARM 需先关机）。
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 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`：

```bash
# 第一步：发起设备码请求（务必包含 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` 并挂载到系统升级或数据库迁移前执行，即可实现秒级兜底回滚：

```bash
#!/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 邮局配置指南](/zh/guides/netcup-port-25-mail-server-rdns-guide/)》），也可直接向 `${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 区域（如购买 [建站虚拟主机](/zh/webhosting/) 获赠的免费域名或单独注册的 `.de/.com`）直接对接现成的 `acme.sh`（`dns_netcup`）、Traefik/Lego 与 1Panel 插件。

### 方案 A：`acme.sh` 签发泛域名证书（必加 `--dnssleep 600`）

Netcup 权威 DNS 集群并非秒级实时刷新，而是每 **5 至 10 分钟批量同步一次区域文件**。不加等待参数会导致 Let's Encrypt 提前查不到 `_acme-challenge` 记录而报错：

```bash
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](/zh/guides/coolify-dokploy-self-hosting-netcup-guide/) 中使用 Traefik 自动签发证书（含不暴露 80 端口的内网 WireGuard 面板域名）：

```yaml
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](/zh/compare/netcup-vs-hetzner/) 可用 Terraform 随时开删实例；合同期管理请使用符合 AGB § 6 规则的 [提前 1 个月通知期退订工具](/zh/tools/cancellation-calculator/)），推荐在首次下单开通后，结合 **SCP REST API v1 + Ansible** 完成初始化、防火墙下发与快照巡检。

## 常见问题解答

### 为什么网上老教程里的 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 天内至少刷新调用一次即可长期免人工续期。

---
Source: EUServerLab (https://euserverlab.com/zh/guides/netcup-scp-rest-api-dns-automation-guide/) | Open Telemetry Dataset: https://euserverlab.com/benchmarks/vps-500-g12-5.json
