【AI全栈】企业级光传输网管系统 (NMS) 本地开发与部署指南 (NMS_Deployment_Guide.md) 企业级光传输网管系统 (NMS) 本地开发与部署指南文档说明本文档记录了基于 C/Go/Next.js 架构的 NMS 网管系统从源码编译、镜像构建到微服务部署的完整流程包含踩坑记录、调试技巧及日常运维 SOP。维护者LucasLC标准作业程序SOP:NMS_Deployment_Guide.md 目录从 0 到 1 部署细节与注意事项核心命令全集调试与日志分析指南日常快速启动与运维 SOP1. 从 0 到 1 部署细节与注意事项1.1 基础环境准备操作系统Windows 10/11 WSL 2 (Ubuntu 24.04) Docker Desktop。Node.js 环境必须降级到 v18.x (如 18.20.4)。⚠️ 避坑指南如果使用 Node 20前端编译时canvas等 C 依赖会报编译错误。使用nvm use 18.20.4切换。Go 环境WSL 中安装 Go 1.20。网络代理由于公司网络封锁必须在 WSL 中配置 Go 代理goenv-wGOPROXYhttps://goproxy.cn,direct1.2 源码编译 (WSL 环境下)进入项目根目录/mnt/d/linux/Controller修复换行符Windows 和 Linux 换行符差异会导致脚本执行失败。dos2unix build.sh build_fixed.shCMake 兼容补丁解决 CMake 版本过低导致的 Policy 报错。sed-is/cmake ${CM_OPTS}/cmake ${CM_OPTS} -DCMAKE_POLICY_VERSION_MINIMUM3.5/gbuild.sh执行编译exportPATH$PATH:$(goenvGOPATH)/bin# 确保 protoc-gen-go 等工具在 PATH 中./build_fixed.sh nms 编译产物成功后会在nmsbuild/目录下生成nms_1.0.0.1_YYYYMMDD.deb(约 146MB)。1.3 构建 Docker 镜像 (核心痛点解决)⚠️ 避坑指南 (GLIBC 问题)原官方镜像nmsimage:1.1基于 Debian 10 (glibc 2.28)而我们在 Ubuntu 24.04 (glibc 2.39) 编译的二进制文件无法在旧镜像中运行会报GLIBC_2.32 not found。解决方案必须基于ubuntu:24.04构建全新的镜像nmsimage:1.2。编写Dockerfile.new安装 supervisor, rabbitmq, redis, rsyslog 等运行时依赖。将编译好的.deb包COPY进新镜像并dpkg -i安装。将旧容器的/etc/supervisor/conf.d/配置文件COPY进新镜像。1.4 微服务依赖链与启动顺序系统采用微服务架构服务之间有严格的依赖关系必须按顺序启动基础中间件MySQL, Nacos, InfluxDB (通过 Docker Compose 或独立容器启动)。NMS 容器内部服务rsyslogd必须最先启动否则 Go 服务如restserver初始化日志时会因找不到 syslog 而闪退。rabbitmqrestserver(Web 服务) 强依赖 RabbitMQ连不上会直接退出。redisneapp(网元管理服务) 强依赖 Redis 获取网元列表连不上会报错。restserverWeb 核心服务监听 8080 端口。neapp,ncsuper,alarmapp等底层网元业务服务。1.5 数据库连通性配置NMS 容器内的服务通过Nacos 配置中心获取数据库连接信息。⚠️ 避坑指南Nacos 中配置的 MySQL 地址如果是127.0.0.1NMS 容器会去连自己内部的数据库通常没有。解决方案登录 Nacos 控制台 (http://localhost:8848/nacos)将数据源 Host 修改为host.docker.internalDocker Desktop 提供的特殊域名指向 Windows 宿主机从而连接到宿主机上运行的go-admin-mysql-1容器。2. 核心命令全集2.1 编译与环境配置 (WSL Ubuntu)# 切换 Node 版本nvm use18.20.4# 配置 Go 代理goenv-wGOPROXYhttps://goproxy.cn,directexportPATH$PATH:$(goenvGOPATH)/bin# 修复脚本并编译dos2unix build.shsed-is/cmake ${CM_OPTS}/cmake ${CM_OPTS} -DCMAKE_POLICY_VERSION_MINIMUM3.5/gbuild.shchmodx build.sh ./build.sh nms2.2 Docker 镜像与容器管理 (Windows PowerShell)# 构建新镜像 (解决 GLIBC 问题)docker build-f Dockerfile.new-t nmsimage:1.2.# 启动基础中间件dockerstartgo-admin-mysql-1 docker-nacos-1 docker-influxdb-1# 启动 NMS 核心容器 (传入必要的环境变量)docker run-d--name docker-nms-1 -p 49159:8080-p 5050:5050-p 5060:5060-p 5070:5070 -p 5672:5672-p 6379:6379-p 830:830 -e NACOShost.docker.internal:8848 -e RBMQ127.0.0.1:5672-e REDIS127.0.0.1:6379 -e NODECOUNT1-e WEB_PROXY/nacoshttp://host.docker.internal:8848;/rbmqhttp://127.0.0.1:15672--cap-addALL nmsimage:1.2# 停止/重启/删除容器docker stop docker-nms-1 docker restart docker-nms-1 dockerrmdocker-nms-12.3 容器内服务管理 (进入容器后执行)# 进入容器dockerexec-itdocker-nms-1bash# Supervisor 服务管理supervisorctl status# 查看所有服务状态supervisorctl start rabbitmq# 启动 RabbitMQsupervisorctl start rsyslogd# 启动 rsyslogsupervisorctl restart restserver# 重启 Web 服务supervisorctl restart neapp# 重启网元服务# 绕过 Supervisor 手动启动 Redis (推荐最稳定)redis-server--daemonizeyes3. 调试与日志分析指南当页面无法访问或数据无法下发时按照以下步骤排查3.1 检查端口监听状态进入容器后使用ss命令检查核心端口是否被正确监听# 检查 Web 服务 (8080), RabbitMQ (5672), Redis (6379)ss-tlnp|grep-E8080|5672|6379预期结果应该看到restserver监听 8080beam.smp(RabbitMQ) 监听 5672redis-server监听 6379。如果缺失说明对应服务没启动使用supervisorctl start 服务名或手动启动。3.2 查看业务日志 (核心排错手段)系统通过 rsyslog 将各个微服务的日志输出到了/var/log/目录下# 查看所有 NMS 业务日志文件ls-la/var/log/nms_*.log# 查看 Web 服务日志 (排查登录、API 报错)tail-50/var/log/nms_restapp.log# 查看网元服务日志 (排查设备连接、数据下发报错)tail-50/var/log/nms_neapp.log# 查看 Supervisor 自身的日志 (排查服务为什么闪退)tail-50/var/log/supervisor/supervisord.log3.3 常见报错与“秒杀”方案报错现象 / 日志关键字根本原因解决方案GLIBC_2.32 not found编译环境(WSL)与运行环境(旧容器) glibc 版本不匹配。必须基于ubuntu:24.04重新docker build构建新镜像。Unix syslog delivery errorrsyslogd服务未启动Go 程序无法写入系统日志。执行supervisorctl start rsyslogd。dial tcp 127.0.0.1:5672: connect: connection refusedRabbitMQ 未启动导致restserver闪退。执行supervisorctl start rabbitmq等待 10 秒后重启restserver。dial tcp 127.0.0.1:6379: connect: connection refusedRedis 未启动导致neapp无法获取网元列表。执行redis-server --daemonize yes然后重启neapp。页面保存数据报错 / 数据库写入失败NMS 容器连不上 MySQL。登录 Nacos (localhost:8848/nacos)将数据库 Host 改为host.docker.internal。cant find command python2Ubuntu 24.04 默认无 python2导致依赖启动脚本失败。执行ln -s /usr/bin/python3 /usr/bin/python2创建软链接。4. 日常快速启动与运维 SOP (每天开机必看)每天上班开机后只需按照以下“四步走”战略即可在3 分钟内恢复整个开发环境。 Step 1: 启动基础中间件 (PowerShell)打开 Windows PowerShell启动数据库和注册中心dockerstartgo-admin-mysql-1 docker-nacos-1 docker-influxdb-1 Step 2: 启动 NMS 核心容器 (PowerShell)启动你亲手构建的 NMS 容器dockerstartdocker-nms-1 Step 3: 容器内“复活”关键服务 (进入容器)由于 Supervisor 的依赖链在冷启动时容易超时失败我们需要手动介入“扶一把”# 1. 进入容器docker exec-it docker-nms-1 bash# 2. 启动 rsyslog (防止其他服务日志报错)supervisorctlstartrsyslogd# 3. 启动 RabbitMQ 并等待supervisorctlstartrabbitmqsleep10# 4. 启动 Redis (最稳定的后台启动方式)redis-server--daemonize yes# 5. 重启核心业务服务让它们重新连接中间件supervisorctl restart restserver supervisorctl restart neapp Step 4: 验证与访问退出容器 (exit)在浏览器中访问http://localhost:49159 附如何让同事访问你的本地环境获取 IP在 PowerShell 执行ipconfig找到你的局域网 IPv4 地址如192.168.1.100。告诉同事让他们访问http://192.168.1.100:49159。放行防火墙如果同事打不开在管理员权限的 PowerShell中执行以下命令放行端口New-NetFirewallRule-DisplayNameAllow NMS Web Port 49159-Direction Inbound-LocalPort 49159-Protocol TCP-Action AllowEveryone以后无论是你自己复习还是带新员工熟悉环境直接把这个 Markdown 甩给他们你就是团队里最硬核的架构师祝你开发愉快