快速开始

本指南将帮助您快速部署和运行 IPAM 系统。

环境要求

必需组件

组件	版本要求	说明
MariaDB	10.11.14+	数据库（推荐）
或 MySQL	8.0+	数据库
或 PostgreSQL	12+	数据库

支持平台

IPAM 服务端支持以下平台：

平台	架构	下载链接
Linux	amd64	server_linux_amd64
Linux	arm64	server_linux_arm64
Windows	amd64	server_windows_amd64.exe
macOS	amd64	server_darwin_amd64
macOS	arm64	server_darwin_arm64

探针客户端支持以下平台：

平台	架构	下载链接
Linux	amd64	probe_linux_amd64
Linux	arm64	probe_linux_arm64
Windows	amd64	probe_windows_amd64.exe

安装步骤

1. 下载程序

# 创建安装目录
mkdir -p /opt/ipam
cd /opt/ipam

# 下载服务端（以 Linux amd64 为例）
wget https://download.liumou.site/ipam/server_linux_amd64 -O ipam-server
chmod +x ipam-server

# 下载探针客户端（可选，用于分布式扫描）
wget https://download.liumou.site/ipam/probe_linux_amd64 -O ipam-probe
chmod +x ipam-probe

2. 配置数据库

创建数据库

CREATE DATABASE ipam CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER 'ipam_user'@'%' IDENTIFIED BY 'your_strong_password';

GRANT CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, SELECT, INDEX ON ipam.* TO 'ipam_user'@'%';

FLUSH PRIVILEGES;

数据库配置建议

# my.cnf 或 my.ini
[mysqld]
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci
max_connections=200
innodb_buffer_pool_size=256M

3. 配置服务端

创建配置文件

# 使用程序生成配置文件模板
./ipam-server -g

# 编辑配置文件
vi config.toml

编辑配置

生成的配置文件包含详细的中文注释，主要需要修改以下内容：

[database]
type = "mysql"
host = "localhost"
port = 3306
user = "ipam_user"
password = "your_strong_password"
name = "ipam"

[server]
port = 8080
host = "0.0.0.0"
mode = "release"

[jwt]
secret = "your-jwt-secret-key-change-this"

[monitoring]
enabled = true              # 是否启用监控功能（必须启用才能接收探针数据）
interval = 30               # 监控检测间隔（秒）
gateway_timeout = 5         # 网关 Ping 超时时间（秒）
ip_timeout = 3              # IP 地址 Ping 超时时间（秒）
max_concurrent = 100        # 最大并发数
enable_host_scanning = false  # 是否启用主程序全量扫描，默认 false

监控配置说明：

• enabled: 控制监控功能开关，必须启用才能接收探针数据
• enable_host_scanning: 控制主程序是否主动执行 ARP/MAC 扫描
  • false（默认）：主程序不主动扫描，仅接收独立探针客户端上报数据（推荐用于中大型网络）
  • true：主程序主动扫描网络（适合小型单网段环境）

4. 启动服务端

./ipam-server

后端服务将在 http://localhost:8080 启动。

命令行参数（可选）：

参数	说明	示例
-c	指定配置文件路径	-c /etc/ipam/config.toml
-l	设置日志级别	-l debug
-f	指定日志文件	-f /var/log/ipam.log
-p	重置管理员密码	-p
-g	生成配置文件模板	-g
-h	显示帮助信息	-h

5. 访问系统

打开浏览器访问：http://localhost:8080

前端静态文件已嵌入到服务端程序中，无需单独部署前端。

默认账户

系统首次启动时自动创建以下账户：

角色	用户名	密码	权限
管理员	admin	admin123	完整系统管理权限
操作员	operator	operator123	IP管理权限
只读用户	readonly	readonly123	仅查看权限

⚠️ 安全提示：首次登录后请立即修改默认密码！

部署探针客户端（可选）

如需分布式扫描，可在各网段部署探针客户端：

# 1. 在管理界面创建 API 密钥

# 2. 启动探针
./ipam-probe \
  -server http://ipam-server:8080 \
  -apikey your-api-key \
  -subnet 192.168.1.0/24 \
  -interval 60

更多探针配置请参考 网络扫描与监控。

生产部署

部署结构

ipam/
├── ipam-server          # 后端可执行文件
├── ipam-probe           # 探针客户端（可选）
├── config.toml          # 配置文件
└── logs/                # 日志目录

使用 systemd 管理服务

创建 /etc/systemd/system/ipam.service：

[Unit]
Description=IPAM Server
After=network.target

[Service]
Type=simple
User=ipam
WorkingDirectory=/opt/ipam
ExecStart=/opt/ipam/ipam-server
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable ipam
sudo systemctl start ipam

使用 Nginx 反向代理

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

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

常见问题

数据库连接失败

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

解决：

1. 检查数据库服务是否运行
2. 验证配置文件中的连接信息
3. 确认用户权限正确
4. 检查防火墙设置

监控功能不工作

问题：IP 在线状态不更新

解决：

1. 检查配置中 monitoring.enabled 是否为 true
2. 确认运行环境有 ping 权限
3. 检查防火墙是否允许 ICMP
4. 查看日志中的错误信息

探针无法连接服务端

问题：探针客户端无法上报数据

解决：

1. 检查服务端地址和 API 密钥是否正确
2. 确认服务端 monitoring.enabled 为 true
3. 检查防火墙是否允许探针访问服务端端口
4. 查看服务端日志确认错误原因

导入导出失败

问题：Excel 导入导出功能异常

解决：

1. 确认 Excel 格式为 .xlsx
2. 检查 Sheet 名称是否正确
3. 验证数据格式是否符合要求
4. 查看详细的错误提示

下一步

• 配置说明 - 深入了解配置项
• 功能介绍 - 了解系统功能
• 网络扫描与监控 - 配置探针和扫描
• API 文档 - 查看 API 接口文档