# 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