Open API RSA 模式使用指南

1. 概述

1.1 文档说明

本文档指导开发者使用 RSA 签名模式调用共绩算力 Open API。RSA 模式在 Token 鉴权基础上增加请求签名，适用于生产环境及对安全性要求较高的集成场景。

阅读本文档前，建议先了解 Open API 接入指南 中的基础概念与 Token 模式。

1.2 RSA 模式工作原理

客户端                                    共绩算力 Open API
  │                                              │
  │  1. 本地持有 RSA 私钥（签名）                 │
  │  2. 平台保存 RSA 公钥（验签）                 │
  │                                              │
  │  构建待签名字符串 → RSA-SHA256 签名           │
  │  ─────────── HTTP Request ──────────────►  │
  │     Header: token, version, timestamp,       │
  │             sign_str                         │
  │     Body: JSON 或加密后的 Base64             │
  │                                              │
  │  ◄────────── HTTP Response ───────────────  │
  │     { code, msg, data }                      │

1.3 与 Token 模式的区别

1.4 基础信息

2. 快速开始

以下流程可在约 15 分钟内完成 RSA 模式首次调用。

openssl genrsa -out private.key 2048
openssl rsa -pubout -in private.key -out public.pem

3. 密钥生成与平台配置

3.1 本地生成密钥对

推荐使用 OpenSSL 生成 2048 位 RSA 密钥对：

openssl genrsa -out private.key 2048

openssl rsa -pubout -in private.key -out public.pem

openssl genrsa -aes256 -out private.key 2048

3.2 在平台配置公钥

1. 访问 https://console.suanli.cn/settings/key
2. 点击「新建密钥」→ 选择「RSA 加验签模式」
3. 填写备注，粘贴公钥（从 -----BEGIN PUBLIC KEY----- 到 -----END PUBLIC KEY----- 的完整内容）
4. 点击生成，立即复制并保存平台返回的 API Token 和 RSA 公钥

3.3 密钥格式说明

默认推荐使用 RsaPkcs8Pem 格式。

4. 签名与加密规范

4.1 请求头（RSA 模式）

4.2 签名流程

1. 构建待签名字符串（5 个字段，以换行符 \n 连接）
2. 使用 RSA 私钥 + SHA-256 + PKCS1v15 填充进行签名
3. 对签名结果进行 Base64 编码
4. 将结果写入 Header sign_str

4.3 待签名字符串规范

{path}\n{version}\n{timestamp}\n{token}\n{body}

4.4 签名示例

GET 请求（无 Body）：

path      = /api/deployment/resource/search
version   = 1.0.0
timestamp = 1770194570564
token     = your-api-token-here
body      = （空字符串）

待签名字符串：
/api/deployment/resource/search
1.0.0
1770194570564
your-api-token-here

POST 请求（含 Body）：

path      = /api/deployment/task/create
version   = 1.0.0
timestamp = 1770194570564
token     = your-api-token-here
body      = {"task_name":"test-task","points":1}

待签名字符串：
/api/deployment/task/create
1.0.0
1770194570564
your-api-token-here
{"task_name":"test-task","points":1}

4.5 请求体加密（可选）

部分接口（如「创建任务」）支持请求体 RSA 加密。是否需要加密以接口文档中「是否需要加密」字段为准。

加密算法规范：

4.6 加密流程：

1. 将请求体 dict 序列化为紧凑 JSON 字符串
2. 按 244 字节分段，使用平台公钥逐段 RSA 加密
3. 拼接所有密文块，进行 Base64 编码 → 得到 encrypted_body
4. 将 encrypted_body 作为 HTTP 请求体发送
5. 签名时 body 字段填入 encrypted_body（先加密，后签名）

4.7 完整请求流程

┌──────────────────────────────────────────────────┐
│ 1. 准备请求体（JSON 或空）                         │
│ 2. 如需加密 → RSA 公钥加密 → Base64               │
│ 3. 构建待签名字符串 path\nversion\n...\nbody      │
│ 4. RSA-SHA256 签名 → Base64 → sign_str            │
│ 5. 设置 Header 并发送 HTTP 请求                     │
└──────────────────────────────────────────────────┘

4.8 加密请求签名示例

以「创建任务」接口为例，假设原始 JSON 为：

{"task_name":"test-task","points":1}

加密后 HTTP 请求体变为 Base64 字符串（示意）：

