mgmt/README.md.backup

# 🏗️ 基础设施管理项目

这是一个现代化的多云基础设施管理平台，专注于 OpenTofu、Ansible 和 Nomad + Podman 的集成管理。

## 📝 重要提醒 (Sticky Note)

### ✅ Consul集群状态更新

**当前状态**：Consul集群运行健康，所有节点正常运行

**集群信息**：
- **Leader**: warden (100.122.197.112:8300)
- **节点数量**: 3个服务器节点
- **健康状态**: 所有节点健康检查通过
- **节点列表**:
  - master (100.117.106.136) - 韩国主节点
  - ash3c (100.116.80.94) - 美国服务器节点
  - warden (100.122.197.112) - 北京服务器节点，当前集群leader

**配置状态**：
- Ansible inventory配置与实际集群状态一致
- 所有节点均为服务器模式
- bootstrap_expect=3，符合实际节点数量

**依赖关系**：
- Tailscale (第1天) ✅
- Ansible (第2天) ✅
- Nomad (第3天) ✅
- Consul (第4天) ✅ **已完成**
- Terraform (第5天) ✅ **进展良好**
- Vault (第6天) ⏳ 计划中
- Waypoint (第7天) ⏳ 计划中

**下一步计划**：
- 继续推进Terraform状态管理
- 准备Vault密钥管理集成
- 规划Waypoint应用部署流程

---

## 🎯 项目特性

- **🌩️ 多云支持**: Oracle Cloud, 华为云, Google Cloud, AWS, DigitalOcean
- **🏗️ 基础设施即代码**: 使用 OpenTofu 管理云资源
- **⚙️ 配置管理**: 使用 Ansible 自动化配置和部署
- **🐳 容器编排**: Nomad 集群管理和 Podman 容器运行时
- **🔄 CI/CD**: Gitea Actions 自动化流水线
- **📊 监控**: Prometheus + Grafana 监控体系
- **🔐 安全**: 多层安全防护和合规性

## 🔄 架构分层与职责划分

### ⚠️ 重要：Terraform 与 Nomad 的职责区分

本项目采用分层架构，明确区分了不同工具的职责范围，避免混淆：

#### 1. **Terraform/OpenTofu 层面 - 基础设施生命周期管理**
- **职责**: 管理云服务商提供的计算资源（虚拟机）的生命周期
- **操作范围**: 
  - 创建、更新、删除虚拟机实例
  - 管理网络资源（VCN、子网、安全组等）
  - 管理存储资源（块存储、对象存储等）
  - 管理负载均衡器等云服务
- **目标**: 确保底层基础设施的正确配置和状态管理

#### 2. **Nomad 层面 - 应用资源调度与编排**
- **职责**: 在已经运行起来的虚拟机内部进行资源分配和应用编排
- **操作范围**:
  - 在现有虚拟机上调度和运行容器化应用
  - 管理应用的生命周期（启动、停止、更新）
  - 资源分配和限制（CPU、内存、存储）
  - 服务发现和负载均衡
- **目标**: 在已有基础设施上高效运行应用服务

#### 3. **关键区别**
- **Terraform** 关注的是**虚拟机本身**的生命周期管理
- **Nomad** 关注的是**在虚拟机内部**运行的应用的资源调度
- **Terraform** 决定"有哪些虚拟机"
- **Nomad** 决定"虚拟机上运行什么应用"

#### 4. **工作流程示例**
```
1. Terraform 创建虚拟机 (云服务商层面)
   ↓
2. 虚拟机启动并运行操作系统
   ↓
3. 在虚拟机上安装和配置 Nomad 客户端
   ↓
4. Nomad 在虚拟机上调度和运行应用容器
```

**重要提醒**: 这两个层面不可混淆，Terraform 不应该管理应用层面的资源，Nomad 也不应该创建虚拟机。严格遵守此分层架构是项目成功的关键。

## 📁 项目结构

