可乐呢o3o

可乐呢o3o

admission

默认分类
16
2026-04-28

Windows 新电脑从零搭建 admission-api + admission-frontend 完整教程

本文目标：

  1. 在一台全新的 Windows 电脑上安装所有必需工具。
  2. 配置 Git、GitHub、SSH Key、环境变量。
  3. 使用 SSH 拉取项目代码。
  4. 启动后端 admission-api 和前端 admission-frontend。

1. 本教程最终会安装哪些程序

请按下面顺序安装：

  1. Git for Windows
  2. GitHub 账号
  3. Node.js LTS
  4. Go 1.25+
  5. Docker Desktop
  6. MSYS2
  7. GNU Make

说明：

  • Git：拉代码、提交代码、配置 SSH。
  • GitHub：托管代码、Fork、Pull Request、协作。
  • Node.js：运行前端。
  • Go：运行后端。
  • Docker Desktop：启动 PostgreSQL 和 Redis。
  • MSYS2：提供 Windows 安装器，并能安装 GNU Make。
  • GNU Make：真正执行 make dev、make db。

2. Windows 系统前置检查

2.1 检查 Windows 版本

按 Win + R，输入：

winver

建议：

  • Windows 11
  • 或 Windows 10 2004 及以上

Docker Desktop 官方要求较新版本的 Windows，并依赖虚拟化能力。

2.2 检查 BIOS 是否开启虚拟化

Docker Desktop 依赖虚拟化。

检查方法：

  1. 按 Ctrl + Shift + Esc 打开任务管理器。
  2. 切到“性能”页。
  3. 点击“CPU”。
  4. 查看右下角 虚拟化 是否为“已启用”。

如果未启用：

  1. 重启电脑进入 BIOS/UEFI。
  2. 打开 Intel VT-x / AMD-V / SVM。
  3. 保存并重启。

3. 注册并配置 GitHub 账号

3.1 注册 GitHub 账号

打开：

https://github.com/

操作：

  1. 点击 Sign up。
  2. 使用常用邮箱注册。
  3. 完成邮箱验证。
  4. 设置用户名。

建议：

  • 用户名尽量稳定，不要频繁改。
  • 邮箱最好和你未来提交 Git 的邮箱保持一致。

4. 安装 Git for Windows

4.1 下载

官方地址：

https://git-scm.com/install/windows

4.2 安装建议

安装过程中建议保留默认项，并注意以下选项：

  1. Choosing the default editor used by Git
    建议选你熟悉的编辑器；如果没有偏好，可保留默认。
  2. Adjusting your PATH environment
    选择包含 Git 命令到命令行的选项。
  3. Choosing HTTPS transport backend
    保持默认。
  4. Configuring the line ending conversions
    建议选择适合 Windows 的默认选项。
  5. Choosing the terminal emulator to use with Git Bash
    保持默认。

4.3 安装后验证

打开新的 PowerShell，运行：

git --version

能看到版本号就说明安装成功。

4.4 如果 git 命令不能识别，检查 PATH

通常 Git 会自动写入 PATH。若没有生效，手动检查以下目录是否存在于 Path：

C:\Program Files\Git\cmd

5. 配置 Git 全局信息

打开 PowerShell，执行：

git config --global user.name "你的姓名或英文名"
git config --global user.email "你的GitHub注册邮箱"

检查配置：

git config --global --list

说明：

  • user.name：提交记录显示的作者名。
  • user.email：提交记录关联的邮箱。

6. 生成 SSH Key 并绑定到 GitHub

后续建议全部使用 SSH 拉代码，不要混用 HTTPS。

6.1 检查本机是否已有 SSH Key

打开 PowerShell，执行：

Get-ChildItem $HOME\.ssh

如果看到了类似这些文件：

  • id_ed25519
  • id_ed25519.pub

说明可能已经存在 SSH Key。

如果你是新电脑，通常可以直接新建一套。

6.2 生成新的 SSH Key

执行：