xK7g3fP2mN8vQ1wR5tY9zA...(加密后的 Base64，非原始 JSON)

签名时 body 字段使用加密后的 Base64 字符串：

path      = /api/deployment/task/create
version   = 1.0.0
timestamp = 1770194570564
token     = your-api-token-here
body      = xK7g3fP2mN8vQ1wR5tY9zA...(加密后的 Base64)

待签名字符串：
/api/deployment/task/create
1.0.0
1770194570564
your-api-token-here
xK7g3fP2mN8vQ1wR5tY9zA...(加密后的 Base64)

5. 请求与响应说明

5.1 HTTP 请求示例

POST /api/deployment/task/detail HTTP/1.1
Host: openapi.suanli.cn
Content-Type: application/json
token: your-api-token-here
version: 1.0.0
timestamp: 1770194570564
sign_str: EowIBAAKCAQEA...(Base64 签名)

{"task_id": 1}

5.2 cURL 示例

curl -X POST "https://openapi.suanli.cn/api/deployment/task/detail" \
  -H "Content-Type: application/json" \
  -H "token: your-api-token-here" \
  -H "version: 1.0.0" \
  -H "timestamp: 1770194570564" \
  -H "sign_str: YOUR_BASE64_SIGNATURE" \
  -d '{"task_id": 1}'

5.3 统一响应格式

{
  "code": 0000,
  "msg": "success",
  "data": { }
}

5.4 加密请求 HTTP 示例

加密请求的 HTTP Body 为 Base64 字符串（非 JSON 对象），签名同样基于加密后的 Body：

POST /api/deployment/task/create HTTP/1.1
Host: openapi.suanli.cn
Content-Type: application/json
token: your-api-token-here
version: 1.0.0
timestamp: 1770194570564
sign_str: EowIBAAKCAQEA...(Base64 签名)

xK7g3fP2mN8vQ1wR5tY9zA...(加密后的 Base64 请求体)

5.5 加密请求 cURL 示例

curl -X POST "https://openapi.suanli.cn/api/deployment/task/create" \
  -H "Content-Type: application/json" \
  -H "token: your-api-token-here" \
  -H "version: 1.0.0" \
  -H "timestamp: 1770194570564" \
  -H "sign_str: YOUR_BASE64_SIGNATURE" \
  -d "xK7g3fP2mN8vQ1wR5tY9zA..."

6. 代码集成示例

6.1 环境准备

Python：

pip install cryptography requests

Java： JDK 11+（内置 java.net.http 与 java.security）

Go： Go 1.18+（标准库 crypto/rsa）

6.2 核心签名函数（Python）

import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding

def gen_sign(private_key, path, version, timestamp, token, body=""):
    """生成 RSA-SHA256 签名"""
    sign_content = f"{path}\n{version}\n{timestamp}\n{token}\n{body}"
    signature = private_key.sign(
        sign_content.encode("utf-8"),
        padding.PKCS1v15(),
        hashes.SHA256(),
    )
    return base64.b64encode(signature).decode("utf-8")

6.3 请求体加密函数（Python）

import base64
import json
from cryptography.hazmat.primitives.asymmetric import padding

def encrypt_body(platform_public_key, json_data: dict) -> str:
    """使用平台公钥加密请求体，返回 Base64 字符串"""
    json_str = json.dumps(json_data, separators=(",", ":"), ensure_ascii=False)
    data_bytes = json_str.encode("utf-8")

    encrypted_chunks = []
    chunk_size = 244  # RSA-2048 + PKCS1v15 单段最大明文长度
    for start in range(0, len(data_bytes), chunk_size):
        chunk = data_bytes[start : start + chunk_size]
        encrypted_chunks.append(
            platform_public_key.encrypt(chunk, padding.PKCS1v15())
        )

    return base64.b64encode(b"".join(encrypted_chunks)).decode("utf-8")

6.4 GET 请求示例（Python，无加密）

import time
import requests
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import serialization

BASE_URL = "https://openapi.suanli.cn"
API_TOKEN = "your-api-token-here"
PRIVATE_KEY_PATH = "./private.key"
API_VERSION = "1.0.0"

with open(PRIVATE_KEY_PATH, "rb") as f:
    private_key = serialization.load_pem_private_key(
        f.read(), password=None, backend=default_backend()
    )

path = "/api/deployment/resource/search"
timestamp = str(int(time.time() * 1000))
body = ""