```
mgmt/
├── .gitea/workflows/           # CI/CD 工作流
├── tofu/                       # OpenTofu 基础设施代码 (基础设施生命周期管理)
│   ├── environments/          # 环境配置 (dev/staging/prod)
│   ├── modules/               # 可复用模块
│   ├── providers/             # 云服务商配置
│   └── shared/                # 共享配置
├── configuration/             # Ansible 配置管理
│   ├── inventories/          # 主机清单
│   ├── playbooks/            # 剧本
│   ├── templates/            # 模板文件
│   └── group_vars/           # 组变量
├── jobs/                      # Nomad 作业定义 (应用资源调度与编排)
│   ├── consul/               # Consul 集群配置
│   └── podman/               # Podman 相关作业
├── configs/                   # 配置文件
│   ├── nomad-master.hcl      # Nomad 主节点配置
│   └── nomad-ash3c.hcl       # Nomad 客户端配置
├── docs/                      # 文档
├── security/                  # 安全配置
│   ├── certificates/         # 证书文件
│   └── policies/             # 安全策略
├── tests/                     # 测试脚本和报告
│   ├── mcp_servers/          # MCP服务器测试脚本
│   ├── mcp_server_test_report.md  # MCP服务器测试报告
│   └── legacy/               # 旧的测试脚本
├── tools/                     # 工具和实用程序
├── playbooks/                 # 核心Ansible剧本
└── Makefile                   # 项目管理命令
```

