应用数据导出格式说明

本文档描述 ShangCloud 开发者「数据导出」功能产出的 JSON 文件结构（format_version: 1）。

获取方式

项目	说明
面板	开发者中心 → 数据导出 → `/developer/export?app_id=<APP_ID>`
鉴权	需登录会话，且当前用户为该应用的所有者或合作者
文件名	`shangcloud-app-{app_id}-export-{YYYY-MM-DD}.json`

导出操作会写入应用审计日志（action = export_app_data）。

顶层结构

{
  "format_version": 1,
  "app_id": "12345",
  "exported_at": 1710000000000,
  "scope": {
    "cloud_whitelist": true,
    "cloud_public": true,
    "cloud_private": true,
    "sqlite": true
  },
  "cloud_variables": { ... },
  "sqlite": { ... }
}

字段	类型	说明
`format_version`	`number`	导出格式版本，当前固定为 `1`。解析方应据此做兼容判断。
`app_id`	`string`	被导出的应用 ID。
`exported_at`	`number`	导出时刻的 Unix 时间戳（毫秒）。
`scope`	`object`	本次实际勾选的导出范围（与请求参数一致）。
`cloud_variables`	`object`	可选。云变量与白名单，见下文；未勾选任何云变量相关项时省略。
`sqlite`	`object`	可选。应用 SQLite 数据库，见下文；`scope.sqlite=false` 时省略。

`cloud_variables` — 云变量

{
  "whitelist": [ ... ],
  "public": {
    "score": "100",
    "room_name": "大厅"
  },
  "private": {
    "10001": {
      "score": "42",
      "coins": "999"
    },
    "10002": {
      "score": "7"
    }
  },
  "private_user_count": 2
}

字段	类型	说明
`whitelist`	`array`	云变量白名单配置（来自 `variable_whitelist` 表，最多 10000 条）。
`public`	`object`	应用级公开云变量：`{ 变量名: 字符串值 }`。
`private`	`object`	用户级私有云变量：`{ 用户UID: { 变量名: 字符串值 } }`。仅包含至少有一条有效变量的用户。
`private_user_count`	`number`	`private` 中用户数量（等于 `Object.keys(private).length`）。

公开 vs 私有

公开变量：存储于 Data/Database/{app_id}/，全应用共享一份。

私有变量：存储于 Data/Database/{uid}/{app_id}/，每个用户独立一份。

运行时是否走公开/私有实例，取决于白名单中该变量的 is_public 标志；导出时则按磁盘上的两个作用域分别完整 dump，不依赖白名单过滤。

值类型约定

所有云变量值在导出中均为 UTF-8 字符串（与 Scratch 云变量一致）。

写入的隔离变量不会导出

已删除的键不会出现

`whitelist[]` 单项字段

字段	类型	说明
`id`	`number`	白名单记录 ID。
`variable_name`	`string`	变量名。
`allowed_operations`	`string[]`	允许的操作，如 `["read", "write"]`。
`is_public`	`boolean`	是否为公开变量。
`specific_permissions`	`object \| null`	细粒度权限（JSONB，结构由 Guardian 定义）。
`created_at`	`string`	创建时间，序列化为字符串。

`sqlite` — 应用 SQLite 数据库

每个应用对应一个独立 SQLite 文件：Data/AppDB/{app_id}/data.db。

数据库不存在时

{
  "exists": false,
  "tables": []
}

正常导出

{
  "exists": true,
  "table_count": 1,
  "tables": [
    {
      "name": "scores",
      "rls_enabled": true,
      "columns": [
        { "name": "_id", "type": "INTEGER", "nullable": false, "reserved": true },
        { "name": "_owner", "type": "TEXT", "nullable": false, "reserved": true },
        { "name": "_created_at", "type": "INTEGER", "nullable": true, "reserved": true },
        { "name": "_updated_at", "type": "INTEGER", "nullable": true, "reserved": true },
        { "name": "score", "type": "INTEGER", "nullable": true, "reserved": false },
        { "name": "name", "type": "TEXT", "nullable": true, "reserved": false }
      ],
      "rows": [
        {
          "_id": 1,
          "_owner": "10001",
          "_created_at": 1710000000,
          "_updated_at": 1710000100,
          "score": 100,
          "name": "player"
        }
      ]
    }
  ]
}

