cloudreve-tools

cloudreve-tools 是给自建 Cloudreve V4 用的小工具包，重点是从 note_server 读取 login_hub 保存的 Cloudreve 登录态，然后上传本地文件。

安装

pip install cloudreve-tools

本仓库开发态安装：

python3 -m pip install -e .

凭据

不要把 token、cookie、密码写进命令或文件。工具默认从环境变量读取：

export NOTE_SERVER_TOKEN='<note_server 普通 token>'
export NOTE_SERVER_URL='https://note.luke9012.cn'
export CLOUDREVE_BASE_URL='https://cloud.luke9012.cn'

NOTE_SERVER_URL 和 CLOUDREVE_BASE_URL 可省略，默认就是上面两个地址。

上传文件

login_hub 在 note_server 里的完整 key 是：

login:{platform}:{account}:session

CLI 支持短 key：

• cloudreve -> login:cloudreve:main:session
• cloudreve:main -> login:cloudreve:main:session

上传命令：

cloudreve-tools upload cloudreve:main /我的软件/recon_reader/1.0.0 \
  "/Users/luke/Desktop/recon_reader/recon_reader 1.0.0.apk" \
  "/Users/luke/Desktop/recon_reader/recon_reader mac 1.0.0.zip"

输出 JSON：

cloudreve-tools upload --json cloudreve:main /我的软件/demo ./demo.zip

发布 App Release

release 命令会把 release 文件上传到：

/我的软件/<app>/<version>/

同时生成并上传：

/我的软件/<app>/latest.json

示例：

cloudreve-tools release mptext_reader 1.0.3 \
  --build-number 4 \
  --android "/Users/luke/Desktop/mptext_reader/mptext_reader 1.0.3.apk" \
  --macos "/Users/luke/Desktop/mptext_reader/mptext_reader mac 1.0.3.zip" \
  --notes "更新说明" \
  --json

同名远端文件默认会覆盖，便于同版本修正包和重复发布。如果希望严格禁止覆盖，可加：

--no-overwrite

latest.json 结构：

{
  "app": "mptext_reader",
  "version": "1.0.3",
  "build_number": 4,
  "published_at": "2026-06-19T00:00:00Z",
  "android": {
    "url": "https://cloud.luke9012.cn/...",
    "sha256": "...",
    "size": 12345678
  },
  "macos": {
    "url": "https://cloud.luke9012.cn/...",
    "sha256": "...",
    "size": 12345678
  },
  "notes": "更新说明"
}

命令最后会输出 manifest_url，这个地址就是客户端后续做更新检查时要读取的公开 manifest URL。release 文件和 latest.json 的 Cloudreve 公开 URL 来自 Cloudreve V4 的 source link 接口，域名保持 https://cloud.luke9012.cn。

Cloudreve source link 绑定文件 entity，不适合作为客户端长期内置的更新地址。没有稳定 manifest 入口时，命令会把 Cloudreve source link 回退为 manifest_url，同时在 warnings 中提示它不稳定；调试用的 Cloudreve 地址单独输出为 cloudreve_manifest_url。

如果已经有匿名可读、会被外部流程同步的稳定 manifest 入口，可显式声明：

cloudreve-tools release mptext_reader 1.0.3 \
  --build-number 4 \
  --android "/Users/luke/Desktop/mptext_reader/mptext_reader 1.0.3.apk" \
  --macos "/Users/luke/Desktop/mptext_reader/mptext_reader mac 1.0.3.zip" \
  --stable-manifest-url "https://note.luke9012.cn/public/releases/mptext_reader/latest.json" \
  --json

此时 manifest_url 会输出这个稳定入口，cloudreve_manifest_url 仍保留 Cloudreve 的 latest.json source link。

直链与自动更新域名

Cloudreve 直链、发布清单和 App 自动更新下载地址统一使用 https://cloud.luke9012.cn。不要把链接改写成 img.luke9012.cn。

release / direct-link 命令默认也应保留 cloud.luke9012.cn 作为公开下载域名。

Python 用法

from cloudreve_tools import CloudreveClient, CloudreveSession, NoteServerClient

bundle = NoteServerClient().load_session_bundle("cloudreve:main")
client = CloudreveClient(CloudreveSession.from_bundle(bundle))
result = client.upload("./demo.zip", "/我的软件/demo")
print(result.uri)