panda
db867dcbe5
7.4 KiB
FastAPI 项目 - 开发（Development）
Docker Compose
- 使用 Docker Compose 启动本地 stack：
docker compose watch
- 启动后，你可以在浏览器中访问以下地址：
前端（通过 Docker 构建，基于路径路由）：http://localhost:5173
后端（基于 OpenAPI 的 JSON Web API）：http://localhost:8000
自动生成的 Swagger UI 交互文档：http://localhost:8000/docs
Adminer 数据库管理界面：http://localhost:8080
Traefik UI（查看代理如何路由请求）：http://localhost:8090
注意：第一次启动整个 stack 时，后端会等待数据库就绪并完成配置，这可能需要一点时间。你可以通过查看日志来确认进度。
在另一个终端中查看日志：
docker compose logs
查看某个特定服务的日志时，可以加上服务名，例如：
docker compose logs backend
Mailcatcher
Mailcatcher 是一个简单的 SMTP 服务器，在本地开发过程中会拦截后端发出的所有邮件。邮件不会真正发送出去，而是通过 Web 界面展示。
它适用于：
- 在开发阶段测试邮件功能；
- 检查邮件内容与排版；
- 调试邮件相关逻辑，而无需发送真实邮件。
在本地使用 Docker Compose 运行时，后端会自动配置为使用 Mailcatcher（SMTP 端口为 1025）。所有被捕获的邮件可以在 http://localhost:1080 查看。
本地开发
Docker Compose 文件已经配置好，让每个服务在 localhost 上使用不同端口。
后端与前端使用的端口与其本地开发服务器一致：后端为 http://localhost:8000，前端为 http://localhost:5173。
这样你可以随时关闭某个 Docker 服务并启动本地开发服务器，其余服务仍能通过相同端口正常访问。
例如，想用本地 Vite 开发服务器，可以在另一个终端中停止 Docker 中的 frontend 服务：
docker compose stop frontend
然后启动本地前端开发服务器：
cd frontend
npm run dev
同样地，可以停止 Docker 中的 backend 服务：
docker compose stop backend
接着运行本地后端开发服务器：
cd backend
fastapi dev app/main.py
在 localhost.tiangolo.com 下使用 Docker Compose
启动 Docker Compose stack 时，默认使用 localhost，不同服务（后端、前端、Adminer 等）分别占用不同端口。
在生产（或预发布）环境中，每个服务通常使用不同子域名，例如后端使用 api.example.com，前端使用 dashboard.example.com。
在 deployment.md 中提到的 Traefik 就是用于根据子域名将请求转发到对应服务的反向代理。
如果你想在本地完整测试这套子域名路由方案，可以修改本地 .env 文件中的配置：
DOMAIN=localhost.tiangolo.com
该值会被 Docker Compose 用于配置各服务的基础域名。
Traefik 会将 api.localhost.tiangolo.com 的请求转发到后端，将 dashboard.localhost.tiangolo.com 的请求转发到前端。
localhost.tiangolo.com 是一个特殊域名，它及其所有子域名都指向 127.0.0.1，非常适合作为本地多子域名开发环境。
修改 .env 后，重新运行：
docker compose watch
在生产环境部署时，主 Traefik 一般在 Docker Compose 之外单独配置。本地开发时，docker-compose.override.yml 中包含了一个 Traefik 配置，仅用于测试如 api.localhost.tiangolo.com 与 dashboard.localhost.tiangolo.com 这样的本地域名是否按预期工作。
Docker Compose 文件与环境变量
主配置文件 docker-compose.yml 包含整个 stack 的全部配置，docker compose 会自动读取它。
另外还有一个 docker-compose.override.yml 文件，专门用于开发环境的覆盖配置，例如将源代码目录挂载为 volume。docker compose 会自动将其作为 docker-compose.yml 的覆盖层进行合并。
这些 Docker Compose 文件会读取 .env 文件中的配置，并将其作为环境变量注入到容器中。
此外，在运行 docker compose 命令前，某些脚本可能会设置额外的环境变量供配置使用。
修改环境变量后，请记得重启 stack：
docker compose watch
.env 文件
.env 文件包含所有配置、生成的密钥和密码等。
根据你的工作流程，你可能希望将其从 Git 中排除（尤其当项目是公开的）。在这种情况下，需要确保 CI 工具在构建或部署时能够获取到这些配置。
一种做法是：将每个环境变量添加到 CI/CD 系统中，并修改 docker-compose.yml，让它读取对应的环境变量，而不是从 .env 文件中读取。
Pre-commit 与代码检查
本项目使用 pre-commit 进行代码检查与格式化。
安装后，它会在每次 git commit 之前自动运行，确保代码在提交前就保持一致的风格和格式。
项目根目录下有一个 .pre-commit-config.yaml 配置文件，定义了所有检查规则。
安装 pre-commit 以自动运行
pre-commit 已经作为项目依赖的一部分，你也可以按照 官方文档 全局安装它。
安装好 pre-commit 工具后，需要在本地仓库"安装"它，使其在每次提交前自动执行。
使用 uv 的方式：
❯ uv run pre-commit install
pre-commit installed at .git/hooks/pre-commit
现在每次执行 commit 时，例如：
git commit
...pre-commit 都会运行，检查并格式化即将提交的代码，如果有修改会要求你重新 git add 这些文件后再提交。
然后你可以 git add 修改 / 修复的文件，再执行 commit。
手动运行 pre-commit 钩子
你也可以手动对所有文件运行 pre-commit，使用 uv 的方式：
❯ uv run pre-commit run --all-files
check for added large files..............................................Passed
check toml...............................................................Passed
check yaml...............................................................Passed
ruff.....................................................................Passed
ruff-format..............................................................Passed
eslint...................................................................Passed
prettier.................................................................Passed
访问地址
生产或预发布环境使用相同的路径结构，只是替换为你自己的域名。
开发环境地址
以下是本地开发环境的地址。
自动生成的交互式文档（Swagger UI）：http://localhost:8000/docs
自动生成的备选文档（ReDoc）：http://localhost:8000/redoc
Adminer：http://localhost:8080
Traefik UI：http://localhost:8090
MailCatcher：http://localhost:1080
配置 localhost.tiangolo.com 后的开发地址
以下是本地开发环境的地址。
前端：http://dashboard.localhost.tiangolo.com
后端：http://api.localhost.tiangolo.com
自动生成的交互式文档（Swagger UI）：http://api.localhost.tiangolo.com/docs
自动生成的备选文档（ReDoc）：http://api.localhost.tiangolo.com/redoc
Adminer：http://localhost.tiangolo.com:8080
Traefik UI：http://localhost.tiangolo.com:8090
MailCatcher：http://localhost.tiangolo.com:1080