About SteamCloudFileManager

SteamCloudFileManager is a cross-platform GUI application for managing Steam Cloud saves, built with Rust and the Steamworks SDK. It provides direct access to Steam's underlying cloud storage interfaces by parsing the remotecache.vdf file to reconstruct the remote directory tree as a visual file tree. Users can upload, download, and delete any cloud file, with support for batch operations and drag-and-drop transfers. The tool includes regex-based search and filtering by filename, path, or sync status, automatic game library scanning via libraryfolders.vdf, and root path resolution that converts numeric Root IDs into local absolute paths. It also offers experimental symlink synchronization for syncing configuration files across platforms, and direct reading and editing of UFS configuration through appinfo.vdf. Available on Windows, macOS, Ubuntu, Debian, Fedora, Arch Linux, and as an AppImage, SteamCloudFileManager is useful for gamers who want full visibility and control over their Steam Cloud data, developer

f

Published by

fldicoahkiin

Visit View Profile

README.md

View on GitHub

Steam Cloud File Manager

English | 简体中文

steam_cloud

基于 Rust 和 egui 构建的跨平台 Steam 云存档管理工具

功能

基于 Rust 与 Steamworks SDK 开发的云存档管理工具。通过直接调用 Steam 底层接口，实现了对云端文件的完全可视与控制。支持任意文件的上传、下载与删除，并提供软链接同步功能，有效解决了部分游戏配置文件无法跨平台同步的问题。

VDF 文件树可视化：完整解析 remotecache.vdf，还原云端目录结构。
批量传输：支持多文件选择与拖拽上传/下载。
深度控制：直接删除云端文件，强制更新同步状态。
Root 路径映射：解析 remotecache.vdf 中的数字 Root ID (0-12)，自动转换为本地磁盘绝对路径（该映射关系在官方文档中未公开）。
搜索与过滤：支持文件名、路径及同步状态的正则表达式检索。
游戏库扫描：通过解析 libraryfolders.vdf 自动发现本地游戏。
软链接同步：支持将非原生支持的本地文件通过软链接挂载至 Steam Cloud（实验性）。
UFS 配置管理：直接读写 appinfo.vdf，实现类 Steamworks 后台的 Auto-Cloud 配置编辑（实验性）。可添加/编辑/删除 savefiles 规则和 rootoverrides 路径映射，自定义游戏的云同步行为。
多平台支持：Windows / macOS / Linux。

平台兼容性

支持 Windows (x64)、macOS (Intel & Apple Silicon) 以及 Linux (x64)。构建产物包含常规的安装包及免安装版本（Generic Binary / AppImage）。

注：由于 Steamworks SDK 的上游限制，目前无法构建 Windows 和 Linux 的 ARM64 版本。

安装

Windows

下载
解压到任意位置
双击 SteamCloudFileManager.exe 运行

注意：

Windows 版本日志保存在应用所在目录的 logs/ 文件夹。

macOS 版本日志保存在 ~/Library/Logs/SteamCloudFileManager/ 目录。

Linux 版本日志保存在 ~/.local/share/SteamCloudFileManager/logs/ 目录。

macOS

Homebrew

安装（推荐，自动安装到应用程序）：

brew tap Fldicoahkiin/tap
brew install --cask steam-cloud-file-manager

如果安装后提示应用损坏，请运行：xattr -cr "/Applications/Steam Cloud File Manager.app"

作为 Formula 安装（仅提供终端启动命令）：

brew install steam-cloud-file-manager

手动安装

下载对应版本：
- Intel 芯片：
- Apple Silicon：
打开 DMG 文件
将应用拖入 Applications 文件夹
如遇 "损坏" 或 "无法打开" 提示，请在终端执行以下命令修复签名：
```
xattr -c "/Applications/Steam Cloud File Manager.app"
```

Arch Linux (AUR)

yay -S steam-cloud-file-manager-bin
# 或
paru -S steam-cloud-file-manager-bin

手动构建：

