️ NMS 开发环境完整搭建指南WSL Docker 版文档说明本文档详细记录了在 Windows 环境下搭建 NMS 网管系统开发环境的完整流程特别区分了公司内网环境和本地外挂手机热点/家庭网络环境的差异配置。适用场景内网开发环境公司网络有 HTTPS 拦截、代理限制本地外挂环境手机热点、家庭宽带可直连外网维护者LucasLC最后更新2026年6月30日 目录环境架构总览Windows 基础环境搭建WSL 2 Ubuntu 安装Docker Desktop 安装与配置Ubuntu 内部工具链搭建网络环境差异化配置项目代码准备环境验证常见问题排查1. 环境架构总览1.1 技术栈要求组件版本要求用途Windows10 (21H2) / 11宿主机WSL 2最新版Linux 子系统Ubuntu24.04 LTS编译环境glibc 2.39Docker Desktop最新版容器运行时Node.js18.x (推荐 18.20.4)前端编译Go1.20后端编译CMake3.16C 编译GCC/G9C 编译Protobuf3.x协议编译1.2 环境架构图┌─────────────────────────────────────────────────────┐ │ Windows 10/11 宿主机 │ │ │ │ ┌───────────────────────────────────────────────┐ │ │ │ WSL 2 (Ubuntu 24.04) │ │ │ │ ├─ Node.js 18.20.4 (nvm 管理) │ │ │ │ ├─ Go 1.26 │ │ │ │ ├─ CMake, GCC, G, Make │ │ │ │ ├─ Protobuf Compiler │ │ │ │ └─ 项目源码 /mnt/d/linux/Controller │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────┐ │ │ │ Docker Desktop │ │ │ │ ├─ docker-nms-1 (NMS 核心系统) │ │ │ │ ├─ go-admin-mysql-1 (MySQL 8.0) │ │ │ │ ├─ docker-nacos-1 (Nacos 配置中心) │ │ │ │ └─ docker-influxdb-1 (InfluxDB 时序库) │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ 浏览器 ──► http://localhost:49159 (Web 界面) │ └─────────────────────────────────────────────────────┘1.3 内网 vs 本地外挂环境对比场景网络特点配置重点内网开发HTTPS 拦截、GitHub 不通、npm 慢必须配置代理Go/npm/apt本地外挂直连外网、速度快无需代理可直接下载2. Windows 基础环境搭建2.1 启用 WSL 2 功能以管理员身份运行 PowerShell# 启用 WSL 功能dism.exe/online/enable-feature/featurename:Microsoft-Windows-Subsystem-Linux/all/norestart# 启用虚拟机平台dism.exe/online/enable-feature/featurename:VirtualMachinePlatform/all/norestart# 重启电脑Restart-Computer2.2 安装 WSL 2 内核更新包重启后下载并安装 WSL 2 Linux 内核更新包下载地址https://aka.ms/wsl2kernel双击安装2.3 设置 WSL 2 为默认版本wsl--set-default-version 22.4 安装 Ubuntu 24.04# 方式 1通过 Microsoft Store 安装推荐内网用户# 打开 Microsoft Store搜索 Ubuntu 24.04 LTS点击安装# 方式 2通过命令行安装本地外挂用户wsl--install-d Ubuntu-24.04首次启动 Ubuntu设置用户名建议lucaslcliu或你的名字设置密码记住这个密码后面 sudo 要用2.5 验证 WSL 安装# 查看已安装的发行版wsl-l-v# 预期输出# NAME STATE VERSION# * Ubuntu-24.04 Running 23. WSL 2 Ubuntu 安装3.1 进入 Ubuntu# 方式 1命令行进入wsl-d Ubuntu-24.04# 方式 2在开始菜单找到 Ubuntu 24.04 点击打开3.2 更新系统# 更新软件包列表sudoaptupdate# 升级已安装的软件包sudoaptupgrade-y3.3 安装基础工具sudoaptinstall-y\build-essential\curl\wget\git\vim\dos2unix\unzip\zip\ca-certificates\gnupg\lsb-release\software-properties-common3.4 验证安装gcc--version# 应显示 gcc 13.xgit--version# 应显示 git 2.x4. Docker Desktop 安装与配置4.1 下载 Docker Desktop官网下载https://www.docker.com/products/docker-desktop/内网用户可能需要通过公司内部软件中心安装4.2 安装 Docker Desktop双击安装包按提示安装关键选项勾选 “Use WSL 2 based engine”安装完成后重启电脑4.3 启用 WSL 2 集成打开 Docker Desktop点击右上角设置 (齿轮图标)进入Resources → WSL Integration启用“Enable integration with my default WSL distro”在下方的发行版列表中打开 Ubuntu-24.04 的开关点击Apply Restart4.4 验证 Docker 在 WSL 中可用# 在 Ubuntu 中执行docker--versiondockerrun hello-world预期输出Docker version 24.x.x, build xxxxxxx Hello from Docker! This message shows that your installation appears to be working correctly.4.5 配置 Docker 镜像加速内网用户可选如果拉取镜像慢可以配置国内镜像源# 创建 daemon.jsonsudomkdir-p/etc/dockersudotee/etc/docker/daemon.json-EOF { registry-mirrors: [ https://docker.m.daocloud.io, https://dockerhub.azk8s.cn, https://hub-mirror.c.163.com ] } EOF# 重启 Dockersudosystemctl restartdocker5. Ubuntu 内部工具链搭建5.1 安装 Node.js (使用 nvm)为什么用 nvm因为项目需要 Node.js 18.x而系统默认可能是 20nvm 可以灵活切换版本。# 安装 nvmcurl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh|bash# 重新加载 shell 配置source~/.bashrc# 验证 nvm 安装nvm--version# 安装 Node.js 18.20.4项目指定版本nvminstall18.20.4# 设置为默认版本nvmaliasdefault18.20.4 nvm use18.20.4# 验证node--version# 应显示 v18.20.4npm--version# 应显示 10.x.x5.2 安装 Go# 方式 1通过 apt 安装简单但版本可能较旧sudoaptinstall-ygolang# 方式 2手动安装最新版推荐# 访问 https://go.dev/dl/ 下载最新版wgethttps://go.dev/dl/go1.22.5.linux-amd64.tar.gzsudorm-rf/usr/local/gosudotar-C/usr/local-xzfgo1.22.5.linux-amd64.tar.gz# 配置环境变量echoexport PATH$PATH:/usr/local/go/bin~/.bashrcechoexport PATH$PATH:$(go env GOPATH)/bin~/.bashrcsource~/.bashrc# 验证go version# 应显示 go1.22.x5.3 安装 CMake 和其他编译工具sudoaptinstall-y\cmake\make\protobuf-compiler\libprotobuf-dev验证cmake--version# 应显示 3.x.xprotoc--version# 应显示 libprotoc 3.x.x5.4 安装 Go 的 protobuf 插件goinstallgoogle.golang.org/protobuf/cmd/protoc-gen-golatest goinstallgoogle.golang.org/grpc/cmd/protoc-gen-go-grpclatest6. 网络环境差异化配置核心重点6.1 内网开发环境配置特点公司网络有 HTTPS 拦截GitHub、Docker Hub 访问慢或被拦截npm、Go 模块下载失败6.1.1 Go 代理配置必须# 配置 Go 使用国内代理goenv-wGOPROXYhttps://goproxy.cn,direct goenv-wGOSUMDBsum.golang.google.cn# 验证goenvGOPROXY# 应显示 https://goproxy.cn,direct6.1.2 npm 镜像配置必须# 使用淘宝镜像npmconfigsetregistry https://registry.npmmirror.com# 验证npmconfig get registry# 应显示 https://registry.npmmirror.com/6.1.3 apt 源配置可选如果系统更新慢可以换阿里云源# 备份原配置sudocp/etc/apt/sources.list /etc/apt/sources.list.bak# 替换为阿里云源Ubuntu 24.04 是 noblesudosed-is|http://archive.ubuntu.com|https://mirrors.aliyun.com|g/etc/apt/sources.listsudosed-is|http://security.ubuntu.com|https://mirrors.aliyun.com|g/etc/apt/sources.list# 更新sudoaptupdate6.1.4 Git 代理配置如果公司需要# 如果公司有 HTTP 代理问 IT 部门要代理地址gitconfig--globalhttp.proxy http://proxy.company.com:8080gitconfig--globalhttps.proxy http://proxy.company.com:8080# 取消代理gitconfig--global--unsethttp.proxygitconfig--global--unsethttps.proxy6.1.5 Docker 镜像拉取失败的处理方案 A使用手机热点临时下载# 1. 电脑连接手机热点# 2. 在 WSL 中拉取镜像dockerpull ubuntu:24.04dockerpull mysql:8.0dockerpull nacos/nacos-server:v2.1.1dockerpull influxdb:latest# 3. 切回公司网络方案 B使用离线镜像包让有外网的同事帮忙导出镜像docker save -o nacos.tar nacos/nacos-server:v2.1.1通过 U 盘拷贝到你的电脑导入镜像docker load -i nacos.tar6.2 本地外挂环境配置特点直连外网速度快无需代理配置可以直接访问 GitHub、Docker Hub6.2.1 Go 配置可选代理# 直连外网可以不配置代理但配置了也无妨goenv-wGOPROXYhttps://goproxy.cn,direct6.2.2 npm 配置可选镜像# 直连外网可以用官方源npmconfigsetregistry https://registry.npmjs.org/# 或者继续用淘宝镜像国内速度更快npmconfigsetregistry https://registry.npmmirror.com6.2.3 直接拉取 Docker 镜像# 直接拉取无需任何配置dockerpull ubuntu:24.04dockerpull mysql:8.0dockerpull nacos/nacos-server:v2.1.1dockerpull influxdb:latest6.3 网络环境切换速查表操作内网环境本地外挂环境Go 代理go env -w GOPROXYhttps://goproxy.cn,direct可选建议保留npm 镜像npm config set registry https://registry.npmmirror.com可用官方源或镜像apt 源建议换阿里云源默认即可Docker 镜像需要镜像加速或离线包直接 pullGit 代理可能需要配置公司代理不需要7. 项目代码准备7.1 克隆项目代码# 创建项目目录mkdir-p/mnt/d/linuxcd/mnt/d/linux# 克隆代码内网用户可能需要配置 Git 代理gitclone你的项目仓库地址Controller# 进入项目目录cdController7.2 修复脚本换行符关键Windows 和 Linux 的换行符不同会导致脚本执行失败# 修复所有 .sh 脚本的换行符find.-name*.sh-execdos2unix{}\;# 或者手动修复关键脚本dos2unix build.sh dos2unix build_fixed.sh7.3 应用 CMake 兼容补丁# 解决 CMake 版本策略报错sed-is/cmake ${CM_OPTS}/cmake ${CM_OPTS} -DCMAKE_POLICY_VERSION_MINIMUM3.5/gbuild.sh8. 环境验证8.1 一键验证脚本在 Ubuntu 中执行以下命令检查所有环境是否就绪echo 环境验证 echo1. WSL 版本:cat/proc/version|grep-oLinux version [^ ]*echoecho2. Node.js:node--versionechoecho3. npm:npm--versionechoecho4. Go:go versionechoecho5. Go 代理:goenvGOPROXYechoecho6. Docker:docker--versionechoecho7. CMake:cmake--version|head-1echoecho8. GCC:gcc--version|head-1echoecho9. Protobuf:protoc--versionechoecho10. Git:git--versionechoecho11. npm 镜像:npmconfig get registryechoecho 验证完成 8.2 预期输出 环境验证 1. WSL 版本: Linux version 5.15.xxx-x-microsoft-standard-WSL2 2. Node.js: v18.20.4 3. npm: 10.x.x 4. Go: go version go1.22.x linux/amd64 5. Go 代理: https://goproxy.cn,direct 6. Docker: Docker version 24.x.x 7. CMake: cmake version 3.x.x 8. GCC: gcc (Ubuntu 13.x.x) 13.x.x 9. Protobuf: libprotoc 3.x.x 10. Git: git version 2.x.x 11. npm 镜像: https://registry.npmmirror.com/ 验证完成 8.3 验证 Docker 镜像拉取# 测试拉取一个小镜像dockerpull alpine:latest# 如果成功说明 Docker 配置正常# 如果失败检查网络配置或镜像加速9. 常见问题排查9.1 ❌ WSL 无法启动现象WSL 2 需要更新其内核组件解决# 在 PowerShell 中执行wsl--update wsl--shutdown wsl9.2 ❌ Docker 在 WSL 中不可用现象Cannot connect to the Docker daemon at unix:///var/run/docker.sock解决确保 Docker Desktop 正在运行进入 Docker Desktop → Settings → Resources → WSL Integration启用 Ubuntu-24.04 的开关在 WSL 中执行sudo service docker restart9.3 ❌ npm install 失败内网环境现象npm ERR! network request to https://registry.npmjs.org/... failed解决# 切换到淘宝镜像npmconfigsetregistry https://registry.npmmirror.com# 清除缓存重试npmcache clean--forcenpminstall9.4 ❌ Go 依赖下载失败现象go: downloading ... tls: failed to verify certificate解决# 配置 Go 代理goenv-wGOPROXYhttps://goproxy.cn,direct# 清除模块缓存go clean-modcache# 重新下载go mod download9.5 ❌ Node.js 版本不对现象Error: The engine node is incompatible with this module. Expected version 18.x.解决# 切换到 18.20.4nvminstall18.20.4 nvm use18.20.4 nvmaliasdefault18.20.4# 验证node--version# 应显示 v18.20.49.6 ❌ 脚本执行报/bin/bash^M: bad interpreter原因Windows 换行符 (CRLF) 和 Linux 换行符 (LF) 不兼容解决# 修复单个脚本dos2unix build.sh# 批量修复所有 .sh 脚本find.-name*.sh-execdos2unix{}\;9.7 ❌ Docker 镜像拉取超时内网环境解决# 方式 1配置镜像加速参考 4.5 节# 方式 2使用手机热点临时下载# 1. 断开公司网络# 2. 连接手机热点# 3. 拉取镜像dockerpull镜像名# 4. 切回公司网络9.8 ❌ WSL 磁盘空间不足现象no space left on device解决# 在 PowerShell 中查看 WSL 磁盘占用wsl--system df-h# 清理 Docker 无用镜像docker system prune-a# 清理 apt 缓存sudo apt clean sudo apt autoremove# 如果还是不够可以扩展 WSL 虚拟磁盘# 参考https://learn.microsoft.com/en-us/windows/wsl/disk-space 附录快速配置脚本一键执行A.1 本地外挂环境一键配置将以下内容保存为setup_local.sh在 Ubuntu 中执行#!/bin/bashset-eecho 开始配置本地外挂开发环境...# 1. 更新系统echo 更新系统...sudoaptupdatesudoaptupgrade-y# 2. 安装基础工具echo 安装基础工具...sudoaptinstall-y\build-essentialcurlwgetgitvimdos2unix\unzipzipca-certificates gnupg lsb-release\cmakemakeprotobuf-compiler libprotobuf-dev# 3. 安装 nvm Node.js 18echo 安装 Node.js 18...curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh|bashsource~/.bashrc nvminstall18.20.4 nvmaliasdefault18.20.4 nvm use18.20.4# 4. 安装 Goecho 安装 Go...wgethttps://go.dev/dl/go1.22.5.linux-amd64.tar.gzsudorm-rf/usr/local/gosudotar-C/usr/local-xzfgo1.22.5.linux-amd64.tar.gzechoexport PATH$PATH:/usr/local/go/bin~/.bashrcechoexport PATH$PATH:$(go env GOPATH)/bin~/.bashrcsource~/.bashrc# 5. 配置 Go 代理国内加速goenv-wGOPROXYhttps://goproxy.cn,direct goenv-wGOSUMDBsum.golang.google.cn# 6. 配置 npm 镜像npmconfigsetregistry https://registry.npmmirror.com# 7. 安装 Go protobuf 插件goinstallgoogle.golang.org/protobuf/cmd/protoc-gen-golatest goinstallgoogle.golang.org/grpc/cmd/protoc-gen-go-grpclatestecho✅ 配置完成echoecho请验证环境echo node --versionecho go versionecho docker --versionA.2 内网环境一键配置将以下内容保存为setup_corp.sh在 Ubuntu 中执行#!/bin/bashset-eecho 开始配置内网开发环境...# 1. 换阿里云 apt 源echo 更换 apt 源...sudocp/etc/apt/sources.list /etc/apt/sources.list.baksudosed-is|http://archive.ubuntu.com|https://mirrors.aliyun.com|g/etc/apt/sources.listsudosed-is|http://security.ubuntu.com|https://mirrors.aliyun.com|g/etc/apt/sources.list# 2. 更新系统echo 更新系统...sudoaptupdatesudoaptupgrade-y# 3. 安装基础工具echo 安装基础工具...sudoaptinstall-y\build-essentialcurlwgetgitvimdos2unix\unzipzipca-certificates gnupg lsb-release\cmakemakeprotobuf-compiler libprotobuf-dev# 4. 安装 nvm Node.js 18echo 安装 Node.js 18...curl-o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh|bashsource~/.bashrc nvminstall18.20.4 nvmaliasdefault18.20.4 nvm use18.20.4# 5. 安装 Goecho 安装 Go...wgethttps://golang.google.cn/dl/go1.22.5.linux-amd64.tar.gzsudorm-rf/usr/local/gosudotar-C/usr/local-xzfgo1.22.5.linux-amd64.tar.gzechoexport PATH$PATH:/usr/local/go/bin~/.bashrcechoexport PATH$PATH:$(go env GOPATH)/bin~/.bashrcsource~/.bashrc# 6. 配置 Go 代理内网必须goenv-wGOPROXYhttps://goproxy.cn,direct goenv-wGOSUMDBsum.golang.google.cn# 7. 配置 npm 镜像内网必须npmconfigsetregistry https://registry.npmmirror.com# 8. 安装 Go protobuf 插件goinstallgoogle.golang.org/protobuf/cmd/protoc-gen-golatest goinstallgoogle.golang.org/grpc/cmd/protoc-gen-go-grpclatest# 9. 配置 Docker 镜像加速echo 配置 Docker 镜像加速...sudomkdir-p/etc/dockersudotee/etc/docker/daemon.json-EOF { registry-mirrors: [ https://docker.m.daocloud.io, https://hub-mirror.c.163.com ] } EOFecho✅ 内网环境配置完成echoecho⚠️ 注意事项echo 1. Docker 镜像拉取失败时可临时切换手机热点下载echo 2. 如果 Git 需要代理请联系 IT 部门获取代理地址echo 3. 验证环境node --version go version docker --version 下一步环境搭建完成后请参考《NMS 企业级网管系统从 0 到 1 史诗级部署全记录》- 编译和部署的详细流程《NMS_Deployment_Guide.md》- 日常运维 SOP 和命令速查文档版本v1.0最后更新2026年6月30日维护者LucasLC 环境搭建完成你已经具备了开始 NMS 开发的所有条件