> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.

# 数据存储

插件应根据数据用途、查询方式和生命周期选择存储方式。不要为少量配置自行维护数据库，也不要把不可恢复的业务数据当作缓存。

## 选择存储方式

| 数据类型                             | 建议方式                                             |
| -------------------------------- | ------------------------------------------------ |
| 需要通过 Halo API 查询、授权或与其他插件交互的业务数据 | 自定义模型和 `ReactiveExtensionClient`                 |
| 由用户在插件设置页面维护的少量配置                | `Setting`、`ConfigMap` 和 `ReactiveSettingFetcher` |
| 密码、Token、API Key 和私钥             | `Secret`，其他资源只保存 Secret 名称                       |
| 插件专用数据库、索引或无法表示为自定义模型的文件         | `PluginsRootGetter` 下的插件专属目录                     |
| 可以重新生成的临时结果                      | 明确标识的缓存目录，并允许安全删除和重建                             |

配置读取参考[获取插件配置](https://docs.halo.run/developer-guide/plugin/api-reference/server/setting-fetcher.md)，自定义模型参考[自定义模型](https://docs.halo.run/developer-guide/plugin/api-reference/server/extension.md)，密钥存储和第三方请求参考[敏感数据与出站请求](https://docs.halo.run/developer-guide/plugin/security/outbound-http.md)。

## 使用本地文件

`PluginsRootGetter` 从 Halo 2.18.0 开始提供插件根目录。插件应在该根目录下使用稳定且唯一的专属子目录，通常采用自身 `metadata.name` 或不会与其他插件冲突的固定名称。不能读写其他插件目录，也不能把路径暴露为任意用户输入。

本地文件不会自动获得自定义模型的查询、权限和版本能力。写入关键文件时，应先写入同目录临时文件，确认内容完整后再替换目标文件，避免进程中断留下半写状态。

## 运行和部署边界

- **多副本**：本地目录通常不是跨副本共享存储。需要多副本一致读写的数据应使用自定义模型或明确配置的外部存储。
- **生命周期**：禁用或重载插件时不要删除持久化数据；仅在明确的卸载约定和用户知情情况下清理。
- **并发**：SQLite 等单文件数据库需要处理锁、超时和并发写入，不能假设每次调度或请求都串行执行。
- **敏感数据**：不要在日志、ConfigMap、自定义模型或未保护的缓存中存储密钥和个人敏感信息。密码、Token、API Key 和私钥应使用 Halo `Secret`；确需存储其他敏感文件时，应限制文件权限并说明数据用途。

## 备份和升级

Halo 不会自动理解插件私有文件或数据库的 schema。选择本地存储后，插件需要自行定义：

1. 哪些文件属于持久化数据，哪些可以重建。
2. Halo 备份是否包含这些数据，以及用户如何单独备份和恢复。
3. schema 版本、升级顺序和失败后的恢复方式。
4. 新版本能否安全地重复执行升级步骤。

不要把未经验证的迁移过程描述为 Halo 的通用迁移方案。发布前应在数据副本上验证升级、降级限制、损坏恢复和插件卸载行为。