From 30121cc427bb38fe4e3206321868e98815adc573 Mon Sep 17 00:00:00 2001 From: Wu Clan Date: Tue, 24 Dec 2024 22:23:52 +0800 Subject: [PATCH] update docs --- docs/guide/deploy/Docker.md | 438 +++++++++++++++--------------- docs/guide/reference/db.md | 43 ++- docs/guide/summary/quick-start.md | 73 +++-- 3 files changed, 309 insertions(+), 245 deletions(-) diff --git a/docs/guide/deploy/Docker.md b/docs/guide/deploy/Docker.md index bda2177..914555b 100644 --- a/docs/guide/deploy/Docker.md +++ b/docs/guide/deploy/Docker.md @@ -2,29 +2,29 @@ title: Docker 部署 --- -> [!WARNING] -> -> 默认端口冲突：8000，3306，6379，5672 -> -> 建议在部署前关闭本地服务：mysql，redis，rabbitmq... +::: warning +默认端口冲突：8000、3306、6379、5672、5432 + +如果 docker 容器启动时端口被占用，会导致启动失败，建议在启动前检查本地端口占用情况 +::: ## 本机部署 -> [!CAUTION] -> **部署** 意味着你的所有代码已经准备就绪，可以用于生产，而本机部署则是为了能够快捷的提供本地 API 服务，所以，此教程仅提供 API 本机部署教程 +本机部署是为了能够快捷的提供本地 API 服务 ### 后端 :::: steps + 1. env - 进入 `deploy/backend/docker-compose` 目录，创建环境变量文件 `.env` + 进入 `deploy/backend/docker-compose` 目录，创建环境变量文件 `.env` ```shell touch .env.server ../../../backend/.env ``` - 将初始化环境变量配置拷贝到环境变量文件中 + 将初始化环境变量配置拷贝到环境变量文件中 ```shell cp .env.server ../../../backend/.env @@ -32,10 +32,10 @@ title: Docker 部署 2. 按需修改配置文件 `backend/core/conf.py` 和 `.env` 3. 执行一键启动命令 - - ::: info - 命令执行期间遇到镜像拉取问题请自行 Google - ::: + + ::: info + 命令执行期间遇到镜像拉取问题请自行 Google + ::: ```shell docker-compose up -d --build @@ -43,12 +43,13 @@ title: Docker 部署 4. 等待命令执行完成 5. 打开浏览器访问：[http://127.0.0.1:8000/api/v1/docs](http://127.0.0.1:8000/api/v1/docs) -:::: + :::: ### 前端 -> [!CAUTION] -> 此教程不提供前端本机部署方案，对于前后端本地开发或联调，你不应该进行部署，请转至文档：[本地开发](../summary/quick-start.md#本地开发) +::: caution +此教程不提供前端本机部署方案，对于前后端本地开发或联调，请转至文档：[本地开发](../summary/quick-start.md#本地开发) +::: ## 服务器部署 @@ -58,10 +59,12 @@ title: Docker 部署 ### 后端 :::: steps + 1. 拉取代码到服务器 - 将代码拉取到服务器通常采用 ssh 方式（更安全），但是你也可以选择使用 https 方式，具体方式请根据个人自行决定，如果使用 ssh 方式拉取代码， - 请自行 Google 拉取教程，如果使用 https 方式，你可以查看 [后端步骤2](../introduction/quick-start.md#后端) + 将代码拉取到服务器通常采用 ssh 方式（更安全），但是你也可以选择使用 https 方式，具体方式请根据个人自行决定，如果使用 ssh + 方式拉取代码， + 请自行 Google 拉取教程，如果使用 https 方式，你可以查看 [后端步骤2](../introduction/quick-start.md#后端) 2. env @@ -82,182 +85,197 @@ title: Docker 部署 建议修改 `.env` 中的 `ENVIRONMENT` 为 `pro` 4. 更新脚本文件 - - 仓库内的 `docker-compose.yml` 文件默认为后端独立部署，如果你没有前端需求，而只需调用后端 API，请查看 [本机部署](#本机部署) - - ::: details - ```yaml - version: "3.10" - - networks: - fba_network: - name: fba_network - driver: bridge - ipam: - driver: default - config: - - subnet: 172.10.10.0/24 - - volumes: - fba_mysql: - name: fba_mysql - fba_redis: - name: fba_redis - fba_static: - name: fba_static - fba_rabbitmq: - name: fba_rabbitmq - - services: - fba_server: - build: - context: ../../../ - dockerfile: backend/backend.dockerfile - image: fba_server:latest - container_name: fba_server - restart: always - depends_on: - - fba_mysql - - fba_redis - - fba_celery - volumes: - - fba_static:/fba/backend/app/static - networks: - - fba_network - command: - - bash - - -c - - | - wait-for-it -s fba_mysql:3306 -s fba_redis:6379 -t 300 - mkdir -p /var/log/supervisor/ - supervisord -c /fba/deploy/backend/supervisor.conf - supervisorctl restart fastapi_server - - fba_mysql: - image: mysql:8.0.29 - ports: - - "${DOCKER_MYSQL_MAP_PORT:-3306}:3306" - container_name: fba_mysql - restart: always - environment: - MYSQL_DATABASE: fba - MYSQL_ROOT_PASSWORD: 123456 - TZ: Asia/Shanghai - volumes: - - fba_mysql:/var/lib/mysql - networks: - - fba_network - command: - --default-authentication-plugin=mysql_native_password - --character-set-server=utf8mb4 - --collation-server=utf8mb4_general_ci - --lower_case_table_names=1 - - fba_redis: - image: redis:6.2.7 - ports: - - "${DOCKER_REDIS_MAP_PORT:-6379}:6379" - container_name: fba_redis - restart: always - environment: - - TZ=Asia/Shanghai - volumes: - - fba_redis:/var/lib/redis - networks: - - fba_network - - # 后端专用，这与 fba_ui 冲突，如果你选择使用 fba_ui， // [!code focus:51] // [!code --:15] - # 你应该注释或删除 fba_nginx 容器脚本，并使用 fba_ui 容器 - fba_nginx: - image: nginx - ports: - - "8000:80" - container_name: fba_nginx - restart: always - depends_on: - - fba_server - volumes: - - ../nginx.conf:/etc/nginx/nginx.conf:ro - - fba_static:/www/fba_server/backend/static - networks: - - fba_network - - # 如果服务器内存小于 4GB，CPU 小于四个内核 // [!code ++:34] - # 建议进入 fba_ui 项目单独构建这个容器（参考下方前端部署教程） - # 如果你不选择单独构建，务必在执行下面步骤前根据前端部署教程更新前端配置文件 - # 如果你选择单独构建，务必注释或删除此容器脚本 - fba_ui: - build: - context: /root/fastapi_best_architecture_ui # 根据 fba_ui 项目存放目录修改此路径 - dockerfile: Dockerfile - image: fba_ui:latest - ports: - - "80:80" - - "443:443" - container_name: fba_ui - restart: always - depends_on: - - fba_server - command: - - nginx - - -g - - daemon off; - volumes: - # nginx https conf - # 通过 docker 进行部署时，需要打开此配置项并确保<挂载到容器内的证书文件路径>配置 - # 与 nginx conf 中的 ssl 证书文件路径配置一致，如果你直接将 ssl 证书文件 cp - # 到了 docker 容器内，则无需挂载证书文件，直接将它们注释或删除即可 - # local_ssl_pem_path：你在服务器存放 ssl pem 证书文件的路径，自行修改 - # local_ssl_key_path: 你在服务器存放 ssl key 证书文件的路径，自行修改 - # /etc/ssl/xxx.pem：挂载到容器内 ssl pem 证书文件的路径，自行修改 - # /etc/ssl/xxx.key：挂载到容器内 ssl key 证书文件的路径，自行修改 - - local_ssl_pem_path:/etc/ssl/xxx.pem - - local_ssl_key_path:/etc/ssl/xxx.key - - fba_static:/www/fba_server/backend/static - networks: - - fba_network - - fba_rabbitmq: - hostname: fba_rabbitmq - image: rabbitmq:3.12.7 - ports: - - "15672:15672" - - "5672:5672" - container_name: fba_rabbitmq - restart: always - environment: - - RABBITMQ_DEFAULT_USER=guest - - RABBITMQ_DEFAULT_PASS=guest - volumes: - - fba_rabbitmq:/var/lib/rabbitmq - networks: - - fba_network - - fba_celery: - build: - context: ../../../ - dockerfile: backend/celery.dockerfile - image: fba_celery:latest - ports: - - "8555:8555" - container_name: fba_celery - restart: always - depends_on: - - fba_rabbitmq - networks: - - fba_network - command: - - bash - - -c - - | - wait-for-it -s fba_rabbitmq:5672 -t 300 - mkdir -p /var/log/supervisor/ - supervisord -c /fba/deploy/backend/supervisor.conf - supervisorctl restart celery_worker - supervisorctl restart celery_beat - supervisorctl restart celery_flower - ``` - ::: + + 如果你没有前端需求，请查看 [本机部署](#本机部署)，否则，请查看下方脚本并修改 `docker-compose.yml` 文件 + + ```yaml :collapsed-lines=6 + version: "3.10" + + networks: + fba_network: + name: fba_network + driver: bridge + ipam: + driver: default + config: + - subnet: 172.10.10.0/24 + + volumes: + fba_mysql: + name: fba_mysql + fba_redis: + name: fba_redis + fba_static: + name: fba_static + fba_rabbitmq: + name: fba_rabbitmq + + services: + fba_server: + build: + context: ../../../ + dockerfile: backend/backend.dockerfile + image: fba_server:latest + container_name: fba_server + restart: always + depends_on: + - fba_mysql + - fba_redis + - fba_celery + volumes: + - fba_static:/fba/backend/app/static + networks: + - fba_network + command: + - bash + - -c + - | + wait-for-it -s fba_mysql:3306 -s fba_redis:6379 -t 300 + mkdir -p /var/log/supervisor/ + supervisord -c /fba/deploy/backend/supervisor.conf + supervisorctl restart fastapi_server + + fba_mysql: + image: mysql:8.0.29 + ports: + - "${DOCKER_MYSQL_MAP_PORT:-3306}:3306" + container_name: fba_mysql + restart: always + environment: + MYSQL_DATABASE: fba + MYSQL_ROOT_PASSWORD: 123456 + TZ: Asia/Shanghai + volumes: + - fba_mysql:/var/lib/mysql + networks: + - fba_network + command: + --default-authentication-plugin=mysql_native_password + --character-set-server=utf8mb4 + --collation-server=utf8mb4_general_ci + --lower_case_table_names=1 + + # 如果你是 postgres 用户，应保留 fba_postgres 容器脚本并删除 fba_mysql 容器脚本 // [!code focus:16] // [!code ++:16] + # 否则，删除 fba_postgres 容器脚本 + fba_postgres: + image: postgres:16 + ports: + - "${DOCKER_MYSQL_MAP_PORT:-5432}:5432" + container_name: fba_postgres + restart: always + environment: + POSTGRES_DB: fba + POSTGRES_PASSWORD: 123456 + TZ: Asia/Shanghai + volumes: + - fba_mysql:/var/lib/postgresql/data + networks: + - fba_network + + fba_redis: + image: redis:6.2.7 + ports: + - "${DOCKER_REDIS_MAP_PORT:-6379}:6379" + container_name: fba_redis + restart: always + environment: + - TZ=Asia/Shanghai + volumes: + - fba_redis:/var/lib/redis + networks: + - fba_network + + # 后端专用，这与 fba_ui 容器冲突，如果你选择使用 fba_ui 容器，// [!code focus:51] // [!code --:15] + # 你应该注释或删除 fba_nginx 容器脚本，并使用 fba_ui 容器 + fba_nginx: + image: nginx + ports: + - "8000:80" + container_name: fba_nginx + restart: always + depends_on: + - fba_server + volumes: + - ../nginx.conf:/etc/nginx/nginx.conf:ro + - fba_static:/www/fba_server/backend/static + networks: + - fba_network + + # 如果服务器内存小于 4GB，CPU 小于四个内核 // [!code ++:34] + # 建议进入 fba_ui 项目单独构建这个容器（参考下方前端部署教程） + # 如果你不选择单独构建，务必在执行下面步骤前根据前端部署教程更新前端配置文件 + # 如果你选择单独构建，务必注释或删除此容器脚本 + fba_ui: + build: + context: /root/fastapi_best_architecture_ui # 根据 fba_ui 项目存放目录修改此路径 + dockerfile: Dockerfile + image: fba_ui:latest + ports: + - "80:80" + - "443:443" + container_name: fba_ui + restart: always + depends_on: + - fba_server + command: + - nginx + - -g + - daemon off; + volumes: + # nginx https conf + # 通过 docker 进行部署时，需要打开此配置项并确保<挂载到容器内的证书文件路径>配置 + # 与 nginx conf 中的 ssl 证书文件路径配置一致，如果你直接将 ssl 证书文件 cp + # 到了 docker 容器内，则无需挂载证书文件，直接将它们注释或删除即可 + # local_ssl_pem_path：你在服务器存放 ssl pem 证书文件的路径，自行修改 + # local_ssl_key_path: 你在服务器存放 ssl key 证书文件的路径，自行修改 + # /etc/ssl/xxx.pem：挂载到容器内 ssl pem 证书文件的路径，自行修改 + # /etc/ssl/xxx.key：挂载到容器内 ssl key 证书文件的路径，自行修改 + - local_ssl_pem_path:/etc/ssl/xxx.pem + - local_ssl_key_path:/etc/ssl/xxx.key + - fba_static:/www/fba_server/backend/static + networks: + - fba_network + + fba_rabbitmq: + hostname: fba_rabbitmq + image: rabbitmq:3.12.7 + ports: + - "15672:15672" + - "5672:5672" + container_name: fba_rabbitmq + restart: always + environment: + - RABBITMQ_DEFAULT_USER=guest + - RABBITMQ_DEFAULT_PASS=guest + volumes: + - fba_rabbitmq:/var/lib/rabbitmq + networks: + - fba_network + + fba_celery: + build: + context: ../../../ + dockerfile: backend/celery.dockerfile + image: fba_celery:latest + ports: + - "8555:8555" + container_name: fba_celery + restart: always + depends_on: + - fba_rabbitmq + networks: + - fba_network + command: + - bash + - -c + - | + wait-for-it -s fba_rabbitmq:5672 -t 300 + mkdir -p /var/log/supervisor/ + supervisord -c /fba/deploy/backend/supervisor.conf + supervisorctl restart celery_worker + supervisorctl restart celery_beat + supervisorctl restart celery_flower + ``` 5. 执行一键启动命令 @@ -270,7 +288,7 @@ title: Docker 部署 ``` 6. 等待命令执行完成 -:::: + :::: ### 前端 @@ -279,17 +297,17 @@ title: Docker 部署 ::: :::: steps + 1. 拉取代码到服务器 2. env 修改 `.env.production` 中的 `VITE_API_BASE_URL` 为域名地址 -3. 更新 nginx +3. 更新 nginx 配置 - 进入 deploy 目录，编辑 nginx.conf 文件 + 进入 deploy 目录，修改 `nginx.conf` 文件 - ::: details - ``` + ``` :collapsed-lines=6 # For more information on configuration, see: # * Official English Documentation: http://nginx.org/en/docs/ # * Official Russian Documentation: http://nginx.org/ru/docs/ @@ -326,7 +344,7 @@ title: Docker 部署 listen [::]:80 default_server; server_name 127.0.0.1; - listen 443 ssl; // [!code focus:10] // [!code ++:10] + listen 443 ssl; // [!code focus:10] // [!code ++:9] # docker ssl 证书文件路径配置应该与 docker-compose 中的保持一致 # /etc/ssl/xxx.pem：挂载到容器内 ssl pem 证书文件的路径，自行修改 # /etc/ssl/xxx.key：挂载到容器内 ssl key 证书文件的路径，自行修改 @@ -372,16 +390,14 @@ title: Docker 部署 } } ``` - ::: 4. 更新脚本文件 ::: warning - 如果已通过后端 docker-compose 构建前端项目，此步骤和后面的剩余步骤直接跳过即可 + 如果你已通过后端 docker-compose 构建前端项目，此步骤和后面的剩余步骤直接跳过即可 ::: - ::: details - ```yaml + ```yaml :collapsed-lines=6 networks: fba_network: external: true @@ -420,7 +436,6 @@ title: Docker 部署 networks: - fba_network ``` - ::: 5. 构建并启动容器 @@ -429,24 +444,25 @@ title: Docker 部署 ```shell docker network create fba_network ``` - + 构建 ```shell docker-compose build fba_ui ``` - + 启动 ```shell docker-compose run fba_ui ``` + :::: ## 注意事项 ::: warning -请不要频繁使用 `docker-compose up -d --build` 命令，每次执行，此命令都会构建容器，并将原容器自动进行本地备份保留，这会导致硬盘空间迅速递减 +不建议频繁使用 `docker-compose up -d --build` 命令，此命令每次执行都会重新构建容器，并将原容器自动本地备份保留，这会导致硬盘空间迅速锐减 ::: 清理未使用的镜像 @@ -466,9 +482,3 @@ docker container prune ```shell docker system prune ``` - -清理所有悬空的镜像和卷 - -```shell -docker system prune -a --volumes -``` diff --git a/docs/guide/reference/db.md b/docs/guide/reference/db.md index 18a09db..c8c65ec 100644 --- a/docs/guide/reference/db.md +++ b/docs/guide/reference/db.md @@ -2,4 +2,45 @@ title: 切换数据库 --- -coming soon... +FBA 支持 MySQL、PostgreSQL 两种数据库，默认配置使用 MySQL + +::: tip +此教程仅适用于 pg 用户 +::: + +如果本地未安装 pg，你可以使用以下命令创建 Docker 镜像 + +```shell +docker run -d --name fba_postgres --restart always -e POSTGRES_DB='fba' -e POSTGRES_PASSWORD='123456' -e TZ='Asia/Shanghai' -v fba_postgrs:/var/lib/postgresql/data -p 5432:5432 postgres:16 +``` + +## 默认配置 + +pg 与 MySQL 在用户名、端口号等方面有所不同，如果你使用上面的命令创建了 Docker 镜像，需修改 `.env` 部分配置如下，否则，请根据 +pg 配置进行修改 + +```env +# Database +DATABASE_TYPE='postgresql' +DATABASE_HOST='127.0.0.1' +DATABASE_PORT=5432 +DATABASE_USER='postgres' +DATABASE_PASSWORD='123456' +``` + +## 注意事项 + +FBA 在模型中使用 `with_variant` 尽可能兼容 MySQL 和 PostgreSQL，例如： + +```python +# [!code word:with_variant] +remark: Mapped[str | None] = mapped_column(LONGTEXT().with_variant(TEXT, 'postgresql')) +``` + +兼容性代码涉及的其他地方： + +- 代码生成 +- 创建数据库链接 +- docker-compose.yml + +如果你只使用其中一种数据库，可直接修改为数据库对应类型 diff --git a/docs/guide/summary/quick-start.md b/docs/guide/summary/quick-start.md index 26b5b5e..6af2b7a 100644 --- a/docs/guide/summary/quick-start.md +++ b/docs/guide/summary/quick-start.md @@ -9,18 +9,22 @@ title: 快速开始 ### 后端 +::: tip +如果你是 PostgreSQL 用户，请先移步到 [切换数据库](../reference/db.md) +::: + :::: steps 1. 准备本地环境 * Python 3.10+ - * Mysql 8.0+ + * MySQL 8.0+ 或 PostgreSQL 16.0 + * Redis 推荐最新稳定版 2. 准备 Git 仓库 ::: info - 提供两种方案，选择其中一种即可 + 两种方案，选择其中一种即可 ::: 1. 拉取源代码仓库 @@ -31,9 +35,9 @@ title: 快速开始 git clone https://github.com/fastapi-practices/fastapi_best_architecture.git ``` - 2. 拉取模板仓库 + 2. 创建模板仓库 - 此项目支持创建模板仓库，意味着，你可以直接创建一个非 fork（独立无绑定的关系）的个人账户仓库，如果所示，进入此项目 + 此项目支持创建模板仓库，意味着，你可以直接创建一个非 fork（独立无绑定的关系）的个人仓库，如果所示，进入此项目 GitHub 首页， 使用 `use this template` 按钮创建即可，创建完成之后，使用 `git clone` 命令拉取你自己的仓库即可 @@ -47,7 +51,7 @@ title: 快速开始 pip install -r requirements.txt ``` -4. 创建一个数据库：`fba`，选择 utf8mb4 编码 +4. 创建数据库：`fba`，选择 utf8mb4 编码，postgres 用户可忽略编码 5. 启动 Redis 6. env @@ -69,21 +73,27 @@ title: 快速开始 默认情况下，首次启动不需要修改 ::: -8. 数据库迁移 [alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html) +8. 创建数据库表（三选一） - 生成迁移文件 + - 直接启动后端项目（自动创建） + - 数据库迁移 [alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html) - ```shell - alembic revision --autogenerate - ``` + ::: details + 生成迁移文件 - 执行迁移 + ```shell + alembic revision --autogenerate + ``` - ```shell - alembic upgrade head - ``` + 执行迁移 + + ```shell + alembic upgrade head + ``` + ::: + - 执行 `backend/sql/` 目录下对应数据库的 `create_tables.sql` 脚本 -9. 启动 celery worker, beat 和 flower ==(可选)== +9. ==（可选）== 启动 celery worker, beat 和 flower Celery 应用程序 @@ -105,11 +115,13 @@ title: 快速开始 10. 初始化测试数据 - 使用 `backend/sql/init_test_data.sql` 文件初始化测试数据 + 执行 `backend/sql/init_test_data.sql` 脚本初始化测试数据 11. 启动 fastapi 服务 - 此项目采用 fastapi CLI 应用启动服务，当前，为了方便本地调试，你仍然可以选择使用 pycharm 右键运行 `main.py` 文件 + ::: warning + 此项目默认使用 CLI 启动服务，为了方便本地调试，你仍然可以选择在 IDE 中右键运行 main.py 文件 + ::: 帮助 @@ -129,6 +141,12 @@ title: 快速开始 ### 前端 +::: caution +目前它仅作为效果演示，而不是用于生产！ + +如果你不想因前端依赖安装问题带来困扰，请务必使用 yarn v1.x 版本 +::: + :::: steps 1. 准备本地环境 @@ -138,12 +156,6 @@ title: 快速开始 2. 安装和启动 - ::: caution - 目前它仅作为效果演示，而不是用于生产！ - - 如果你不想因前端依赖安装问题带来困扰，请务必使用 yarn v1.x 版本 - ::: - 安装依赖 ```shell @@ -156,11 +168,12 @@ title: 快速开始 yarn dev ``` - ::: warning + ::: tip 第一次启动可能会很慢，你可以查看此 [Issue](https://github.com/fastapi-practices/fastapi_best_architecture_ui/issues/72) 查看详情 ::: - :::: + +:::: ## 开发流程 @@ -187,15 +200,15 @@ title: 快速开始 通过 `pytest` 运行单元测试，项目内仅提供了非常简易的 demo，并不是完整单元测试，如需要，请自行编写 ::: -::: steps +:::: steps -1. 创建测试数据库 `fba_test`，选择 utf8mb4 编码 -2. 使用 `backend/sql/create_tables.sql` 文件创建数据库表 -3. 使用 `backend/sql/init_pytest_data.sql` 文件初始化用于单元测试的测试数据 +1. 创建测试数据库 `fba_test`，选择 utf8mb4 编码，postgres 用户可忽略编码 +2. 创建数据库表，执行 `backend/sql/` 目录下对应数据库的 `create_tables.sql` 脚本 +3. 初始化测试数据，执行 `backend/sql/` 目录下对应数据库的 `init_test_data.sql` 脚本 4. 进入 `backend` 目录，执行单元测试命令 ```shell pytest -vs --disable-warnings ``` -::: +::::