git clone https://aur.archlinux.org/steam-cloud-file-manager-bin.git
cd steam-cloud-file-manager-bin
makepkg -si
steam-cloud-file-manager

或下载预构建包：

tar -xzf SteamCloudFileManager-*-linux-x86_64-aur.tar.gz
cd SteamCloudFileManager-*-linux-x86_64-aur
makepkg -si
steam-cloud-file-manager

Debian/Ubuntu

下载

sudo dpkg -i steam-cloud-file-manager_*.deb
sudo apt-get install -f
steam-cloud-file-manager

Fedora/RHEL/openSUSE

下载

sudo dnf install ./steam-cloud-file-manager-*.rpm
steam-cloud-file-manager

AppImage（通用）

下载

chmod +x SteamCloudFileManager-*.AppImage
./SteamCloudFileManager-*.AppImage

.tar.gz（通用）

下载

tar -xzf SteamCloudFileManager-*-linux-x86_64.tar.gz
./steam-cloud-file-manager

从源码构建

git clone https://github.com/Fldicoahkiin/SteamCloudFileManager.git
cd SteamCloudFileManager
cargo build --release

构建依赖：

Cargo
Rust 1.90.0+
- 使用 Rust 2021 edition
- 安装：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
C++ 编译工具链：
- Windows:
  - Visual Studio 2019 或更新版本（推荐安装 "Desktop development with C++" 工作负载）
  - 或 Build Tools for Visual Studio
- macOS:
  - Xcode Command Line Tools: xcode-select --install
- Linux:
  - gcc/g++ 或 clang
  - Ubuntu/Debian: sudo apt install build-essential
  - Fedora: sudo dnf install gcc gcc-c++
  - Arch: sudo pacman -S base-devel

运行依赖：

Steam 客户端（必须以调试模式运行）

使用说明

Steam 调试模式

本工具使用 CDP 协议与 Steam 通信，必须以调试模式启动 Steam。

为什么需要调试模式？

CDP（Chrome DevTools Protocol）是 Steam 内置浏览器的调试接口
我们通过这个接口获取云端文件列表和下载链接
只有开启调试模式，CDP 端口才会启用

Windows:

右键点击 Steam 快捷方式，选择“属性”
在“目标”栏末尾添加：-cef-enable-debugging
点击“确定”并启动 Steam

macOS:

退出 Steam

在终端执行：

open -a Steam --args -cef-enable-debugging

Linux:

关闭 Steam
在终端执行：
```
steam -cef-enable-debugging &
```
或者修改 Steam 快捷方式，在 Exec 行末尾添加 -cef-enable-debugging

注意： 本软件提供了“以调试模式重启 Steam”按钮，可以自动根据引导完成上述操作。

基本操作流程

确保 Steam 已运行在调试模式。
选择目标游戏：
- 游戏库选择：点击游戏库按钮选择本地游戏（会自动连接）。
- 手动输入：输入 App ID 后点击 "连接"。
加载完成后，可在左侧树状视图中操作文件。

App ID 可以通过 Steam 商店 URL 或 SteamDB 上找到。

⚠️ 警告

删除不可逆：删除操作会立即提交至本地缓存，无法撤销。

数据安全：建议在批量操作前先备份原始文件。

同步机制：文件变更写入本地缓存后，Steam 会在后台异步上传。请勿在同步完成前强制杀掉 Steam 进程。

技术架构

云同步机制

