> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akria.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 测试环境 | Test Environment

> 开发环境使用手册 - 从零开始到部署第一个服务

# 🧪 测试环境使用手册 | Test Environment Guide

欢迎使用 Project Team 的 Kubernetes 测试环境！本手册将指导您从零开始，完成环境配置、权限设置和第一个服务的部署。

<Info>
  本环境采用多租户隔离设计，每个开发人员拥有独立的命名空间（如 `dev-1`），确保环境安全和资源隔离。
</Info>

## 📋 目录 | Table of Contents

<AccordionGroup>
  <Accordion title="权限与隔离" icon="shield">
    了解您的操作权限和限制
  </Accordion>

  <Accordion title="环境准备" icon="gear">
    本地环境配置和集群连接
  </Accordion>

  <Accordion title="快速开始" icon="rocket">
    部署第一个服务
  </Accordion>

  <Accordion title="服务访问" icon="network-wired">
    配置域名和网络访问
  </Accordion>

  <Accordion title="资源管理" icon="gauge">
    查看配额和使用情况
  </Accordion>

  <Accordion title="故障排查" icon="wrench">
    常见问题和解决方案
  </Accordion>
</AccordionGroup>

## 🔐 权限与隔离 | Permission & Isolation

### 我能做什么？

作为测试环境的使用者，您拥有以下权限：

<CardGroup cols={2}>
  <Card title="资源管理" icon="cubes">
    在您的命名空间内创建、修改和删除任何资源（Pod、Service、ConfigMap、PVC 等）
  </Card>

  <Card title="服务暴露" icon="globe">
    通过 Nginx Proxy Manager (NPM) 暴露您的服务
  </Card>

  <Card title="日志查看" icon="file-lines">
    查看和管理您命名空间内的所有日志
  </Card>

  <Card title="配置管理" icon="file-code">
    创建和管理 ConfigMap、Secret 等配置资源
  </Card>
</CardGroup>

### 我不能做什么？

<Warning>
  为了确保集群安全和环境隔离，以下操作被严格禁止：
</Warning>

* **跨环境访问**：无法查看或操作其他开发环境（如 `dev-2`、`dev-3`）或生产环境的任何资源
* **集群管理**：无法操作 Node、Namespace 或集群级别的身份配置（RBAC）
* **绕过网关**：严禁通过 NodePort 等其他方式绕过 NPM 暴露服务

### 常见问题 | FAQ

<AccordionGroup>
  <Accordion title="Q: 我能使用生产环境的数据库吗？" icon="question">
    **A: 不可以。** 出于安全和数据隔离的考虑，开发环境无法连接生产数据库。您需要在自己的命名空间内部署一个独立的测试数据库。
  </Accordion>

  <Accordion title="Q: 我的数据会丢失吗？" icon="question">
    **A: 只要正确配置了 PVC (PersistentVolumeClaim)**，即使 Pod 重启或删除，您的数据库数据也会保留在持久卷中。
  </Accordion>

  <Accordion title="Q: 如何申请更多资源？" icon="question">
    **A: 请联系管理员。** 管理员可以通过修改配额文件在线扩容，无需重启服务。
  </Accordion>
</AccordionGroup>

## 🛠️ 环境准备 | Environment Setup

### 步骤 1: 获取配置文件

从管理员处获取您的 `dev-x-kubeconfig.yaml` 文件。

<Danger>
  **安全警告**：配置文件包含敏感的登录 Token，**绝对禁止**将其上传至 GitHub、GitLab 等任何公开代码管理平台。
</Danger>

### 步骤 2: 安装 kubectl

<CodeGroup>
  ```bash macOS (使用 Homebrew) theme={null}
  # 如果已安装 Homebrew
  brew install kubectl

  # 如果未安装 Homebrew，先安装 Homebrew：
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  # 然后安装 kubectl
  brew install kubectl
  ```

  ```bash macOS (不使用 Homebrew) theme={null}
  # 直接下载二进制文件
  curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"

  # 添加执行权限
  chmod +x ./kubectl

  # 移动到 PATH 目录
  sudo mv ./kubectl /usr/local/bin/kubectl

  # 验证安装
  kubectl version --client
  ```

  ```bash Ubuntu/Debian theme={null}
  sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates curl
  curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
  echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
  sudo apt-get update && sudo apt-get install -y kubectl
  ```

  ```powershell Windows theme={null}
  curl.exe -LO "https://dl.k8s.io/release/v1.28.0/bin/windows/amd64/kubectl.exe"
  ```
</CodeGroup>

<Tip>
  **macOS 用户**：如果系统提示未找到 `brew` 命令，可以选择安装 Homebrew 或直接下载 kubectl 二进制文件。Homebrew 是 macOS 上常用的包管理器，推荐安装。
</Tip>

### 步骤 3: 配置集群连接