sign_str = gen_sign(private_key, path, API_VERSION, timestamp, API_TOKEN, body)

headers = {
    "Content-Type": "application/json",
    "token": API_TOKEN,
    "version": API_VERSION,
    "timestamp": timestamp,
    "sign_str": sign_str,
}

response = requests.get(BASE_URL + path, headers=headers)
print(response.json())

6.5 POST 加密请求示例（Python）

import time
import requests
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import serialization

BASE_URL = "https://openapi.suanli.cn"
API_TOKEN = "your-api-token-here"
PRIVATE_KEY_PATH = "./private.key"              # 您的私钥，用于签名
PLATFORM_PUBLIC_KEY_PATH = "./platform_pub.pem" # 平台公钥，用于加密
API_VERSION = "1.0.0"

with open(PRIVATE_KEY_PATH, "rb") as f:
    private_key = serialization.load_pem_private_key(
        f.read(), password=None, backend=default_backend()
    )

with open(PLATFORM_PUBLIC_KEY_PATH, "rb") as f:
    platform_public_key = serialization.load_pem_public_key(
        f.read(), backend=default_backend()
    )

path = "/api/storage/encrypt/check"
timestamp = str(int(time.time() * 1000))

json_data = {
    "storage_name": "demo-oss",
    "juicefs_region_id": 3,
    "bucket": "demo-bucket",
    "dir": "dataset",
    "endpoint": "oss-cn-beijing.aliyuncs.com",
    "access_key": "access-key",
    "secret_key": "secret-key"
}

encrypted_body = encrypt_body(platform_public_key, json_data)

sign_str = gen_sign(
    private_key, path, API_VERSION, timestamp, API_TOKEN, encrypted_body
)

headers = {
    "Content-Type": "application/json",
    "token": API_TOKEN,
    "version": API_VERSION,
    "timestamp": timestamp,
    "sign_str": sign_str,
}

response = requests.post(
    BASE_URL + path,
    headers=headers,
    data=encrypted_body,  # 发送加密后的 Base64 字符串
)
print(response.json())

6.6 POST 加密请求示例（Java）

import javax.crypto.Cipher;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

public class EncryptedPostExample {

    private static final String BASE_URL = "https://openapi.suanli.cn";
    private static final String API_TOKEN = "your-api-token-here";
    private static final String API_VERSION = "1.0.0";
    private static final int CHUNK_SIZE = 244;

    public static void main(String[] args) throws Exception {
        PrivateKey privateKey = loadPrivateKey("./private.key");
        PublicKey platformPublicKey = loadPublicKey("./platform_pub.pem");

        String path = "/api/deployment/task/create";
        String timestamp = String.valueOf(System.currentTimeMillis());
        String json = "{\"task_name\":\"test-task\",\"points\":1}";

        // 1. 加密
        String encryptedBody = encryptBody(platformPublicKey, json);

        // 2. 签名（基于加密后的 body）
        String signStr = genSign(privateKey, path, API_VERSION, timestamp, API_TOKEN, encryptedBody);

        // 3. 发送
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + path))
                .header("Content-Type", "application/json")
                .header("token", API_TOKEN)
                .header("version", API_VERSION)
                .header("timestamp", timestamp)
                .header("sign_str", signStr)
                .POST(HttpRequest.BodyPublishers.ofString(encryptedBody))
                .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }

    static String encryptBody(PublicKey publicKey, String plainText) throws Exception {
        Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
        cipher.init(Cipher.ENCRYPT_MODE, publicKey);
        byte[] data = plainText.getBytes(StandardCharsets.UTF_8);
        java.io.ByteArrayOutputStream output = new java.io.ByteArrayOutputStream();
        for (int i = 0; i < data.length; i += CHUNK_SIZE) {
            int end = Math.min(i + CHUNK_SIZE, data.length);
            output.write(cipher.doFinal(data, i, end - i));
        }
        return Base64.getEncoder().encodeToString(output.toByteArray());
    }

    static String genSign(PrivateKey privateKey, String path, String version,
                          String timestamp, String token, String body) throws Exception {
        String content = path + "\n" + version + "\n" + timestamp + "\n" + token + "\n" + body;
        Signature sig = Signature.getInstance("SHA256withRSA");
        sig.initSign(privateKey);
        sig.update(content.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(sig.sign());
    }

    static PrivateKey loadPrivateKey(String path) throws Exception {
        String pem = Files.readString(Path.of(path))
                .replace("-----BEGIN PRIVATE KEY-----", "")
                .replace("-----END PRIVATE KEY-----", "")
                .replaceAll("\\s", "");
        byte[] keyBytes = Base64.getDecoder().decode(pem);
        return KeyFactory.getInstance("RSA")
                .generatePrivate(new PKCS8EncodedKeySpec(keyBytes));
    }

    static PublicKey loadPublicKey(String path) throws Exception {
        String pem = Files.readString(Path.of(path))
                .replace("-----BEGIN PUBLIC KEY-----", "")
                .replace("-----END PUBLIC KEY-----", "")
                .replaceAll("\\s", "");
        byte[] keyBytes = Base64.getDecoder().decode(pem);
        return KeyFactory.getInstance("RSA")
                .generatePublic(new X509EncodedKeySpec(keyBytes));
    }
}