ssh-keygen -t ed25519 -C "你的GitHub注册邮箱"

系统会提示：

Enter file in which to save the key
直接回车，使用默认路径：C:\Users\你的用户名\.ssh\id_ed25519

6.3 启动 ssh-agent

以管理员身份打开 PowerShell，执行：

Get-Service -Name ssh-agent | Set-Service -StartupType Manual
Start-Service ssh-agent

6.4 把私钥加入 ssh-agent

切回普通 PowerShell 窗口，执行：

ssh-add $HOME\.ssh\id_ed25519

6.5 复制公钥内容

执行：

Get-Content $HOME\.ssh\id_ed25519.pub

复制整行输出内容，通常以 ssh-ed25519 开头。

6.6 把公钥添加到 GitHub

打开：

https://github.com/settings/keys

操作：

  1. 点击 New SSH key
  2. Title 填一个容易识别的名字
    例如：
My Windows Laptop
  1. Key type 选择 Authentication Key
  2. 把刚才复制的公钥粘贴进去
  3. 点击 Add SSH key

6.7 测试 SSH 是否配置成功

执行：

ssh -T git@github.com

第一次连接时会提示确认主机指纹，输入：

yes

如果成功，通常会看到 GitHub 的欢迎信息。

7. 安装 nvm for Windows

7.1 下载

使用 nvm for Windows 官方发布页：

https://github.com/coreybutler/nvm-windows/releases

下载：

nvm-setup.exe

7.2 安装

双击 nvm-setup.exe，基本保持默认即可。

建议注意两项安装路径：

  1. NVM for Windows 安装目录
    建议保留默认目录
  2. Node.js symlink 目录
    建议也保留默认目录

如果这台电脑以前装过 Node.js，建议先卸载旧版系统级 Node，再安装 nvm，避免路径冲突。

7.3 安装 Node.js LTS

打开新的 PowerShell，先验证 nvm 是否可用：

nvm version

然后安装24：

nvm install 24

安装完成后，执行：

nvm use 24

如果你想查看本机已经安装了哪些 Node 版本，可执行：

nvm list

7.4 验证 Node 和 npm

打开新的 PowerShell，执行：

node -v
npm -v

都能输出版本号即成功。

8. 安装 Go 1.25+

8.1 下载

官方地址：

https://go.dev/doc/install

安装版本要求：

  • Go 1.25 或更高

8.2 安装

使用官方 Windows 安装包，按默认安装即可。

8.3 验证

打开新的 PowerShell，执行：

go version

9. 安装 Docker Desktop

9.1 下载

官方地址：

https://docs.docker.com/desktop/setup/install/windows-install/

9.2 首次安装建议

安装 Docker Desktop 时：

  1. 按默认步骤安装。
  2. 建议使用 WSL 2 后端。
  3. 安装完成后按要求重启电脑。

9.3 如果系统还没安装 WSL

以管理员身份打开 PowerShell，执行：

wsl --install

执行后重启电脑。

重启后再次打开 PowerShell 检查：

wsl --status
wsl --version

9.4 启动 Docker Desktop

安装完成后：

  1. 从开始菜单打开 Docker Desktop
  2. 首次启动等待其初始化完成
  3. 看到 Docker 正常运行再继续

9.5 验证

打开 PowerShell，执行：

docker --version
docker compose version

10. 安装 MSYS2

之所以安装 MSYS2，是因为它提供了稳定的 Windows 安装器，并且可以安装 GNU Make。

10.1 下载

官方地址：

https://www.msys2.org/

10.2 安装

双击下载好的安装程序，基本保持默认即可。

建议安装到默认目录：

C:\msys64

不要随意改到带空格、中文或过深层级的目录。

10.3 首次启动

安装完成后，从开始菜单打开：

MSYS2 MSYS

首次启动后先更新基础包。

在 MSYS2 MSYS 终端里执行：

pacman -Syu