graph TB
    subgraph dev["🔧 开发者"]
        Steamworks["Steamworks 后台<br/>配置 ufs"]
        GameCode["游戏代码"]
    end

    Cloud(("🌐 Steam 服务器"))

    subgraph client["🖥️ Steam 客户端"]
        subgraph vdf["本地 VDF 文件"]
            AppInfo[(appinfo.vdf)]
            RemoteCache[(remotecache.vdf)]
        end

        subgraph sync["☁️ Steam 云同步"]
            Auto["Steam 自动云 Auto-Cloud<br/>自动递归查找匹配文件"]
            API["Steam 云 API<br/>ISteamRemoteStorage接口"]
        end
    end

    %% Steamworks 配置下发流程
    Steamworks --> Cloud
    Cloud -->|下发 ufs 配置| AppInfo
    AppInfo -->|ufs 配置规则| Auto
    Auto --> RemoteCache

    %% 游戏代码调用 API
    GameCode -->|调用 API| API
    API -->|写入文件| RemoteCache

    %% 双向同步
    RemoteCache <===>|双向同步| Cloud

本工具交互流程：

graph TB
    Tool["🛠️ 本工具"]

    subgraph client["🖥️ Steam 客户端"]
        subgraph vdf["本地 VDF 文件"]
            AppInfo[(appinfo.vdf)]
            RemoteCache[(remotecache.vdf)]
        end

        subgraph sync["☁️ Steam 云同步"]
            Auto["Steam 自动云 Auto-Cloud"]
            API["Steam 云 API"]
        end

        Browser["🌐 Steam 内置浏览器<br/>127.0.0.1:8080"]
    end

    Cloud(("🌐 Steam 服务器"))

    %% 本工具的操作（介入流程）
    Tool -.->|读取| AppInfo
    Tool -.->|读取| RemoteCache
    Tool ==>|注入 ufs 配置| AppInfo
    Tool -->|调用 API| API
    Tool -->|CDP 获取下载链接| Browser

    %% Steam 内部流程
    AppInfo -->|ufs 配置规则| Auto
    Auto --> RemoteCache
    API -->|写入文件| RemoteCache
    RemoteCache <===>|双向同步| Cloud
    Browser <-->|访问云存储| Cloud

完整架构图（点击展开）

graph LR
    subgraph left["外部"]
        subgraph dev["🔧 开发者"]
            Steamworks["Steamworks 后台<br/>配置 ufs"]
            GameCode["游戏代码"]
        end
        Tool["🛠️ 本工具"]
    end

    subgraph client["🖥️ Steam 客户端"]
        subgraph vdf["本地 VDF 文件"]
            AppInfo[(appinfo.vdf)]
            RemoteCache[(remotecache.vdf)]
        end

        subgraph sync["☁️ Steam 云同步"]
            Auto["Auto-Cloud"]
            API["Steam 云 API"]
        end

        Browser["🌐 内置浏览器"]
    end

    Cloud(("🌐 Steam<br/>服务器"))

    %% 开发者流程
    Steamworks --> Cloud
    Cloud -->|下发 ufs 配置| AppInfo
    GameCode -->|调用 API| API

    %% Steam 内部流程
    AppInfo --> Auto
    Auto --> RemoteCache
    API --> RemoteCache
    RemoteCache <===> Cloud
    Browser <--> Cloud

    %% 本工具的操作
    Tool -.->|读取| AppInfo
    Tool -.->|读取| RemoteCache
    Tool ==>|注入 ufs| AppInfo
    Tool -->|调用| API
    Tool -->|CDP| Browser

Steam 云同步的两种方式

Steam 提供两种云同步机制：

自动云（Auto-Cloud）\ 开发者在 Steamworks 后台配置，Steam 自动扫描指定目录：

Steam 会主动扫描配置的目录
根据 pattern（如 *.sav）自动匹配文件
新文件会自动添加到 remotecache.vdf 并同步
配置存储在 appinfo.vdf 的 ufs 节中

Steam Cloud API\ 游戏代码调用 ISteamRemoteStorage::FileWrite() 显式注册文件：

Steam 不会主动扫描
需要游戏调用 API 注册文件
用户手动创建的文件不会自动同步

本工具的定位：\ 本工具提供两种方式控制云同步：

