环境搭建与锁定版本清单

原则：能用官方安装器就用官方安装器；能用 winget 就用 winget（自动加 PATH）；装完立刻用"验证命令"确认。顺序：Go → VS Code → Git → Node/pnpm →（按需）Flutter/Python/C++/Docker。

1.1 Go 1.27.x（主线语言，第一个装）

1. 下载：https://go.dev/dl/ 选 Windows x86-64 的 go1.27.2.windows-amd64.msi（1.27.x 线最新补丁；或 winget install GoLang.Go）。
2. 安装：默认路径 C:\Program Files\Go，一路 Next。装完重开终端（PATH 刷新）。
3. 验证：

go version          # 期望：go version go1.27.2 windows/amd64
go env GOPROXY      # 国内网络：应显示 https://goproxy.cn,direct

国内网络必做（否则 go get 会卡超时）：

go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.google.cn

工作区习惯（不强制）：go env -w GOPATH=C:\Users\你的用户名\go（默认即可），项目目录随意放，Go 用 go.mod 管理模块，不依赖 GOPATH 位置。

1.2 VS Code 1.141.0 + Go 扩展

1. 下载 https://code.visualstudio.com/ 的 Windows x64 安装包（当前稳定版 1.141.0），或 winget install Microsoft.VisualStudioCode。
2. 装扩展：扩展面板搜 Go（发布者 golang，扩展 ID golang.go）并安装。gopls（v0.23.0）由扩展自动托管，不用手动装。
3. 首次打开 .go 文件时，右下角会提示安装 gopls/delve 等工具，点 Install All（走 goproxy.cn 很快）。
4. 可选：winget install JetBrains.GoLand（GoLand 2026.2，已适配 Go 1.27；教程以 VS Code 为准，GoLand 是付费备选）。

1.3 Git（版本纪律的地基）

winget install Git.Git
git --version

装完设置用户（一次性）：git config --global user.name "你的名字"; git config --global user.email "你的邮箱"。推荐在 VS Code 里装 GitLens 扩展（看 diff 用）。

1.4 Node.js 24 LTS + pnpm 12

winget install OpenJS.NodeJS.LTS        # Node 24 LTS 线（当前 v24.21.0）
node --version                          # 期望 v24.x.x
npm install -g pnpm                     # 全局装 pnpm（npm 装的是最新稳定 12.11.x）
pnpm --version                          # 期望 12.x

国内网络：给 pnpm 配 registry 镜像（否则装包慢/失败）：

pnpm config set registry https://registry.npmmirror.com

换机器/换项目时注意：registry 是用户级配置，镜像只加速下载，锁文件（pnpm-lock.yaml）里记录的是版本不是源，不影响可复现。

1.5 Flutter stable 3.47.6（路径 C，有 APP 项目再装也行）

1. 下载 stable 渠道 Windows 包：https://docs.flutter.dev/install/archive（3.47.6，2026-10-02，随包 Dart 3.13.5）。
2. 解压到 C:\flutter，把 C:\flutter\bin 加进 PATH（系统环境变量）。
3. 国内网络配置镜像（flutter 与 pub）：

$env:FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"
$env:PUB_HOSTED_URL="https://pub.flutter-io.cn"
# 上述是临时变量；永久设置：系统环境变量里新建这两个变量，值同上
flutter --version        # 期望 Flutter 3.47.6 + Dart 3.13.5
flutter doctor            # 检查依赖；做 Windows 桌面开发装好 VS2022 C++ 工作负载即可

提醒：Flutter 是"项目驱动"卫星（08 §1.2 路径 C）。没接到 APP 项目前，可以不装或只装 SDK 不配 Android 环境；要配 Android 时按 13 模块第 1 章操作。

1.6 Python 3.14.8（AI 胶水卫星）

winget install Python.Python.3.14        # 或手动下载：https://www.python.org/downloads/ 选 3.14.8
python --version        # 期望 Python 3.14.8（注意：不要选 3.15.0，刚发布，按版本纪律规则 2）

• 安装器勾选 Add python.exe to PATH。
• 包管理用 uv（比 pip/venv 快一个量级；14 模块详述）：pip install uv 或 winget install astral-sh.uv，然后 uv --version。
• pip 国内镜像（可选）：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

1.7 C/C++ 工具链（根基卫星，第 15 模块用）

1. Visual Studio 2022 安装器 → 勾选工作负载 "使用 C++ 的桌面开发"（含 MSVC v143 编译器 + CMake 工具）。下载：https://visualstudio.microsoft.com/zh-hans/
2. CMake 也可独立装最新稳定 4.4.3：https://cmake.org/download/（Windows x86_64 安装器，装时勾选"Add CMake to PATH"）。
3. 轻量替代（不装 VS 时）：MSYS2 / WinLibs 的 MinGW-w64 + GCC。

cmake --version        # 期望 4.4.x
cl                    # 期望显示 MSVC 版本（在"Developer PowerShell for VS 2022"里执行）

1.8 本机跑数据库：Docker Desktop 还是 WSL2？

winget install Docker.DockerDesktop        # Docker Desktop 4.94.0（含 Engine 29.8.x）
docker --version                            # 期望 Docker version 29.x
docker compose version                      # 期望 v2.x

