# pan-sdk

**Repository Path**: tua123/pan-sdk

## Basic Information

- **Project Name**: pan-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-13
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pan-sdk

`pan-sdk` 是可被其他 Go 项目导入的网盘驱动库，包含阿里云盘、百度网盘、夸克/UC、迅雷、123 网盘、蓝奏云、蓝奏云优享、OpenList、CloudOpenList、Fanqie 和 PanSearch。仓库不提供 CLI。

## 安装

```bash
go get gitee.com/tua123/pan-sdk@v0.3.6
```

升级到 `v0.3.6`：

```bash
go get gitee.com/tua123/pan-sdk@v0.3.6
go mod tidy
```

迅雷凭据结构和 refresh token 续签方式有调整，业务项目升级前请阅读 [`UPGRADING.md`](UPGRADING.md)；完整版本变更见 [`CHANGELOG.md`](CHANGELOG.md)。

要求 Go 1.24 或更高版本。公共仓库可直接通过 `GOPROXY=...,direct` 下载，不需要 `GOPRIVATE` 或 Gitee 凭据。

## 基本用法

```go
package main

import (
	"fmt"

	"gitee.com/tua123/pan-sdk/driver/quark"
	"gitee.com/tua123/pan-sdk/link"
)

func main() {
	fmt.Println(link.IsQuark("https://pan.quark.cn/s/example"))
	drive := quark.NewQuark("your-cookie")
	_ = drive
}
```

`driver.Driver` 保留完整组合接口；调用方也可以依赖更小的 `driver.Searcher`、`driver.Linker`、`driver.Downloader`、`driver.Uploader` 和 `driver.FileManager`。

## 分享链接有效性检测

`check` 包可在收录链接前检查百度、夸克、UC、阿里云盘、迅雷、天翼、123、115 和移动云盘分享链接，不需要网盘账号：

```go
package main

import (
	"context"
	"time"

	"gitee.com/tua123/pan-sdk/check"
)

func shouldSkip(ctx context.Context, rawURL, extractionCode string) bool {
	checker := check.New(check.WithTimeout(15 * time.Second))
	result, err := checker.CheckRequest(ctx, check.Request{
		URL:            rawURL,
		ExtractionCode: extractionCode,
	})
	if err != nil {
		// 超时、限流、风控、网络错误和未知响应都不能证明链接失效；保留并稍后重试。
		return false
	}
	return result.ShouldSkipIngestion()
}
```

只有厂商明确确认链接过期、删除、取消、封禁、违规、不存在或内容为空时，结果才是 `unavailable`；格式错误是 `malformed`。这两类结果的 `ShouldSkipIngestion()` 为 `true`。需要提取码的链接是 `password_required`，不会被当作失效；无法确认的结果是 `unknown` 并返回错误，调用方应保留或重试，避免因“未知错误”误删资源。

百度、夸克/UC、阿里、迅雷和 123 网盘转存驱动与上述语义保持一致：明确失效或内容为空会包装对应驱动的 `ErrShareInvalid`；账号、超时、限流、风控、提取码和未知响应仍是普通运行错误。

## 123 网盘

123 网盘驱动支持 Bearer Token 优先、账号密码失效回退、目录浏览、搜索、创建目录、删除/恢复、MD5 秒传、5 MiB 分块上传、下载、创建分享和递归转存。默认使用 Web 协议；账号 API 使用 `api.123278.com`，生成的分享页使用 `www.123pan.com`：

```go
config := pan123.Config{
	ID:            "account-id",
	Alias:         "my-123pan",
	Authorization: "Bearer ...",
	Username:      "account", // Token 失效时才使用
	Password:      "password",
	LoginUUID:     "persisted-device-id",
	UpdateAuthorization: persistRotatedAuthorization,
}

drive, err := pan123.NewPan123(config)
if err != nil {
	return err
}
result, err := drive.Transfer(ctx, shareURL, "/转存目录", pan123.TransferOptions{})
```

默认同名策略为 `DuplicateKeepBoth`。分享转存先做不带账号凭据的公开预检，随后才登录并创建目标目录；123 网盘没有在此流程中使用整树复制任务，驱动会递归创建目录并按分享文件 ETag 秒传。中途失败时不会删除已经创建的内容，调用方应检查 `TransferResult.Partial` 和 `CreatedIDs`。

