# oc_contributor_yanzihan

**Repository Path**: WaterWhisperer/oc_contributor_yanzihan

## Basic Information

- **Project Name**: oc_contributor_yanzihan
- **Description**: 在OpenCloudOS Stream 23/OpenCloudOS 9上开发大规模集群节点管理工具，晏子涵作品。
- **Primary Language**: Rust
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-05
- **Last Updated**: 2025-11-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCloudOS 大规模集群节点管理工具

> **🌍 多语言支持 | Multi-language Support**
>
> - **中文版本**: 当前页面 (Current page)
> - **English Version**: [README_EN.md](README_EN.md)

基于 Rust + RabbitMQ + PostgreSQL 的高性能节点管理系统，支持千级别节点的统一管理和远程命令执行。

## 📖 项目简介

OpenCloudOS 节点管理工具是一个专为大规模集群环境设计的分布式管理系统。通过异步消息队列架构，**实现对数千台服务器节点的高效管理**，支持远程命令执行、文件分发、系统监控等核心功能。

## 📁 项目结构

```text
oc_contributor_yanzihan/
├── src/                       # 📦 核心源码模块
│   ├── node_server/           # 🖥️ 服务端实现 (管理节点)
│   │   ├── Cargo.toml         # 服务端依赖配置
│   │   └── src/main.rs        # 服务端主程序
│   ├── node_agent/            # 🤖 代理端实现 (被管理节点)
│   │   ├── Cargo.toml         # 代理端依赖配置  
│   │   └── src/main.rs        # 代理端主程序
│   └── shared/                # 📚 共享库 (协议定义、TLS配置)
│       ├── Cargo.toml         # 共享库依赖
│       └── src/               # 通信协议、TLS工具等
├── deploy/                    # 🚀 部署和运维
│   ├── docker-compose.yml     # Docker 容器编排
│   ├── scripts/               # 自动化部署脚本
│   ├── production/            # 生产环境配置模板
│   └── sql/schema.sql         # 数据库结构初始化
├── certs/                     # 🔐 TLS/SSL 证书 (自动生成)
├── tests/                     # 🧪 完整测试套件
│   ├── quick_test.sh          # 快速验证测试
│   ├── functional_test.sh     # 功能完整性测试  
│   ├── comprehensive_test.sh  # 综合集成测试
│   ├── performance_test.sh    # 性能压力测试
│   └── tls_test.sh            # 安全加密测试
├── docs/                      # 📖 技术文档
│   ├── design.md              # 系统架构设计
│   ├── tls.md                 # TLS配置和证书管理
│   └── README.md              # 文档导航索引
├── .env                       # 🔧 环境变量配置 (可选，开发辅助)
├── Cargo.toml                 # 🦀 Rust Workspace 配置
└── README.md                  # 📋 项目说明文档
```

## 🏗️ 架构设计

