【AI全栈】NMS 开发环境完整搭建指南(WSL + Docker 版)

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

文档说明 :本文档详细记录了在 Windows 环境下搭建 NMS 网管系统开发环境的完整流程,特别区分了公司内网环境和本地外挂(手机热点/家庭网络)环境的差异配置

适用场景

  • 🏢 内网开发环境:公司网络,有 HTTPS 拦截、代理限制
  • 🏠 本地外挂环境:手机热点、家庭宽带,可直连外网

维护者 :LucasLC

最后更新:2026年6月30日


📑 目录

  1. 环境架构总览
  2. [Windows 基础环境搭建](#Windows 基础环境搭建)
  3. [WSL 2 + Ubuntu 安装](#WSL 2 + Ubuntu 安装)
  4. [Docker Desktop 安装与配置](#Docker Desktop 安装与配置)
  5. [Ubuntu 内部工具链搭建](#Ubuntu 内部工具链搭建)
  6. 网络环境差异化配置
  7. 项目代码准备
  8. 环境验证
  9. 常见问题排查

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 内核更新包:

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

4.2 安装 Docker Desktop

  • 双击安装包,按提示安装
  • 关键选项:勾选 "Use WSL 2 based engine"
  • 安装完成后重启电脑

4.3 启用 WSL 2 集成

  1. 打开 Docker Desktop
  2. 点击右上角 设置 (齿轮图标)
  3. 进入 Resources → WSL Integration
  4. 启用 "Enable integration with my default WSL distro"
  5. 在下方的发行版列表中,打开 Ubuntu-24.04 的开关
  6. 点击 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

解决

  1. 确保 Docker Desktop 正在运行
  2. 进入 Docker Desktop → Settings → Resources → WSL Integration
  3. 启用 Ubuntu-24.04 的开关
  4. 在 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 开发的所有条件!