430 lines
9.7 KiB
Markdown
430 lines
9.7 KiB
Markdown
# PostgreSQL 16 K3s 部署指南
|
||
|
||
本目录包含在 K3s 集群中部署 PostgreSQL 16 数据库的完整配置文件。
|
||
|
||
## 📋 目录结构
|
||
|
||
```
|
||
001-pg16/
|
||
├── README.md # 本文件 - 部署说明
|
||
└── k8s/ # K8s 配置文件目录
|
||
├── namespace.yaml # infrastructure 命名空间
|
||
├── secret.yaml # 数据库密码
|
||
├── configmap.yaml # 初始化脚本
|
||
├── pvc.yaml # 持久化存储卷声明
|
||
├── deployment.yaml # PostgreSQL 部署配置
|
||
├── service.yaml # 服务配置
|
||
└── README.md # K8s 配置详细说明
|
||
```
|
||
|
||
## 🚀 快速部署
|
||
|
||
### 前置条件
|
||
|
||
1. **已安装 K3s**
|
||
```bash
|
||
# 检查 K3s 是否运行
|
||
sudo systemctl status k3s
|
||
|
||
# 检查节点状态
|
||
sudo kubectl get nodes
|
||
```
|
||
|
||
2. **配置 kubectl 权限**（可选，避免每次使用 sudo）
|
||
```bash
|
||
# 方法1：复制配置到用户目录（推荐）
|
||
mkdir -p ~/.kube
|
||
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
|
||
sudo chown $USER:$USER ~/.kube/config
|
||
chmod 600 ~/.kube/config
|
||
|
||
# 验证配置
|
||
kubectl get nodes
|
||
```
|
||
|
||
### 一键部署
|
||
|
||
```bash
|
||
# 进入配置目录
|
||
cd /path/to/001-pg16/k8s
|
||
|
||
# 部署所有资源
|
||
kubectl apply -f .
|
||
|
||
# 或者使用 sudo（如果未配置 kubectl 权限）
|
||
sudo kubectl apply -f .
|
||
```
|
||
|
||
### 查看部署状态
|
||
|
||
```bash
|
||
# 查看 Pod 状态
|
||
kubectl get pods -n infrastructure
|
||
|
||
# 查看 Pod 详细信息
|
||
kubectl describe pod -n infrastructure -l app=pg16
|
||
|
||
# 查看初始化日志（实时）
|
||
kubectl logs -n infrastructure -l app=pg16 -f
|
||
|
||
# 查看服务状态
|
||
kubectl get svc -n infrastructure
|
||
|
||
# 查看 PVC 状态
|
||
kubectl get pvc -n infrastructure
|
||
```
|
||
|
||
## ✅ 验证部署
|
||
|
||
### 1. 检查 Pod 是否运行
|
||
|
||
```bash
|
||
kubectl get pods -n infrastructure
|
||
```
|
||
|
||
期望输出：
|
||
```
|
||
NAME READY STATUS RESTARTS AGE
|
||
pg16-xxxxxxxxx-xxxxx 1/1 Running 0 2m
|
||
```
|
||
|
||
### 2. 验证数据库创建
|
||
|
||
```bash
|
||
# 统计数据库总数（应该是 303 个）
|
||
kubectl exec -n infrastructure -l app=pg16 -- psql -U postgres -c "SELECT count(*) FROM pg_database;"
|
||
|
||
# 查看前 10 个数据库
|
||
kubectl exec -n infrastructure -l app=pg16 -- psql -U postgres -c "SELECT datname FROM pg_database WHERE datname LIKE 'pg0%' ORDER BY datname LIMIT 10;"
|
||
|
||
# 查看最后 10 个数据库
|
||
kubectl exec -n infrastructure -l app=pg16 -- psql -U postgres -c "SELECT datname FROM pg_database WHERE datname LIKE 'pg2%' ORDER BY datname DESC LIMIT 10;"
|
||
```
|
||
|
||
期望结果：
|
||
- 总数据库数：303 个（300 个业务数据库 + postgres + template0 + template1）
|
||
- 数据库命名：pg001, pg002, ..., pg300
|
||
- 数据库所有者：fei
|
||
|
||
### 3. 测试数据库连接
|
||
|
||
```bash
|
||
# 方法1：直接在 Pod 内执行 SQL
|
||
kubectl exec -n infrastructure -l app=pg16 -- psql -U fei -d pg001 -c "SELECT current_database(), version();"
|
||
|
||
# 方法2：进入 Pod 交互式操作
|
||
kubectl exec -it -n infrastructure -l app=pg16 -- bash
|
||
# 在 Pod 内执行
|
||
psql -U fei -d pg001
|
||
# 退出
|
||
\q
|
||
exit
|
||
```
|
||
|
||
## 🔌 连接数据库
|
||
|
||
### 集群内部连接
|
||
|
||
从集群内其他 Pod 连接：
|
||
|
||
```
|
||
主机: pg16.infrastructure.svc.cluster.local
|
||
端口: 5432
|
||
用户: fei
|
||
密码: feiks..
|
||
数据库: pg001 ~ pg300
|
||
```
|
||
|
||
连接字符串示例：
|
||
```
|
||
postgresql://fei:feiks..@pg16.infrastructure.svc.cluster.local:5432/pg001
|
||
```
|
||
|
||
### 集群外部连接
|
||
|
||
#### 方法1：使用 NodePort（推荐）
|
||
|
||
```bash
|
||
# 获取节点 IP
|
||
kubectl get nodes -o wide
|
||
|
||
# 使用 NodePort 连接
|
||
psql -h <节点IP> -U fei -d pg001 -p 30432
|
||
```
|
||
|
||
连接信息：
|
||
- 主机：节点 IP 地址
|
||
- 端口：30432
|
||
- 用户：fei
|
||
- 密码：feiks..
|
||
|
||
#### 方法2：使用 Port Forward
|
||
|
||
```bash
|
||
# 转发端口到本地
|
||
kubectl port-forward -n infrastructure svc/pg16 5432:5432
|
||
|
||
# 在另一个终端连接
|
||
psql -h localhost -U fei -d pg001 -p 5432
|
||
```
|
||
|
||
## 📊 数据库信息
|
||
|
||
### 默认配置
|
||
|
||
- **PostgreSQL 版本**: 16
|
||
- **命名空间**: infrastructure
|
||
- **数据库数量**: 300 个（pg001 ~ pg300）
|
||
- **超级用户**: fei（密码：feiks..）
|
||
- **系统用户**: postgres（密码：adminks..）
|
||
- **持久化存储**: 20Gi（使用 K3s 默认 local-path StorageClass）
|
||
|
||
### 资源配置
|
||
|
||
- **CPU 请求**: 500m
|
||
- **CPU 限制**: 2000m
|
||
- **内存请求**: 512Mi
|
||
- **内存限制**: 2Gi
|
||
|
||
### 服务端口
|
||
|
||
- **ClusterIP 服务**: pg16（端口 5432）
|
||
- **NodePort 服务**: pg16-nodeport（端口 30432）
|
||
|
||
## 🔧 常用操作
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
# 查看最近 50 行日志
|
||
kubectl logs -n infrastructure -l app=pg16 --tail=50
|
||
|
||
# 实时查看日志
|
||
kubectl logs -n infrastructure -l app=pg16 -f
|
||
|
||
# 查看上一次容器的日志（如果 Pod 重启过）
|
||
kubectl logs -n infrastructure -l app=pg16 --previous
|
||
```
|
||
|
||
### 进入容器
|
||
|
||
```bash
|
||
# 进入 PostgreSQL 容器
|
||
kubectl exec -it -n infrastructure -l app=pg16 -- bash
|
||
|
||
# 直接进入 psql
|
||
kubectl exec -it -n infrastructure -l app=pg16 -- psql -U postgres
|
||
```
|
||
|
||
### 重启 Pod
|
||
|
||
```bash
|
||
# 删除 Pod（Deployment 会自动重建）
|
||
kubectl delete pod -n infrastructure -l app=pg16
|
||
|
||
# 或者重启 Deployment
|
||
kubectl rollout restart deployment pg16 -n infrastructure
|
||
```
|
||
|
||
### 扩缩容（不推荐用于数据库）
|
||
|
||
```bash
|
||
# 查看当前副本数
|
||
kubectl get deployment pg16 -n infrastructure
|
||
|
||
# 注意：PostgreSQL 不支持多副本，保持 replicas=1
|
||
```
|
||
|
||
## 🗑️ 卸载
|
||
|
||
### 删除部署（保留数据）
|
||
|
||
```bash
|
||
# 删除 Deployment 和 Service
|
||
kubectl delete deployment pg16 -n infrastructure
|
||
kubectl delete svc pg16 pg16-nodeport -n infrastructure
|
||
|
||
# PVC 和数据会保留
|
||
```
|
||
|
||
### 完全卸载（包括数据）
|
||
|
||
```bash
|
||
# 删除所有资源
|
||
kubectl delete -f k8s/
|
||
|
||
# 或者逐个删除
|
||
kubectl delete deployment pg16 -n infrastructure
|
||
kubectl delete svc pg16 pg16-nodeport -n infrastructure
|
||
kubectl delete pvc pg16-data -n infrastructure
|
||
kubectl delete configmap pg16-init-script -n infrastructure
|
||
kubectl delete secret pg16-secret -n infrastructure
|
||
kubectl delete namespace infrastructure
|
||
```
|
||
|
||
**⚠️ 警告**: 删除 PVC 会永久删除所有数据库数据，无法恢复！
|
||
|
||
## 🔐 安全建议
|
||
|
||
### 修改默认密码
|
||
|
||
部署后建议立即修改默认密码：
|
||
|
||
```bash
|
||
# 进入 Pod
|
||
kubectl exec -it -n infrastructure -l app=pg16 -- psql -U postgres
|
||
|
||
# 修改 fei 用户密码
|
||
ALTER USER fei WITH PASSWORD '新密码';
|
||
|
||
# 修改 postgres 用户密码
|
||
ALTER USER postgres WITH PASSWORD '新密码';
|
||
|
||
# 退出
|
||
\q
|
||
```
|
||
|
||
然后更新 Secret：
|
||
|
||
```bash
|
||
# 编辑 secret.yaml，修改密码（需要 base64 编码）
|
||
echo -n "新密码" | base64
|
||
|
||
# 更新 Secret
|
||
kubectl apply -f k8s/secret.yaml
|
||
```
|
||
|
||
### 网络安全
|
||
|
||
- 默认配置使用 NodePort 30432 暴露服务
|
||
- 生产环境建议：
|
||
- 使用防火墙限制访问 IP
|
||
- 或者删除 NodePort 服务，仅使用集群内部访问
|
||
- 配置 NetworkPolicy 限制访问
|
||
|
||
```bash
|
||
# 删除 NodePort 服务（仅保留集群内访问）
|
||
kubectl delete svc pg16-nodeport -n infrastructure
|
||
```
|
||
|
||
## 🐛 故障排查
|
||
|
||
### Pod 无法启动
|
||
|
||
```bash
|
||
# 查看 Pod 状态
|
||
kubectl describe pod -n infrastructure -l app=pg16
|
||
|
||
# 查看事件
|
||
kubectl get events -n infrastructure --sort-by='.lastTimestamp'
|
||
|
||
# 查看日志
|
||
kubectl logs -n infrastructure -l app=pg16
|
||
```
|
||
|
||
常见问题：
|
||
- **ImagePullBackOff**: 无法拉取镜像，检查网络连接
|
||
- **CrashLoopBackOff**: 容器启动失败，查看日志
|
||
- **Pending**: PVC 无法绑定，检查存储类
|
||
|
||
### PVC 无法绑定
|
||
|
||
```bash
|
||
# 查看 PVC 状态
|
||
kubectl describe pvc pg16-data -n infrastructure
|
||
|
||
# 查看 StorageClass
|
||
kubectl get storageclass
|
||
|
||
# 检查 local-path-provisioner
|
||
kubectl get pods -n kube-system | grep local-path
|
||
```
|
||
|
||
### 数据库连接失败
|
||
|
||
```bash
|
||
# 检查服务是否正常
|
||
kubectl get svc -n infrastructure
|
||
|
||
# 检查 Pod 是否就绪
|
||
kubectl get pods -n infrastructure
|
||
|
||
# 测试集群内连接
|
||
kubectl run -it --rm debug --image=postgres:16 --restart=Never -- psql -h pg16.infrastructure.svc.cluster.local -U fei -d pg001
|
||
```
|
||
|
||
### 初始化脚本未执行
|
||
|
||
如果发现数据库未创建 300 个数据库：
|
||
|
||
```bash
|
||
# 查看初始化日志
|
||
kubectl logs -n infrastructure -l app=pg16 | grep -i "init\|create database"
|
||
|
||
# 检查 ConfigMap 是否正确挂载
|
||
kubectl exec -n infrastructure -l app=pg16 -- ls -la /docker-entrypoint-initdb.d/
|
||
|
||
# 查看脚本内容
|
||
kubectl exec -n infrastructure -l app=pg16 -- cat /docker-entrypoint-initdb.d/01-init.sh
|
||
```
|
||
|
||
**注意**: PostgreSQL 初始化脚本只在首次启动且数据目录为空时执行。如果需要重新初始化：
|
||
|
||
```bash
|
||
# 删除 Deployment 和 PVC
|
||
kubectl delete deployment pg16 -n infrastructure
|
||
kubectl delete pvc pg16-data -n infrastructure
|
||
|
||
# 重新部署
|
||
kubectl apply -f k8s/
|
||
```
|
||
|
||
## 📝 备份与恢复
|
||
|
||
### 备份单个数据库
|
||
|
||
```bash
|
||
# 备份 pg001 数据库
|
||
kubectl exec -n infrastructure -l app=pg16 -- pg_dump -U fei pg001 > pg001_backup.sql
|
||
|
||
# 备份所有数据库
|
||
kubectl exec -n infrastructure -l app=pg16 -- pg_dumpall -U postgres > all_databases_backup.sql
|
||
```
|
||
|
||
### 恢复数据库
|
||
|
||
```bash
|
||
# 恢复单个数据库
|
||
cat pg001_backup.sql | kubectl exec -i -n infrastructure -l app=pg16 -- psql -U fei pg001
|
||
|
||
# 恢复所有数据库
|
||
cat all_databases_backup.sql | kubectl exec -i -n infrastructure -l app=pg16 -- psql -U postgres
|
||
```
|
||
|
||
### 数据持久化
|
||
|
||
数据存储在 K3s 的 local-path 存储中，默认路径：
|
||
```
|
||
/var/lib/rancher/k3s/storage/pvc-<uuid>_infrastructure_pg16-data/
|
||
```
|
||
|
||
## 📚 更多信息
|
||
|
||
- PostgreSQL 官方文档: https://www.postgresql.org/docs/16/
|
||
- K3s 官方文档: https://docs.k3s.io/
|
||
- Kubernetes 官方文档: https://kubernetes.io/docs/
|
||
|
||
## 🆘 获取帮助
|
||
|
||
如有问题，请检查：
|
||
1. Pod 日志: `kubectl logs -n infrastructure -l app=pg16`
|
||
2. Pod 状态: `kubectl describe pod -n infrastructure -l app=pg16`
|
||
3. 事件记录: `kubectl get events -n infrastructure`
|
||
|
||
---
|
||
|
||
**版本信息**
|
||
- PostgreSQL: 16
|
||
- 创建日期: 2026-01-29
|
||
- 最后更新: 2026-01-29
|