123云盘直链鉴权开发手册 - 碎梦亦欺花

123云盘直链鉴权开发手册

123云盘直链下载内容默认公开。为防止资源被非法盗链和恶意下载，建议开启 URL鉴权。通过在URL中加入加密签名（MD5）和时间戳（Timestamp），您可以有效控制链接的有效期并验证请求合法性。

1. 鉴权工作流

1. 用户服务端：根据鉴权算法、UID和私钥（PrivateKey）生成带 auth_key 参数的加密链接。
2. 终端用户：点击该加密链接发起下载请求。
3. 123云盘节点：验证时间戳是否过期，并重新计算MD5值。若校验一致且未过期，则允许下载；否则返回 403 错误。

2. URL 构造规则

2.1 鉴权 URL 格式

http://<UID>.v.123pan.cn/<UID>/<Path>?auth_key=<Timestamp>-<Rand>-<UID>-<MD5Hash>

2.2 签名计算方法(<MD5Hash>的计算)

1. 构造待签名字符串：

   URI-Timestamp-Rand-UID-PrivateKey

   (注：URI 为请求路径，必须包含 UID 部分，不包含协议头、域名及参数。例如：/13/files/1.txt)

2. 计算 MD5：

   MD5Hash = md5sum(待签名字符串)

   (注：结果为 32 位小写字符串)

3. 字段定义

字段	说明	示例
UID	用户在123云盘的唯一标识	13
Path	文件的相对路径	/files/1.txt
Timestamp	链接失效的时间点（Unix 时间戳，10位整数）	1689220731
Rand	随机字符串（建议使用 UUID 或随机数，不可含中划线）	123
PrivateKey	鉴权密钥（在123云盘管理后台设置）	289ds32418bxdba
auth_key	最终生成的鉴权参数	1689220731-123-13-3bdacc0e0...

4. 官方代码实现示例

PHP

<?php
function generateAuthUrl($baseUrl, $uid, $privateKey, $expirationMinutes = 60) {
    $timestamp = time() + ($expirationMinutes * 60);
    $rand = bin2hex(random_bytes(4));
    $urlParts = parse_url($baseUrl);
    $uri = $urlParts['path'];
    
    $signStr = "{$uri}-{$timestamp}-{$rand}-{$uid}-{$privateKey}";
    $md5Hash = md5($signStr);
    
    $authKey = "{$timestamp}-{$rand}-{$uid}-{$md5Hash}";
    return "{$baseUrl}?auth_key={$authKey}";
}

$uid = "13";
$key = "289ds32418bxdba";
$url = "[http://13.v.123pan.cn/13/files/1.txt](http://13.v.123pan.cn/13/files/1.txt)";
echo generateAuthUrl($url, $uid, $key);
?>

Java

import java.security.MessageDigest;
import java.util.UUID;

public class AuthTool {
    public static String generateAuthUrl(String baseUrl, String uid, String privateKey, int expirationMinutes) throws Exception {
        long timestamp = (System.currentTimeMillis() / 1000) + (expirationMinutes * 60);
        String rand = UUID.randomUUID().toString().replace("-", "");
        String uri = new java.net.URL(baseUrl).getPath();

        String signStr = String.format("%s-%d-%s-%s-%s", uri, timestamp, rand, uid, privateKey);
        
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] hash = md.digest(signStr.getBytes("UTF-8"));
        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        String md5Hash = hexString.toString();

        return String.format("%s?auth_key=%d-%s-%s-%s", baseUrl, timestamp, rand, uid, md5Hash);
    }

    public static void main(String[] args) throws Exception {
        System.out.println(generateAuthUrl("[http://13.v.123pan.cn/13/files/1.txt](http://13.v.123pan.cn/13/files/1.txt)", "13", "289ds32418bxdba", 60));
    }
}

Python

import hashlib
import time
import uuid
from urllib.parse import urlparse

def generate_auth_url(base_url, uid, private_key, expiration_minutes=60):
    timestamp = int(time.time()) + (expiration_minutes * 60)
    rand = uuid.uuid4().hex
    uri = urlparse(base_url).path
    
    sign_str = f"{uri}-{timestamp}-{rand}-{uid}-{private_key}"
    md5_hash = hashlib.md5(sign_str.encode('utf-8')).hexdigest()
    
    auth_key = f"{timestamp}-{rand}-{uid}-{md5_hash}"
    return f"{base_url}?auth_key={auth_key}"

uid = "13"
key = "289ds32418bxdba"
url = "[http://13.v.123pan.cn/13/files/1.txt](http://13.v.123pan.cn/13/files/1.txt)"
print(generate_auth_url(url, uid, key))

Go

package main

import (
	"crypto/md5"
	"fmt"
	"net/url"
	"time"
)

func GenerateAuthUrl(baseUrl string, uid string, privateKey string, exp int64) (string, error) {
	u, err := url.Parse(baseUrl)
	if err != nil {
		return "", err
	}
	timestamp := time.Now().Unix() + (exp * 60)
	rand := fmt.Sprintf("%d", time.Now().UnixNano())
	uri := u.Path
	
	signStr := fmt.Sprintf("%s-%d-%s-%s-%s", uri, timestamp, rand, uid, privateKey)
	md5Hash := fmt.Sprintf("%x", md5.Sum([]byte(signStr)))
	
	authKey := fmt.Sprintf("%d-%s-%s-%s", timestamp, rand, uid, md5Hash)
	return fmt.Sprintf("%s?auth_key=%s", baseUrl, authKey), nil
}

func main() {
	res, _ := GenerateAuthUrl("[http://13.v.123pan.cn/13/files/1.txt](http://13.v.123pan.cn/13/files/1.txt)", "13", "289ds32418bxdba", 60)
	fmt.Println(res)
}

C#

using System;
using System.Security.Cryptography;
using System.Text;

public class Program {
    public static string GenerateAuthUrl(string baseUrl, string uid, string privateKey, int expirationMinutes = 60) {
        long timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds() + (expirationMinutes * 60);
        string rand = Guid.NewGuid().ToString("N");
        string uri = new Uri(baseUrl).AbsolutePath;

        string signStr = $"{uri}-{timestamp}-{rand}-{uid}-{privateKey}";
        
        using (MD5 md5 = MD5.Create()) {
            byte[] inputBytes = Encoding.UTF8.GetBytes(signStr);
            byte[] hashBytes = md5.ComputeHash(inputBytes);
            StringBuilder sb = new StringBuilder();
            for (int i = 0; i < hashBytes.Length; i++) {
                sb.Append(hashBytes[i].ToString("x2"));
            }
            string md5Hash = sb.ToString();
            return $"{baseUrl}?auth_key={timestamp}-{rand}-{uid}-{md5Hash}";
        }
    }

    public static void Main() {
        Console.WriteLine(GenerateAuthUrl("[http://13.v.123pan.cn/13/files/1.txt](http://13.v.123pan.cn/13/files/1.txt)", "13", "289ds32418bxdba"));
    }
}

5. 配置步骤

1. 开启鉴权：登录 123云盘直链管理控制台，在右下角“鉴权管理”区域点击开启。
2. 设置密钥：输入自定义的鉴权密钥（PrivateKey），并同步更新到您的应用服务器。
3. 部署算法：参考上述代码实现，确保 URI 包含 /UID/ 前缀。
4. 测试验证：
   • 验证正常链接。
   • 故意修改随机数或时间戳，验证 403 拦截情况。

6. 注意事项

• URI 规范：签名用的 URI 必须以 / 开头，且包含完整的 UID 路径。
• 安全性：随机数（Rand）务必保证唯一性或高随机性，防止签名被重放攻击。