补充共享 PostgreSQL 应用接入与使用指南
This commit is contained in:
@@ -12,6 +12,7 @@
|
||||
- [OpenBao 使用指南](services/openbao.md)：日常登录、按权限取密与机器身份边界。
|
||||
- [NetBox 使用指南](services/netbox.md)：浏览设备和 IPAM，按 Git 来源维护资产镜像。
|
||||
- [SPIFFE/SPIRE](services/spire.md)：按 #34 整理的阶段状态、使用与 runbook 入口。
|
||||
- [共享 PostgreSQL 使用指南](services/shared-postgresql.md)：应用接入、连接示例与共享实例维护边界。
|
||||
- [PostgreSQL Tenant Operator](services/postgresql-tenant-operator.md)：计划在共享 PostgreSQL 上提供的 DBaaS 中间层。
|
||||
- [Gitea Dynamic Runner](services/gitea-dynamic-runner.md)：原 microVM runner，现支持 Pod/VM 两种一次性执行环境。
|
||||
- [NATS](services/nats.md)：已部署的集群共享消息服务，目前仅 Dynamic Runner 消费。
|
||||
|
||||
@@ -9,15 +9,16 @@
|
||||
- [Grafana](services/grafana.md)：内存看板、指标查询、日志搜索和数据源用途。
|
||||
- [zot](services/zot.md)：拉取、发布授权、workflow 身份职责与后端数据恢复边界。
|
||||
- [SeaweedFS](services/seaweedfs.md)：S3 入口、专用凭据、列举与上传下载示例。
|
||||
|
||||
- [OpenBao](services/openbao.md)：人的登录、按权限取密及机器身份边界。
|
||||
- [NetBox](services/netbox.md)：浏览设备与 IPAM，明确 Git 来源与评估用途。
|
||||
|
||||
- [共享 PostgreSQL](services/shared-postgresql.md)：应用接入、连接检查与共享实例维护边界。
|
||||
|
||||
以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。
|
||||
|
||||
## 后续使用说明
|
||||
|
||||
1. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。
|
||||
1. codex-proxy、LiteLLM gateway、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。
|
||||
|
||||
## 文档同步与来源链接
|
||||
|
||||
|
||||
+1
-1
@@ -26,7 +26,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
|
||||
| openviking | 上下文检索服务 | `记录端口 1933 / 8020` | 配置与部署指南；未附上线记录 | `apps/openviking/README.md` | 缺导入、查询的完整例子 |
|
||||
| ps3netsrv | PS3 网络内容服务 | `未记录` | Docker 运维文档记录运行 | `apps/ps3netsrv/docker-compose.yml` | 缺客户端使用与挂载说明 |
|
||||
| [seaweedfs](seaweedfs.md) | S3 对象存储 | `s3.ad.ddupan.top` | zot 文档记录已使用 | `apps/seaweedfs/README.md` | 已有客户端读写指南与备份边界说明 |
|
||||
| shared-postgresql | 共享 PostgreSQL / CNPG | `shared-db namespace` | 历史迁移记录已完成 | `apps/shared-postgresql/migration.md` | 缺服务首页、租户接入说明 |
|
||||
| [shared-postgresql](shared-postgresql.md) | 共享 PostgreSQL / CNPG | `shared-db namespace` | 历史迁移记录已完成 | `apps/shared-postgresql/migration.md` | 已有连接、应用接入与共享资源边界指南 |
|
||||
| smtp-relay | 应用经 Microsoft 365 发信 | `smtp-relay.smtp-relay.svc.cluster.local:25` | 有配置与测试指南；未附上线记录 | `apps/smtp-relay/README.md` | 补发信链路与消费者说明 |
|
||||
| tailscale | 远程网络与子网路由 | `Tailscale 网络` | 有配置；本轮未读敏感安装脚本 | `apps/tailscale/subnet-routes.sh` | 缺 README、路由与客户端说明 |
|
||||
| vlmcsd | KMS 兼容服务，使用范围未记录 | `未记录` | 仅发现配置 | `apps/vlmcsd/compose.yaml` | 缺 README 与状态说明 |
|
||||
|
||||
@@ -21,6 +21,7 @@ homelab 资源有限，为每个应用维护一套数据库会浪费资源。绝
|
||||
计划自行实现这个中间层，让下游通过统一接口申请可消费的数据库，降低共享实例的管理成本。
|
||||
|
||||
这段现状和设计动机由维护者于 2026-09-16 提供；本轮没有查询数据库或集群。
|
||||
现有实例的日常接入见[共享 PostgreSQL 使用指南](shared-postgresql.md)。
|
||||
现有实例的源码入口为 homelab-infra 的 `apps/shared-postgresql/`。
|
||||
|
||||
## 当前进度
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: 共享 PostgreSQL 使用指南
|
||||
lifecycle: active
|
||||
evidence: documented
|
||||
last_reviewed: 2026-09-16
|
||||
last_verified: null
|
||||
---
|
||||
|
||||
# 共享 PostgreSQL
|
||||
|
||||
集群内的多个服务共用一套 PostgreSQL，避免为每个应用维护独立数据库实例造成资源浪费。
|
||||
共享实例已经在使用；计划中的 [PostgreSQL Tenant Operator](postgresql-tenant-operator.md)
|
||||
将负责简化 database、role 和凭据的管理，目前不能把该计划当成已上线的自助申请入口。
|
||||
|
||||
共享使用的现状来自维护者于 2026-09-16 的说明。连接入口与部署配置来自 homelab-infra
|
||||
工作区 `apps/shared-postgresql/`；本轮未连接数据库或查询 Kubernetes。
|
||||
|
||||
## 连接入口
|
||||
|
||||
| 使用场景 | 来源中记录的地址 |
|
||||
|---|---|
|
||||
| 集群内现有应用的兼容入口 | `shared-postgresql.shared-db.svc.cluster.local:5432` |
|
||||
| CNPG 读写入口 | `shared-postgresql-rw.shared-db.svc.cluster.local:5432` |
|
||||
| Tailscale 暴露所用的 Kubernetes Service | `shared-postgresql-tailscale`，namespace `shared-db` |
|
||||
|
||||
兼容 Service 的配置选择 CNPG primary。应用应使用 Service 地址，不固定到某个 Pod IP。
|
||||
表中的 `.svc.cluster.local` 是集群内 DNS 地址；不能直接当作集群外客户端的可达地址。
|
||||
Tailscale Service 配置存在不等于已经确认外部地址和访问权限，集群外接入须由维护者提供实际入口。
|
||||
|
||||
## 新应用接入前准备什么
|
||||
|
||||
向维护者说明应用名称、所需 database/role、扩展、连接数预期、网络来源及凭据消费方式。
|
||||
由维护者按现有管理流程建立并授权，再提供连接参数和秘密引用；本页不提供尚未上线的 Tenant CR 示例。
|
||||
|
||||
应用使用自己的数据库与账号，不复用其他应用或实例管理员的凭据。
|
||||
已有应用的秘密来源以各自 README 和配置为准，不能假定所有历史凭据已统一迁移到同一种流程。
|
||||
使用 [OpenBao](openbao.md) 与 ESO 的应用，应消费受管秘密，不能直接修改 ESO 生成的副本。
|
||||
连接 TLS 的要求及 CA 材料也应作为接入参数交付，不通过关闭校验解决连接问题。
|
||||
|
||||
## 第一次连接：确认目标数据库与身份
|
||||
|
||||
在已能访问集群内 Service、已安装 `psql` 的受控终端操作。
|
||||
将下例占位符替换为已分配的 database 和应用 role；密码通过终端提示输入，不写入命令行或 wiki。
|
||||
连接参数中的 TLS 配置沿用维护者交付的配置。
|
||||
|
||||
```bash
|
||||
psql -X -W -v ON_ERROR_STOP=1 \
|
||||
-h shared-postgresql-rw.shared-db.svc.cluster.local -p 5432 \
|
||||
-U YOUR_APP_ROLE -d YOUR_APP_DATABASE \
|
||||
-c 'SELECT current_database(), current_user, 1 AS connection_ok;'
|
||||
```
|
||||
|
||||
预期返回自己的数据库名、登录角色及 `connection_ok = 1`。
|
||||
该示例不修改业务数据，也不证明建表、迁移或其他权限已经满足。
|
||||
`-X` 避免加载本地 psql 启动脚本，`-W` 请求密码提示，`ON_ERROR_STOP` 使命令遇错退出。
|
||||
语法见 [PostgreSQL psql 文档](https://www.postgresql.org/docs/current/app-psql.html)。
|
||||
AI 接续任务时先确认操作范围，再执行现场查询；不能因为存在这段示例就自动登录数据库。
|
||||
|
||||
## 共享实例的维护边界
|
||||
|
||||
- 应用 schema migration 只面向自己的数据库，按应用升级流程执行；需要额外扩展或权限时先交由维护者处理。
|
||||
- 连接池、慢查询和批量任务会影响共享资源，新增消费者时应说明负载预期。
|
||||
- 数据库停用、role 删除和数据清理是独立操作，不能因应用 manifest 删除就推断数据库可一并删除。
|
||||
- 配置文件记录 `instances: 1`，使用 CNPG 本身不代表已经配置数据库多副本高可用。
|
||||
|
||||
存储配置为 OpenEBS 的 `localpv-zfs-ceph`。持久卷存在不等于已有独立备份或完成恢复验收，
|
||||
本页不对当前备份情况作未经验证的结论。
|
||||
历史迁移文档中的 dump/restore 与回滚步骤属于迁移场景，不能整段重跑作为日常接入流程。
|
||||
其中出现的旧服务名也不代表这些服务仍在运行。
|
||||
|
||||
## 遇到问题先看哪里
|
||||
|
||||
- 域名不解析或连接超时：先确认客户端位于何处、使用的入口及网络访问范围。
|
||||
- 认证失败：核对 role、database 和应用自己的凭据来源；不要改用 `postgres` 绕过问题。
|
||||
- 登录成功但操作被拒绝：区分数据库连接、schema、表和扩展权限，向维护者提供失败动作，不发送密码。
|
||||
- 多个消费者同时异常：转到共享数据库和存储的运维入口，避免在各应用中分别覆盖连接配置。
|
||||
|
||||
源码入口为 homelab-infra 的 `apps/shared-postgresql/migration.md`、
|
||||
`cloudnativepg-cluster.yaml` 和 `shared-postgresql-service.yaml`（后两者位于同一目录）。
|
||||
服务依赖 Kubernetes、CNPG、集群 DNS 与持久存储；Tailscale 入口另依赖对应网络及授权。
|
||||
Reference in New Issue
Block a user