Skip to content
/ SteamCloudFileManager Public

Cross-platform GUI for Steam Cloud. Visualizes remote storage as a file tree with download, upload, and delete capabilities. Built with Rust. | 跨平台 Steam 云存档 GUI。以树状视图显示云端文件，支持下载、上传及删除操作。基于 Rust 开发。

License

GPL-3.0 license
111 stars 2 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

Fldicoahkiin/SteamCloudFileManager

BranchesTags

Repository files navigation

Steam Cloud File Manager

English | 简体中文

steam_cloud

Rust dependency status GitHub stars GitHub forks

License: GPL-3.0 GitHub release GitHub downloads Build Release QQ群

Homebrew AUR Windows macOS Ubuntu Debian Fedora Arch Linux AppImage

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

功能

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

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

平台兼容性

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

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

安装

Windows

  1. 下载 Portable-x64
  2. 解压到任意位置
  3. 双击 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

手动安装

  1. 下载对应版本：

    • Intel 芯片：DMG-Intel
    • Apple Silicon：DMG-Apple Silicon

  2. 打开 DMG 文件

  3. 将应用拖入 Applications 文件夹

  4. 如遇 "损坏" 或 "无法打开" 提示，请在终端执行以下命令修复签名：

    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

或下载 AUR-x64 预构建包：

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

Debian/Ubuntu

下载 Deb-x64

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

Fedora/RHEL/openSUSE

下载 Rpm-x64

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

AppImage（通用）

下载 AppImage-x64

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

.tar.gz（通用）

下载 tar.gz-x64

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:
    • 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:

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

macOS:

  1. 退出 Steam

  2. 在终端执行：

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

Linux:

  1. 关闭 Steam

  2. 在终端执行：

    steam -cef-enable-debugging &

    或者修改 Steam 快捷方式，在 Exec 行末尾添加 -cef-enable-debugging

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

基本操作流程

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

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 Cloud"]
            Auto["Auto-Cloud<br/>自动扫描匹配"]
            API["Steam Cloud API<br/>ISteamRemoteStorage"]
        end
        
        SteamBrowser["🌐 Steam 内置浏览器<br/>127.0.0.1:8080"]
    end
    
    ThirdParty["🛠️ 第三方工具<br/>（如本工具）"]
    
    %% Steamworks 配置 → Auto-Cloud
    Steamworks --> Cloud
    Cloud -->|下发配置| AppInfo
    AppInfo -->|ufs 配置规则| Auto
    Auto --> RemoteCache
    
    %% 游戏代码/第三方工具 → API
    GameCode -->|调用| API
    ThirdParty -->|调用| API
    API -->|写入文件| RemoteCache
    
    %% 双向同步
    RemoteCache <===>|双向同步| Cloud
Loading

本工具交互流程：

graph TB
    subgraph tool["🛠️ 本工具"]
        App["Steam 云文件管理器"]
        Parser["VDF 解析器"]
        Resolver["Root ID 路径映射"]
        UI["文件管理界面"]
    end
    
    subgraph client["🖥️ Steam 客户端"]
        subgraph vdf["📁 VDF 文件"]
            AppInfo[(appinfo.vdf)]
            RemoteCache[(remotecache.vdf)]
        end
        API["Steam Cloud API<br/>ISteamRemoteStorage"]
        Browser["🌐 Steam 内置浏览器<br/>127.0.0.1:8080"]
    end
    
    CDP["CDP 协议<br/>Chrome DevTools Protocol"]
    Cloud(("☁️ Steam 服务器"))
    
    %% 读取 VDF
    App --> Parser
    Parser -.读取文件列表.-> RemoteCache
    Parser -.读取ufs配置.-> AppInfo
    
    %% Root ID 映射
    RemoteCache -.提取 Root ID.-> Resolver
    AppInfo -.路径映射规则.-> Resolver
    Resolver --> UI
    
    %% API 操作
    UI -->|上传/删除/同步/移除| API
    API -->|写入文件| RemoteCache
    
    %% 下载链接
    UI -->|获取下载链接| CDP
    CDP --> Browser
    Browser -->|访问云存储| Cloud
    Cloud -.-> Browser
    Browser -.返回下载链接.-> UI