字段	类型	说明
`exists`	`boolean`	磁盘上是否存在 `data.db`。
`table_count`	`number`	仅在成功导出时出现；等于 `tables.length`。
`tables`	`array`	表列表（不含内部元数据表 `_sc_tables` 本身作为「用户表」导出；仅 `_sc_tables` 中登记的应用管理表）。
`error`	`string`	可选。读取失败时出现，此时 `tables` 可能为空且 `exists` 仍为 `true`。

`tables[]` 单项

字段	类型	说明
`name`	`string`	表名。
`rls_enabled`	`boolean`	建表时设定的行级安全开关（创建后不可更改）。
`columns`	`array`	列定义（含保留列与用户列）。
`rows`	`array`	该表全部数据行（无 500 行分页上限）。

`columns[]` 单项

字段	类型	说明
`name`	`string`	列名。
`type`	`string`	SQLite 类型，通常为大写：`TEXT` / `INTEGER` / `REAL` / `BOOLEAN` 等。
`nullable`	`boolean`	是否可空（来自 `PRAGMA table_info` 的 notnull 反值）。
`reserved`	`boolean`	是否为系统保留列（名称以 `_` 开头）。

保留列语义

每张应用管理表自动附带：

列	含义
`_id`	自增主键
`_owner`	创建该行的用户 UID（字符串）
`_created_at`	创建时间戳
`_updated_at`	最近更新时间戳

用户自定义列名不得以 _ 开头。

行数据值类型

与 SQLite 原生类型对应：整数、浮点、字符串、布尔（库内可能以 0/1 存储）。

JSON 序列化后：数字保持 number，文本为 string，null 为 null。

不保证 BOOLEAN 在 JSON 中一定是 true/false，解析时建议兼容 0/1。

完整示例

{
  "format_version": 1,
  "app_id": "12345",
  "exported_at": 1710000000000,
  "scope": {
    "cloud_whitelist": true,
    "cloud_public": true,
    "cloud_private": true,
    "sqlite": true
  },
  "cloud_variables": {
    "whitelist": [
      {
        "id": 1,
        "variable_name": "score",
        "allowed_operations": ["read", "write"],
        "is_public": false,
        "specific_permissions": null,
        "created_at": "2024-01-01 12:00:00"
      },
      {
        "id": 2,
        "variable_name": "global_counter",
        "allowed_operations": ["read", "write"],
        "is_public": true,
        "specific_permissions": null,
        "created_at": "2024-01-02 08:00:00"
      }
    ],
    "public": {
      "global_counter": "128"
    },
    "private": {
      "10001": {
        "score": "42"
      }
    },
    "private_user_count": 1
  },
  "sqlite": {
    "exists": true,
    "table_count": 1,
    "tables": [
      {
        "name": "scores",
        "rls_enabled": true,
        "columns": [
          { "name": "_id", "type": "INTEGER", "nullable": false, "reserved": true },
          { "name": "_owner", "type": "TEXT", "nullable": false, "reserved": true },
          { "name": "_created_at", "type": "INTEGER", "nullable": true, "reserved": true },
          { "name": "_updated_at", "type": "INTEGER", "nullable": true, "reserved": true },
          { "name": "score", "type": "INTEGER", "nullable": true, "reserved": false }
        ],
        "rows": [
          {
            "_id": 1,
            "_owner": "10001",
            "_created_at": 1710000000,
            "_updated_at": 1710000000,
            "score": 42
          }
        ]
      }
    ]
  }
}

未包含的内容

当前 format_version: 1 不导出：

Guardian 规则 / 事件规则 / Serverless 函数源码

OAuth 客户端密钥、应用配置

成就、联机大厅、房间运行时状态

用户账户信息（仅出现 UID 引用）

原始 Bitcask / SQLite 二进制文件

隐私与安全

导出文件包含全部用户的私有云变量与 SQLite 行数据，属于敏感数据。

仅应用所有者与合作者拥有权限调用导出 API。

请勿将导出文件上传至公开仓库或分享给无关第三方。

导入/恢复能力不在本格式版本范围内。

数据导出

应用数据导出格式说明#

获取方式#

顶层结构#

cloud_variables — 云变量#

公开 vs 私有#

值类型约定#

whitelist[] 单项字段#

sqlite — 应用 SQLite 数据库#

数据库不存在时#

正常导出#

tables[] 单项#

columns[] 单项#

保留列语义#

行数据值类型#

完整示例#

未包含的内容#

隐私与安全#