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