🛠️ NMS 开发环境完整搭建指南(WSL + Docker 版)
文档说明 :本文档详细记录了在 Windows 环境下搭建 NMS 网管系统开发环境的完整流程,特别区分了公司内网环境和本地外挂(手机热点/家庭网络)环境的差异配置。
适用场景:
- 🏢 内网开发环境:公司网络,有 HTTPS 拦截、代理限制
- 🏠 本地外挂环境:手机热点、家庭宽带,可直连外网
维护者 :LucasLC
最后更新:2026年6月30日
📑 目录
- 环境架构总览
- [Windows 基础环境搭建](#Windows 基础环境搭建)
- [WSL 2 + Ubuntu 安装](#WSL 2 + Ubuntu 安装)
- [Docker Desktop 安装与配置](#Docker Desktop 安装与配置)
- [Ubuntu 内部工具链搭建](#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:
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 为默认版本
powershell
wsl --set-default-version 2
2.4 安装 Ubuntu 24.04
powershell
# 方式 1:通过 Microsoft Store 安装(推荐内网用户)
# 打开 Microsoft Store,搜索 "Ubuntu 24.04 LTS",点击安装
# 方式 2:通过命令行安装(本地外挂用户)
wsl --install -d Ubuntu-24.04
首次启动 Ubuntu:
- 设置用户名(建议:
lucaslcliu或你的名字) - 设置密码(记住这个密码,后面 sudo 要用)
2.5 验证 WSL 安装
powershell
# 查看已安装的发行版
wsl -l -v
# 预期输出:
# NAME STATE VERSION
# * Ubuntu-24.04 Running 2
3. WSL 2 + Ubuntu 安装
3.1 进入 Ubuntu
powershell
# 方式 1:命令行进入
wsl -d Ubuntu-24.04
# 方式 2:在开始菜单找到 Ubuntu 24.04 点击打开
3.2 更新系统
bash
# 更新软件包列表
sudo apt update
# 升级已安装的软件包
sudo apt upgrade -y
3.3 安装基础工具
bash
sudo apt install -y \
build-essential \
curl \
wget \
git \
vim \
dos2unix \
unzip \
zip \
ca-certificates \
gnupg \
lsb-release \
software-properties-common
3.4 验证安装
bash
gcc --version # 应显示 gcc 13.x
git --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 中可用
bash
# 在 Ubuntu 中执行
docker --version
docker run 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 镜像加速(内网用户可选)
如果拉取镜像慢,可以配置国内镜像源:
bash
# 创建 daemon.json
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://dockerhub.azk8s.cn",
"https://hub-mirror.c.163.com"
]
}
EOF
# 重启 Docker
sudo systemctl restart docker
5. Ubuntu 内部工具链搭建
5.1 安装 Node.js (使用 nvm)
为什么用 nvm? 因为项目需要 Node.js 18.x,而系统默认可能是 20+,nvm 可以灵活切换版本。
bash
# 安装 nvm
curl -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(项目指定版本)
nvm install 18.20.4
# 设置为默认版本
nvm alias default 18.20.4
nvm use 18.20.4
# 验证
node --version # 应显示 v18.20.4
npm --version # 应显示 10.x.x
5.2 安装 Go
bash
# 方式 1:通过 apt 安装(简单,但版本可能较旧)
sudo apt install -y golang
# 方式 2:手动安装最新版(推荐)
# 访问 https://go.dev/dl/ 下载最新版
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
# 配置环境变量
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc
# 验证
go version # 应显示 go1.22.x
5.3 安装 CMake 和其他编译工具
bash
sudo apt install -y \
cmake \
make \
protobuf-compiler \
libprotobuf-dev
验证:
bash
cmake --version # 应显示 3.x.x
protoc --version # 应显示 libprotoc 3.x.x
5.4 安装 Go 的 protobuf 插件
bash
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
6. 网络环境差异化配置(核心重点)
6.1 🏢 内网开发环境配置
特点:
- 公司网络有 HTTPS 拦截
- GitHub、Docker Hub 访问慢或被拦截
- npm、Go 模块下载失败
6.1.1 Go 代理配置(必须)
bash
# 配置 Go 使用国内代理
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.google.cn
# 验证
go env GOPROXY # 应显示 https://goproxy.cn,direct
6.1.2 npm 镜像配置(必须)
bash
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
# 验证
npm config get registry # 应显示 https://registry.npmmirror.com/
6.1.3 apt 源配置(可选)
如果系统更新慢,可以换阿里云源:
bash
# 备份原配置
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
# 替换为阿里云源(Ubuntu 24.04 是 noble)
sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list
sudo sed -i 's|http://security.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list
# 更新
sudo apt update
6.1.4 Git 代理配置(如果公司需要)
bash
# 如果公司有 HTTP 代理(问 IT 部门要代理地址)
git config --global http.proxy http://proxy.company.com:8080
git config --global https.proxy http://proxy.company.com:8080
# 取消代理
git config --global --unset http.proxy
git config --global --unset https.proxy
6.1.5 Docker 镜像拉取失败的处理
方案 A:使用手机热点临时下载
bash
# 1. 电脑连接手机热点
# 2. 在 WSL 中拉取镜像
docker pull ubuntu:24.04
docker pull mysql:8.0
docker pull nacos/nacos-server:v2.1.1
docker pull 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 配置(可选代理)
bash
# 直连外网可以不配置代理,但配置了也无妨
go env -w GOPROXY=https://goproxy.cn,direct
6.2.2 npm 配置(可选镜像)
bash
# 直连外网可以用官方源
npm config set registry https://registry.npmjs.org/
# 或者继续用淘宝镜像(国内速度更快)
npm config set registry https://registry.npmmirror.com
6.2.3 直接拉取 Docker 镜像
bash
# 直接拉取,无需任何配置
docker pull ubuntu:24.04
docker pull mysql:8.0
docker pull nacos/nacos-server:v2.1.1
docker pull 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 克隆项目代码
bash
# 创建项目目录
mkdir -p /mnt/d/linux
cd /mnt/d/linux
# 克隆代码(内网用户可能需要配置 Git 代理)
git clone <你的项目仓库地址> Controller
# 进入项目目录
cd Controller
7.2 修复脚本换行符(关键!)
Windows 和 Linux 的换行符不同,会导致脚本执行失败:
bash
# 修复所有 .sh 脚本的换行符
find . -name "*.sh" -exec dos2unix {} \;
# 或者手动修复关键脚本
dos2unix build.sh
dos2unix build_fixed.sh
7.3 应用 CMake 兼容补丁
bash
# 解决 CMake 版本策略报错
sed -i 's/cmake ${CM_OPTS}/cmake ${CM_OPTS} -DCMAKE_POLICY_VERSION_MINIMUM=3.5/g' build.sh
8. 环境验证
8.1 一键验证脚本
在 Ubuntu 中执行以下命令,检查所有环境是否就绪:
bash
echo "========== 环境验证 =========="
echo "1. WSL 版本:"
cat /proc/version | grep -o "Linux version [^ ]*"
echo ""
echo "2. Node.js:"
node --version
echo ""
echo "3. npm:"
npm --version
echo ""
echo "4. Go:"
go version
echo ""
echo "5. Go 代理:"
go env GOPROXY
echo ""
echo "6. Docker:"
docker --version
echo ""
echo "7. CMake:"
cmake --version | head -1
echo ""
echo "8. GCC:"
gcc --version | head -1
echo ""
echo "9. Protobuf:"
protoc --version
echo ""
echo "10. Git:"
git --version
echo ""
echo "11. npm 镜像:"
npm config get registry
echo ""
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 镜像拉取
bash
# 测试拉取一个小镜像
docker pull alpine:latest
# 如果成功,说明 Docker 配置正常
# 如果失败,检查网络配置或镜像加速
9. 常见问题排查
9.1 ❌ WSL 无法启动
现象:
WSL 2 需要更新其内核组件
解决:
powershell
# 在 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
解决:
bash
# 切换到淘宝镜像
npm config set registry https://registry.npmmirror.com
# 清除缓存重试
npm cache clean --force
npm install
9.4 ❌ Go 依赖下载失败
现象:
go: downloading ... tls: failed to verify certificate
解决:
bash
# 配置 Go 代理
go env -w GOPROXY=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".
解决:
bash
# 切换到 18.20.4
nvm install 18.20.4
nvm use 18.20.4
nvm alias default 18.20.4
# 验证
node --version # 应显示 v18.20.4
9.6 ❌ 脚本执行报 /bin/bash^M: bad interpreter
原因:Windows 换行符 (CRLF) 和 Linux 换行符 (LF) 不兼容
解决:
bash
# 修复单个脚本
dos2unix build.sh
# 批量修复所有 .sh 脚本
find . -name "*.sh" -exec dos2unix {} \;
9.7 ❌ Docker 镜像拉取超时
内网环境解决:
bash
# 方式 1:配置镜像加速(参考 4.5 节)
# 方式 2:使用手机热点临时下载
# 1. 断开公司网络
# 2. 连接手机热点
# 3. 拉取镜像
docker pull <镜像名>
# 4. 切回公司网络
9.8 ❌ WSL 磁盘空间不足
现象:
no space left on device
解决:
powershell
# 在 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 中执行:
bash
#!/bin/bash
set -e
echo "🚀 开始配置本地外挂开发环境..."
# 1. 更新系统
echo "📦 更新系统..."
sudo apt update && sudo apt upgrade -y
# 2. 安装基础工具
echo "🔧 安装基础工具..."
sudo apt install -y \
build-essential curl wget git vim dos2unix \
unzip zip ca-certificates gnupg lsb-release \
cmake make protobuf-compiler libprotobuf-dev
# 3. 安装 nvm + Node.js 18
echo "📗 安装 Node.js 18..."
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18.20.4
nvm alias default 18.20.4
nvm use 18.20.4
# 4. 安装 Go
echo "🐹 安装 Go..."
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc
# 5. 配置 Go 代理(国内加速)
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.google.cn
# 6. 配置 npm 镜像
npm config set registry https://registry.npmmirror.com
# 7. 安装 Go protobuf 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
echo "✅ 配置完成!"
echo ""
echo "请验证环境:"
echo " node --version"
echo " go version"
echo " docker --version"
A.2 内网环境一键配置
将以下内容保存为 setup_corp.sh,在 Ubuntu 中执行:
bash
#!/bin/bash
set -e
echo "🏢 开始配置内网开发环境..."
# 1. 换阿里云 apt 源
echo "🔄 更换 apt 源..."
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list
sudo sed -i 's|http://security.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list
# 2. 更新系统
echo "📦 更新系统..."
sudo apt update && sudo apt upgrade -y
# 3. 安装基础工具
echo "🔧 安装基础工具..."
sudo apt install -y \
build-essential curl wget git vim dos2unix \
unzip zip ca-certificates gnupg lsb-release \
cmake make protobuf-compiler libprotobuf-dev
# 4. 安装 nvm + Node.js 18
echo "📗 安装 Node.js 18..."
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18.20.4
nvm alias default 18.20.4
nvm use 18.20.4
# 5. 安装 Go
echo "🐹 安装 Go..."
wget https://golang.google.cn/dl/go1.22.5.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc
# 6. 配置 Go 代理(内网必须)
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.google.cn
# 7. 配置 npm 镜像(内网必须)
npm config set registry https://registry.npmmirror.com
# 8. 安装 Go protobuf 插件
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
# 9. 配置 Docker 镜像加速
echo "🐳 配置 Docker 镜像加速..."
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://hub-mirror.c.163.com"
]
}
EOF
echo "✅ 内网环境配置完成!"
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
🎉 环境搭建完成!你已经具备了开始 NMS 开发的所有条件!