12 KiB

Raw Blame History Unescape Escape

Hadoop Fault Detecting API 部署手册

1. 项目概述

Hadoop Fault Detecting API是一个基于FastAPI开发的后端服务，用于监控和管理Hadoop集群，提供集群管理、节点监控、日志分析、故障检测等功能。

2. 环境要求

2.1 硬件要求

配置项	最低要求	推荐配置
CPU	4核	8核
内存	8GB	16GB
磁盘	100GB	200GB
网络	千兆网卡	万兆网卡

2.2 软件要求

软件	版本	说明
Python	3.13+	开发和运行环境
PostgreSQL	14+	数据库
Redis	6.0+	可选，用于缓存
Git	2.0+	版本控制
Nginx	1.18+	反向代理（可选）
Docker	20.10+	容器化部署（可选）
Docker Compose	1.29+	容器编排（可选）

3. 部署准备

3.1 克隆代码

# 克隆代码到本地
git clone https://github.com/your-repo/hadoop-fault-detecting.git
cd hadoop-fault-detecting

3.2 安装Python依赖

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

3.3 配置环境变量

创建.env文件，配置以下环境变量：

# 数据库配置
DATABASE_URL=postgresql+asyncpg://username:password@localhost:5432/hadoop_fault

# JWT配置
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRE_MINUTES=30

# LLM配置
OPENAI_API_KEY=your_openai_api_key

# Hadoop节点配置
HADOOP_NODES={"hadoop-master": "192.168.1.100", "hadoop-node1": "192.168.1.101"}

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=app.log

4. 数据库部署

4.1 安装PostgreSQL

Ubuntu

sudo apt update
sudo apt install postgresql postgresql-contrib -y

# 启动PostgreSQL服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

CentOS

sudo dnf install postgresql-server postgresql-contrib -y

# 初始化数据库
sudo postgresql-setup initdb

# 启动PostgreSQL服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

Windows

下载安装包：https://www.postgresql.org/download/windows/

按照安装向导进行安装，记住设置的密码。

4.2 创建数据库和用户

# 登录PostgreSQL
sudo -u postgres psql

# 创建数据库
CREATE DATABASE hadoop_fault;

# 创建用户
CREATE USER username WITH PASSWORD 'password';

# 授权用户访问数据库
GRANT ALL PRIVILEGES ON DATABASE hadoop_fault TO username;

# 退出PostgreSQL\q

4.3 初始化数据库

# 运行数据库迁移（如果有）
# alembic upgrade head

# 或直接启动服务，FastAPI会自动创建表
python -m uvicorn app.main:app --reload

5. 服务部署

5.1 直接部署

开发环境

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 启动开发服务器
python -m uvicorn app.main:app --reload

访问地址：

API文档：http://localhost:8000/docs
ReDoc：http://localhost:8000/redoc

生产环境

# 激活虚拟环境
source venv/bin/activate

# 启动生产服务器
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

5.2 使用systemd部署

创建systemd服务文件：/etc/systemd/system/hadoop-fault-api.service

[Unit]
Description=Hadoop Fault Detecting API
After=network.target postgresql.service

[Service]
User=your_user
Group=your_group
WorkingDirectory=/path/to/hadoop-fault-detecting
Environment="PATH=/path/to/hadoop-fault-detecting/venv/bin"
ExecStart=/path/to/hadoop-fault-detecting/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
Restart=on-failure

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl start hadoop-fault-api
sudo systemctl enable hadoop-fault-api

查看服务状态：

sudo systemctl status hadoop-fault-api
sudo journalctl -u hadoop-fault-api -f

5.3 使用Docker部署

构建Docker镜像

创建Dockerfile：

FROM python:3.13-slim

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# 复制依赖文件
COPY requirements.txt .

# 安装Python依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 8000

# 启动服务
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

创建.dockerignore文件：

__pycache__
venv
.env
*.log
.git

构建镜像：

docker build -t hadoop-fault-api .

使用Docker Compose