Steam Cloud API：手动调用 API 注册文件，解决游戏不写入软链接目录的问题
UFS 配置注入（新功能）：直接修改本地 appinfo.vdf 的 ufs 节，实现类似 Steamworks 后台的配置管理。可以：
- 添加/编辑/删除 savefiles 规则（指定同步目录、文件匹配模式、递归搜索选项）
- 添加/编辑/删除 rootoverrides 路径映射（跨平台路径转换）
- 配置 pathtransforms 路径转换规则（可选，用于动态路径替换）
- 为任意游戏自定义云同步路径

⚠️ 注意：UFS 配置注入修改的是本地 appinfo.vdf，Steam 更新可能会覆盖这些修改。建议在修改前备份配置。

数据流

graph TD
    subgraph 操作栏
        Upload[上传]
        Download[下载]
        SyncToCloud[同步到云端]
        Delete[删除]
        Forget[移出同步]
        Compare[文件对比]
        Refresh[刷新]
        Backup[备份]
    end

    subgraph SteamAPI[Steam API]
        WriteFile[write_file]
        ReadFile[read_file]
        DeleteFile[delete_file]
        ForgetFile[forget_file]
        SyncCloud[sync_cloud_files]
    end

    subgraph 数据获取
        CDPClient[CDP 客户端]
        VDFParser[VDF 解析器]
    end

    Upload -->|选择本地文件| WriteFile
    WriteFile --> SyncCloud

    Download --> CDPClient
    CDPClient -->|获取下载链接| HTTP[HTTP 下载]
    HTTP --> LocalDisk[本地磁盘]

    SyncToCloud -->|仅本地文件上传| WriteFile

    Delete --> DeleteFile
    DeleteFile --> SyncCloud

    Forget -->|从云端移除但保留本地| ForgetFile
    ForgetFile --> SyncCloud

    Compare --> CDPClient
    Compare --> VDFParser
    CDPClient -->|计算云端 Hash| HashCompare[Hash 对比]
    VDFParser -->|计算本地 Hash| HashCompare

    Backup --> ReadFile
    ReadFile --> LocalDisk

    Refresh --> VDFParser
    Refresh --> CDPClient
    VDFParser --> FileList[文件列表]
    CDPClient --> FileList

    SyncCloud -.->|后台异步| CloudServer[Steam 云端]

数据源优先级

来源	数据内容	优先级	说明
VDF	本地缓存的文件列表、同步状态	主要	解析 `remotecache.vdf`
CDP	云端实时文件列表、下载链接	补充	通过 Steam 内置浏览器获取
Steam API	文件读写、删除、配额查询	操作	`ISteamRemoteStorage` 接口

同步状态 (`is_persisted`)

新上传的文件
  is_persisted = false  ← 仅在本地缓存
  ↓
  Steam 后台上传（需要数秒到数分钟）
  ↓
  is_persisted = true   ← 已同步到云端

⚠️ 重要：sync_cloud_files() 调用后会立即返回，实际上传在后台异步进行。断开连接时 Steam 会强制完成同步。

CDP 协议

通过 Steam 客户端的 CEF (Chromium Embedded Framework) 调试接口获取云端实时数据：

检测: 访问 http://127.0.0.1:8080/json 获取调试目标列表
连接: 建立 WebSocket 连接到目标页面
导航: 跳转到 store.steampowered.com/account/remotestorage
注入: 执行 JavaScript 提取文件列表和下载链接
合并: 将 CDP 数据与 VDF 数据合并，补充下载链接和实时状态

VDF 解析与 Root 映射

工具实时解析 remotecache.vdf 获取文件列表，同时解析 appinfo.vdf 提取游戏的云存储规则 (ufs 节)，自动处理 Steam 的 Root ID 映射系统：

什么是 Root ID？

Steam 在 remotecache.vdf 中使用数字 Root ID (0-12) 标识文件存储位置。这个数字 ID 到路径的映射关系在任何官方文档中都没有公开，是通过解析 VDF 文件和实际游戏测试验证得出的。

