数据库模型

本文档整理了 Studio 将数据存放在哪里、以何种形态存放。在确定备份范围或需要直接查询时可参考此文档。

有两处存储位置

PostgreSQL 中存放元数据，文件系统（DATA_ROOT）中存放应用源码和构建产物。两者都要备份才能恢复 —— 只备份 DB 的话没有应用代码，只备份文件的话不知道谁创建了什么。

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

PostgreSQL 有两种模式之一 —— 内置容器（默认）或 Platform 公共 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`	已应用的迁移名称及时间

watchers 以前叫 flows

在 2026-07-13 统一了命名（ALTER TABLE flows RENAME TO watchers，数据保留）。新安装时也照样先建成 flows 再重命名的顺序 —— 因为迁移历史是既往记录，不做改动。如果要直接写查询，用的是 watchers。

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

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

请勿手动修改模式

如果 schema_migrations 与实际模式不一致，下次升级时迁移会因为「试图创建已存在的对象」而失败，导致整个应用无法启动。

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

默认值为 /var/lib/pp-studio。以下内容全部存放在此路径下。

存放的内容	缺失时的后果
应用工作区（生成的源码）	无法打开应用 —— DB 中只有元数据
构建产物	重新构建即可
会话·状态	进行中的工作会丢失
内置 PG 数据	在 `COMPOSE_PROFILES=bundled-pg` 的安装中，数据库主体就在这里

如果使用内置 PG，DATA_ROOT 就等于数据库备份

在内置模式下，PostgreSQL 数据目录也位于 DATA_ROOT 之下。也就是说，如果遗漏这一路径，将会同时丢失数据库和应用源码。

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

至少试着做一次恢复演练

只有备份而从未做过恢复演练，是最危险的状态。相关步骤请参见备份与恢复。