创建docker-compose.yml文件：

version: '3.8'

services:
  db:
    image: postgres:14
    environment:
      POSTGRES_DB: hadoop_fault
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  api:
    build: .
    environment:
      DATABASE_URL: postgresql+asyncpg://username:password@db:5432/hadoop_fault
      JWT_SECRET: your_jwt_secret_key
      JWT_EXPIRE_MINUTES: 30
      OPENAI_API_KEY: your_openai_api_key
    ports:
      - "8000:8000"
    depends_on:
      - db
    restart: unless-stopped

volumes:
  postgres_data:

启动服务：

docker-compose up -d

查看日志：

docker-compose logs -f

停止服务：

docker-compose down

6. 配置说明

6.1 主要配置文件

配置文件	作用	位置
.env	环境变量配置	项目根目录
app/config.py	应用配置	app/
requirements.txt	Python依赖	项目根目录

6.2 环境变量说明

环境变量	类型	说明	示例
DATABASE_URL	字符串	数据库连接URL	postgresql+asyncpg://username:password@localhost:5432/hadoop_fault
JWT_SECRET	字符串	JWT密钥	your_jwt_secret_key
JWT_EXPIRE_MINUTES	整数	JWT令牌有效期（分钟）	30
OPENAI_API_KEY	字符串	OpenAI API密钥	sk-xxxxxxxxxxxxxxxxxx
HADOOP_NODES	JSON字符串	Hadoop节点配置	{"hadoop-master": "192.168.1.100"}
LOG_LEVEL	字符串	日志级别	INFO
LOG_FILE	字符串	日志文件路径	app.log

6.3 应用配置说明

在app/config.py中可以配置应用的各种参数：

# 应用配置
APP_TITLE = "Hadoop Fault Detecting API"
APP_VERSION = "v1"

# 数据库配置
DATABASE_URL = os.getenv("DATABASE_URL")

# JWT配置
JWT_SECRET = os.getenv("JWT_SECRET")
JWT_EXPIRE_MINUTES = int(os.getenv("JWT_EXPIRE_MINUTES", 30))

# LLM配置
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Hadoop节点配置
HADOOP_NODES = json.loads(os.getenv("HADOOP_NODES", "{}"))

# 日志配置
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
LOG_FILE = os.getenv("LOG_FILE", "app.log")

7. 反向代理配置

7.1 使用Nginx

创建Nginx配置文件：/etc/nginx/conf.d/hadoop-fault-api.conf

server {
    listen 80;
    server_name api.example.com;

    # 日志配置
    access_log /var/log/nginx/hadoop-fault-api.access.log;
    error_log /var/log/nginx/hadoop-fault-api.error.log;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # 静态文件配置（如果有）
    location /static/ {
        alias /path/to/hadoop-fault-detecting/static/;
        expires 30d;
    }
}

测试并重启Nginx：

sudo nginx -t
sudo systemctl restart nginx

7.2 使用HTTPS

生成SSL证书：

sudo certbot certonly --nginx -d api.example.com

更新Nginx配置：

server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name api.example.com;

    # SSL证书配置
    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 其他配置...
    location / {
        proxy_pass http://localhost:8000;
        # 其他proxy配置...
    }
}

8. 监控和维护

8.1 日志监控

应用日志默认保存在项目根目录的app.log文件中，可以通过以下命令查看日志：

# 实时查看日志
tail -f app.log

# 查看错误日志
grep -i error app.log

# 查看特定时间段的日志
grep "2025-12-18" app.log

8.2 健康检查

应用提供了健康检查接口，可以通过以下命令检查服务状态：

curl http://localhost:8000/api/v1/health

响应示例：

{
  "status": "ok",
  "database": "connected"
}

8.3 数据库备份

定期备份数据库：

# 备份数据库
pg_dump -U username -d hadoop_fault > hadoop_fault_backup_$(date +%Y%m%d_%H%M%S).sql

# 恢复数据库
psql -U username -d hadoop_fault < hadoop_fault_backup.sql

