ipam/README.md

# IPAM 管理系统

企业级 IP 地址管理系统，支持自动化扫描、发现和管理网络 IP 资产。

---

## ✨ 功能特性

### 核心管理
- **网段管理** - CIDR 网段创建、分组、自动生成 IP 列表、使用率监控
- **IP 资产台账** - 在线/离线/空闲/保留状态管理、MAC地址、主机名、厂商识别、使用人/业务标注
- **搜索筛选** - 按网段、状态、IP/MAC/主机名快速搜索

### 智能扫描
- **ICMP Ping 扫描** - 快速检测在线状态
- **ARP 扫描** - 二层网络 MAC 地址发现
- **反向 DNS 解析** - 自动获取主机名
- **MAC 厂商识别** - 内置 IEEE OUI 数据库，识别 3000+ 设备厂商
- **异步任务执行** - Celery 后台并发扫描，不阻塞 Web 服务

### SNMP 网络设备集成
- **多版本支持** - SNMPv2c (Community)、SNMPv3 (认证+加密)
- **自动采集** - ARP 表、接口表、设备信息
- **设备状态** - 轮询状态监控、在线/离线检测

### 告警与异常检测
- **IP 冲突告警** - 同一 IP 对应多个 MAC 地址
- **未授权接入检测** - 新接入设备不在白名单内自动告警
- **网段耗尽预警** - 网段使用率超阈值告警
- **设备离线告警** - 网络设备长时间不在线告警
- **MAC 白名单** - 可信设备免告警

### 用户与安全
- **JWT 身份认证** - Token 登录、自动刷新
- **4 级角色权限** - 只读 / 操作员 / 管理员 / 超级管理员
- **操作审计日志** - 全量操作记录、可追溯查询
- **密码加密存储** - bcrypt 加密

### 报表与导出
- **CSV 格式导出** - IP 地址表、网段汇总、告警记录、SNMP 设备、ARP 表
- **系统汇总报表** - IP 使用率、在线率、告警统计、网段分布

---

## 🚀 快速开始

### 环境要求
- Python 3.11+
- MySQL 8.0+
- Redis 6.0+
- Node.js 18+

### 一键启动所有服务

#### 方式一：使用启动脚本（推荐）
```bash
cd /root/ipam
./start.sh
```

#### 方式二：手动启动


#### 安装依赖环境
```bash
cd /root/ipam/backend
source venv/bin/activate
pip install "pysnmp==4.4.12" "pyasn1<0.5.0" "pysmi<0.4.0"
apt install -y celery
```

##### 1️⃣ 启动后端 API 服务
```bash
cd /root/ipam/backend
source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8008
```

##### 2️⃣ 启动 Celery Worker（执行扫描任务）
```bash
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
```

##### 3️⃣ 启动 Celery Beat（定时任务调度器，自动扫描必须启动）
```bash
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app beat --loglevel=info
```

##### 4️⃣ 启动前端
```bash
cd /root/ipam/frontend
npm install
npm run dev -- --host 0.0.0.0 --port 3000
```

---

## ⏰ 自动扫描配置

### 扫描频率配置

系统默认配置了 **3 个定时扫描任务**：

| 任务名称 | 执行频率 | 扫描内容 | 说明 |
|----------|----------|----------|------|
| **每小时全量扫描** | 每 60 分钟 | Ping + ARP + DNS | 快速刷新在线状态 |
| **每日深度扫描** | 每天凌晨 02:00 | Ping + ARP + DNS | 每日完整扫描更新 |
| **统计更新** | 每 15 分钟 | 仅更新统计 | 更新网段使用率 |

### 如何自定义扫描频率

编辑配置文件：`/root/ipam/backend/app/tasks/celery_app.py`

```python
# 定时任务配置 (第 36-55 行)
celery_app.conf.beat_schedule = {
    # 每小时执行一次全量扫描
    'full-scan-every-hour': {
        'task': 'app.tasks.scan_tasks.full_network_scan',
        'schedule': 3600.0,  # 单位：秒，修改此值调整频率
        'args': (True, True, True)  # (启用Ping, 启用ARP, 启用DNS)
    },
    # 每天凌晨2点执行深度扫描
    'full-scan-daily': {
        'task': 'app.tasks.scan_tasks.full_network_scan',
        'schedule': crontab(hour=2, minute=0),  # 修改 hour/minute 调整时间
        'args': (True, True, True)
    },
    # 每15分钟更新统计
    'update-stats-every-15min': {
        'task': 'app.tasks.scan_tasks.update_all_statistics',
        'schedule': 900.0,  # 单位：秒
    },
}
```

