【AI全栈】NMS 开发环境完整搭建指南（WSL + Docker 版）-平芜编程栈

🛠️ NMS 开发环境完整搭建指南（WSL + Docker 版）

文档说明：本文档详细记录了在 Windows 环境下搭建 NMS 网管系统开发环境的完整流程，特别区分了公司内网环境和本地外挂（手机热点/家庭网络）环境的差异配置。
适用场景：
🏢内网开发环境：公司网络，有 HTTPS 拦截、代理限制
🏠本地外挂环境：手机热点、家庭宽带，可直连外网
维护者：LucasLC
最后更新：2026年6月30日

📑 目录

环境架构总览
Windows 基础环境搭建
WSL 2 + Ubuntu 安装
Docker Desktop 安装与配置
Ubuntu 内部工具链搭建
网络环境差异化配置
项目代码准备
环境验证
常见问题排查

1. 环境架构总览

1.1 技术栈要求

组件	版本要求	用途
Windows	10 (21H2+) / 11	宿主机
WSL 2	最新版	Linux 子系统
Ubuntu	24.04 LTS	编译环境（glibc 2.39）
Docker Desktop	最新版	容器运行时
Node.js	18.x (推荐 18.20.4)	前端编译
Go	1.20+	后端编译
CMake	3.16+	C++ 编译
GCC/G++	9+	C++ 编译
Protobuf	3.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-Computer

2.2 安装 WSL 2 内核更新包

重启后，下载并安装 WSL 2 Linux 内核更新包：

下载地址：https://aka.ms/wsl2kernel
双击安装

2.3 设置 WSL 2 为默认版本

wsl--set-default-version 2

2.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 2

3. WSL 2 + Ubuntu 安装

3.1 进入 Ubuntu

# 方式 1：命令行进入wsl-d Ubuntu-24.04# 方式 2：在开始菜单找到 Ubuntu 24.04 点击打开

3.2 更新系统

# 更新软件包列表sudoaptupdate# 升级已安装的软件包sudoaptupgrade-y

3.3 安装基础工具

sudoaptinstall-y\build-essential\curl\wget\git\vim\dos2unix\unzip\zip\ca-certificates\gnupg\lsb-release\software-properties-common

3.4 验证安装

gcc--version# 应显示 gcc 13.xgit--version# 应显示 git 2.x

4. 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 & Restart

4.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 restartdocker

5. Ubuntu 内部工具链搭建

5.1 安装 Node.js (使用 nvm)

为什么用 nvm？因为项目需要 Node.js 18.x，而系统默认可能是 20+，nvm 可以灵活切换版本。

# 安装 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.x

5.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# 配置环境变量echo'export PATH=$PATH:/usr/local/go/bin'>>~/.bashrcecho'export PATH=$PATH:$(go env GOPATH)/bin'>>~/.bashrcsource~/.bashrc# 验证go version# 应显示 go1.22.x

5.3 安装 CMake 和其他编译工具

sudoaptinstall-y\cmake\make\protobuf-compiler\libprotobuf-dev

验证：

cmake--version# 应显示 3.x.xprotoc--version# 应显示 libprotoc 3.x.x

5.4 安装 Go 的 protobuf 插件

goinstallgoogle.golang.org/protobuf/cmd/protoc-gen-go@latest goinstallgoogle.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

6. 网络环境差异化配置（核心重点）

6.1 🏢 内网开发环境配置

特点：

公司网络有 HTTPS 拦截
GitHub、Docker Hub 访问慢或被拦截
npm、Go 模块下载失败

6.1.1 Go 代理配置（必须）

# 配置 Go 使用国内代理goenv-wGOPROXY=https://goproxy.cn,direct goenv-wGOSUMDB=sum.golang.google.cn# 验证goenvGOPROXY# 应显示 https://goproxy.cn,direct

6.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 是 noble）sudosed-i's|http://archive.ubuntu.com|https://mirrors.aliyun.com|g'/etc/apt/sources.listsudosed-i's|http://security.ubuntu.com|https://mirrors.aliyun.com|g'/etc/apt/sources.list# 更新sudoaptupdate

6.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.proxy

6.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.tar

6.2 🏠 本地外挂环境配置

特点：

直连外网，速度快
无需代理配置
可以直接访问 GitHub、Docker Hub

6.2.1 Go 配置（可选代理）

# 直连外网可以不配置代理，但配置了也无妨goenv-wGOPROXY=https://goproxy.cn,direct

6.2.2 npm 配置（可选镜像）

# 直连外网可以用官方源npmconfigsetregistry https://registry.npmjs.org/# 或者继续用淘宝镜像（国内速度更快）npmconfigsetregistry https://registry.npmmirror.com

6.2.3 直接拉取 Docker 镜像

# 直接拉取，无需任何配置dockerpull ubuntu:24.04dockerpull mysql:8.0dockerpull nacos/nacos-server:v2.1.1dockerpull influxdb:latest

6.3 🔄 网络环境切换速查表

