首次提交：初始化项目

2026-02-05 00:11:05 +08:00
commit 26eaf8110b
171 changed files with 17105 additions and 0 deletions
--- a/009-基础设施/001-pg16/README.md
+++ b/009-基础设施/001-pg16/README.md
@@ -0,0 +1,429 @@
+# 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