**常用配置示例：**
```python
# 每 30 分钟扫描一次
'schedule': 1800.0

# 每天凌晨 3:30 扫描
'schedule': crontab(hour=3, minute=30)

# 工作日上午 9 点扫描
'schedule': crontab(hour=9, minute=0, day_of_week='mon-fri')

# 仅扫描 Ping，不扫描 ARP 和 DNS
'args': (True, False, False)
```

**⚠️ 注意：修改配置后必须重启 Celery Worker 和 Celery Beat 才会生效！**

### 扫描任务包含的内容

每次完整扫描会执行以下操作：
1. **ICMP Ping** - 检测 IP 是否在线
2. **ARP 扫描** - 获取 MAC 地址（同网段有效）
3. **反向 DNS** - 解析主机名
4. **MAC 厂商识别** - 根据 MAC 地址前 3 字节识别厂商
5. **自动更新** - 更新 IP 状态、MAC、主机名、最后发现时间
6. **异常检测** - 触发 IP 冲突、未授权接入等告警检查

### 监控定时任务状态

#### 查看 Celery 活跃任务
```bash
cd /root/ipam/backend
source venv/bin/activate
celery -A app.tasks.celery_app inspect active
```

#### 查看定时任务调度
```bash
celery -A app.tasks.celery_app inspect scheduled
```

#### 查看 Worker 状态
```bash
celery -A app.tasks.celery_app inspect stats
```

---

## 🛠️ 生产环境部署建议

### 使用 Systemd 管理服务（开机自启）

#### 1. 创建 IPAM API 服务
```ini
# /etc/systemd/system/ipam-api.service
[Unit]
Description=IPAM API Service
After=network.target mysql.service redis.service

[Service]
Type=simple
User=root
WorkingDirectory=/root/ipam/backend
Environment="PATH=/root/ipam/backend/venv/bin"
ExecStart=/root/ipam/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8008
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

#### 2. 创建 Celery Worker 服务
```ini
# /etc/systemd/system/ipam-celery-worker.service
[Unit]
Description=IPAM Celery Worker
After=network.target redis.service

[Service]
Type=simple
User=root
WorkingDirectory=/root/ipam/backend
Environment="PATH=/root/ipam/backend/venv/bin"
ExecStart=/root/ipam/backend/venv/bin/celery -A app.tasks.celery_app worker --loglevel=info --concurrency=4
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

#### 3. 创建 Celery Beat 服务
```ini
# /etc/systemd/system/ipam-celery-beat.service
[Unit]
Description=IPAM Celery Beat Scheduler
After=network.target redis.service

[Service]
Type=simple
User=root
WorkingDirectory=/root/ipam/backend
Environment="PATH=/root/ipam/backend/venv/bin"
ExecStart=/root/ipam/backend/venv/bin/celery -A app.tasks.celery_app beat --loglevel=info
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

#### 4. 启用并启动服务
```bash
# 重新加载配置
systemctl daemon-reload

# 启用开机自启
systemctl enable ipam-api ipam-celery-worker ipam-celery-beat

# 启动服务
systemctl start ipam-api ipam-celery-worker ipam-celery-beat

# 查看服务状态
systemctl status ipam-api ipam-celery-worker ipam-celery-beat
```

---

## 🌐 访问地址

| 服务 | 地址 | 说明 |
|------|------|------|
| 管理后台 | `http://服务器IP:3000` | Vue 前端界面 |
| API 服务 | `http://服务器IP:8008` | REST API |
| Swagger 文档 | `http://服务器IP:8008/docs` | API 在线测试文档 |
| Redoc 文档 | `http://服务器IP:8008/redoc` | API 文档 |

**默认管理员账号：**
- 用户名: `admin`
- 密码: `admin123`

---

## 📊 技术栈

