live_recorder/docs/postgresql-migration.md

PostgreSQL 共享服务与历史数据迁移

fnOS 原生部署

fnOS 方案由两个独立 FPK 组成：

应用	默认端口	持久化内容
nxsir.postgresql	管理界面 15433、数据库 127.0.0.1:15432	PostgreSQL 数据、凭据散列、审计日志
liverecorder	Web 管理界面 18080	应用日志、签发后的数据库客户端凭据、迁移回退数据

安装顺序：

1. 安装 PostgreSQL 共享服务，设置独立管理密码与长度至少 20 位的应用接入令牌。
2. 安装 Live Recorder，设置应用管理员密码，并填写同一个接入令牌。
3. Live Recorder 只通过 127.0.0.1 注册。共享服务为它创建独立数据库和 SCRAM 角色，随机密码只在注册响应中返回一次。
4. 注册成功后，接入令牌会从 Live Recorder 持久化目录删除；签发凭据保存在权限为 0600 的 postgres-client.conf。

新安装不会启动 Live Recorder 包内的旧 PostgreSQL。录制路径默认是 fnOS 共享目录 liverecorder/records，也可以在“设置 → 录制 → 输出根目录”修改；路径模板会继续在该根目录下生成平台、主播、日期等层级，已有目录会直接复用，不会重复嵌套。

从旧 fnOS 版本自动迁移

升级包检测到旧 PG_VERSION 且尚无迁移标记时会：

1. 启动旧的私有 PG15，只读导出 custom-format 转储并生成 SHA-256。
2. 清空新签发的目标 schema，以 --no-owner --no-acl 恢复。
3. 精确比较十张业务表在源库和目标库中的行数。
4. 全部成功后写入 shared-database.active 标记并停止旧 PostgreSQL。

任一步失败都会继续使用旧数据库，下次启动再重试。系统不会自动删除旧数据、转储、校验文件；确认新版本稳定并另行备份后再手工清理。迁移标记一旦存在，凭据损坏时应用会拒绝回退到已经过期的旧库，防止录制数据分叉。

管理与备份

• PostgreSQL 管理面板使用独立 admin 会话，不复用 Live Recorder 登录。
• SQL 工作台只接受单条 SELECT、WITH、EXPLAIN、SHOW、VALUES 或 TABLE，并在只读事务、30 秒超时和 1000 行上限下执行。
• 自动签发的应用数据库与角色不能在普通数据库/角色页面直接删除，应从客户端页面吊销。
• 备份仅手动触发，使用 custom-format pg_dump 并保存 SHA-256；恢复需要明确输入目标数据库名称确认。

fnOS 验证

./scripts/smoke-postgresql-fnos-package.sh artifacts/fnos/nxsir-postgresql-15.1.0-x86_64.fpk
./scripts/smoke-fnos-package.sh artifacts/fnos/liverecorder-1.1.0-x86_64.fpk artifacts/fnos/nxsir-postgresql-15.1.0-x86_64.fpk
./scripts/smoke-fnos-migration.sh artifacts/fnos/liverecorder-1.1.0-x86_64.fpk artifacts/fnos/nxsir-postgresql-15.1.0-x86_64.fpk

下面保留 Docker/宿主机从旧 SQLite 导入 PostgreSQL 的流程。

这份说明对应当前主线版本：应用正式运行数据库已经切换为 PostgreSQL，SQLite 仅用于一次性历史数据导入。

1. 迁移前准备

1. 备份旧的 SQLite 文件和 records/ 目录。
2. 停止当前 API 写入流量，避免迁移过程中旧库继续变化。
3. 准备好新的 PostgreSQL 容器：

docker compose up -d postgres

4. 确认 PostgreSQL 已就绪：

docker compose ps

2. 运行一次性迁移

迁移命令会：

• 对 PostgreSQL 执行 EF Core migrations
• 检查目标库必须为空
• 只读打开旧 SQLite
• 按既定顺序导入所有业务数据

Docker Compose 部署建议直接这样跑：

docker compose run --rm api --migrate-sqlite /app/data/live-recorder.db

如果你是在宿主机本地直接运行 .NET，则可以使用：

dotnet run --project src/LiveRecorder.WebApi -- --migrate-sqlite /app/data/live-recorder.db

Windows 本地示例：

dotnet run --project src\LiveRecorder.WebApi -- --migrate-sqlite "C:\path\to\live-recorder.db"

迁移完成后，控制台会输出每张表的 source -> target 行数校验结果。

3. 正式切流

1. 启动完整服务：

docker compose up -d

2. 验证这些接口和流程：
   • 登录
   • /api/live-rooms
   • /api/record-sessions
   • /api/logs
   • 自动开录
   • 系统日志持续写入

4. Docker 默认环境变量

当前 docker-compose.yml 默认使用：

• POSTGRES_DB=live_recorder
• POSTGRES_USER=live_recorder
• POSTGRES_PASSWORD=change_me

正式部署前请至少覆盖 POSTGRES_PASSWORD。

5. 回滚方案

如果切换后需要回滚：

1. 停止新版本 API。
2. 保留 PostgreSQL 数据卷，不做破坏性清理。
3. 用迁移前备份的 SQLite 文件恢复旧版本应用。
4. 检查 records/ 目录没有被误覆盖后，再重新开放流量。

6. 注意事项

• 迁移命令默认拒绝导入到非空 PostgreSQL 数据库。
• SQLite 不再作为正式运行主库，只保留历史迁移用途。
• /app/data 目录在 Docker 方案里仍会挂载，主要用于迁移阶段存放旧 SQLite 备份。