Root ID	Steamworks 根名称	Windows 路径示例
0	`Default`	`userdata/{uid}/{appid}/remote/`
1	`App Install Directory`	`steamapps/common/GameName/`
2	`WinMyDocuments`	`%USERPROFILE%\Documents\`
3	`WinAppDataLocal`	`%LOCALAPPDATA%\`
9	`WinSavedGames`	`%USERPROFILE%\Saved Games\`
11	`SteamCloudDocuments`	`Documents\Steam Cloud\`
12	`WinAppDataLocalLow`	`%USERPROFILE%\AppData\LocalLow\`

详细说明：

开发者在 Steamworks 后台配置时使用字符串名称（如 WinMyDocuments）
Steam 客户端在 remotecache.vdf 中存储为数字 ID（如 2）
官方只公开了字符串名称，数字 ID 需要通过解析 remotecache.vdf 获取
Root 路径映射表 - 完整的验证数据和跨平台映射

注意：Root 路径映射表通过实际游戏测试验证，欢迎提交新的验证数据！

TODO

功能开发

[x] 多语言支持（i18n）- 已支持简体中文/English
[x] 版本更新检测
[x] 树状视图
[x] 批量上传/下载
[x] 文件冲突检测与处理
[x] 云存档备份
[x] 软链接同步支持（实验性）
[x] UFS 配置管理（实验性）- 类 Steamworks 后台的 Auto-Cloud 配置编辑
[ ] 自动备份计划
[ ] 开机自启动（随系统启动，托盘后台运行）
[ ] 启动时自动注入 UFS 配置（无需手动操作即可识别本地存档路径）
[ ] UFS 配置管理页面（独立的可视化界面，替代当前弹窗式编辑）
[ ] 云存档版本历史（查看和回滚历史版本）

包管理器支持

[x] AUR (Arch User Repository) - yay -S steam-cloud-file-manager-bin
[x] Homebrew (macOS) - brew tap Fldicoahkiin/tap && brew install steam-cloud-file-manager
[ ] Winget (Windows) - winget install steam-cloud-file-manager
[ ] Scoop (Windows) - scoop install steam-cloud-file-manager
[ ] Chocolatey (Windows) - choco install steam-cloud-file-manager
[ ] APT 仓库 (Debian/Ubuntu) - apt install steam-cloud-file-manager
[ ] DNF/YUM 仓库 (Fedora/RHEL) - dnf install steam-cloud-file-manager
[ ] Flatpak - flatpak install steam-cloud-file-manager
[ ] Snap - snap install steam-cloud-file-manager

贡献

欢迎提交 Issue 和 Pull Request！详细指南请查看 CONTRIBUTING.md。

如何贡献

🐛 报告 Bug：使用 Issue 模板提交问题
✨ 请求功能：分享你的想法和建议
📖 完善文档：帮助改进 README 和技术文档
🌐 贡献翻译：添加新的语言支持，请查看 i18n 贡献指南
🗺️ 补充 Root 映射：提交游戏的 remotecache.vdf 验证数据，帮助完善 Root 路径映射表
🔧 提交代码：修复 Bug 或实现新功能

当前支持的语言：

简体中文
English

贡献者

项目结构

src/
├── main.rs                 # 入口：初始化日志、启动 eframe
├── app.rs                  # 主应用：状态持有、UI 渲染循环
├── app_state.rs            # 状态结构定义
├── app_handlers.rs         # 业务逻辑处理器
├── async_handlers.rs       # 异步任务管理（channel 持有）
│
├── steam_api.rs            # Steam API 封装（CloudFile 结构）
├── steam_worker.rs         # 外部进程通信（JSON RPC）
├── steam_process.rs        # Steam 进程管理（启动/关闭）
│
├── file_manager.rs         # 文件操作（上传/下载/删除）
├── file_tree.rs            # 文件树结构
├── downloader.rs           # 批量下载器
├── backup.rs               # 备份功能
├── conflict.rs             # 冲突检测
├── symlink_manager.rs      # 软链接管理
│
├── vdf_parser.rs           # VDF 文件解析（appinfo.vdf, loginusers.vdf）
├── appinfo_writer.rs       # appinfo.vdf 写入（UFS 配置注入）
├── path_resolver.rs        # 路径解析（savefiles 配置 → 实际路径）
├── cdp_client.rs           # CDP 网页解析（获取远程文件列表）
├── game_scanner.rs         # 游戏扫描（合并 VDF + CDP）
├── user_manager.rs         # 用户管理
│
├── config.rs               # 配置管理（设置持久化）
├── update.rs               # 自动更新
├── logger.rs               # 日志系统
├── i18n/                   # 国际化
│   ├── mod.rs              # 语言枚举与分发逻辑
│   ├── en.rs               # English
│   └── zh.rs               # 简体中文
├── icons.rs                # 图标系统（Phosphor Icons）
├── version.rs              # 版本信息
│
└── ui/
    ├── mod.rs              # UI 模块导出
    ├── app_panels.rs       # 面板渲染（顶部/底部/中心、操作按钮、状态栏）
    ├── controls.rs         # 控件渲染
    ├── file_list.rs        # 文件列表（表格/树状）
    ├── windows.rs          # 窗口（游戏选择、用户选择）
    ├── settings.rs         # 设置窗口
    ├── theme.rs            # 主题系统（颜色/深色模式）
    ├── upload_dialog.rs    # 上传对话框
    ├── backup_dialog.rs    # 备份对话框
    ├── conflict_dialog.rs  # 冲突对话框
    ├── guide_dialog.rs     # 引导对话框
    ├── appinfo_dialog.rs   # AppInfo 对话框
    ├── symlink_dialog.rs   # 软链接对话框
    └── font_loader.rs      # 字体加载

许可证

本项目采用 GPL-3.0 许可证 - 详见 LICENSE 文件

致谢

核心依赖

steamworks-rs - Steamworks SDK 的 Rust 绑定
egui - 即时模式 GUI 框架
eframe - egui 的跨平台框架
keyvalues-parser - VDF 文本格式解析器
tungstenite - WebSocket 客户端（CDP 通信）

工具库

rfd - 原生文件对话框
ureq - HTTP 客户端
anyhow - 错误处理
tracing - 日志追踪
serde - 序列化框架
image - 图像处理
self_update - 自动更新
regex - 正则表达式
chrono - 时间日期
walkdir - 目录遍历
open - 打开文件/URL
dirs - 系统目录
uuid - UUID 生成
sha1 - 哈希计算
byteorder - 字节序处理

UI 扩展

egui-phosphor - Phosphor 图标库
egui_extras - egui 扩展组件

打包工具

cargo-bundle - macOS .app/.dmg 打包
cargo-deb - Debian/Ubuntu .deb 打包
cargo-generate-rpm - Fedora/RHEL .rpm 打包
cargo-appimage - 通用 AppImage 打包
cargo-aur - Arch Linux PKGBUILD 生成

参考项目

SteamCloudFileManagerLite - C# 实现的轻量版本
Facepunch.Steamworks - Steamworks C# 封装
SteamTools (Watt Toolkit) - 开源 Steam 工具箱
SteamDatabase/SteamAppInfo - appinfo.vdf 二进制格式文档
tormak9970/new-vdf-parser - Rust 二进制 VDF 解析库
tralph3/Steam-Metadata-Editor - Python Steam 元数据编辑器

文档资料

Steamworks SDK - 官方 SDK 文档
Steamworks Steam Cloud - 官方 Steam Cloud 文档
ISteamRemoteStorage API - Steam Cloud API 参考
Steam Cloud Best Practices - 官方最佳实践
VDF Parser (Python) - Python VDF 解析库
Stack Exchange: Steam Cloud - Root 路径社区验证
Quick Guide to Steam Cloud Saves - 开发者云存档指南
A Gentle Introduction to Steamworks - Steamworks 集成入门教程
Elena Temple Dev Blog - Unity 云存档配置实例

SteamCloudFileManager