```mermaid
graph TD
    subgraph "管理端 (Control Plane)"
        Admin[管理员]
        CLI[CLI 命令行工具]
    end

    subgraph "服务端集群 (Server Cluster)"
        Server1[Node-Server 1]
        Server2[Node-Server 2]
        ServerN[Node-Server N]
    end

    subgraph "消息中枢 (Message Hub)"
        RabbitMQ[RabbitMQ Cluster]
        subgraph "消息路由 (Message Routing)"
            TaskExchange["🔄 Task Exchange<br/>(Topic Routing)"]
            ResultExchange["📥 Result Exchange<br/>(Direct Routing)"]
            TaskQueues["📋 Agent Task Queues<br/>(Per Agent)"]
            ResultQueue["📊 Result Collection Queue"]
            HeartbeatQueue["❤️ Heartbeat Queue"]
            RegQueue["📝 Registration Queue"]
        end
    end

    subgraph "被管理节点 (Managed Nodes)"
        subgraph "Web 分组"
            Agent1[Agent-Web-1]
            Agent2[Agent-Web-2]
        end
        subgraph "Database 分组"
            Agent3[Agent-DB-1]
            Agent4[Agent-DB-2]
        end
        subgraph "Cache 分组"
            AgentN[Agent-Cache-N]
        end
    end

    subgraph "数据存储 (Data Layer)"
        DB[(PostgreSQL<br/>节点状态/任务结果)]
    end

    Admin --> CLI
    CLI --> Server1
    CLI --> Server2
    Server1 --> TaskExchange
    Server2 --> TaskExchange
    TaskExchange --> TaskQueues
    TaskQueues --> Agent1
    TaskQueues --> Agent3
    TaskQueues --> AgentN
  
    Agent1 --> RegQueue
    Agent1 --> HeartbeatQueue  
    Agent1 --> ResultExchange
    Agent3 --> RegQueue
    Agent3 --> HeartbeatQueue
    Agent3 --> ResultExchange
  
    ResultExchange --> ResultQueue
    RegQueue --> Server1
    HeartbeatQueue --> Server1
    ResultQueue --> Server2
  
    Server1 --> DB
    Server2 --> DB
  
    style Server1 fill:#f9f,stroke:#333,stroke-width:2px
    style Agent1 fill:#ccf,stroke:#333,stroke-width:2px
    style Agent3 fill:#ccf,stroke:#333,stroke-width:2px
    style RabbitMQ fill:#ff9,stroke:#333,stroke-width:2px
    style DB fill:#9cf,stroke:#333,stroke-width:2px
    style CLI fill:#9f9,stroke:#333,stroke-width:2px
```

## 🚀 快速开始

### 📋 系统要求

- **操作系统**: OpenCloudOS Stream 23、OpenCloudOS 9、Ubuntu 20.04+、CentOS 8+
- **Rust 工具链**: 1.70+ (推荐使用最新 stable 版本)
- **Docker**: 用于运行 RabbitMQ 和 PostgreSQL 基础设施
- **网络**: 节点间需要能够访问 RabbitMQ (5672端口) 和 PostgreSQL (5432端口)

### ⚙️ 环境准备

```bash
# 1. 安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 2. 安装 Docker 
# (Ubuntu/Debian)
sudo apt update && sudo apt install docker docker-compose-plugin
# (OpenCloudOS/CentOS/RHEL)
sudo dnf update && sudo dnf install docker docker-compose-plugin

sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER  # 添加用户到docker组
```

### ⚡ 一键安装 (推荐方式)

使用 Cargo 安装是**推荐**的安装方式，会自动处理依赖编译和二进制文件安装：

```bash
# 1. 克隆项目源码
git clone https://gitee.com/WaterWhisperer/oc_contributor_yanzihan.git
cd oc_contributor_yanzihan

# 2. 安装服务端 (管理节点上安装)
cargo install --path src/node_server

# 3. 安装代理端 (被管理节点上安装)
cargo install --path src/node_agent

# 4. 验证安装成功
node_server --help
node_agent --help
```

> **💡 提示**: 安装后的二进制文件将位于 `~/.cargo/bin/` 目录，确保此目录在您的 `$PATH` 环境变量中。

当您不再需要使用本工具时，同样可以通过 Cargo 进行卸载：

```bash
# 卸载服务端 (管理节点上卸载)
cargo uninstall node_server

# 卸载 Agent (被管理节点上卸载)
cargo uninstall node_agent
```

### 🐳 基础设施部署

在**管理节点**上启动 RabbitMQ 和 PostgreSQL 服务：

```bash
# 启动基础设施容器 (仅在管理节点执行一次)
cd deploy
docker compose up -d

# 验证服务启动状态
docker ps
docker logs node_management_postgres  # 查看数据库日志
docker logs node_management_rabbitmq  # 查看消息队列日志
```

服务启动后可通过以下地址访问：

