---
title: 元数据文件存储
description: 说明 SuccApp 元数据在服务器数据库和 AI 低代码开发本地工作区中的两种存储形态，以及 `.meta` 的作用。
navTitle: 文件存储
---
# 元数据文件存储

SuccApp 元数据有两种常见存储形态：服务器运行时的数据库存储，以及 AI 低代码开发（AI building）使用的本地工作区文件存储。理解这两层关系，可以避免把本地 `.spg`、`.dash`、`.tbl` 和 `.meta` 文件误认为服务器生产环境中的真实落库形态。

## 服务器中的存储{#server-storage}

在生产环境中，元数据文件存储在数据库中。服务器通过元数据仓库服务读写项目、目录、文件内容、版本和资源属性；文件系统路径只是产品和接口层面的资源路径表达，不表示生产环境一定存在同名磁盘文件。

元数据文件的核心存储表是：

| 系统表 | 作用 |
| --- | --- |
| [META\_FILES 文件表](../../sys-tables/meta/META_FILES.md) | 存放元数据目录结构、文件基本信息和当前文件内容。`PROJECT_NAME`、`PARENT_DIR`、`NAME` 共同表达资源路径；`CONTENT` 保存当前内容，可能按 `IS_GZ` 压缩；`REVISION`、`HASH`、`SIZE` 等字段用于版本和内容变化判断。 |
| [META\_REVISIONS 历史版本表](../../sys-tables/meta/META_REVISIONS.md) | 记录元数据资源历史版本内容和修改信息，用于查看历史、恢复版本和清理版本。 |
| [META\_FILES\_REFLABELS 文件和标签的映射表](../../sys-tables/meta/META_FILES_REFLABELS.md) | 记录元数据文件与标签之间的关系，用于按标签检索和统计资源分类。 |

更多元数据相关系统表可在[系统表](../../sys-tables/README.md)的 `meta` 分组中查看。

::: tip 提示
不要直接修改生产数据库中的元数据系统表。元数据的增删改应通过 SuccApp 设计器、SuccApp CLI、SuccApp for VS Code 或受控的服务端接口完成，这样系统才能同步维护版本、缓存、引用和权限相关信息。
:::

## 本地工作区中的存储{#workspace-storage}

AI 低代码开发流程会把服务器数据库中的元数据项目拉取到本地，形成一个适合 AI Agent 和 Git 处理的工作目录。克隆或拉取时，SuccApp CLI / SuccApp for VS Code 会读取服务器元数据树和文件内容，再转换成本地目录和文件。

本地工作区通常包含两类信息：

| 本地内容 | 说明 |
| --- | --- |
| 元数据文件 | 页面、仪表板、报表、模型、程序流、脚本、主题、配置和资源等内容以文件形式落在项目目录中，例如 `.spg`、`.dash`、`.rpt`、`.tbl`、`.query`、`.afl`、`.wfl`、`settings.json` 和图片资源。AI Agent 主要编辑这些文件。 |
| `.meta` 文件 | 保存当前目录下直接子资源的附加属性，例如 `id`、`revision`、描述、排序、图标、隐藏状态、标签、`option` 和 `customOption`。这些属性在服务器中来自元数据系统表字段，本地则写入对应目录的 `.meta` 索引文件。 |

例如本地文件：

```text
DEMO/app/portal.app/index.spg
```

它的文件内容保存在 `index.spg` 中；对应的资源属性保存在父目录的 `.meta` 中：

```json
{
	"index.spg": {
		"id": "UfOoq4xbolMgpuFPItTdcE",
		"revision": 12,
		"desc": "门户首页",
		"order": 6,
		"modifier": "admin",
		"modifyTime": 1760966400000
	}
}
```

`.meta` 是本地工作区中的目录级资源元信息索引，不是服务器中的真实元数据文件。完整规则见 [.meta 资源元信息](../file-types/config/meta.md)。

## 同步时如何转换{#sync}

克隆、拉取和推送会在服务器数据库形态与本地文件形态之间转换：

1. **克隆项目**：从服务器读取项目、目录、文件内容和资源属性，把内容写成本地文件，把资源属性写入对应目录的 `.meta`。
2. **拉取变化**：把服务器上的最新内容和属性刷新到本地同步基线，再应用到工作区。
3. **本地编辑**：AI Agent 或人工修改项目目录中的元数据文件，必要时维护相关目录 `.meta`。
4. **推送变化**：SuccApp 将本地文件内容和 `.meta` 中允许写回的属性提交给服务器，服务器再写入元数据系统表并返回权威的 `id`、`revision`、`modifyTime` 等信息。

本地工作区还会维护 `.succapp/remote/` 下的服务器基线，用于判断本地变化、远端变化和冲突。日常编辑应面向项目目录中的文件和 `.meta`，不要把 `.succapp/remote/` 当作业务工作目录。

## 编辑注意{#notes}

1. 不要通过修改本地 `.meta` 中的 `id`、`revision`、`creator`、`createTime`、`modifier`、`modifyTime` 等服务器控制字段来改变服务器事实；推送时这些字段以服务器返回为准。
2. 新增、移动、重命名或删除元数据文件时，同时检查所在目录或目标目录的 `.meta` 和文件内部引用路径。
3. 如果只想修改页面、模型、报表等正文内容，优先编辑对应元数据文件；只有描述、排序、隐藏状态、标签、自定义属性等资源属性变化，才需要关注 `.meta`。
4. AI 低代码开发的完整工作流见[元数据即代码](../../ai-building/basics/metadata-as-code.md)和[连接服务器与克隆项目](../../ai-building/workspace/connect-and-clone.md)。