6.7 POST 加密请求示例（Go）

package main

import (
    "crypto"
    "crypto/rand"
    "crypto/rsa"
    "crypto/x509"
    "encoding/base64"
    "encoding/pem"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

const (
    baseURL    = "https://openapi.suanli.cn"
    apiToken   = "your-api-token-here"
    apiVersion = "1.0.0"
    chunkSize  = 244
)

func main() {
    privateKey := loadPrivateKey("./private.key")
    platformPublicKey := loadPublicKey("./platform_pub.pem")

    path := "/api/deployment/task/create"
    timestamp := fmt.Sprintf("%d", time.Now().UnixMilli())
    jsonData := `{"task_name":"test-task","points":1}`

    // 1. 加密
    encryptedBody := encryptBody(platformPublicKey, jsonData)

    // 2. 签名
    signStr := genSign(privateKey, path, apiVersion, timestamp, apiToken, encryptedBody)

    // 3. 发送
    req, _ := http.NewRequest(http.MethodPost, baseURL+path, strings.NewReader(encryptedBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("token", apiToken)
    req.Header.Set("version", apiVersion)
    req.Header.Set("timestamp", timestamp)
    req.Header.Set("sign_str", signStr)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

func encryptBody(pub *rsa.PublicKey, plain string) string {
    data := []byte(plain)
    var encrypted []byte
    for i := 0; i < len(data); i += chunkSize {
        end := i + chunkSize
        if end > len(data) {
            end = len(data)
        }
        chunk, _ := rsa.EncryptPKCS1v15(rand.Reader, pub, data[i:end])
        encrypted = append(encrypted, chunk...)
    }
    return base64.StdEncoding.EncodeToString(encrypted)
}

func genSign(priv *rsa.PrivateKey, path, version, timestamp, token, body string) string {
    content := path + "\n" + version + "\n" + timestamp + "\n" + token + "\n" + body
    sig, _ := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA256, []byte(content))
    return base64.StdEncoding.EncodeToString(sig)
}

func loadPrivateKey(path string) *rsa.PrivateKey {
    data, _ := os.ReadFile(path)
    block, _ := pem.Decode(data)
    key, _ := x509.ParsePKCS8PrivateKey(block.Bytes)
    return key.(*rsa.PrivateKey)
}

func loadPublicKey(path string) *rsa.PublicKey {
    data, _ := os.ReadFile(path)
    block, _ := pem.Decode(data)
    pub, _ := x509.ParsePKIXPublicKey(block.Bytes)
    return pub.(*rsa.PublicKey)
}

7. 调试与排错

7.1 调试 Checklist

7.2 常见错误

签名验证失败

打印待签名字符串逐字段比对；确认 body 与最终发送内容一致；确认私钥与平台公钥为同一密钥对。

私钥加载失败

检查 PEM 格式与文件路径；如有密码保护需传入 password 参数。

时间戳过期

同步系统时间；每次请求重新生成 timestamp，勿复用旧值。

加密后签名仍失败

确认 sign 使用的是加密后的 Base64 字符串，而非原始 JSON。

7.3 调试代码片段

sign_content = f"{uri}\n{version}\n{timestamp}\n{token}\n{body}"
print("--- BEGIN STRING TO SIGN ---")
print(repr(sign_content))
print("--- END STRING TO SIGN ---")
print(f"sign_str: {sign_str}")

8. 安全最佳实践

9. 常见问题

10. 相关文档