开源TR-069 ACS（自动配置服务器）GenieACS 的四个主要模块详细介绍

GenieACS 是一个开源的 TR-069（CWMP）自动配置服务器（ACS），广泛用于管理宽带终端设备（如光猫、机顶盒、路由器等）。它采用模块化设计，共分为四个核心模块：genieacs-cwmp 、genieacs-nbi 、genieacs-fs 和 genieacs-ui。每个模块独立运行，通过 MongoDB 和 Redis 共享数据。下面分别详细说明每个模块的功能、配置和使用方式。

1. genieacs-cwmp（CWMP Server）

功能：

这是 GenieACS 的核心模块，负责处理 CPE（终端设备）发起的 TR-069 协议会话。
接收和响应 Inform、GetParameterValues、SetParameterValues、Download、Reboot 等 RPC 请求。
维护设备会话状态，执行预设（Presets）、任务（Tasks）和虚拟参数（Virtual Parameters）的逻辑。
支持 Connection Request（主动唤醒设备），实现 ACS 主动下发指令。
与 MongoDB 交互存储设备数据、会话历史，与 Redis 缓存实时状态。

配置（主要配置文件：config.json 或环境变量）：

CWMP_INTERFACE / CWMP_PORT：监听接口和端口（默认 7547，SSL 可配 7557）。
CWMP_SSL：是否启用 HTTPS（需提供证书）。
CONNECTION_REQUEST_PORT：Connection Request 监听端口（默认 3000）。
MAX_WORKERS：处理并发会话的工作进程数（建议根据服务器性能设置）。
LOG_LEVEL：日志级别（debug/info/error）。
MongoDB/Redis 连接字符串：MONGODB_CONNECTION_URL、REDIS_URL。

示例环境变量：

bash 复制代码

export CWMP_PORT=7547
export CONNECTION_REQUEST_PORT=3000
export MONGODB_CONNECTION_URL=mongodb://localhost:27017/genieacs
export REDIS_URL=redis://localhost:6379/0

使用：

启动命令：genieacs-cwmp（或使用 PM2/Systemd）。
CPE 必须在设备端配置 ACS URL 为 http://your-server:7547/（或 HTTPS）。
支持大量并发（数万设备），适合生产环境核心服务。
调试时可查看日志中的会话交互细节。

2. genieacs-nbi（Northbound Interface）

功能：

提供 RESTful API（北向接口），用于外部系统（如 OSS/BSS、前端页面、脚本）对设备进行批量管理。
支持设备查询、参数读取/设置、任务下发、固件升级、批量操作、事件订阅（Webhook）等。
API 路径通常为 /devices、/tasks、/presets、/files 等。
支持过滤器（强大的查询语法，如 SerialNumber: "123*" AND SoftwareVersion: "1.0"）。
可触发 Provision（脚本）执行复杂逻辑。

配置：

NBI_INTERFACE / NBI_PORT：监听接口和端口（默认 7557）。
NBI_SSL：是否启用 HTTPS。
AUTHENTICATION：API 认证方式（基本认证、JWT 等，可通过 config 或环境变量配置用户）。
同样需要 MongoDB/Redis 连接。

示例：

bash 复制代码

export NBI_PORT=7557
export USERNAME=admin
export PASSWORD=supersecret

使用：

启动命令：genieacs-nbi。

示例 API 调用（使用 curl）：

bash 复制代码

# 查询所有设备
curl -u admin:supersecret http://localhost:7557/devices

# 对设备下发 GetParameterValues
curl -u admin:supersecret -X POST http://localhost:7557/devices/123456/tasks \
     -d '{"name": "getParameterValues", "parameterNames": ["InternetGatewayDevice.DeviceInfo.SerialNumber"]}'

# 添加固件升级任务
curl -u admin:supersecret -X POST http://localhost:7557/devices/?query=ModelName:"ABC" \
     -d '{"name": "download", "file": "firmware-v2.bin"}'

常用于与第三方系统集成或自定义前端调用。

3. genieacs-fs（File Server）

功能：

专用的文件服务模块，用于向 CPE 提供固件、配置文件、脚本等文件的 HTTP 下载。
支持文件元数据管理（版本、设备类型匹配）。
在 Download RPC 中，ACS 会返回该模块的下载 URL，CPE 再从此模块下载文件。
支持文件缓存、断点续传（部分设备支持）和访问日志。

配置：

FS_INTERFACE / FS_PORT：监听端口（默认 7567）。
FS_SSL：是否启用 HTTPS。
DOWNLOAD_TIMEOUT：下载超时时间。
文件存储路径：默认 ./files，可通过 FILES_DIRECTORY 指定。

示例：

bash 复制代码

export FS_PORT=7567
export FILES_DIRECTORY=/var/genieacs/files

使用：

启动命令：genieacs-fs。
将固件或配置文件放入文件目录（或通过 API 上传）。

通过 NBI API 注册文件：

bash 复制代码

curl -u admin:supersecret -X POST http://localhost:7557/files \
     -F "file=@firmware-v2.bin" \
     -F "metadata={\"version\": \"2.0\", \"deviceType\": \"ONT\"}"

在任务中引用文件名即可触发下载。

4. genieacs-ui（User Interface）

功能：

官方提供的 Web 图形化管理界面（基于 React）。
提供设备列表、实时参数查看、任务下发、固件管理、预设配置、图表统计、日志查看等功能。
支持多用户权限（管理员/只读）。
通过调用 NBI API 实现所有操作，适合运维人员日常使用。

配置：

UI_PORT：Web 服务端口（默认 3000）。
JWT_SECRET：用于用户登录的 JWT 密钥。
NBI_URL：指向 genieacs-nbi 的地址（默认 http://localhost:7557）。

示例环境变量：

bash 复制代码

export UI_PORT=3000
export JWT_SECRET=your_very_secure_secret
export NBI_URL=http://localhost:7557

使用：

构建并启动：先 npm install && npm run build，然后 genieacs-ui（或使用 Docker）。
访问地址：http://your-server:3000。
默认管理员账号：admin / secret（首次登录后建议修改）。
主要页面：
- Devices：设备列表、搜索、批量操作。
- Presets/Provision：配置自动化脚本。
- Files：固件/文件管理。
- Tasks：查看任务执行状态。
- Dashboard：概览统计。

总结

四个模块相互独立，可分别部署在不同服务器上（推荐生产环境分离 cwmp 和其他模块以提升安全性）。
所有模块共享同一个 MongoDB（存储设备数据、任务、预设等）和 Redis（缓存、会话状态）。
典型部署方式：使用 Docker Compose 或 PM2 + Systemd 管理服务。
官方文档：https://docs.genieacs.com