**架构分层说明**:
- **tofu/** 目录包含 Terraform/OpenTofu 代码，负责管理云服务商提供的计算资源生命周期
- **jobs/** 目录包含 Nomad 作业定义，负责在已有虚拟机内部进行应用资源调度
- 这两个目录严格分离，确保职责边界清晰

**注意：** 项目已从 Docker Swarm 迁移到 Nomad + Podman，原有的 swarm 目录已不再使用。所有中间过程脚本和测试文件已清理，保留核心配置文件以符合GitOps原则。

## 🔄 GitOps 原则

本项目遵循 GitOps 工作流，确保基础设施状态与 Git 仓库中的代码保持一致：

- **声明式配置**: 所有基础设施和应用程序配置都以声明式方式存储在 Git 中
- **版本控制和审计**: 所有变更都通过 Git 提交，提供完整的变更历史和审计跟踪
- **自动化同步**: 通过 CI/CD 流水线自动将 Git 中的变更应用到实际环境
- **状态收敛**: 系统会持续监控实际状态，并自动修复任何与期望状态的偏差

### GitOps 工作流程

1. **声明期望状态**: 在 Git 中定义基础设施和应用程序的期望状态
2. **提交变更**: 通过 Git 提交来应用变更
3. **自动同步**: CI/CD 系统检测到变更并自动应用到环境
4. **状态验证**: 系统验证实际状态与期望状态一致
5. **监控和告警**: 持续监控状态并在出现偏差时发出告警

这种工作流确保了环境的一致性、可重复性和可靠性，同时提供了完整的变更历史和回滚能力。

## 🚀 快速开始

### 1. 环境准备

```bash
# 克隆项目
git clone <repository-url>
cd mgmt

# 检查环境状态
./mgmt.sh status

# 快速部署（适用于开发环境）
./mgmt.sh deploy
```

### 2. 配置云服务商

```bash
# 复制配置模板
cp tofu/environments/dev/terraform.tfvars.example tofu/environments/dev/terraform.tfvars

# 编辑配置文件，填入你的云服务商凭据
vim tofu/environments/dev/terraform.tfvars
```

### 3. 初始化基础设施

```bash
# 初始化 OpenTofu
./mgmt.sh tofu init

# 查看执行计划
./mgmt.sh tofu plan

# 应用基础设施变更
cd tofu/environments/dev && tofu apply
```

### 4. 部署 Nomad 服务

```bash
# 部署 Consul 集群
nomad run /root/mgmt/jobs/consul/consul-cluster.nomad

# 查看 Nomad 任务
nomad job status

# 查看节点状态
nomad node status
```

### ⚠️ 重要提示：网络访问注意事项

**Tailscale 网络访问**：
- 本项目中的 Nomad 和 Consul 服务通过 Tailscale 网络进行访问
- 访问 Nomad (端口 4646) 和 Consul (端口 8500) 时，必须使用 Tailscale 分配的 IP 地址
- 错误示例：`http://127.0.0.1:4646` 或 `http://localhost:8500` (无法连接)
- 正确示例：`http://100.x.x.x:4646` 或 `http://100.x.x.x:8500` (使用 Tailscale IP)

**获取 Tailscale IP**：
```bash
# 查看当前节点的 Tailscale IP
tailscale ip -4

# 查看所有 Tailscale 网络中的节点
tailscale status
```

**常见问题**：
- 如果遇到 "connection refused" 错误，请确认是否使用了正确的 Tailscale IP
- 确保 Tailscale 服务已启动并正常运行
- 检查网络策略是否允许通过 Tailscale 接口访问相关端口
- 更多详细经验和解决方案，请参考：[Consul 和 Nomad 访问问题经验教训](.gitea/issues/consul-nomad-access-lesson.md)

### 🔄 Nomad 集群领导者轮换与访问策略

**Nomad 集群领导者机制**：
- Nomad 使用 Raft 协议实现分布式一致性，集群中只有一个领导者节点
- 领导者节点负责处理所有写入操作和协调集群状态
- 当领导者节点故障时，集群会自动选举新的领导者

**领导者轮换时的访问策略**：

1. **动态发现领导者**：
```bash
# 查询当前领导者节点
curl -s http://<任意Nomad服务器IP>:4646/v1/status/leader
# 返回结果示例: "100.90.159.68:4647"

# 使用返回的领导者地址进行API调用
curl -s http://100.90.159.68:4646/v1/nodes
```

2. **负载均衡方案**：
   - **DNS 负载均衡**：使用 Consul DNS 服务，通过 `nomad.service.consul` 解析到当前领导者
   - **代理层负载均衡**：在 Nginx/HAProxy 配置中添加健康检查，自动路由到活跃的领导者节点
   - **客户端重试机制**：在客户端代码中实现重试逻辑，当连接失败时尝试其他服务器节点

3. **推荐访问模式**：
```bash
# 使用领导者发现脚本
#!/bin/bash
# 获取任意一个Nomad服务器IP
SERVER_IP="100.116.158.95"
# 查询当前领导者
LEADER=$(curl -s http://${SERVER_IP}:4646/v1/status/leader | sed 's/"//g')
# 使用领导者地址执行命令
nomad node status -address=http://${LEADER}
```

4. **高可用性配置**：
   - 将所有 Nomad 服务器节点添加到客户端配置中
   - 客户端会自动连接到可用的服务器节点
   - 对于写入操作，客户端会自动重定向到领导者节点

**注意事项**：
- Nomad 集群领导者轮换是自动进行的，通常不需要人工干预
- 在领导者选举期间，集群可能会短暂无法处理写入操作
- 建议在应用程序中实现适当的重试逻辑，以处理领导者切换期间的临时故障

## 🛠️ 常用命令

| 命令 | 描述 |
|------|------|
| `make status` | 显示项目状态总览 |
| `make deploy` | 快速部署所有服务 |
| `make cleanup` | 清理所有部署的服务 |
| `cd tofu/environments/dev && tofu <cmd>` | OpenTofu 管理命令 |
| `nomad job status` | 查看 Nomad 任务状态 |
| `nomad node status` | 查看 Nomad 节点状态 |
| `podman ps` | 查看运行中的容器 |
| `ansible-playbook playbooks/configure-nomad-clients.yml` | 配置 Nomad 客户端 |
| `./run_tests.sh` 或 `make test-mcp` | 运行所有MCP服务器测试 |
| `make test-kali` | 运行Kali Linux快速健康检查 |
| `make test-kali-security` | 运行Kali Linux安全工具测试 |
| `make test-kali-full` | 运行Kali Linux完整测试套件 |

## 🌩️ 支持的云服务商

### Oracle Cloud Infrastructure (OCI)
- ✅ 计算实例
- ✅ 网络配置 (VCN, 子网, 安全组)
- ✅ 存储 (块存储, 对象存储)
- ✅ 负载均衡器

### 华为云
- ✅ 弹性云服务器 (ECS)
- ✅ 虚拟私有云 (VPC)
- ✅ 弹性负载均衡 (ELB)
- ✅ 云硬盘 (EVS)

### Google Cloud Platform
- ✅ Compute Engine
- ✅ VPC 网络
- ✅ Cloud Load Balancing
- ✅ Persistent Disk

### Amazon Web Services
- ✅ EC2 实例
- ✅ VPC 网络
- ✅ Application Load Balancer
- ✅ EBS 存储

### DigitalOcean
- ✅ Droplets
- ✅ VPC 网络
- ✅ Load Balancers
- ✅ Block Storage

## 🔄 CI/CD 流程

### 基础设施部署流程
1. **代码提交** → 触发 Gitea Actions
2. **OpenTofu Plan** → 生成执行计划
3. **人工审核** → 确认变更
4. **OpenTofu Apply** → 应用基础设施变更
5. **Ansible 部署** → 配置和部署应用

### 应用部署流程
1. **应用代码更新** → 构建容器镜像
2. **镜像推送** → 推送到镜像仓库
3. **Nomad Job 更新** → 更新任务定义
4. **Nomad 部署** → 滚动更新服务
5. **健康检查** → 验证部署状态

## 📊 监控和可观测性

### 监控组件
- **Prometheus**: 指标收集和存储
- **Grafana**: 可视化仪表板
- **AlertManager**: 告警管理
- **Node Exporter**: 系统指标导出

### 日志管理
- **ELK Stack**: Elasticsearch + Logstash + Kibana
- **Fluentd**: 日志收集和转发
- **结构化日志**: JSON 格式标准化

## 🔐 安全最佳实践

### 基础设施安全
- **网络隔离**: VPC, 安全组, 防火墙
- **访问控制**: IAM 角色和策略
- **数据加密**: 传输和静态加密
- **密钥管理**: 云服务商密钥管理服务

### 应用安全
- **容器安全**: 镜像扫描, 最小权限
- **网络安全**: 服务网格, TLS 终止
- **秘密管理**: Docker Secrets, Ansible Vault
- **安全审计**: 日志监控和审计

## 🧪 测试策略

### 基础设施测试
- **语法检查**: OpenTofu validate
- **安全扫描**: Checkov, tfsec
- **合规检查**: OPA (Open Policy Agent)

### 应用测试
- **单元测试**: 应用代码测试
- **集成测试**: 服务间集成测试
- **端到端测试**: 完整流程测试

### MCP服务器测试
项目包含完整的MCP（Model Context Protocol）服务器测试套件，位于 `tests/mcp_servers/` 目录：

- **context7服务器测试**: 验证初始化、工具列表和搜索功能
- **qdrant服务器测试**: 测试文档添加、搜索和删除功能
- **qdrant-ollama服务器测试**: 验证向量数据库与LLM集成功能

测试脚本包括Shell脚本和Python脚本，支持通过JSON-RPC协议直接测试MCP服务器功能。详细的测试结果和问题修复记录请参考 `tests/mcp_server_test_report.md`。

运行测试：
```bash
# 运行单个测试脚本
cd tests/mcp_servers
./test_local_mcp_servers.sh

# 或运行Python测试
python test_mcp_servers_simple.py
```

### Kali Linux系统测试
项目包含完整的Kali Linux系统测试套件，位于 `configuration/playbooks/test/` 目录。测试包括：

1. **快速健康检查** (`kali-health-check.yml`): 基本系统状态检查
2. **安全工具测试** (`kali-security-tools.yml`): 测试各种安全工具的安装和功能
3. **完整系统测试** (`test-kali.yml`): 全面的系统测试和报告生成
4. **完整测试套件** (`kali-full-test-suite.yml`): 按顺序执行所有测试

运行测试：
```bash
# Kali Linux快速健康检查
make test-kali

# Kali Linux安全工具测试
make test-kali-security

# Kali Linux完整测试套件
make test-kali-full
```

## 📚 文档

- [Consul集群故障排除](docs/consul-cluster-troubleshooting.md)
- [磁盘管理](docs/disk-management.md)
- [Nomad NFS设置](docs/nomad-nfs-setup.md)
- [Consul-Terraform集成](docs/setup/consul-terraform-integration.md)
- [OCI凭据设置](docs/setup/oci-credentials-setup.md)
- [Oracle云设置](docs/setup/oracle-cloud-setup.md)

## 🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交变更 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🆘 支持

如果你遇到问题或有疑问：

1. 查看 [文档](docs/)
2. 搜索 [Issues](../../issues)
3. 创建新的 [Issue](../../issues/new)

## ⚠️ 重要经验教训

### Terraform 与 Nomad 职责区分
**问题**：在基础设施管理中容易混淆 Terraform 和 Nomad 的职责范围，导致架构设计混乱。

**根本原因**：Terraform 和 Nomad 虽然都是基础设施管理工具，但它们在架构中处于不同层面，负责不同类型的资源管理。

**解决方案**：
1. **明确分层架构**：
   - **Terraform/OpenTofu**：负责云服务商提供的计算资源（虚拟机）的生命周期管理
   - **Nomad**：负责在已有虚拟机内部进行应用资源调度和编排

2. **职责边界清晰**：
   - Terraform 决定"有哪些虚拟机"
   - Nomad 决定"虚拟机上运行什么应用"
   - 两者不应越界管理对方的资源

3. **工作流程分离**：
   ```
   1. Terraform 创建虚拟机 (云服务商层面)
      ↓
   2. 虚拟机启动并运行操作系统
      ↓
   3. 在虚拟机上安装和配置 Nomad 客户端
      ↓
   4. Nomad 在虚拟机上调度和运行应用容器
   ```

**重要提醒**：严格遵守这种分层架构是项目成功的关键。任何混淆这两个层面职责的做法都会导致架构混乱和管理困难。

### Consul 和 Nomad 访问问题
**问题**：尝试访问 Consul 服务时，使用 `http://localhost:8500` 或 `http://127.0.0.1:8500` 无法连接。

**根本原因**：本项目中的 Consul 和 Nomad 服务通过 Nomad + Podman 在集群中运行，并通过 Tailscale 网络进行访问。这些服务不在本地运行，因此无法通过 localhost 访问。

**解决方案**：
1. **使用 Tailscale IP**：必须使用 Tailscale 分配的 IP 地址访问服务
   ```bash
   # 查看当前节点的 Tailscale IP
   tailscale ip -4
   
   # 查看所有 Tailscale 网络中的节点
   tailscale status
   
   # 访问 Consul (使用实际的 Tailscale IP)
   curl http://100.x.x.x:8500/v1/status/leader
   
   # 访问 Nomad (使用实际的 Tailscale IP)
   curl http://100.x.x.x:4646/v1/status/leader
   ```

2. **服务发现**：Consul 集群由 3 个节点组成，Nomad 集群由十多个节点组成，需要正确识别服务运行的节点

3. **集群架构**：
   - Consul 集群：3 个节点 (kr-master, us-ash3c, bj-warden)
   - Nomad 集群：十多个节点，包括服务器节点和客户端节点

**重要提醒**：在开发和调试过程中，始终记住使用 Tailscale IP 而不是 localhost 访问集群服务。这是本项目架构的基本要求，必须严格遵守。

### Consul 集群配置管理经验
**问题**：Consul集群配置文件与实际运行状态不一致，导致集群管理混乱和配置错误。

**根本原因**：Ansible inventory配置文件中的节点信息与实际Consul集群中的节点状态不匹配，包括节点角色、数量和expect值等关键配置。

**解决方案**：
1. **定期验证集群状态**：使用Consul API定期检查集群实际状态，确保配置文件与实际运行状态一致
   ```bash
   # 查看Consul集群节点信息
   curl -s http://<consul-server>:8500/v1/catalog/nodes
   
   # 查看节点详细信息
   curl -s http://<consul-server>:8500/v1/agent/members
   
   # 查看集群leader信息
   curl -s http://<consul-server>:8500/v1/status/leader
   ```

2. **保持配置文件一致性**：确保所有相关的inventory配置文件（如`csol-consul-nodes.ini`、`consul-nodes.ini`、`consul-cluster.ini`）保持一致，包括：
   - 服务器节点列表和数量
   - 客户端节点列表和数量
   - `bootstrap_expect`值（必须与实际服务器节点数量匹配）
   - 节点角色和IP地址

3. **正确识别节点角色**：通过API查询确认每个节点的实际角色，避免将服务器节点误配置为客户端节点，或反之
   ```json
   // API返回的节点信息示例
   {
     "Name": "warden",
     "Addr": "100.122.197.112",
     "Port": 8300,
     "Status": 1,
     "ProtocolVersion": 2,
     "Delegate": 1,
     "Server": true  // 确认节点角色
   }
   ```

4. **更新配置流程**：当发现配置与实际状态不匹配时，按照以下步骤更新：
   - 使用API获取集群实际状态
   - 根据实际状态更新所有相关配置文件
   - 确保所有配置文件中的信息保持一致
   - 更新配置文件中的说明和注释，反映最新的集群状态

**实际案例**：
- **初始状态**：配置文件显示2个服务器节点和5个客户端节点，`bootstrap_expect=2`
- **实际状态**：Consul集群运行3个服务器节点（master、ash3c、warden），无客户端节点，`expect=3`
- **解决方案**：更新所有配置文件，将服务器节点数量改为3个，移除所有客户端节点配置，将`bootstrap_expect`值更新为3

**重要提醒**：Consul集群配置必须与实际运行状态保持严格一致。任何不匹配都可能导致集群不稳定或功能异常。定期使用Consul API验证集群状态，并及时更新配置文件，是确保集群稳定运行的关键。

## 🎉 致谢

感谢所有为这个项目做出贡献的开发者和社区成员！
## 脚本整理

项目脚本已重新整理，按功能分类存放在 `scripts/` 目录中：

- `scripts/setup/` - 环境设置和初始化
- `scripts/deployment/` - 部署相关脚本  
- `scripts/testing/` - 测试脚本
- `scripts/utilities/` - 工具脚本
- `scripts/mcp/` - MCP 服务器相关
- `scripts/ci-cd/` - CI/CD 相关

详细信息请查看 [脚本索引](scripts/SCRIPT_INDEX.md)。