数据库模型

本文档说明了 Studio 将数据存储在哪里，以及以何种形式存储。在确定备份范围或需要直接查询时，请参阅此文档。

存储有两个位置

PostgreSQL 存储元数据，文件系统（DATA_ROOT）存储应用源代码和构建产物。两者都必须备份，才能恢复 —— 仅备份数据库则没有应用代码，仅备份文件则无法知道谁创建了什么。

存储	内容
PostgreSQL	用户 · 应用元数据 · 对话 · 审计 · Watcher · 技能
文件系统（`DATA_ROOT`）	工作区（应用源代码） · 构建产物 · 状态

PostgreSQL 采用两种模式之一 —— 捆绑容器（默认）或平台共享 PG。请参阅环境变量参考。

表 — 共11个

分组	表	内容
用户	`studio_users`	账户 · 角色（`admin`/`builder`/`viewer`） · 密码哈希
	`studio_tokens`	已签发令牌
对话	`ask_conversations`	聊天线程
	`ask_history`	收发消息及耗时
Watcher	`watchers`	周期性监控定义及通知设置
	`notification_seen`	通知确认状态
技能	`skills`	现场知识登记本
部署	`deploy_log`	部署历史
审计 · 用量	`audit_log`	谁做了什么
	`usage_log`	AI 令牌用量
模式	`schema_migrations`	已应用的迁移名称和时间

迁移日志中可见 flows

即使全新安装，也会先以 flows 创建，然后重命名为 watchers —— 因为迁移历史一旦记录便不再更改。如果直接编写查询，应使用 watchers。

服务器启动时，按编号顺序应用 src/infra/db/migrations/ 中的 .sql，并将已应用的文件名记录在 schema_migrations 中。已应用过的不会再次执行。

-- 지금 어디까지 적용됐는지
SELECT name, applied_at FROM schema_migrations ORDER BY name;

请勿手动修改模式

如果 schema_migrations 与实际模式不一致，下次升级时迁移会尝试「创建已存在的内容」而失败，导致界面完全无法启动。

升级前请先备份 → 备份与恢复。

默认路径是 /var/lib/pp-studio。以下内容全部存储于其中。

数据库不在 DATA_ROOT 中

Studio 使用外部 PostgreSQL。即使整体备份 DATA_ROOT，数据库仍需要单独备份 —— 请参阅备份与恢复。

必须备份的内容	遗漏后果
PostgreSQL 转储	账户 · Watcher · 对话 · 审计记录消失
`DATA_ROOT`	应用源代码丢失，无法打开应用
`/etc/kopens/plantpulse-studio.env`	需要重新填写连接信息 · 密钥

请至少进行一次恢复演练

只备份而从未进行过恢复是最危险的状态。操作步骤见备份与恢复。