53 lines
2.7 KiB
Markdown
53 lines
2.7 KiB
Markdown
# 在 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。
|
||
|
||
```powershell
|
||
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`。
|
||
|
||
## 日常使用
|
||
|
||
```powershell
|
||
# 查看运行日志
|
||
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 访问宿主机服务](https://docs.docker.com/desktop/features/networking/networking-how-tos/)。
|