Loading
完整架构图（点击展开） 
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 Cloud"]
            Auto["Auto-Cloud<br/>自动扫描匹配"]
            API["Steam Cloud API<br/>ISteamRemoteStorage"]
        end
        
        SteamBrowser["🌐 Steam 内置浏览器<br/>127.0.0.1:8080"]
    end
    
    CDP["CDP 协议<br/>Chrome DevTools Protocol"]
    
    ThirdParty["🛠️ 第三方工具<br/>（如本工具）"]
    
    subgraph tool["🛠️ 本工具"]
        App["Steam 云文件管理器"]
        Parser["VDF 解析器"]
        Resolver["Root ID 路径映射"]
        UI["文件管理界面"]
    end
    
    %% Steamworks 配置 → Auto-Cloud
    Steamworks --> Cloud
    Cloud -->|下发配置| AppInfo
    AppInfo -->|ufs 配置规则| Auto
    Auto --> RemoteCache
    
    %% 游戏代码/第三方工具 → API
    GameCode -->|调用| API
    ThirdParty -->|调用| API
    
    %% 双向同步
    API -->|写入文件| RemoteCache
    RemoteCache <===>|双向同步| Cloud
    
    %% 本工具读取
    App --> Parser
    Parser -.读取文件列表.-> RemoteCache
    Parser -.读取ufs配置.-> AppInfo
    
    %% Root ID 映射
    RemoteCache -.提取 Root ID.-> Resolver
    AppInfo -.路径映射规则.-> Resolver
    Resolver --> UI
    
    %% 本工具调用 API（与游戏代码相同）
    UI -->|上传/删除/同步/移除| API
    
    %% 下载链接
    UI -->|获取下载链接| CDP
    CDP --> SteamBrowser
    SteamBrowser -->|访问云存储| Cloud
    Cloud -.-> SteamBrowser
    SteamBrowser -.返回下载链接.-> UI
Loading

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 注册这些文件，让它们进入云同步。

数据流

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 云端]
Loading

数据源优先级

来源 数据内容 优先级 说明
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) 调试接口获取云端实时数据：

  1. 检测: 访问 http://127.0.0.1:8080/json 获取调试目标列表
  2. 连接: 建立 WebSocket 连接到目标页面
  3. 导航: 跳转到 store.steampowered.com/account/remotestorage
  4. 注入: 执行 JavaScript 提取文件列表和下载链接
  5. 合并: 将 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 SteamCloudDocuments userdata/{uid}/{appid}/remote/
1 App Install Directory steamapps/common/GameName/
2 WinMyDocuments %USERPROFILE%\Documents\
4 WinAppDataLocal %LOCALAPPDATA%\
9 WinSavedGames %USERPROFILE%\Saved Games\
12 WinAppDataLocalLow %USERPROFILE%\AppData\LocalLow\

详细说明：

  • 开发者在 Steamworks 后台配置时使用字符串名称（如 WinMyDocuments）

  • Steam 客户端在 remotecache.vdf 中存储为数字 ID（如 2）

  • 官方只公开了字符串名称，数字 ID 需要通过解析 remotecache.vdf 获取

  • Root 路径映射表 - 完整的验证数据和跨平台映射

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

TODO

功能开发

  • 多语言支持（i18n）- 已支持简体中文/English
  • 版本更新检测
  • 树状视图
  • 批量上传/下载
  • 文件冲突检测与处理
  • 云存档备份
  • 软链接同步支持（实验性）
  • UFS 配置注入（实验性）- 直接修改 appinfo.vdf 添加自定义云同步路径
  • 自动备份计划

包管理器支持

  • AUR (Arch User Repository) - yay -S steam-cloud-file-manager-bin
  • Homebrew (macOS) - brew tap Fldicoahkiin/tap && brew 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.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 文件

致谢

核心依赖

工具库

UI 扩展

打包工具

参考项目

文档资料

Star History

Star History Chart

About

Cross-platform GUI for Steam Cloud. Visualizes remote storage as a file tree with download, upload, and delete capabilities. Built with Rust. | 跨平台 Steam 云存档 GUI。以树状视图显示云端文件，支持下载、上传及删除操作。基于 Rust 开发。

Topics

windows macos linux rust steam cross-platform archlinux steam-api file-manager backup-tool vdf steam-cloud cloud-sync save-manager egui steam-tools steamcloud game-saves steamworks-sdk

Resources

Readme

License

GPL-3.0 license

Contributing

Contributing
Activity

Stars

111 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 20

v1.2.2 Latest
Jan 14, 2026
+ 19 releases

Packages

No packages published

Languages