pikasTech-unidesk/docs/issue/baidu-netdisk-env-setup.md

Baidu Netdisk 环境变量配置说明

Date: 2026-05-11

我能补什么，不能补什么

我可以在本机生成并持久化这个本地密钥：

• UNIDESK_BAIDU_NETDISK_TOKEN_KEY：UniDesk 本地随机密钥，只用于把百度 access_token / refresh_token 加密后写入 PostgreSQL。

我不能代替你生成下面两个值，因为它们属于你的百度网盘开放平台应用：

• UNIDESK_BAIDU_NETDISK_CLIENT_ID：百度 OAuth client_id，在部分百度控制台页面也叫 AppKey/API Key。
• UNIDESK_BAIDU_NETDISK_CLIENT_SECRET：百度 OAuth client_secret，在部分百度控制台页面也叫 Secret Key。

截至 2026-05-11，本机已经在 .state/docker-compose.env 中生成并写入了 UNIDESK_BAIDU_NETDISK_TOKEN_KEY。百度应用的 client id 和 client secret 仍保持未配置状态，因为它们是账号归属的密钥，不能猜测，也不能提交到仓库。

获取百度应用凭证

1. 打开百度网盘开放平台控制台，为 UniDesk 创建一个应用，或复用你已有的应用。
2. 开启 OAuth 和网盘文件 API 所需权限；当前服务请求的 scope 是 basic,netdisk。
3. 复制应用的 OAuth client id/AppKey 和 client secret/Secret Key。
4. 妥善保管密钥，不要把它粘贴到 config.json、文档、源码、git commit、截图、issue 评论或前端代码里。

官方参考：

• 开放平台概览：https://pan.baidu.com/union/doc/nksg0sbfs
• 设备码模式：https://pan.baidu.com/union/doc/fl1x114ti
• 授权码模式：https://pan.baidu.com/union/doc/al0rwqzzl

配置这台主机

UniDesk CLI 会把 Docker 运行时变量写到 .state/docker-compose.env；该文件已被 git 忽略，适合放本机密钥。请把下面占位值替换为真实百度凭证：

cd /root/unidesk
python3 - <<'PY'
from pathlib import Path

updates = {
    "UNIDESK_BAIDU_NETDISK_CLIENT_ID": "paste-baidu-client-id-here",
    "UNIDESK_BAIDU_NETDISK_CLIENT_SECRET": "paste-baidu-client-secret-here",
    # Optional. "/" makes UniDesk work at the Baidu Netdisk root; use /apps/<name> to sandbox again.
    "UNIDESK_BAIDU_NETDISK_APP_ROOT": "/",
}

path = Path(".state/docker-compose.env")
lines = path.read_text("utf-8").splitlines() if path.exists() else []
seen = set()
for index, line in enumerate(lines):
    if "=" not in line:
        continue
    key = line.split("=", 1)[0]
    if key in updates:
        lines[index] = f"{key}={updates[key]}"
        seen.add(key)
for key, value in updates.items():
    if key not in seen:
        lines.append(f"{key}={value}")
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("\n".join(lines) + "\n", "utf-8")
PY

也可以在当前 shell 里临时 export，然后运行会调用 writeComposeEnv 的 UniDesk CLI 命令，例如 server rebuild baidu-netdisk。CLI 会把这些 shell 变量持久化到 .state/docker-compose.env：

cd /root/unidesk
export UNIDESK_BAIDU_NETDISK_CLIENT_ID='paste-baidu-client-id-here'
export UNIDESK_BAIDU_NETDISK_CLIENT_SECRET='paste-baidu-client-secret-here'
export UNIDESK_BAIDU_NETDISK_APP_ROOT='/'
bun scripts/cli.ts server rebuild baidu-netdisk

应用并验证

填好凭证后，只重建 Baidu Netdisk 后端，并等待异步 job 完成：

cd /root/unidesk
bun scripts/cli.ts server rebuild baidu-netdisk
bun scripts/cli.ts job status latest

然后验证服务并启动二维码/设备码登录流程：

bun scripts/cli.ts microservice health baidu-netdisk
bun scripts/cli.ts microservice proxy baidu-netdisk /api/auth/device/start --method POST --raw

手动扫码授权前的预期状态：

• health.body.auth.configured 为 true。
• health.body.auth.clientIdConfigured 为 true。
• health.body.auth.clientSecretConfigured 为 true。
• health.body.auth.tokenKeyConfigured 为 true。
• /api/auth/device/start 返回设备登录会话、二维码/用户码元数据，不返回原始百度 token。

扫码并授权后：

bun scripts/cli.ts microservice proxy baidu-netdisk '/api/account' --raw
bun scripts/cli.ts microservice proxy baidu-netdisk '/api/files?dir=/&limit=20' --raw
bun scripts/cli.ts microservice proxy baidu-netdisk /api/self-test --method POST --raw

/api/files 访问根目录时应返回 ok=true 和文件数组；/api/self-test 会生成小文本、上传到当前 UNIDESK_BAIDU_NETDISK_APP_ROOT 指向的工作目录、列表确认、下载并比较 MD5，适合授权完成后的端到端验收。如果你把 UNIDESK_BAIDU_NETDISK_APP_ROOT 改回 /apps/<name>，后端会在首次访问时确保该应用目录存在。

Token Key 轮换

只应在首次登录前，或明确退出登录并丢弃旧加密 token 记录后，才轮换 UNIDESK_BAIDU_NETDISK_TOKEN_KEY。这个 key 用于解密 baidu_netdisk_tokens 和 baidu_netdisk_auth_sessions 中的既有加密记录；如果已有加密记录后再改 key，旧记录会不可读，需要重新扫码登录。

如果测试登录后必须轮换，先正常退出登录：

bun scripts/cli.ts microservice proxy baidu-netdisk /api/auth/logout --method POST --raw

然后更新 UNIDESK_BAIDU_NETDISK_TOKEN_KEY，重建 baidu-netdisk，再重新发起二维码登录。

安全检查清单

• 百度凭证只放在 .state/docker-compose.env、root 管理的密钥系统或临时 shell 环境里。
• 不要提交 .env、.state/docker-compose.env、access token、refresh token、dlink 或包含密钥的截图。
• 不要把 4244 暴露到公网；Baidu Netdisk 必须继续走 UniDesk microservice proxy。
• 成功登录后不要随意轮换 token key，除非已经准备重新登录。