| 组件 | 技术选型 | 版本 |
|------|----------|------|
| Web 框架 | FastAPI | 0.115 |
| ORM | SQLAlchemy | 2.0 |
| 数据库 | MySQL | 8.0 |
| 异步任务 | Celery + Redis | 5.4 |
| SNMP | PySNMP | 4.4.12 |
| 密码加密 | Passlib + bcrypt | - |
| JWT 认证 | python-jose | - |
| 前端框架 | Vue 3 + Element Plus | 3.5 / 2.9 |
| 路由 | Vue Router | 4.4 |
| 状态管理 | Pinia | 2.4 |
| HTTP 客户端 | Axios | 1.7 |

---

## 🔐 角色权限矩阵

| 操作 | Viewer (只读) | Operator (操作员) | Admin (管理员) | Super Admin (超级管理员) |
|------|---------------|------------------|----------------|---------------------|
| 查看所有数据 | ✅ | ✅ | ✅ | ✅ |
| 编辑 IP 信息 | ❌ | ✅ | ✅ | ✅ |
| 执行扫描 | ❌ | ✅ | ✅ | ✅ |
| 确认/解决告警 | ❌ | ✅ | ✅ | ✅ |
| 网段管理 | ❌ | ❌ | ✅ | ✅ |
| SNMP 设备/凭据 | ❌ | ❌ | ✅ | ✅ |
| MAC 白名单 | ❌ | ❌ | ✅ | ✅ |
| 导出报表 | ❌ | ❌ | ✅ | ✅ |
| 查看审计日志 | ❌ | ❌ | ✅ | ✅ |
| 用户管理 | ❌ | ❌ | ❌ | ✅ |
| 系统设置 | ❌ | ❌ | ❌ | ✅ |

---

## 📋 API 端点总览

| 模块 | 端点数量 | 主要功能 |
|------|----------|----------|
| 认证 | 10 | 登录、登出、Token刷新、用户管理 |
| 网段管理 | 7 | CRUD、扫描、IP列表、统计 |
| IP 地址 | 5 | 列表、详情、编辑、扫描 |
| 扫描 | 8 | 单IP、网段、异步任务、状态查询 |
| SNMP | 13 | 凭据、设备、轮询、ARP表、接口 |
| 告警 | 11 | 列表、确认/解决/忽略、检测、白名单 |
| 审计日志 | 5 | 日志查询、用户日志、资源历史、统计、清理 |
| 报表 | 6 | CSV导出、汇总统计 |

---

## 💡 常见问题

### Q: 为什么 IP 扫描后 MAC 地址都是空的？
A: ARP 扫描只能获取**同网段**设备的 MAC 地址。跨网段需要配置 SNMP 采集核心交换机的 ARP 表。

### Q: 定时扫描没有执行？
A: 请检查 **Celery Beat** 是否正常启动，Celery Worker 是否正常运行，Redis 连接是否正常。

### Q: 如何临时禁用自动扫描？
A: 停止 Celery Beat 服务即可，不会影响手动触发扫描。

### Q: 如何调整扫描并发数？
A: 启动 Celery Worker 时调整 `--concurrency` 参数：
```bash
celery -A app.tasks.celery_app worker --concurrency=8  # 8并发
```

### Q: 扫描时间太长怎么办？
A: 1. 增加并发数 2. 关闭 DNS 解析（较慢）3. 分网段分时段扫描

---

## 📁 项目结构

```
/root/ipam/
├── backend/
│   ├── app/
│   │   ├── api/v1/           # API 路由
│   │   ├── core/             # 配置、数据库、安全
│   │   ├── models/           # 数据模型
│   │   ├── schemas/          # Pydantic 验证模型
│   │   ├── services/         # 业务逻辑层
│   │   ├── tasks/            # Celery 异步任务
│   │   └── main.py           # 应用入口
│   └── venv/                 # Python 虚拟环境
├── frontend/
│   ├── src/
│   │   ├── views/            # 页面组件
│   │   ├── components/       # 通用组件
│   │   ├── router/           # 路由配置
│   │   └── main.js           # 应用入口
│   └── node_modules/
├── start.sh                   # 一键启动脚本
├── stop.sh                    # 停止服务脚本
├── DEV_PROGRESS.md           # 开发进度文档
└── README.md                  # 本文件
```

---

## 📞 支持

如遇问题，请查看：
1. API 文档：`http://<服务器IP>:8008/docs`
2. 开发进度：`DEV_PROGRESS.md`
3. Celery 日志：查看 Worker 和 Beat 终端输出

---

## 📝 License

MIT License