装完启动 Docker Desktop，等托盘鲸鱼图标变绿。记住：Docker 只用于本机开发；1GB 服务器不装 Docker（§3）。

1.9 全部装完，跑一遍总验证

go version && node --version && pnpm --version
python --version && cmake --version && git --version
docker --version
flutter --version        # 已装才跑

本机环境验收标准：以上命令全部有输出、版本号与 §4 总表一致，本机环境就绪，可以进 10 模块了。

目标：一台 1GB 内存的云服务器（Debian 13 或 Ubuntu 26.04 LTS），从零到"能安全接收 Go 二进制"。20 模块负责完整部署，这里只做安全地基。

2.1 选系统与初始化

• 系统：Debian 13 "trixie"（当前 stable） 首选（官方要求内存低、干净）；Ubuntu 26.04.1 LTS 备选（官方要求 1.5GB 内存起，1GB 机器装 Debian 更稳）。[https://www.debian.org/releases/]
• 购买后立即：改 root 密码 / 或建普通用户；记下公网 IP。
• SSH 登录：Windows 终端里 ssh root@服务器IP。

2.2 一次性加固脚本（root 下逐行执行）

# 1) 更新系统
apt update && apt upgrade -y

# 2) 时区设为北京时间
timedatectl set-timezone Asia/Shanghai

# 3) 建普通用户并加入 sudo（把 yourname 换成你的用户名）
adduser yourname
usermod -aG sudo yourname

# 4) 配置 SSH 密钥登录（本机 PowerShell 执行，不是服务器上）：
#    ssh-keygen -t ed25519                        # 本机生成（已有可跳过）
#    type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh root@服务器IP "cat >> ~/.ssh/authorized_keys"
#    然后服务器上：sed -i 's/^#\?PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config
#    systemctl restart ssh

# 5) 防火墙：只开 SSH / HTTP / HTTPS
apt install -y ufw
ufw allow OpenSSH && ufw allow 80/tcp && ufw allow 443/tcp
ufw enable          # 确认后输入 y；这一步做完 SSH 断开会话是正常的，用新用户+密钥重连

# 6) 1GB 内存加 swap（重要，防 OOM）
fallocate -l 2G /swapfile && chmod 600 /swapfile
mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

# 7) 验证
free -h              # 期望看到 Swap 2.0Gi
df -h                # 磁盘余量

服务器准备验收标准：能用普通用户 + 密钥登录；root 密码登录已关；防火墙只有 22/80/443；swap 生效；时区正确。这套做完，进 11 模块做部署，或直接进 20 模块系统学。

这是 07 报告选 Go 的核心约束在运维上的投影。五条原则，20 模块会逐条展开。

全系列唯一版本事实来源。每个版本号均于 2026-10-14 实际访问官方页面确认，关键项经第二来源抽查（08 §10 有速览版）。安装时直接抄这张表，不要自己选。

4.1 语言与前端

4.2 数据库四件套

4.3 基础设施与服务器

4.4 Go 生态（工作台与各专题）

4.5 IDE 与工具链

表中未列的小依赖（godotenv、x/crypto/bcrypt、Python 的 uv 等）：各专题模块在写代码前会自己核验最新稳定版并写入该模块来源表（见 08 总纲 §8 与各模块）。你不需要管。

08 总纲 §7 讲"规则"，这里讲"命令"：怎么查当前版本、怎么核对是不是官方最新、怎么把版本写死进项目。

5.1 查版本命令速查

5.2 核对"是不是官方最新"（每次评估 30 秒）

1. Go：打开 https://go.dev/dl/ 看最新稳定版，与 §4 总表对比；
2. Go 生态库：打开 https://pkg.go.dev/<模块路径> 看顶部 Version；
3. 前端包：打开 https://data.jsdelivr.com/v1/packages/npm/<包名>/resolved?specifier=latest；
4. 数据库：打开 §4 总表里的官方发布说明页。

但记住纪律："有新版" ≠ "该升级"。升级只允许三种情况（安全通告 / 新特性解决真实问题 / 全新项目）。核对的目的是心里有数，不是动手升级。

5.3 把版本写死进项目（README 版本表模板）

# 版本表（本项目唯一事实来源，冻结日期 2026-10）
| 组件        | 锁定版本            | 锁文件             | 上次评估 | 升级条件命中? |
|-------------|---------------------|--------------------|----------|---------------|
| Go          | 1.27.x              | go.mod + go.sum    | 2026-10  | 否            |
| Gin         | v1.12.x             | go.sum             | 2026-10  | 否            |
| GORM        | v1.31.x (v2 API)    | go.sum             | 2026-10  | 否            |
| SQLite 驱动 | glebarez/sqlite     | go.sum             | 2026-10  | 否            |
| Vue3        | ^3.5                | pnpm-lock.yaml     | 2026-10  | 否            |
| Vite        | ^8.3                | pnpm-lock.yaml     | 2026-10  | 否            |
| Node        | 24 LTS              | .nvmrc             | 2026-10  | 否            |

本页所有版本号均于 2026-10-14 由核验子代理实际访问下列官方页面确认；关键项（Go、PostgreSQL、SQLite、Vue、Vite、GORM、Gin、golang-jwt、modernc）经第二来源（jsDelivr API / pkg.go.dev / 官方发布页）抽查复核。