live_recorder/docs/postgresql-migration.md

PostgreSQL 共享服务部署说明

fnOS 原生部署

fnOS 方案由两个独立 FPK 和一个商店运行时依赖组成：

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

Live Recorder 还依赖商店应用 nodejs_v22，并从 /var/apps/nodejs_v22/target/bin/node 调用 Node.js 22。FPK 的 install_dep_apps=nxsir.postgresql:nodejs_v22 会让 fnOS 检查并启用两个依赖。

安装顺序：

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

Live Recorder 1.2.5 起只使用共享 PostgreSQL，不再打包、启动或回退到旧内置 PostgreSQL，也不再提供旧内置数据库的自动迁移能力。升级前必须确认 postgres-client.conf 有效，或在升级向导填写共享服务应用接入令牌。历史版本留下的 postgres/ 和 postgres-migration/ 目录不会被应用读取，也不会自动删除。

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

管理与备份

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

fnOS 验证

PostgreSQL 共享服务由独立仓库构建和发布：https://gitea.nxsir.cn/nanxun/postgresqlfpk。

./scripts/smoke-fnos-package.sh \
  artifacts/fnos/liverecorder-1.2.19-x86_64.fpk \
  /path/to/nxsir-postgresql-15.1.1-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 备份。