8.4 性能监控

可以使用以下工具监控服务性能：

Prometheus + Grafana：监控系统和应用性能
New Relic：应用性能监控
ELK Stack：日志收集和分析

9. 常见问题和解决方案

9.1 数据库连接失败

问题：启动服务时提示数据库连接失败

解决方案：

检查数据库服务是否正在运行
检查数据库连接URL是否正确
检查数据库用户权限是否正确
检查防火墙设置是否允许连接

9.2 端口被占用

问题：启动服务时提示端口8000已被占用

解决方案：

查找占用端口的进程：lsof -i :8000
终止占用端口的进程：kill -9 <PID>
或修改服务端口：uvicorn app.main:app --port 8001

9.3 依赖安装失败

问题：安装依赖时出现错误

解决方案：

确保Python版本符合要求
更新pip：pip install --upgrade pip
安装系统依赖：
- Ubuntu：apt install build-essential libpq-dev
- CentOS：yum install gcc gcc-c++ postgresql-devel
尝试使用国内镜像源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

9.4 JWT令牌无效

问题：请求API时提示"Invalid credentials"

解决方案：

检查JWT_SECRET是否正确配置
检查令牌是否过期
检查令牌格式是否正确
检查请求头中是否正确携带令牌

9.5 500服务器错误

问题：请求API时返回500错误

解决方案：

查看应用日志，定位错误原因
检查数据库连接是否正常
检查代码中是否有未处理的异常
检查依赖版本是否兼容

10. 更新和升级

10.1 代码更新

# 拉取最新代码
git pull

# 安装新依赖
pip install -r requirements.txt

# 重启服务
# 直接部署：重启uvicorn服务
# systemd部署：sudo systemctl restart hadoop-fault-api
# Docker部署：docker-compose up -d --build

10.2 数据库迁移

如果使用Alembic进行数据库迁移：

# 创建迁移脚本
alembic revision --autogenerate -m "描述"

# 执行迁移
alembic upgrade head

11. 安全最佳实践

使用HTTPS：生产环境中使用HTTPS加密传输
定期更新依赖：定期更新Python依赖，修复安全漏洞
限制访问权限：设置适当的文件和目录权限
配置防火墙：限制只有特定IP可以访问服务
使用强密码：数据库和用户密码使用强密码
定期备份：定期备份数据库和配置文件
监控日志：实时监控日志，及时发现异常
使用VPN：如果服务部署在公网，考虑使用VPN访问

12. 联系方式

开发团队：Hadoop故障检测团队
文档地址：docs/deployment_guide.md
版本历史：
- v1.0 (2025-12-18)：初始版本

注意：本部署手册将根据项目的更新不断完善，建议定期查看最新版本。

12 KiB Raw Blame History Unescape Escape

Hadoop Fault Detecting API 部署手册

1. 项目概述

2. 环境要求

2.1 硬件要求

2.2 软件要求

3. 部署准备

3.1 克隆代码

3.2 安装Python依赖

3.3 配置环境变量

4. 数据库部署

4.1 安装PostgreSQL

Ubuntu

CentOS

Windows

4.2 创建数据库和用户

4.3 初始化数据库

5. 服务部署

5.1 直接部署

开发环境

生产环境

5.2 使用systemd部署

5.3 使用Docker部署

构建Docker镜像

使用Docker Compose

6. 配置说明

6.1 主要配置文件

6.2 环境变量说明

6.3 应用配置说明

7. 反向代理配置

7.1 使用Nginx

7.2 使用HTTPS

8. 监控和维护

8.1 日志监控

8.2 健康检查

8.3 数据库备份

8.4 性能监控

9. 常见问题和解决方案

9.1 数据库连接失败

9.2 端口被占用

9.3 依赖安装失败

9.4 JWT令牌无效

9.5 500服务器错误

10. 更新和升级

10.1 代码更新

10.2 数据库迁移

11. 安全最佳实践

12. 联系方式

12 KiB

Raw Blame History Unescape Escape