136 lines
5.0 KiB
Markdown
136 lines
5.0 KiB
Markdown
# 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 验证
|
|
|
|
```bash
|
|
./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 容器：
|
|
|
|
```bash
|
|
docker compose up -d postgres
|
|
```
|
|
|
|
4. 确认 PostgreSQL 已就绪：
|
|
|
|
```bash
|
|
docker compose ps
|
|
```
|
|
|
|
## 2. 运行一次性迁移
|
|
|
|
迁移命令会：
|
|
|
|
- 对 PostgreSQL 执行 EF Core migrations
|
|
- 检查目标库必须为空
|
|
- 只读打开旧 SQLite
|
|
- 按既定顺序导入所有业务数据
|
|
|
|
Docker Compose 部署建议直接这样跑：
|
|
|
|
```bash
|
|
docker compose run --rm api --migrate-sqlite /app/data/live-recorder.db
|
|
```
|
|
|
|
如果你是在宿主机本地直接运行 .NET，则可以使用：
|
|
|
|
```bash
|
|
dotnet run --project src/LiveRecorder.WebApi -- --migrate-sqlite /app/data/live-recorder.db
|
|
```
|
|
|
|
Windows 本地示例：
|
|
|
|
```powershell
|
|
dotnet run --project src\LiveRecorder.WebApi -- --migrate-sqlite "C:\path\to\live-recorder.db"
|
|
```
|
|
|
|
迁移完成后，控制台会输出每张表的 `source -> target` 行数校验结果。
|
|
|
|
## 3. 正式切流
|
|
|
|
1. 启动完整服务：
|
|
|
|
```bash
|
|
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 备份。
|