student_management_system/Docker使用说明.md

在 Docker Desktop 中运行沃林学生管理系统

本配置在 Docker 中运行 FastAPI 和前端，继续连接 Windows 电脑上的现有 MySQL。 数据库记录仍保存在原 MySQL 中。容器启动只加载应用，不执行初始化、重建表或示例数据写入。

启动

1. 启动 Docker Desktop，使用 Linux containers，并确保电脑上的 MySQL 已启动。
2. 在项目目录打开 PowerShell。
3. 首次配置时复制 .env.example 为 .env，填写现有 MySQL 密码。已经有 .env 时保留原文件。
4. 保留项目中的 ai.local.json；新电脑没有该文件时，复制 ai.local.example.json 为 ai.local.json 并按需配置 AI。

Set-Location 'D:\xwt0803\fastoffer\student_management_system'
docker compose up -d --build
docker compose ps

• 工作台：http://localhost:8004/
• API 文档：http://localhost:8004/docs
• Docker Desktop 的 Containers 页面中，项目名为 wolin-student-management，服务为 web。
• 本配置仅开放本机访问。容器内监听 0.0.0.0:8004，Windows 映射地址为 127.0.0.1:8004。

日常使用

# 查看运行日志
docker compose logs --tail=100 web
# 停止 / 重新启动
docker compose stop
docker compose start
# 修改代码后重新构建并启动
docker compose up -d --build
# 删除本项目容器和网络（不会删除 Windows 上的 MySQL 数据）
docker compose down

.env 保存端口和数据库连接参数，AI 配置通过只读文件挂载传入。 这两个配置文件不会打包到镜像中。修改 .env 后执行 docker compose up -d。 Python 和前端代码已经打包入镜像，修改它们后需要重新构建。

排查问题

• 端口冲突：停止在 PyCharm 中启动的同一应用，或将 .env 中 APP_PORT 改为 8005，然后执行 docker compose up -d，使用新端口访问。
• 页面可打开但数据报错 / 容器 unhealthy：查看日志，检查本机 MySQL 服务及 .env 的数据库名、端口、用户、密码。容器通过 host.docker.internal 连接电脑，不能填写 localhost。
• MySQL 拒绝容器连接：确认 MySQL 监听地址和账号允许的来源地址；不要直接将数据库对公网开放。当前配置不新增数据库端口映射。
• AI 未配置：填写 ai.local.json；该文件从电脑只读挂载到容器，密钥不会写入镜像。

健康检查通过 /healthz 接口同时检查应用和数据库连接；首次启动通常需要约 30 秒显示 healthy。 Docker Desktop 重启后容器会自动恢复运行（手动停止过的容器需手动启动）。Windows MySQL 也需要处于运行状态。

参考：Docker Desktop 访问宿主机服务。