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+

### 一键启动所有服务

#### 方式一：使用启动脚本（推荐）

`start.sh` 目录自适应，无论部署在 `/opt`、`/usr/local`、`/root` 还是其它任意目录，
直接以脚本所在目录为项目根运行即可（需 root 权限）：

```bash
cd /你的部署目录     # 例如 /opt/ipam，跟随你实际的部署路径
bash start.sh
```

运行时会自动：创建 Python venv → 安装后端依赖 → 启动 MySQL/Redis 容器 →
生成 3 个 systemd 服务（backend / celery-worker / celery-beat）并 enable 开机自启 →
启动前端。更多细节见下文「生产环境部署建议」。

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

> ⚠️ 仅供开发调试用。生产环境推荐使用方式一（start.sh），可自动生成 systemd 服务、开机自启、崩溃自动重启。

#### 安装依赖环境
```bash
# 以下 <项目目录> 均指你实际的部署路径，例如 /opt/ipam
cd <项目目录>/backend
source venv/bin/activate
pip install "pysnmp==4.4.12" "pyasn1<0.5.0" "pysmi<0.4.0"
```

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

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

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

##### 4️⃣ 启动前端
```bash
cd <项目目录>/frontend
npm install
npm run dev -- --host 0.0.0.0 --port 3000
```

---

## ⏰ 自动扫描配置

### 扫描频率配置

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

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

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

编辑配置文件：`<项目目录>/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 <项目目录>/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
```

---

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

### 推荐方式：使用 start.sh（自动化，目录自适应）

`start.sh` 已内置完整的生产级部署逻辑，**无需手动创建任何 systemd 单元**：

- **目录自适应**：不硬编码路径，自动以脚本所在目录为项目根。无论部署在
  `/opt/ipam`、`/usr/local/ipam`、`/root/ipam` 还是其它任意目录都能工作。
- **systemd 自动生成**：运行 `start.sh` 时自动生成并 `systemctl enable` 如下
  3 个服务，实现**开机自启** + **崩溃自动重启**（`Restart=always`）：

  | 服务名 | 内容 | 说明 |
  |--------|------|------|
  | `ipam-backend` | uvicorn :8008 | 后端 API |
  | `ipam-celery-worker` | celery worker | 执行扫描/轮询任务 |
  | `ipam-celery-beat` | celery beat | 定时任务调度器（每60秒触发 SNMP 设备自动轮询） |

  日志写入 `/var/log/ipam/*.log`。

#### 首次部署（全新机器）

```bash
# 1. 前置：Python3 / Node.js / Docker 需已安装
# 2. git clone 代码（放到你想要的任何目录）
git clone https://git.cnbugs.com/AI-Agent/ipam.git /opt/ipam
cd /opt/ipam

# 3. 一键启动（需 root 权限，自动装依赖 + 起 MySQL/Redis 容器 + 生成 systemd + 启前端）
bash start.sh
```

启动成功后即可访问：
- 管理界面 `http://服务器IP:3000`
- API 文档 `http://服务器IP:8008/docs`

> 💡 首次运行 `start.sh` 会自动创建 Python venv、安装前端依赖（含 vite）、
> 启动 MySQL/Redis Docker 容器、生成 3 个 systemd 服务并 enable 开机自启，
> 全程无需人工干预。若部署目录想换到别处，把项目整个复制过去再跑一次
> `bash start.sh` 即可自动重写 systemd 单元。

#### 服务管理命令

```bash
# 启动 / 停止 / 重启
bash start.sh
bash stop.sh

# 查看状态（开机自启 + 运行中）
systemctl status ipam-backend ipam-celery-worker ipam-celery-beat

# 查看日志
tail -f /var/log/ipam/ipam-backend.log
tail -f /var/log/ipam/ipam-celery-worker.log
tail -f /var/log/ipam/ipam-celery-beat.log
```

---

### 生产服务器更新流程（git 部署时）

生产代码是通过 `git clone` 放上去的，日常更新用 `git pull` 拉取远端最新代码，
再重启服务即可。**推荐更新流程**：

```bash
cd /你的部署目录            # 例如 /opt/ipam，跟随你实际的部署路径

# 1.（可选）备份当前脚本，防止意外
cp start.sh /tmp/start.sh.bak

# 2. 拉取远端最新代码（含全部修复：单IP扫描、SNMP自动轮询、告警检测、部署脚本）
git pull origin master

# 3. 重启服务让新代码生效（需 root）
#    - 后端 / Celery Worker / Celery Beat 是 systemd 管理，重启它们即可
systemctl restart ipam-backend ipam-celery-worker ipam-celery-beat

#    - 前端 vite dev server 是 nohup 方式，需手动重启：
pkill -f "vite" ; sleep 2
cd frontend && nohup npm run dev -- --host 0.0.0.0 --port 3000 > /tmp/ipam-frontend.log 2>&1 &

# 4. 全量一键启动（更省心：自动检测目录重新生成 systemd + 拉起全部服务）
#    bash start.sh

# 5. 验证服务全部正常
systemctl is-active ipam-backend ipam-celery-worker ipam-celery-beat   # 应输出 3 个 active
curl -s http://localhost:8008/health                                   # 后端健康
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000           # 前端 200
```

**更新要点：**

1. **后端 / Celery 是 systemd 管理**（ipam-backend / ipam-celery-worker /
   ipam-celery-beat），更新代码后只需 `systemctl restart` 这三个服务，
   它们会保持开机自启和崩溃自动重启。
2. **前端是 nohup 方式**（vite dev server，开发服务不纳入 systemd），需要
   `pkill -f vite` 后重新 `npm run dev` 启动。
3. **依赖变更时**：若 `git pull` 拉取后要求新 Python 包，执行
   `cd backend && venv/bin/pip install -r requirements.txt`；
   前端依赖变化则 `cd frontend && npm install --include=dev`。
4. **若你切换了部署目录**（从 /opt 挪到 /usr/local 等），直接在新位置跑一次
   `bash start.sh`，它会自动按新目录重新生成 systemd 单元，无需手动改任何配置。
5. **首次部署到新机器**建议直接跑 `bash start.sh`（一键全自动），日常增量更新
   用第 2~4 步的重启方式即可，两者效果一致。


---

## 🌐 访问地址

| 服务 | 地址 | 说明 |
|------|------|------|
| 管理后台 | `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. 分网段分时段扫描

---

## 📁 项目结构

```
<项目目录>/            # 例如 /opt/ipam、/usr/local/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