如果终端提示你关闭窗口后重新打开，再按提示操作：

  1. 关闭 MSYS2 MSYS
  2. 重新打开 MSYS2 MSYS
  3. 再执行一次：
pacman -Syu

直到更新完成为止。

11. 安装 GNU Make

11.1 在 MSYS2 里安装

打开：

MSYS2 MSYS

执行：

pacman -S make

安装过程中如果询问是否继续，输入：

Y

11.2 配置 PATH

执行：

  1. 打开 Windows 环境变量界面
  2. 编辑 Path
  3. 加入下面这个目录：
C:\msys64\usr\bin

这是 make.exe 默认所在位置。

11.3 验证

关闭所有已打开的终端窗口，重新打开一个新的 PowerShell，执行：

make --version

如果能看到 GNU Make 版本信息，说明成功。

12. Windows 环境变量如何手动配置

如果某个命令安装后仍然提示“无法识别”，请手动检查 Path。

12.1 打开环境变量界面

  1. 开始菜单搜索：
Edit the system environment variables
  1. 点击：
环境变量
  1. 在“用户变量”或“系统变量”里找到 Path
  2. 点击“编辑”
  3. 把缺失的目录逐条加进去

12.2 本教程可能会用到的 PATH 目录

C:\Program Files\Git\cmd
C:\Users\你的用户名\AppData\Roaming\nvm
C:\Program Files\nodejs
C:\Program Files\Go\bin
C:\Program Files\Docker\Docker\resources\bin
C:\msys64\usr\bin

12.3 修改完 PATH 后一定要做的事

  1. 关闭所有已打开的终端窗口
  2. 重新打开 PowerShell
  3. 再执行版本检查命令

13. 一次性检查所有工具是否安装成功

打开 PowerShell，逐条执行：

git --version
ssh -V
nvm version
node -v
npm -v
go version
docker --version
docker compose version
make --version

只要都能输出版本号，就说明开发机基础环境已经就绪。

14. 用 SSH 拉取这两个仓库

建议把代码统一放在一个目录，例如：

D:\workspace

或者：

C:\dev

14.1 创建代码目录

例如：

mkdir D:\workspace
cd D:\workspace

14.2 使用 SSH 克隆后端仓库

git clone git@github.com:LiukerSun/admission-api.git

14.3 使用 SSH 克隆前端仓库

git clone git@github.com:LiukerSun/admission-frontend.git

14.4 确认目录结构

最终建议类似这样：

D:\workspace\admission-api
D:\workspace\admission-frontend

15. 运行后端 admission-api

后端仓库 README 写明了开发依赖：

  • Go 1.25+
  • Docker & Docker Compose
  • Make

并且开发启动命令是：

make db
make dev

15.1 进入后端目录

cd D:\workspace\admission-api

15.2 首次初始化数据库和缓存

make db

这个命令会自动做几件事：

  1. 如果没有 .env，从 .env.example 自动创建
  2. 启动 PostgreSQL 容器
  3. 启动 Redis 容器
  4. 运行数据库迁移

15.3 启动开发模式

make dev

这个命令会：

  1. 启动 PostgreSQL、Redis
  2. 自动生成 Swagger 文档
  3. 跑数据库迁移
  4. 用宿主机 Go 进程启动后端服务

15.4 成功后访问地址

后端默认地址：

http://localhost:8080

Swagger 文档：

http://localhost:8080/swagger/index.html

健康检查：

http://localhost:8080/health

15.5 后端常用命令

make db
make dev
make run
make down
make logs

16. 运行前端 admission-frontend

16.1 打开一个新的 PowerShell 窗口

不要关闭后端窗口，后端要保持运行。

16.2 进入前端目录

cd D:\workspace\admission-frontend

16.3 创建前端环境变量文件

执行：

Copy-Item .env.example .env

16.4 编辑 .env

确保内容类似：

VITE_API_BASE_URL=http://localhost:8080

16.5 安装依赖

npm install

16.6 启动前端

npm run dev

16.7 成功后访问地址

