Blockstack Browser 连接 Gaia 存储完整指南:多玩家存储 Provider 配置详解
Blockstack Browser 连接 Gaia 存储完整指南:多玩家存储 Provider 配置详解
Blockstack Browser 是 Blockstack 生态的官方浏览器,负责管理你的 Blockstack ID,并把个人资料和 App 数据安全地存到 Gaia 存储中。Gaia 是 Blockstack 的分布式存储系统,由一个个 Gaia Hub(存储 Provider)提供服务:既可以一键连接 Blockstack PBC 提供的默认免费存储 hub(https://hub.blockstack.org),也可以在注册或设置时填写自定义 Gaia Hub 地址,实现数据的完全自主掌控。本文用 4 个步骤带你完成 Gaia 存储连接与多玩家存储(multi-player storage)Provider 配置。
一、先搞懂:Gaia 与存储 Provider 是什么?
Gaia(github: blockstack/gaia)是 Blockstack 的分布式高性能存储系统,你的 profile.json 个人资料、头像,以及各 App 发布的数据文件,最终都存放在你连接的 Gaia Hub 上。可以简单理解为:
| 概念 | 通俗解释 |
|---|---|
| Gaia Hub | 存储数据的"服务器",每个 Hub 就是一个存储 Provider |
| 默认存储 hub | Blockstack PBC 官方免费提供的 https://hub.blockstack.org |
| 自定义存储 hub | 你自己或第三方部署的 Gaia Hub,填入 URL 即可接入 |
| 多玩家存储 | 你的数据不仅自己能读,其他用户也能通过你的 ID 公开读取 |
连接哪个 Provider,由你在浏览器里选择,数据主权完全在你手中。
二、连接默认免费存储 hub 的步骤
第一次使用 Blockstack Browser 时,连接存储几乎是"无感"的,浏览器会自动完成:
- 创建或登录账号:打开浏览器后注册邮箱、设置密码,生成 12 个助记词(seed phrase);
- 自动生成身份密钥:浏览器调用 app/js/account/store/account/actions.js 中的
initializeWallet,从助记词派生出身份密钥对; - 自动连接默认 hub:路由守卫检测到
storageConnected为false,自动把你重定向到/connect-storage页面(见 app/js/routes.js),屏幕短暂显示 "Connecting to Gaia storage..." 后进入主页; - 连接成功标记:浏览器把返回的
gaiaHubConfig(含专属写入令牌与地址前缀)存入设置状态,并将storageConnected置为true(app/js/connect-storage/index.js)。
整个过程由 connectStorage 动作自动完成,源码位于 app/js/account/store/settings/actions.js。
三、浏览器背后做了哪些事?
自动连接时,浏览器内部依次执行三步,这也是多玩家存储 Provider 配置的核心链路:
| 步骤 | 说明 | 相关代码 |
|---|---|---|
| ① 取第一组身份密钥 | idKeypairs<a href="https://link.gitcode.com/i/faa0379134ea4e3b7f9322f701e59dc4" target="_blank">0].key 用于向 Hub 申请专属写入令牌 |
[actions.js#L73-L78 |
② 调用 connectToGaiaHub |
与 hub 通信,返回 gaiaHubConfig(token + url_prefix + address) |
blockstack-inc.js#L18-L19 |
| ③ 上传 profile 并标记就绪 | 通过 setCoreStorageConfig 上传 profile.json,然后 storageIsConnected() |
actions.js#L96-L108 |
其中默认的 hub 地址定义在设置默认值中:
// app/js/account/store/settings/default.js
gaiaHubUrl: 'https://hub.blockstack.org',
见 app/js/account/store/settings/default.js。
四、配置自定义 Gaia Hub:两种入口
如果你想让数据存放在自己控制的服务器上(更彻底的"数据主权"),Blockstack Browser 提供两个入口:
入口 1:注册 / App 登录流程中直接选择
- 应用推荐 hub:当 App 请求授权时,浏览器会展示推荐页,让你在"使用 App 推荐的 Provider / 使用 Blockstack 官方 Provider / 使用其他 Provider"之间三选一,源码见 app/js/sign-up/views/_recommended-gaia-hub.js;
- 输入自定义地址:选择"其他 Provider"后,在 Gaia Hub URL 输入框粘贴你的 Hub 地址(必填校验见 _custom-hub.js)。
入口 2:账号设置中修改 gaiaHubUrl
登录后进入 账号 → API 设置(路由 account/api),找到 URL for Gaia Hub Connection 输入框修改保存即可,源码见 app/js/account/ApiSettingsPage.js。
此外,设置页 account/storage 提供"连接默认存储"按钮和"自建 Gaia 存储 hub"入口,实现位于 app/js/account/StorageProvidersPage.js。
⚠️ 注意:页面中明确提示 "our storage migration feature will be included in a future version"——即换 Hub 与数据迁移功能将在此后版本支持。更换 Provider 前请先导出个人资料备份(
profiles页面提供 Export),以免数据留在旧 Hub 上。
五、开发者视角:多玩家存储如何工作
对开发者来说,"多玩家存储"意味着你的 App 数据对其他用户可见。授权时 App 会请求两个关键 scope:
store_write:允许 App 往 Gaia 写数据(默认包含);publish_data:把 App 写入的用户文件通过profile.json的apps属性公开给其他人。
授权界面会显示 "publish data stored for the app" 的确认提示:
拿到权限后,开发者只需两个 API 即可管理存储:getFile() 读取、putFile() 写入,支持任意文件类型(JSON、Markdown、SQL 均可)。官方教程推荐用"索引文件 + 子文件夹"的设计避免整文件覆盖(完整教程见 docs/multi-player-storage.md):
六、关键文件速查
| 内容 | 文件位置 |
|---|---|
Gaia 连接核心动作 connectStorage |
app/js/account/store/settings/actions.js |
默认 hub 地址 gaiaHubUrl |
app/js/account/store/settings/default.js |
| 存储 Provider 设置页 | app/js/account/StorageProvidersPage.js |
| API 设置页(自定义 hub URL) | app/js/account/ApiSettingsPage.js |
| 自动连接存储中间页 | app/js/connect-storage/index.js |
| 自定义 Hub 注册页 | app/js/sign-up/views/_custom-hub.js |
| 多玩家存储官方教程 | docs/multi-player-storage.md |
小结:普通用户基本无需操心——Blockstack Browser 会自动连接默认免费 hub;进阶用户可以随时通过 API 设置换成自己的 Gaia Hub,掌握数据存放的每一寸细节。🚀


