# 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 忽略，适合放本机密钥。请把下面占位值替换为真实百度凭证：

```bash
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`：

```bash
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 完成：

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

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

```bash
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。

扫码并授权后：

```bash
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，旧记录会不可读，需要重新扫码登录。

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

```bash
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，除非已经准备重新登录。