前端默认地址：

http://localhost:5173

17. 这套前后端的典型启动顺序

以后每次开发，推荐顺序如下：

17.1 先启动 Docker Desktop

确保 Docker 图标显示正常运行。

17.2 启动后端

cd D:\workspace\admission-api
make dev

17.3 启动前端

打开第二个终端：

cd D:\workspace\admission-frontend
npm run dev

17.4 打开浏览器

访问：

http://localhost:5173

18. GitHub 的基本使用方法

如果你只是“会克隆代码”还不够，至少需要掌握下面这套最小流程。

18.1 理解几个核心概念

  • Repository：仓库
  • Clone：把远程仓库复制到本地
  • Commit：保存一次本地变更记录
  • Push：把本地提交传到 GitHub
  • Pull：把远程更新拉回本地
  • Branch：分支
  • Pull Request：把你的分支改动提交给主分支审核
  • Fork：把别人的仓库复制到你自己的 GitHub 账号下

18.2 查看远程仓库地址

进入项目目录，执行：

git remote -v

18.3 拉取最新代码

git pull

18.4 创建自己的开发分支

不要直接在主分支乱改。

git checkout -b feat/my-change

18.5 查看当前改动

git status
git diff

18.6 提交代码

git add .
git commit -m "feat: your change summary"

18.7 推送到 GitHub

第一次推送新分支：

git push -u origin feat/my-change

之后继续推送：

git push

18.8 在 GitHub 上发起 Pull Request

  1. 打开 GitHub 仓库页面
  2. GitHub 通常会提示 Compare & pull request
  3. 点击进入
  4. 填写标题和说明
  5. 提交 PR

19. 这两个项目相关的本地配置说明

19.1 后端环境变量

后端首次执行 make db 或 make dev 时，会自动从 .env.example 创建 .env。

常见变量包括：

  • PORT=8080
  • POSTGRES_PORT=5432
  • REDIS_PORT=6379

如果端口冲突，可以修改 .env。

19.2 前端环境变量

前端需要 .env 文件，核心变量通常是：

VITE_API_BASE_URL=http://localhost:8080

19.3 默认端口

  • 前端：5173
  • 后端：8080
  • PostgreSQL：5432
  • Redis：6379

20. 常见问题排查

20.1 make 命令找不到

原因：

  • 没安装 GNU Make
  • 或 C:\msys64\usr\bin 没进 PATH

解决：

  1. 打开 MSYS2 MSYS
  2. 执行：
pacman -S make
  1. 检查 PATH
  2. 关闭并重新打开 PowerShell
  3. 再执行：
make --version

20.2 ssh -T git@github.com 失败

排查顺序：

  1. 检查是否已把公钥添加到 GitHub
  2. 检查是否执行过：
ssh-add $HOME\.ssh\id_ed25519
  1. 检查是否启用了 ssh-agent
  2. 检查当前网络是否限制 SSH

20.3 npm install 很慢

可能是网络问题。

先确认不是代理或 DNS 问题。

20.4 前端能打开，但接口报错

优先检查：

  1. 后端是否已经启动
  2. http://localhost:8080/health 是否可访问
  3. 前端 .env 中的 VITE_API_BASE_URL 是否正确

20.5 npm run typegen 在 Windows 下失败

这个前端脚本里把临时文件写到了 /tmp/...，这在 Windows 原生 PowerShell 下不一定可用。

这不影响前后端正常启动，只影响“重新生成 API 类型”这个开发动作。

21. 推荐的日常工作流

21.1 每天开始开发前

  1. 打开 Docker Desktop
  2. 拉最新代码：
git pull
  1. 启动后端：
make dev
  1. 启动前端：
npm run dev

21.2 每次开发新功能

git checkout -b feat/功能名

21.3 提交后推送

git add .
git commit -m "feat: 功能说明"
git push -u origin 分支名

然后去 GitHub 页面发 Pull Request。

admission-api 后端框架模板设计文档