<Steps>
  <Step title="准备配置目录">
    ```bash theme={null}
    mkdir -p ~/.kube
    ```
  </Step>

  <Step title="复制配置文件">
    ```bash theme={null}
    cp ~/Downloads/dev-1-kubeconfig.yaml ~/.kube/dev-1-config
    ```
  </Step>

  <Step title="设置环境变量">
    根据您的 Shell 类型选择：

    **Zsh (macOS/Linux 默认)**:

    ```bash theme={null}
    echo 'export KUBECONFIG=~/.kube/dev-1-config' >> ~/.zshrc
    source ~/.zshrc
    ```

    **Bash (典型 Linux)**:

    ```bash theme={null}
    echo 'export KUBECONFIG=~/.kube/dev-1-config' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Step>

  <Step title="验证连接">
    ```bash theme={null}
    kubectl get ns dev-1
    ```

    如果看到命名空间信息，说明连接成功！
  </Step>
</Steps>

<Tip>
  如果看到 `The connection to the server localhost:8080 was refused` 错误，说明 `KUBECONFIG` 环境变量未生效，请检查 Shell 配置文件。
</Tip>

## 🚀 快速开始 | Quick Start

### 部署第一个服务：Nginx

<Steps>
  <Step title="创建部署文件">
    创建 `nginx-deployment.yaml`，包含两个资源：

    <CodeGroup>
      ```yaml Deployment theme={null}
      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"
      ```

      ```yaml Service theme={null}
      apiVersion: v1
      kind: Service
      metadata:
        name: my-nginx-svc
        namespace: dev-1
      spec:
        selector:
          app: my-nginx
        ports:
        - protocol: TCP
          port: 80
          targetPort: 80
        type: ClusterIP
      ```
    </CodeGroup>

    **注意**：在实际部署时，这两个资源可以放在同一个文件中，使用 `---` 分隔。
  </Step>

  <Step title="应用配置">
    ```bash theme={null}
    kubectl apply -f nginx-deployment.yaml
    ```
  </Step>

  <Step title="查看状态">
    ```bash theme={null}
    # 查看 Pod 状态
    kubectl get pods -n dev-1

    # 查看 Service
    kubectl get svc -n dev-1
    ```

    等待 Pod 状态变为 `Running`。
  </Step>
</Steps>

### 部署测试数据库：PostgreSQL

<Accordion title="查看 PostgreSQL 部署示例" icon="database">
  创建 `postgres-deployment.yaml`，包含三个资源：

  <CodeGroup>
    ```yaml PersistentVolumeClaim theme={null}
    apiVersion: v1
    kind: PersistentVolumeClaim
    metadata:
      name: pg-data-pvc
      namespace: dev-1
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 1Gi
    ```

    ```yaml Deployment theme={null}
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-db
      namespace: dev-1
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: my-db
      template:
        metadata:
          labels:
            app: my-db
        spec:
          containers:
          - name: postgres
            image: postgres:15-alpine
            env:
            - name: POSTGRES_PASSWORD
              value: "devpassword"
            ports:
            - containerPort: 5432
            volumeMounts:
            - name: pg-storage
              mountPath: /var/lib/postgresql/data
            resources:
              requests:
                cpu: "200m"
                memory: "256Mi"
              limits:
                cpu: "1000m"
                memory: "1Gi"
          volumes:
          - name: pg-storage
            persistentVolumeClaim:
              claimName: pg-data-pvc
    ```

    ```yaml Service theme={null}
    apiVersion: v1
    kind: Service
    metadata:
      name: my-db-svc
      namespace: dev-1
    spec:
      selector:
        app: my-db
      ports:
      - protocol: TCP
        port: 5432
        targetPort: 5432
      type: ClusterIP
    ```
  </CodeGroup>

  **注意**：在实际部署时，这三个资源可以放在同一个文件中，使用 `---` 分隔。应用配置：

  ```bash theme={null}
  kubectl apply -f postgres-deployment.yaml
  ```
</Accordion>

## 🌐 服务访问 | Service Access

### 统一入口规范

<Warning>
  **重要**：本集群使用 Nginx Proxy Manager (NPM) 作为**唯一统一入口**。为了保证安全和流量追踪，严禁通过 NodePort 等其他方式绕过 NPM 暴露服务。
</Warning>

### 配置域名访问

<Steps>
  <Step title="获取服务名称">
    ```bash theme={null}
    kubectl get svc -n dev-1
    ```

    记录 `NAME` 列的值，例如：`my-nginx-svc`
  </Step>

  <Step title="构建内部域名">
    遵循 K8s 内部 DNS 命名规范：

    ```
    [服务名称].[命名空间].svc.cluster.local
    ```

    例如：`my-nginx-svc.dev-1.svc.cluster.local`
  </Step>

  <Step title="联系管理员配置 NPM">
    在 [NPM 管理后台](https://kuber.akria.net/) 添加 Proxy Host：

    * **Domain Name**: `myapp.dev.changuoo.com`
    * **Forward Host**: `my-nginx-svc.dev-1.svc.cluster.local`
    * **Forward Port**: `80`
  </Step>

  <Step title="验证访问">
    等待管理员配置完成后，通过浏览器访问配置的域名。
  </Step>
</Steps>

## 📊 资源管理 | Resource Management

### 查看配额和使用情况

```bash theme={null}
# 查看当前环境的资源配额
kubectl describe quota dev-quota -n dev-1
```

### 默认配额限制

| 资源类型       | 限制               |
| ---------- | ---------------- |
| **CPU**    | 4 Core (Limit)   |
| **内存**     | 8Gi (Limit)      |
| **存储**     | 20Gi (所有 PVC 总和) |
| **Pod 数量** | 最多 20 个 Pod      |

### 默认资源限制

如果您在 YAML 中未指定资源限制，系统会自动为每个容器分配：

* **CPU**: 100m
* **内存**: 256Mi

<Tip>
  建议在部署时显式指定资源请求和限制，以便更好地管理资源使用。
</Tip>

## 🔧 常用命令 | Common Commands

### 查看资源

<CodeGroup>
  ```bash 查看 Pod theme={null}
  kubectl get pods -n dev-1
  ```

  ```bash 查看 Service theme={null}
  kubectl get svc -n dev-1
  ```

  ```bash 查看所有资源 theme={null}
  kubectl get all -n dev-1
  ```

  ```bash 查看资源详情 theme={null}
  kubectl describe pod <pod-name> -n dev-1
  ```
</CodeGroup>

### 日志管理

<CodeGroup>
  ```bash 实时查看日志 theme={null}
  kubectl logs -f <pod-name> -n dev-1
  ```

  ```bash 查看最后 20 条日志 theme={null}
  kubectl logs --tail=20 <pod-name> -n dev-1
  ```

  ```bash 查看指定容器的日志 theme={null}
  kubectl logs <pod-name> -c <container-name> -n dev-1
  ```
</CodeGroup>

### 调试命令

<CodeGroup>
  ```bash 进入容器 theme={null}
  kubectl exec -it <pod-name> -n dev-1 -- /bin/sh
  ```

  ```bash 查看事件 theme={null}
  kubectl get events -n dev-1 --sort-by='.lastTimestamp'
  ```

  ```bash 删除资源 theme={null}
  kubectl delete -f <yaml-file>
  ```
</CodeGroup>

## 🐛 故障排查 | Troubleshooting

### 排错三步法

<Steps>
  <Step title="第一步：看状态">
    ```bash theme={null}
    kubectl get pods -n dev-1
    ```

    检查 `STATUS` 是否为 `Running`。如果是 `Pending` 或 `CrashLoopBackOff`，进行下一步。
  </Step>

  <Step title="第二步：查详情">
    ```bash theme={null}
    kubectl describe pod <pod-name> -n dev-1
    ```

    滚动到最下方查看 `Events`，通常可以获取存储挂载失败、镜像拉取失败等核心线索。
  </Step>

  <Step title="第三步：看日志">
    ```bash theme={null}
    kubectl logs -f <pod-name> -n dev-1
    ```

    如果是应用内部报错（如数据库连接失败），这里会有最直观的输出。
  </Step>
</Steps>

### 常见问题

<AccordionGroup>
  <Accordion title="Pod 一直处于 Pending 状态" icon="exclamation-triangle">
    **可能原因**：

    * 资源配额已满
    * 节点资源不足

    **解决方法**：

    ```bash theme={null}
    # 查看配额使用情况
    kubectl describe quota dev-quota -n dev-1

    # 查看 Pod 详情
    kubectl describe pod <pod-name> -n dev-1
    ```
  </Accordion>

  <Accordion title="Pod 不断重启 (CrashLoopBackOff)" icon="exclamation-triangle">
    **可能原因**：

    * 应用配置错误
    * 依赖服务未启动
    * 资源限制过小

    **解决方法**：

    ```bash theme={null}
    # 查看日志
    kubectl logs <pod-name> -n dev-1

    # 查看事件
    kubectl describe pod <pod-name> -n dev-1
    ```
  </Accordion>

  <Accordion title="无法访问服务" icon="exclamation-triangle">
    **可能原因**：

    * Service 未正确配置
    * NPM 未配置代理
    * 域名解析问题

    **解决方法**：

    ```bash theme={null}
    # 检查 Service
    kubectl get svc -n dev-1

    # 检查 Pod 是否运行
    kubectl get pods -n dev-1

    # 联系管理员检查 NPM 配置
    ```
  </Accordion>
</AccordionGroup>

## 📚 相关文档 | Related Documentation

<CardGroup cols={2}>
  <Card title="基础设施概览" icon="server" href="/technical/infra-deploy/infrastructure-overview">
    了解集群架构和服务访问方式
  </Card>

  <Card title="YAML 规范" icon="file-code" href="/technical/infra-deploy/yaml-best-practices">
    学习配置文件的标准格式
  </Card>

  <Card title="部署指南" icon="rocket" href="/technical/infra-deploy/deployment-guide">
    生产环境部署操作指南
  </Card>

  <Card title="管理测试环境" icon="user-shield" href="/technical/infra-deploy/admin-test-environment">
    管理员操作手册
  </Card>
</CardGroup>

<Note>
  遇到问题？查看我们的 [开发指南](/guides/website-overview/development) 或通过 GitHub Issues 联系团队。
</Note>