🧪 测试环境使用手册 | Test Environment Guide
欢迎使用 Project Team 的 Kubernetes 测试环境！本手册将指导您从零开始，完成环境配置、权限设置和第一个服务的部署。
本环境采用多租户隔离设计，每个开发人员拥有独立的命名空间（如 dev-1），确保环境安全和资源隔离。
📋 目录 | Table of Contents
了解您的操作权限和限制
本地环境配置和集群连接
部署第一个服务
配置域名和网络访问
查看配额和使用情况
常见问题和解决方案
🔐 权限与隔离 | Permission & Isolation
我能做什么？
作为测试环境的使用者，您拥有以下权限：
资源管理
在您的命名空间内创建、修改和删除任何资源（Pod、Service、ConfigMap、PVC 等）
服务暴露
通过 Nginx Proxy Manager (NPM) 暴露您的服务
配置管理
创建和管理 ConfigMap、Secret 等配置资源
我不能做什么？
- 跨环境访问：无法查看或操作其他开发环境（如
dev-2、dev-3）或生产环境的任何资源
- 集群管理：无法操作 Node、Namespace 或集群级别的身份配置（RBAC）
- 绕过网关：严禁通过 NodePort 等其他方式绕过 NPM 暴露服务
常见问题 | FAQ
A: 不可以。 出于安全和数据隔离的考虑，开发环境无法连接生产数据库。您需要在自己的命名空间内部署一个独立的测试数据库。
A: 只要正确配置了 PVC (PersistentVolumeClaim)，即使 Pod 重启或删除，您的数据库数据也会保留在持久卷中。
A: 请联系管理员。 管理员可以通过修改配额文件在线扩容，无需重启服务。
🛠️ 环境准备 | Environment Setup
步骤 1: 获取配置文件
从管理员处获取您的 dev-x-kubeconfig.yaml 文件。
安全警告：配置文件包含敏感的登录 Token，绝对禁止将其上传至 GitHub、GitLab 等任何公开代码管理平台。
步骤 2: 安装 kubectl
# 如果已安装 Homebrew
brew install kubectl
# 如果未安装 Homebrew，先安装 Homebrew：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 然后安装 kubectl
brew install kubectl
macOS 用户：如果系统提示未找到 brew 命令，可以选择安装 Homebrew 或直接下载 kubectl 二进制文件。Homebrew 是 macOS 上常用的包管理器，推荐安装。
步骤 3: 配置集群连接
复制配置文件
cp ~/Downloads/dev-1-kubeconfig.yaml ~/.kube/dev-1-config
设置环境变量
根据您的 Shell 类型选择：Zsh (macOS/Linux 默认):echo 'export KUBECONFIG=~/.kube/dev-1-config' >> ~/.zshrc
source ~/.zshrc
echo 'export KUBECONFIG=~/.kube/dev-1-config' >> ~/.bashrc
source ~/.bashrc
如果看到 The connection to the server localhost:8080 was refused 错误，说明 KUBECONFIG 环境变量未生效，请检查 Shell 配置文件。
🚀 快速开始 | Quick Start
部署第一个服务：Nginx
创建部署文件
创建 nginx-deployment.yaml，包含两个资源：apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
namespace: dev-1 # 必须指定您的命名空间
spec:
replicas: 1
selector:
matchLabels:
app: my-nginx
template:
metadata:
labels:
app: my-nginx
spec:
containers:
- name: nginx
image: nginx:alpine
ports:
- containerPort: 80
resources:
requests:
cpu: "100m"
memory: "128Mi"
limits:
cpu: "500m"
memory: "512Mi"
--- 分隔。 应用配置
kubectl apply -f nginx-deployment.yaml
查看状态
# 查看 Pod 状态
kubectl get pods -n dev-1
# 查看 Service
kubectl get svc -n dev-1
Running。部署测试数据库：PostgreSQL
创建 postgres-deployment.yaml，包含三个资源：apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: pg-data-pvc
namespace: dev-1
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
--- 分隔。应用配置：kubectl apply -f postgres-deployment.yaml
🌐 服务访问 | Service Access
统一入口规范
重要：本集群使用 Nginx Proxy Manager (NPM) 作为唯一统一入口。为了保证安全和流量追踪，严禁通过 NodePort 等其他方式绕过 NPM 暴露服务。
配置域名访问
获取服务名称
记录 NAME 列的值，例如：my-nginx-svc 构建内部域名
遵循 K8s 内部 DNS 命名规范：[服务名称].[命名空间].svc.cluster.local
my-nginx-svc.dev-1.svc.cluster.local 联系管理员配置 NPM
在 NPM 管理后台 添加 Proxy Host：
- Domain Name:
myapp.dev.changuoo.com
- Forward Host:
my-nginx-svc.dev-1.svc.cluster.local
- Forward Port:
80
验证访问
等待管理员配置完成后，通过浏览器访问配置的域名。
📊 资源管理 | Resource Management
查看配额和使用情况
# 查看当前环境的资源配额
kubectl describe quota dev-quota -n dev-1
默认配额限制
| 资源类型 | 限制 |
|---|
| CPU | 4 Core (Limit) |
| 内存 | 8Gi (Limit) |
| 存储 | 20Gi (所有 PVC 总和) |
| Pod 数量 | 最多 20 个 Pod |
默认资源限制
如果您在 YAML 中未指定资源限制，系统会自动为每个容器分配：
建议在部署时显式指定资源请求和限制，以便更好地管理资源使用。
🔧 常用命令 | Common Commands
查看资源
kubectl get pods -n dev-1
日志管理
kubectl logs -f <pod-name> -n dev-1
调试命令
kubectl exec -it <pod-name> -n dev-1 -- /bin/sh
🐛 故障排查 | Troubleshooting
排错三步法
第一步：看状态
kubectl get pods -n dev-1
STATUS 是否为 Running。如果是 Pending 或 CrashLoopBackOff，进行下一步。第二步：查详情
kubectl describe pod <pod-name> -n dev-1
Events，通常可以获取存储挂载失败、镜像拉取失败等核心线索。第三步：看日志
kubectl logs -f <pod-name> -n dev-1
常见问题
可能原因：解决方法：# 查看配额使用情况
kubectl describe quota dev-quota -n dev-1
# 查看 Pod 详情
kubectl describe pod <pod-name> -n dev-1
Pod 不断重启 (CrashLoopBackOff)
可能原因：解决方法：# 查看日志
kubectl logs <pod-name> -n dev-1
# 查看事件
kubectl describe pod <pod-name> -n dev-1
可能原因：
- Service 未正确配置
- NPM 未配置代理
- 域名解析问题
解决方法：# 检查 Service
kubectl get svc -n dev-1
# 检查 Pod 是否运行
kubectl get pods -n dev-1
# 联系管理员检查 NPM 配置
遇到问题？查看我们的 开发指南 或通过 GitHub Issues 联系团队。 
