Codex
a242e3e3ec
- add scheduled task plumbing across backend core, CLI, and frontend surfaces - add frontend notification UI and keep service pages using the repaired shared stylesheet - refactor code queue runtime and update baidu netdisk/service integration docs
128 lines
5.6 KiB
Markdown
128 lines
5.6 KiB
Markdown
# 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，除非已经准备重新登录。
|