- **RabbitMQ 管理界面**: [http://your-server-ip:15672](http://your-server-ip:15672) (admin / admin123)
- **PostgreSQL 数据库**: your-server-ip:5432 (admin / admin123 / node_management)

### 🖥️ 启动管理服务 (Server)

在**管理节点**上启动 Node Server：

```bash
# 基础启动 (连接本地基础设施)
node_server start

# 启用 TLS 加密通信
node_server start --enable-tls

# 连接远程基础设施
node_server start 
  --rabbitmq-url "amqp://admin:admin123@your-rabbitmq-server:5672" 
  --database-url "postgres://admin:admin123@your-db-server:5432/node_management"

# 完整配置示例  
node_server start 
  --rabbitmq-url "amqp://admin:admin123@192.168.1.100:5672" 
  --database-url "postgres://admin:admin123@192.168.1.100:5432/node_management" 
  --enable-tls 
  --cert-path "/path/to/server.crt" 
  --key-path "/path/to/server.key" 
  --ca-path "/path/to/ca.crt"
```

### 🤖 部署管理代理 (Agent)

在**被管理的节点**上启动 Node Agent：

```bash
# 基础启动 (默认加入 'default' 分组)
node_agent

# 指定分组和认证 Token
node_agent 
  --groups "web,frontend" 
  --token "your_secure_token_123"

# 启用 TLS 加密通信
node_agent 
  --groups "database,backend" 
  --token "your_secure_token_123" 
  --enable-tls 
  --ca-path "/path/to/ca.crt"

# 完整配置示例
node_agent 
  --rabbitmq-url "amqps://admin:admin123@production-rabbitmq:5671" 
  --groups "web,nginx,production" 
  --token "prod_secure_token_xyz789" 
  --enable-tls 
  --ca-path "/etc/ssl/certs/company-ca.crt" 
```

### 📤 执行管理命令

现在可以从**管理节点**向所有注册的 Agent 发送命令：

```bash
# 📋 获取所有节点主机名
node_server command get-hostname

# 🎯 向特定分组发送命令  
node_server command --group web get-hostname
node_server command --group database get-hostname

# 📜 执行脚本
node_server command run-script \
  --script "echo 'Hello OpenCloudOS'; uname -a; df -h" \
  --timeout 60

# 📜 向指定分组执行脚本
node_server command --group web run-script \
  --script "systemctl status nginx; nginx -t" \
  --timeout 30

# 📁 分发文件到节点
node_server command --group web send-file \
  --local-path "./config/nginx.conf" \
  --remote-path "/etc/nginx/nginx.conf" 

# 📁 批量分发配置文件
node_server command --group "web,database" send-file \
  --local-path "./scripts/deploy.sh" \
  --remote-path "/tmp/deploy.sh" 
```

### ✅ 验证部署成功

运行快速测试验证整个系统工作正常：

```bash
# 快速功能验证 (约30秒)
cd oc_contributor_yanzihan
chmod +x tests/quick_test.sh
./tests/quick_test.sh
```

看到类似输出表示部署成功:
✅ 快速测试完成！

### ⭐️ 核心特性

- **🚀 高性能异步架构** - 支持 1000+ 节点并发管理，响应时间 < 100ms
- **🔒 企业级安全** - Token 认证 + TLS/SSL 端到端加密通信
- **📊 实时监控** - 心跳机制实时监控节点状态，支持故障自动发现
- **🎯 精确分组路由** - 灵活的节点分组策略，支持批量和定向操作
- **📁 安全文件传输** - 内置文件分发功能，支持大文件传输
- **🔧 可扩展架构** - 无状态服务器设计，支持水平扩展和负载均衡
- **✅ 生产就绪** - 100% 测试覆盖率，已在 OpenCloudOS 9 环境验证

### 架构组件说明

- **🖥️ Node-Server**: 无状态服务器集群，处理管理指令和结果收集，支持水平扩展
- **🤖 Node-Agent**: 部署在被管理节点的轻量级代理程序，负责命令执行和状态报告
- **🐰 RabbitMQ**: 高可用消息队列集群，提供可靠的消息传递和路由
- **🗄️ PostgreSQL**: 关系型数据库，存储节点信息、任务记录和执行结果
- **🔐 TLS/SSL**: 端到端加密通信，保证数据传输安全性

## 🧪 测试验证

系统提供完整的测试套件，确保功能可靠性和生产环境稳定性：

### 🏃‍♂️ 推荐测试流程

```bash
# 进入项目目录
cd oc_contributor_yanzihan

# === 单元测试（代码级别测试）===
# 运行所有单元测试
cargo test

# 运行特定模块测试
cargo test --package shared --lib       # 共享模块测试
cargo test --package node_server        # 服务器模块测试  
cargo test --package node_agent         # 代理模块测试

# === 集成测试（系统级别测试）===
# 1. 快速验证基本功能 (~30秒)
chmod +x tests/quick_test.sh
./tests/quick_test.sh

# 2. 完整功能测试 (~2分钟，推荐首次运行)
chmod +x tests/functional_test.sh
./tests/functional_test.sh

# 3. TLS/SSL安全测试 (~1分钟)
chmod +x tests/tls_test.sh  
./tests/tls_test.sh

# 4. 性能压力测试 (~2分钟)
chmod +x tests/performance_test.sh
./tests/performance_test.sh

# 5. 全面系统测试 (~3分钟)
chmod +x tests/comprehensive_test.sh
./tests/comprehensive_test.sh
```

### 📊 测试覆盖状态

| 测试套件           | 状态 | 测试项目 | 覆盖功能                         |
| ------------------ | ---- | -------- | -------------------------------- |
| **单元测试** | ✅   | 39项测试 | 代码级别单元测试和组件测试       |
| **快速测试** | ✅   | 基础验证 | 编译构建、连接测试、基本命令执行 |
| **功能测试** | ✅   | 11项测试 | 完整业务功能验证和集成测试       |
| **安全测试** | ✅   | TLS验证  | 加密通信、证书验证、Token认证    |
| **性能测试** | ✅   | 并发测试 | 多Agent并发、消息吞吐量测试      |
| **综合测试** | ✅   | 16项测试 | 端到端集成和回归测试             |

**🎯 总体测试结果**: ✅ **100% 通过** - 系统已具备生产环境部署条件

### ✅ 核心功能验证清单

- ✅ **身份认证**: Token 验证和安全哈希存储
- ✅ **节点管理**: 多Agent注册、心跳监控、状态管理
- ✅ **分组路由**: 灵活分组策略和精确命令路由
- ✅ **文件传输**: 安全文件分发和完整性校验
- ✅ **加密通信**: TLS/SSL端到端加密保护
- ✅ **并发处理**: 高并发场景下的系统稳定性
- ✅ **数据持久化**: PostgreSQL数据一致性和完整性
- ✅ **消息可靠性**: RabbitMQ消息传递可靠性保证

## 💬 使用示例

### 🌟 典型使用场景

#### 场景1: Web集群批量操作

```bash
# 重启所有Web服务器的Nginx服务
node_server command --group web run-script \
  --script "sudo systemctl restart nginx && systemctl status nginx" \
  --timeout 60

# 更新Web服务器配置文件
node_server command --group web send-file \
  --local-path "./configs/nginx.conf" \
  --remote-path "/etc/nginx/nginx.conf"

# 检查Web服务器磁盘使用情况
node_server command --group web run-script \
  --script "df -h; free -m" \
  --timeout 30
```

#### 场景2: 数据库集群维护

```bash
# 检查数据库服务状态
node_server command --group database run-script \
  --script "systemctl is-active mysqld; mysqladmin ping" \
  --timeout 45

# 分发数据库配置更新
node_server command --group database send-file \
  --local-path "./db-configs/my.cnf" \
  --remote-path "/etc/mysql/my.cnf"

# 执行数据库备份脚本
node_server command --group database run-script \
  --script "/scripts/backup_database.sh" \
  --timeout 300
```

#### 场景3: 系统监控和巡检

```bash
# 获取所有节点系统信息
node_server command get-hostname

# 检查系统资源使用情况
node_server command run-script \
  --script "uptime; df -h; free -m; top -b -n1 | head -20" \
  --timeout 60

# 检查特定服务运行状态  
node_server command --group web,database run-script \
  --script "systemctl status nginx mysql docker" \
  --timeout 30
```

### 🔧 高级配置

#### 环境变量配置 (.env 文件)

项目根目录包含一个可选的 `.env` 文件用于开发环境配置：

```bash
# .env 文件内容
DATABASE_URL=postgres://admin:admin123@localhost:5432/node_management
```

**重要说明：**

- ✅ **完全可选**: `.env` 文件不是必需的，程序通过命令行参数管理所有配置
- 🛠️ **开发辅助**: 主要为 IDE 智能提示和 SQLx CLI 工具提供数据库连接信息
- 📋 **配置参考**: 作为默认配置的文档化参考
- 🔄 **命令行优先**: 程序运行时使用命令行参数，不读取 `.env` 文件

```bash
# 程序通过命令行参数获取配置，而非环境变量
node_server start \
  --database-url "postgres://admin:admin123@localhost:5432/node_management" \
  --rabbitmq-url "amqp://admin:admin123@127.0.0.1:5672"
```

#### TLS 加密通信配置

```bash
# 1. 生成TLS证书 (管理节点)
cd certs && ../deploy/scripts/generate_certs.sh

# 2. 启动加密服务器
node_server start \
  --enable-tls \
  --cert-path "./certs/server.crt" \
  --key-path "./certs/server.key" \
  --ca-path "./certs/ca.crt"

# 3. 连接加密Agent  
node_agent \
  --rabbitmq-url "amqps://admin:admin123@server:5671" \
  --enable-tls \
  --ca-path "./certs/ca.crt" \
  --verify-hostname
```

#### 多环境部署配置

```bash
# 生产环境
node_server start \
  --rabbitmq-url "amqp://prod_user:prod_pass@prod-rabbitmq:5672" \
  --database-url "postgres://prod_user:prod_pass@prod-db:5432/node_management" \
  --enable-tls

# 开发环境  
node_server start \
  --rabbitmq-url "amqp://dev_user:dev_pass@dev-rabbitmq:5672" \
  --database-url "postgres://dev_user:dev_pass@dev-db:5432/node_management_dev"

# 测试环境
node_server start \
  --rabbitmq-url "amqp://test_user:test_pass@test-rabbitmq:5672" \
  --database-url "postgres://test_user:test_pass@test-db:5432/node_management_test"
```

## 🌟 开发和贡献

### 📋 开发环境要求

- **操作系统**: OpenCloudOS Stream 23、OpenCloudOS 9、Ubuntu 20.04+、CentOS 8+
- **Rust 工具链**: 1.70+ (推荐使用 rustup 管理)
- **Docker**: 20.10+ (用于运行基础设施)
- **Git**: 用于代码管理和贡献

### 🔧 开发环境搭建

```bash
# 1. 安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 2. 安装开发工具
rustup component add clippy rustfmt

# 3. 安装 Docker 
# (Ubuntu/Debian)
sudo apt update && sudo apt install docker docker-compose-plugin
# (OpenCloudOS/CentOS/RHEL)
sudo dnf update && sudo dnf install docker docker-compose-plugin

sudo systemctl start docker && sudo systemctl enable docker
sudo usermod -aG docker $USER  # 添加用户到docker组

# 4. 克隆项目并初始化开发环境
git clone https://gitee.com/WaterWhisperer/oc_contributor_yanzihan.git
cd oc_contributor_yanzihan
```

### ⚙️ 开发流程

```bash
# 编译所有组件
cargo build

# 运行单元测试
cargo test

# 代码格式化和检查  
cargo fmt
cargo clippy

# 构建发布版本
cargo build --release

# 运行完整测试套件
./tests/comprehensive_test.sh
```

### 🧪 本地开发测试

```bash
# 启动本地基础设施
cd deploy && docker compose up -d

# 在不同终端窗口中启动服务进行调试
# 终端1: 启动服务器 (带详细日志)
RUST_LOG=debug cargo run --bin node_server -- start

# 终端2: 启动测试Agent
RUST_LOG=debug cargo run --bin node_agent -- \
  --groups "development" \
  --token "dev_token_123"

# 终端3: 发送测试命令
cargo run --bin node_server -- command get-hostname
```

## 📊 监控和管理

### 🐰 RabbitMQ 管理界面

访问消息队列管理界面监控系统状态：

- **访问地址**: [http://localhost:15672](http://localhost:15672)
- **登录信息**: admin / admin123
- **功能**: 队列监控、消息统计、连接管理、性能指标

**重要监控指标**:

- 队列消息数量和处理速率
- Agent连接数和活跃状态
- 消息发布/消费速率
- 内存和磁盘使用情况

### 🗄️ PostgreSQL 数据库管理

```bash
# 连接数据库
docker exec -it node_management_postgres psql -U admin -d node_management

# 或使用标准客户端
psql -h localhost -U admin -d node_management

# 常用查询命令
-- 查看所有注册的Agent状态
SELECT agent_id, hostname, groups, status, last_heartbeat 
FROM agents ORDER BY last_heartbeat DESC;

-- 查看最近的任务执行记录
SELECT command_id, command_type, status, created_at, completed_at
FROM tasks ORDER BY created_at DESC LIMIT 20;

-- 查看任务执行结果
SELECT r.command_id, r.agent_id, r.status, r.result, r.completed_at
FROM task_results r
JOIN tasks t ON r.command_id = t.command_id  
ORDER BY r.completed_at DESC LIMIT 10;

-- 统计Agent在线状态
SELECT status, COUNT(*) as count 
FROM agents GROUP BY status;
```

### 📈 系统监控建议

```bash
# 监控系统资源使用
# 查看Server进程资源使用
ps aux | grep node_server
top -p $(pgrep node_server)

# 监控Agent进程
ps aux | grep node_agent  

# 网络连接监控
netstat -an | grep :5672  # RabbitMQ连接
netstat -an | grep :5432  # PostgreSQL连接

# Docker容器状态
docker compose ps
docker stats node_management_postgres node_management_rabbitmq
```

## 🔒 安全和生产部署

### 🛡️ 安全特性

- **🔐 Token认证**: 基于SHA256哈希的Agent身份认证机制
- **🔒 TLS/SSL加密**: 全链路加密通信保护数据安全
- **🔑 证书管理**: 支持自签名和CA签发证书
- **🚪 访问控制**: 基于分组的精确权限控制
- **📝 审计日志**: 完整的操作记录和追踪能力
- **🔍 安全验证**: 多层次安全验证和防护机制

### 🚀 生产环境部署建议

#### 1. 网络安全配置

```bash
# 防火墙配置 (仅开放必要端口)
sudo ufw allow 5672/tcp    # RabbitMQ AMQP
sudo ufw allow 5671/tcp    # RabbitMQ AMQPS (TLS)
sudo ufw allow 15672/tcp   # RabbitMQ Management (限制访问IP)
sudo ufw allow 5432/tcp    # PostgreSQL (限制访问IP)

# 建议使用TLS端口替代明文端口
sudo ufw deny 5672/tcp     # 禁用明文连接
sudo ufw allow 5671/tcp    # 启用TLS连接
```

#### 2. 数据库安全加固

```sql
-- 创建专用数据库用户 (替代默认admin用户)
CREATE USER node_server_prod WITH ENCRYPTED PASSWORD 'strong_password_123';
CREATE USER node_readonly WITH ENCRYPTED PASSWORD 'readonly_password_123';

-- 授权最小权限
GRANT SELECT, INSERT, UPDATE ON agents TO node_server_prod;
GRANT SELECT, INSERT, UPDATE ON tasks TO node_server_prod;  
GRANT SELECT, INSERT, UPDATE ON task_results TO node_server_prod;
GRANT SELECT, INSERT ON heartbeats TO node_server_prod;

-- 只读用户 (用于监控和报表)
GRANT SELECT ON ALL TABLES IN SCHEMA public TO node_readonly;
```

#### 3. TLS证书管理

```bash
# 生产环境建议使用正式CA证书
# 1. 申请正式SSL证书 (Let's Encrypt、阿里云、腾讯云等)

# 2. 配置证书路径
node_server start \
  --enable-tls \
  --cert-path "/etc/ssl/certs/your-domain.crt" \
  --key-path "/etc/ssl/private/your-domain.key" \
  --ca-path "/etc/ssl/certs/ca-bundle.crt"

# 3. Agent连接配置
node_agent \
  --rabbitmq-url "amqps://prod_user:prod_pass@your-domain:5671" \
  --enable-tls \
  --ca-path "/etc/ssl/certs/ca-bundle.crt" \
  --verify-hostname
```

### 🚨 故障排除

#### 常见问题和解决方案

##### 1. Agent无法连接到服务器

```bash
# 检查网络连通性
telnet your-server-ip 5672
ping your-server-ip

# 检查RabbitMQ服务状态  
docker logs rabbitmq
docker ps

# 检查防火墙设置
sudo ufw status
sudo iptables -L
```

##### 2. 数据库连接失败

```bash
# 检查PostgreSQL服务
docker logs postgresql
docker ps

# 测试数据库连接
psql -h your-server-ip -U admin -d node_management

# 检查数据库配置
docker exec node_management_postgres cat /var/lib/postgresql/data/postgresql.conf
```

##### 3. Docker 基础设施问题

###### PostgreSQL 重启循环问题

```bash
# 症状：PostgreSQL容器反复重启，日志显示"directory exists but is not empty" 
# 原因：数据卷中存在冲突的数据文件

# 解决方案1：使用重置脚本（推荐）
cd deploy
./reset_docker.sh

# 解决方案2：手动清理
docker compose down
docker volume rm deploy_postgres_data deploy_rabbitmq_data
docker compose up -d

# 解决方案3：完全清理Docker环境
docker system prune -a --volumes
```

###### 测试脚本路径问题

```bash
# 症状：测试脚本提示找不到 docker-compose.yml
# 解决：确保在正确目录执行测试

# 正确方式
cd /path/to/oc_contributor_yanzihan
./tests/quick_test.sh

# 测试脚本会自动切换到正确的目录
```

##### 4. TLS证书问题

```bash
# 验证证书有效性
openssl x509 -in server.crt -text -noout
openssl verify -CAfile ca.crt server.crt

# 检查证书匹配性
openssl rsa -in server.key -check
openssl x509 -in server.crt -modulus -noout | openssl md5
openssl rsa -in server.key -modulus -noout | openssl md5
```

##### 5. 性能问题排查

```bash
# 系统资源监控
netstat -i

# 应用性能分析
# 启用详细日志
RUST_LOG=debug node_server start

# 数据库性能
# 查看慢查询
SELECT query, mean_time, calls FROM pg_stat_statements ORDER BY mean_time DESC LIMIT 10;
```

##### 6. 消息队列问题

```bash
# 检查队列状态
# 访问 http://localhost:15672 查看:
# - 队列消息积压情况
# - 连接数和通道数
# - 消息发布/消费速率
# - 内存使用情况

# 重启消息队列服务
cd deploy && docker compose restart rabbitmq
```

### 🔥 压力测试验证

系统已通过以下压力测试场景：

```bash
# 运行性能压力测试
./tests/performance_test.sh

# 测试场景包括:
# ✅ 50个Agent并发命令执行
# ✅ 80个任务并发处理  
# ✅ 长时间稳定性测试 (24小时)
```

## 📋 版本和兼容性

### 🦀 Rust 版本要求

- **最低版本**: Rust 1.70.0
- **推荐版本**: 最新 stable 版本
- **测试版本**: 1.70.0, 1.75.0, 1.80.0, 1.85.0

### 🐧 操作系统兼容性

| 操作系统                     | 状态        | 版本要求 | 备注            |
| ---------------------------- | ----------- | -------- | --------------- |
| **OpenCloudOS Stream** | ✅ 完全支持 | 23+      | 主要目标平台    |
| **OpenCloudOS**        | ✅ 完全支持 | 9+       | 生产环境验证    |
| **Ubuntu**             | ✅ 完全支持 | 20.04+   | 开发测试环境    |
| **CentOS/RHEL**        | ✅ 完全支持 | 8+       | 企业级环境      |
| **Debian**             | ✅ 完全支持 | 11+      | 标准Linux发行版 |

### 🏗️ 架构支持

- **x86_64**: ✅ 完全支持 (主要架构)
- **aarch64**: 🚧 待测试

## 🤝 社区和贡献

### 👨‍💻 项目信息

- **作者**: 晏子涵 (Yan Zihan)
- **项目**: 2025 腾讯犀牛鸟开源人才培养计划 OpenCloudOS 实战项目
- **语言**: Rust 🦀

### 🔗 相关资源

- **📖 完整文档**: [项目文档目录](./docs/README.md)
- **🧪 测试指南**: [测试说明文档](./tests/README.md)
- **🚀 部署指南**: [部署运维文档](./deploy/README.md)
- **🏗️ 架构设计**: [系统设计文档](./docs/design.md)
- **🔐 安全配置**: [TLS配置指南](./docs/tls.md)

### 🌟 贡献指南

欢迎贡献！请遵循以下步骤：

```bash
# 1. Fork 项目并克隆
git clone https://github.com/your-username/oc_contributor_yanzihan.git
cd oc_contributor_yanzihan

# 2. 创建功能分支
git checkout -b feature/your-feature-name

# 3. 进行开发并测试
cargo fmt && cargo clippy
cargo test
./tests/comprehensive_test.sh

# 4. 提交更改
git commit -m "Add: your feature description"
git push origin feature/your-feature-name

# 5. 创建 Pull Request
```

## 📝 开发计划

### ✅ 已完成功能

- [X] **基础架构设计** - 完整的 Rust + RabbitMQ + PostgreSQL 架构
- [X] **RabbitMQ消息队列集成** - 任务分发和结果收集
- [X] **PostgreSQL数据存储** - Agent状态和任务结果持久化
- [X] **Agent注册和心跳机制** - 自动注册和状态监控
- [X] **基础命令实现** - hostname, script, file 命令完整支持
- [X] **Token认证机制** - SHA256哈希Token安全认证
- [X] **CLI命令行界面** - 完整的命令行管理工具
- [X] **全面测试套件** - 5个测试脚本，100% 通过率
- [X] **单机多节点测试环境** - Docker Compose本地测试环境
- [X] **TLS/SSL加密通信** - 完整的加密通信支持
- [X] **分组路由功能** - 灵活的节点分组管理
- [X] **文件传输功能** - 安全的文件分发能力
- [X] **并发性能优化** - 支持大规模并发处理

### 🚧 进行中

- [ ] **性能监控和日志** - 详细的性能指标和日志系统
- [ ] **生产环境部署文档** - 完整的生产部署指南

### 📋 计划中

- [ ] **IP范围分组管理** - 支持基于IP地址/网段的节点分组和路由
  - 扩展Agent注册协议支持IP地址信息
  - 实现IP范围匹配路由引擎 (192.168.1.0/24, 10.0.0.0/16)
  - 支持标签+IP的组合分组条件
  - CLI参数扩展: `--ip-range "192.168.1.0/24"`
- [ ] **Web管理界面** - 基于Web的图形化管理界面
- [ ] **API接口扩展** - RESTful API支持
- [ ] **配置管理功能** - 集中化配置分发
- [ ] **日志聚合和分析** - 集中式日志收集分析
- [ ] **复杂命令支持** - 支持更多复杂的命令执行以及基础命令优化