# PostgreSQL FPK for fnOS

`nxsir.postgresql` 是面向 fnOS 原生应用的共享 PostgreSQL 15 服务，不依赖 Docker。多个应用共用一个数据库进程，但通过回环注册 API 获得相互隔离的数据库、SCRAM 角色和随机密码。

主要功能：

- PostgreSQL 15，仅监听 `127.0.0.1:15432`
- 独立管理界面，默认端口 `15433`
- 回环限定的应用注册与凭据签发
- pgvector 扩展申请
- 客户端、数据库、角色与会话管理
- 默认只读的 SQL 工作台（30 秒、1000 行上限）
- 手动 custom-format 备份、SHA-256 与恢复
- 独立管理密码、HttpOnly 会话和接入令牌轮换

## 目录

```text
fnos-postgresql/              fnOS 包清单、向导和生命周期脚本
src/PostgresService.WebApi/   管理与注册 API
frontend/postgres-admin/      Vue 管理界面
scripts/                      构建、包校验和运行级冒烟测试
tests/PostgresService.Tests/  安全凭据单元测试
docs/                         第三方 fnOS 应用接入文档
```

## 构建

环境要求：Linux x86_64、.NET 8 SDK、Node.js/npm、`apt-get`、`dpkg-deb`、curl，以及 fnOS 官方 `fnpack`。可把 `fnpack` 放到 `.tools/fnpack`，或通过 `FNPACK` 指定。

```bash
cd frontend
npm ci
cd ..
./scripts/build-postgresql-fnos-package.sh
```

默认输出：

```text
artifacts/fnos/nxsir-postgresql-15.1.1-x86_64.fpk
artifacts/fnos/nxsir-postgresql-15.1.1-x86_64.fpk.sha256
```

构建脚本会下载 Debian Bookworm PostgreSQL 15 运行时，并对官方 pgvector `0.8.6-1.pgdg12+1` 包执行固定 SHA-256 校验。`app.tgz` 还会检查校验和、路径穿越、绝对/越界链接和 512 MB 解包上限。

如有离线 NuGet 源，可设置 `POSTGRES_SERVICE_NUGET_FEED=/path/to/feed`；否则使用 nuget.org。

## 验证

```bash
dotnet test tests/PostgresService.Tests/PostgresService.Tests.csproj
./scripts/verify-fnos-package.sh artifacts/fnos/nxsir-postgresql-15.1.1-x86_64.fpk
./scripts/smoke-postgresql-fnos-package.sh artifacts/fnos/nxsir-postgresql-15.1.1-x86_64.fpk
```

冒烟测试会临时启动实际包内 PostgreSQL 和管理 API，验证两个隔离客户端、SCRAM、pgvector、跨库拒绝、只读 SQL、写语句拒绝、备份和重启持久性，退出时停止进程并删除临时数据。

## 应用接入

其他 fnOS 应用请直接阅读 [fnOS PostgreSQL 共享服务接入指南](docs/fnos-postgresql-client-integration.md)，其中包含 manifest 依赖、注册 API、凭据落盘、连接示例、pgvector、迁移和故障恢复规范。