快速上手 #

这是新成员的一站式启动指南。按顺序走完这几步，你应该能在本地把整套环境跑起来。

环境要求 #

开始前请确认本机已安装以下工具：

  • Docker >= 24.0（含 Docker Compose v2）
  • Git >= 2.40
  • Node.js >= 20（LTS）
  • 8 GB 以上可用内存，20 GB 以上可用磁盘

克隆仓库 #

git clone https://github.com/lab-edu/lab-edu-infra.git
cd lab-edu-infra
cp .env.example .env

.env 中已预设本地开发默认值，通常情况下无需额外修改。如需自定义数据库密码或端口，直接编辑 .env 即可。

一键启动 #

./scripts/up.sh

该脚本会依次完成镜像拉取、容器编排和服务启动。首次执行需要拉取镜像，耗时会稍长。

其他常用脚本：

  • ./scripts/stop.sh：停止所有容器
  • ./scripts/down.sh：停止并清理容器与网络
  • ./scripts/restart.sh：重启当前环境

验证运行 #

启动完成后，依次确认以下检查点：

  1. 健康检查：访问 http://localhost:8080/actuator/health，应返回 {"status":"UP"}
  2. Web 界面：浏览器打开 http://localhost，应能看到登录页面
  3. 数据库连通：docker ps 确认 db 容器状态为 healthy

如果任一步失败，先执行 docker compose -f infra/docker-compose.yml logs 查看日志。

常见问题 #

端口冲突 #

本机已有服务占用了 80、443 或 5432 端口。解决：编辑 .env 修改 WEB_PORT、DB_PORT，然后 ./scripts/restart.sh。

镜像拉取失败 #

检查是否已登录 GitHub Container Registry：

echo $CR_PAT | docker login ghcr.io -u <your-username> --password-stdin

如未配置 CR_PAT，请联系团队管理员获取访问令牌。

数据库初始化超时 #

首次启动时 PostgreSQL 初始化可能较慢。等待 30 秒后重新访问健康检查端点；若仍失败，执行 ./scripts/down.sh 清理后重新 ./scripts/up.sh。

下一步 #

环境就绪后，建议按以下顺序继续阅读：