panda
db867dcbe5
Deploy to Staging / deploy (push) Has been cancelled
Conflict detector / main (push) Has been cancelled
Lint Backend / lint-backend (push) Has been cancelled
Playwright Tests / changes (push) Has been cancelled
Test Backend / test-backend (push) Has been cancelled
Test Docker Compose / test-docker-compose (push) Has been cancelled
Playwright Tests / test-playwright (1, 4) (push) Has been cancelled
Playwright Tests / test-playwright (2, 4) (push) Has been cancelled
Playwright Tests / test-playwright (3, 4) (push) Has been cancelled
Playwright Tests / test-playwright (4, 4) (push) Has been cancelled
Playwright Tests / merge-playwright-reports (push) Has been cancelled
Playwright Tests / alls-green-playwright (push) Has been cancelled
Issue Manager / issue-manager (push) Has been cancelled
220 lines
7.4 KiB
Markdown
220 lines
7.4 KiB
Markdown
# FastAPI 项目 - 开发（Development）
|
||
|
||
## Docker Compose
|
||
|
||
* 使用 Docker Compose 启动本地 stack：
|
||
|
||
```bash
|
||
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 时，后端会等待数据库就绪并完成配置，这可能需要一点时间。你可以通过查看日志来确认进度。
|
||
|
||
在另一个终端中查看日志：
|
||
|
||
```bash
|
||
docker compose logs
|
||
```
|
||
|
||
查看某个特定服务的日志时，可以加上服务名，例如：
|
||
|
||
```bash
|
||
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` 服务：
|
||
|
||
```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
|
||
```
|
||
|
||
## 访问地址
|
||
|
||
生产或预发布环境使用相同的路径结构，只是替换为你自己的域名。
|
||
|
||
### 开发环境地址
|
||
|
||
以下是本地开发环境的地址。
|
||
|
||
前端：<http://localhost:5173>
|
||
|
||
后端：<http://localhost:8000>
|
||
|
||
自动生成的交互式文档（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>
|