`LoginUUID` 是 123 网盘 Web 登录使用的稳定设备标识，应与 Authorization 一起持久化。留空时 SDK 会为当前实例生成新值，可通过 `drive.LoginUUID()` 读取；需要跨实例续期的服务应在首次构造前调用 `pan123.GenerateLoginUUID()` 并保存。账号密码触发厂商验证时返回可由 `errors.Is(err, pan123.ErrVerificationRequired)` 判断的错误。

风控环境可改用扫码登录，不需要把二维码交给第三方图片服务：

```go
login := pan123.NewQRLogin()
session, err := login.Start(ctx)
if err != nil {
	return err
}
// 将 session.QRCode().Content 在本地渲染成二维码，并轮询 session.Poll(ctx)。
// succeeded 时保存 result.Cookie（Bearer Authorization）和 login.LoginUUID()。
```

本地人工验收可运行 `go run ./cmd/pan123-qr-login -output pan123-login-qr.png`。该命令只生成本地二维码并验证扫码成功，刻意不会输出或保存 Authorization、账号名和设备标识。

只读浏览使用 `pan123.NewBrowser`，也可通过 `pan123.NewBrowserFromAccountConfig` 接入公共 `driver/browse` 配置。

## 只读浏览与扫码登录

`v0.2.3` 继续提供 `driver/browse` 公共层，以及百度、夸克和蓝奏云优享的独立 `Browser`。该能力不会替换 `v0.1.0` 的厂商类型：

```go
config := browse.AccountConfig{
	ID:       "account-id",
	Alias:    "my-quark",
	Cookie:   "replace-with-runtime-cookie",
	UpdateCookie: persistRotatedCookie,
}

drive, err := quark.NewBrowser(config)
if err != nil {
	return err
}
root, err := drive.Root(ctx)
page, err := drive.List(ctx, root, "", 100)
```

任意页浏览可检测 `browse.PagedLister`，深目录索引可检测 `browse.IndexLister`，下载直链可检测 `browse.Linker`。百度和夸克扫码登录分别由 `baidu.NewQRLogin()`、`quark.NewQRLogin()` 创建；扫码请求错误会保留取消和超时语义，但不会泄露二维码 Token、Ticket 或完整请求 URL。完整的无网络编译示例见 [`examples/browse`](examples/browse)。

迅雷真实扫码登录、凭据持久化、分享读取、转存和创建分享示例见 [`examples/xunlei`](examples/xunlei)。示例默认只读，只有显式传 `-write` 才会写入网盘；协议细节和在线测试开关见 [`driver/xunlei/USAGE.md`](driver/xunlei/USAGE.md)。

蓝奏云优享可使用 `ilanzou.WithBrowserProxy(proxy.Config{Enabled: true, Provider: provider})`。代理租约获取、代理传输或代理认证失败时会返回明确错误并使租约失效，绝不回退直连；租户凭据和租约 API 必须留在调用应用中。

## 日志与运行配置

SDK 默认不输出日志，临时目录默认使用操作系统临时目录。应用可在启动时注入日志并覆盖缓存限制：

```go
driver.SetLogger(myLogger)
driver.ConfigureRuntime(driver.RuntimeConfig{
	TempDir:        "/var/lib/my-app/pan-cache",
	MaxBufferLimit: 16 * 1024 * 1024,
	MmapThreshold:  4 * 1024 * 1024,
})
```

`Logger` 只有 `Debug/Info/Warn/Error` 四个方法；参数为交替的 key/value。

## 代理租约

蓝奏类驱动通过 `proxy.Provider` 获取代理，SDK 不处理租户身份、server token 或业务 API：

```go
type Provider interface {
	Acquire(context.Context, string) (*url.URL, error)
	Invalidate(string)
}
```

旧驱动可将 `proxy.Config{Enabled: true, Provider: provider}` 传给 `SetProxy`，浏览驱动使用对应的 `WithBrowserProxy` Option。代理启用但 Provider 缺失时返回 `proxy.ErrProviderRequired`，不会静默直连。

## 在线测试

默认测试均应离线执行。真实厂商测试只在显式配置后运行，例如 `XUNLEI_REFRESH_TOKEN`、`QUARK_COOKIE` 或 `LANZOU_REAL_URL`。123 网盘的本地验收文件 `driver/pan123/pan123_live_credentials_test.go` 被 Git 忽略，默认关闭；仅在受控测试机填写凭据并打开开关。不要把 Cookie、Token、账号密码或私钥提交到源码、测试与日志。

## 稳定性与安全

`v0.x` 以兼容抽取和持续验证为主，公共 API 仍可能调整。安全约束见 [SECURITY.md](SECURITY.md)，第三方组件信息见 [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md)。