操作	内网环境	本地外挂环境
Go 代理	`go env -w GOPROXY=https://goproxy.cn,direct`	可选，建议保留
npm 镜像	`npm config set registry https://registry.npmmirror.com`	可用官方源或镜像
apt 源	建议换阿里云源	默认即可
Docker 镜像	需要镜像加速或离线包	直接 pull
Git 代理	可能需要配置公司代理	不需要

7. 项目代码准备

7.1 克隆项目代码

# 创建项目目录mkdir-p/mnt/d/linuxcd/mnt/d/linux# 克隆代码（内网用户可能需要配置 Git 代理）gitclone<你的项目仓库地址>Controller# 进入项目目录cdController

7.2 修复脚本换行符（关键！）

Windows 和 Linux 的换行符不同，会导致脚本执行失败：

# 修复所有 .sh 脚本的换行符find.-name"*.sh"-execdos2unix{}\;# 或者手动修复关键脚本dos2unix build.sh dos2unix build_fixed.sh

7.3 应用 CMake 兼容补丁

# 解决 CMake 版本策略报错sed-i's/cmake ${CM_OPTS}/cmake ${CM_OPTS} -DCMAKE_POLICY_VERSION_MINIMUM=3.5/g'build.sh

8. 环境验证

8.1 一键验证脚本

在 Ubuntu 中执行以下命令，检查所有环境是否就绪：

echo"========== 环境验证 =========="echo"1. WSL 版本:"cat/proc/version|grep-o"Linux version [^ ]*"echo""echo"2. Node.js:"node--versionecho""echo"3. npm:"npm--versionecho""echo"4. Go:"go versionecho""echo"5. Go 代理:"goenvGOPROXYecho""echo"6. Docker:"docker--versionecho""echo"7. CMake:"cmake--version|head-1echo""echo"8. GCC:"gcc--version|head-1echo""echo"9. Protobuf:"protoc--versionecho""echo"10. Git:"git--versionecho""echo"11. npm 镜像:"npmconfig get registryecho""echo"========== 验证完成 =========="

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 wsl

9.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 restart

9.3 ❌ npm install 失败（内网环境）

现象：

npm ERR! network request to https://registry.npmjs.org/... failed

解决：

# 切换到淘宝镜像npmconfigsetregistry https://registry.npmmirror.com# 清除缓存重试npmcache clean--forcenpminstall

9.4 ❌ Go 依赖下载失败

现象：

go: downloading ... tls: failed to verify certificate

解决：

# 配置 Go 代理goenv-wGOPROXY=https://goproxy.cn,direct# 清除模块缓存go clean-modcache# 重新下载go mod download

9.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.4

9.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"📦 更新系统..."sudoaptupdate&&sudoaptupgrade-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.gzecho'export PATH=$PATH:/usr/local/go/bin'>>~/.bashrcecho'export PATH=$PATH:$(go env GOPATH)/bin'>>~/.bashrcsource~/.bashrc# 5. 配置 Go 代理（国内加速）goenv-wGOPROXY=https://goproxy.cn,direct goenv-wGOSUMDB=sum.golang.google.cn# 6. 配置 npm 镜像npmconfigsetregistry https://registry.npmmirror.com# 7. 安装 Go protobuf 插件goinstallgoogle.golang.org/protobuf/cmd/protoc-gen-go@latest goinstallgoogle.golang.org/grpc/cmd/protoc-gen-go-grpc@latestecho"✅ 配置完成！"echo""echo"请验证环境："echo" node --version"echo" go version"echo" docker --version"

A.2 内网环境一键配置

将以下内容保存为setup_corp.sh，在 Ubuntu 中执行：

#!/bin/bashset-eecho"🏢 开始配置内网开发环境..."# 1. 换阿里云 apt 源echo"🔄 更换 apt 源..."sudocp/etc/apt/sources.list /etc/apt/sources.list.baksudosed-i's|http://archive.ubuntu.com|https://mirrors.aliyun.com|g'/etc/apt/sources.listsudosed-i's|http://security.ubuntu.com|https://mirrors.aliyun.com|g'/etc/apt/sources.list# 2. 更新系统echo"📦 更新系统..."sudoaptupdate&&sudoaptupgrade-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.gzecho'export PATH=$PATH:/usr/local/go/bin'>>~/.bashrcecho'export PATH=$PATH:$(go env GOPATH)/bin'>>~/.bashrcsource~/.bashrc# 6. 配置 Go 代理（内网必须）goenv-wGOPROXY=https://goproxy.cn,direct goenv-wGOSUMDB=sum.golang.google.cn# 7. 配置 npm 镜像（内网必须）npmconfigsetregistry https://registry.npmmirror.com# 8. 安装 Go protobuf 插件goinstallgoogle.golang.org/protobuf/cmd/protoc-gen-go@latest goinstallgoogle.golang.org/grpc/cmd/protoc-gen-go-grpc@latest# 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"✅ 内网环境配置完成！"echo""echo"⚠️ 注意事项："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