Skip to content

Commit c59a983

Browse files
wu-clanwu-clan
committed
update docs
1 parent d462af6 commit c59a983

File tree

15 files changed

+793
-843
lines changed

15 files changed

+793
-843
lines changed

‎docs/.vuepress/config.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,6 @@ export default defineUserConfig({
6969
},
7070
// watermark: false,
7171
markdown: {
72-
alert: true,
7372
abbr: true,
7473
annotation: true,
7574
mermaid: true,

‎docs/code/docker-compose.yml‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
services:
2+
fba_server:
3+
build:
4+
context: .
5+
dockerfile: Dockerfile
6+
image: fba_server:latest
7+
container_name: fba_server
8+
restart: always
9+
# 如果你是 postgres 用户，应将 fba_mysql 修改为 fba_postgres
10+
depends_on: # [!code warning:2]
11+
- fba_mysql
12+
- fba_redis
13+
- fba_celery
14+
volumes:
15+
- ./deploy/backend/docker-compose/.env.server:/fba/backend/.env
16+
- fba_static:/fba/backend/app/static
17+
networks:
18+
- fba_network
19+
# 如果你是 postgres 用户，应将 fba_mysql:3306 修改为 fba_postgres:5432
20+
command: # [!code warning:5]
21+
- bash
22+
- -c
23+
- |
24+
wait-for-it -s fba_mysql:3306 -s fba_redis:6379 -t 300
25+
mkdir -p /var/log/supervisor/
26+
supervisord -c /fba/deploy/backend/supervisor.conf
27+
supervisorctl restart fastapi_server
28+
29+
fba_mysql:
30+
image: mysql:8.0.41
31+
ports:
32+
- "${DOCKER_MYSQL_MAP_PORT:-3306}:3306"
33+
container_name: fba_mysql
34+
restart: always
35+
environment:
36+
MYSQL_DATABASE: fba
37+
MYSQL_ROOT_PASSWORD: 123456
38+
TZ: Asia/Shanghai
39+
volumes:
40+
- fba_mysql:/var/lib/mysql
41+
networks:
42+
- fba_network
43+
command:
44+
--default-authentication-plugin=mysql_native_password
45+
--character-set-server=utf8mb4
46+
--collation-server=utf8mb4_general_ci
47+
--lower_case_table_names=1
48+
49+
# 如果你是 postgres 用户，应保留 fba_postgres 容器脚本并删除 fba_mysql 容器脚本
50+
# 否则，删除 fba_postgres 容器脚本
51+
fba_postgres: # [!code warning:14]
52+
image: postgres:16
53+
ports:
54+
- "${DOCKER_MYSQL_MAP_PORT:-5432}:5432"
55+
container_name: fba_postgres
56+
restart: always
57+
environment:
58+
POSTGRES_DB: fba
59+
POSTGRES_PASSWORD: 123456
60+
TZ: Asia/Shanghai
61+
volumes:
62+
- fba_mysql:/var/lib/postgresql/data
63+
networks:
64+
- fba_network
65+
66+
fba_redis:
67+
image: redis
68+
ports:
69+
- "${DOCKER_REDIS_MAP_PORT:-6379}:6379"
70+
container_name: fba_redis
71+
restart: always
72+
environment:
73+
- TZ=Asia/Shanghai
74+
volumes:
75+
- fba_redis:/usr/local/etc/redis
76+
networks:
77+
- fba_network
78+
79+
# 后端专用，如果使用此容器，意味着你只需部署后端 API 服务，不需要前端；
80+
# 这与下面的 fba_ui 容器冲突，如果你选择使用 fba_ui 容器
81+
# 你应该注释或删除 fba_nginx 容器脚本，并使用 fba_ui 容器
82+
fba_nginx: # [!code warning:13]
83+
image: nginx
84+
ports:
85+
- "8000:80"
86+
container_name: fba_nginx
87+
restart: always
88+
depends_on:
89+
- fba_server
90+
volumes:
91+
- ./deploy/backend/nginx.conf:/etc/nginx/conf.d/default.conf:ro
92+
- fba_static:/www/fba_server/backend/static
93+
networks:
94+
- fba_network
95+
96+
# 如果服务器内存小于 4GB，CPU 小于四个内核
97+
# 建议进入 fba_ui 项目单独构建这个容器（参考下方前端部署教程）
98+
# 如果你不选择单独构建，务必在执行下面步骤前根据前端部署教程更新前端配置文件
99+
# 如果你选择单独构建，务必注释或删除此容器脚本
100+
fba_ui: # [!code warning:30]
101+
build:
102+
context: /root/fastapi_best_architecture_ui # 根据 Arco Desgin Vue 项目存放目录修改此路径
103+
dockerfile: Dockerfile
104+
image: fba_ui:latest
105+
ports:
106+
- "80:80"
107+
- "443:443"
108+
container_name: fba_ui
109+
restart: always
110+
depends_on:
111+
- fba_server
112+
command:
113+
- nginx
114+
- -g
115+
- daemon off;
116+
volumes:
117+
# nginx https conf
118+
# 通过 docker 进行部署时，需要打开此配置项并确保<挂载到容器内的证书文件路径>配置
119+
# 与 nginx conf 中的 ssl 证书文件路径配置一致，如果你直接将 ssl 证书文件 cp
120+
# 到了 docker 容器内，则无需挂载证书文件，直接将它们注释或删除即可
121+
# local_ssl_pem_path：你在服务器存放 ssl pem 证书文件的路径，自行修改
122+
# local_ssl_key_path: 你在服务器存放 ssl key 证书文件的路径，自行修改
123+
# /etc/ssl/xxx.pem：挂载到容器内 ssl pem 证书文件的路径，自行修改
124+
# /etc/ssl/xxx.key：挂载到容器内 ssl key 证书文件的路径，自行修改
125+
- local_ssl_pem_path:/etc/ssl/xxx.pem
126+
- local_ssl_key_path:/etc/ssl/xxx.key
127+
- fba_static:/www/fba_server/backend/static
128+
networks:
129+
- fba_network
130+
131+
fba_rabbitmq:
132+
hostname: fba_rabbitmq
133+
image: rabbitmq:3.13.7
134+
ports:
135+
- "15672:15672"
136+
- "5672:5672"
137+
container_name: fba_rabbitmq
138+
restart: always
139+
environment:
140+
- RABBITMQ_DEFAULT_USER=guest
141+
- RABBITMQ_DEFAULT_PASS=guest
142+
volumes:
143+
- fba_rabbitmq:/var/lib/rabbitmq
144+
networks:
145+
- fba_network
146+
147+
fba_celery:
148+
build:
149+
context: .
150+
dockerfile: Dockerfile
151+
args:
152+
- SERVER_TYPE=celery
153+
image: fba_celery:latest
154+
ports:
155+
- "8555:8555"
156+
container_name: fba_celery
157+
restart: always
158+
depends_on:
159+
- fba_rabbitmq
160+
networks:
161+
- fba_network
162+
command:
163+
- bash
164+
- -c
165+
- |
166+
wait-for-it -s fba_rabbitmq:5672 -t 300
167+
mkdir -p /var/log/supervisor/
168+
supervisord -c /fba/deploy/backend/supervisor.conf
169+
supervisorctl restart celery_worker
170+
supervisorctl restart celery_beat
171+
supervisorctl restart celery_flower
172+
173+
networks:
174+
fba_network:
175+
name: fba_network
176+
driver: bridge
177+
ipam:
178+
driver: default
179+
config:
180+
- subnet: 172.10.10.0/24
181+
182+
volumes:
183+
# 如果你是 postgres 用户，应将 fba_mysql 修改为 fba_postgres
184+
fba_mysql: # [!code warning:2]
185+
name: fba_mysql
186+
fba_redis:
187+
name: fba_redis
188+
fba_static:
189+
name: fba_static
190+
fba_static_upload:
191+
name: fba_static_upload
192+
fba_rabbitmq:
193+
name: fba_rabbitmq

‎docs/code/fastapi-specific-standards-for-fba.mdc‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# FastAPI Best Architecture
2+
3+
您是 FastAPI 和可扩展 API 开发方面的专家，请严格遵循以下原则：
4+
5+
1. 依赖管理
6+
- 使用 FastAPI 的依赖注入系统管理状态和共享资源
7+
- 遵循项目的依赖版本要求：
8+
- Python 3.10+
9+
- FastAPI
10+
- Pydantic v2
11+
- Pydantic Settings @backend\core\conf.py
12+
- SQLAlchemy 2.0（如果使用 ORM 功能）
13+
- SQLAlchemy 配置: @backend\database\db.py
14+
2. SQLAlchemy 规范
15+
- 模型类文档只需描述它是什么表
16+
- 模型存在关系时需要在文件开头添加 `from __future__ import annotations`
17+
- 关系属性 Mapped[] 中的类不要使用字符串
18+
3. Schema 规范
19+
- schema 类文档只需描述简短几个字
20+
- 为 schema 属性添加 Field
21+
4. 路由处理规范
22+
- 同步操作使用 `def`
23+
- 异步操作使用 `async def`
24+
- `api` 目录下的文件自动跳过任何处理
25+
- 使用异步函数处理 I/O 绑定任务
26+
- 理解并遵循 @backend\common\response\response_schema.py 的返回模式
27+
- 保持 API 响应格式的一致性
28+
5. 性能优化规范
29+
- 接口函数内的阻塞型事件使用 run_in_threadpool 处理
30+
- 尽量减少阻塞 I/O 操作
31+
- 在所有数据库调用和外部 API 请求中使用异步操作
32+
- 使用 Redis 工具 @backend\database\redis.py，对静态数据和频繁访问的数据实施缓存
33+
- 优先考虑 API 性能指标（响应时间、延迟、吞吐量）
34+
6. 错误处理规范
35+
- 使用 FastAPI 的异常处理机制
36+
- 统一错误响应格式
37+
- 根据错误工厂 @backend\common\exception\errors.py 提供清晰的错误信息和错误码
38+
- 记录关键错误信息到日志系统 @backend\common\log.py
39+
7. 数据验证规范
40+
- 使用 Pydantic 模型进行数据验证
41+
- 定义清晰的请求和响应模型，参考：@backend\app\admin\schema\user.py
42+
- 合理使用字段验证器
43+
- 提供有意义的验证错误信息

‎docs/code/jwt.py‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
async def jwt_authentication(token: str) -> GetUserInfoWithRelationDetail:
2+
"""
3+
JWT authentication
4+
5+
:param token:
6+
:return:
7+
"""
8+
token_payload = jwt_decode(token)
9+
user_id = token_payload.id
10+
redis_token = await redis_client.get(f'{settings.TOKEN_REDIS_PREFIX}:{user_id}:{token_payload.session_uuid}')
11+
if not redis_token or token != redis_token:
12+
raise TokenError(msg='Token 已过期')
13+
cache_user = await redis_client.get(f'{settings.JWT_USER_REDIS_PREFIX}:{user_id}')
14+
if not cache_user:
15+
async with async_db_session() as db:
16+
current_user = await get_current_user(db, user_id)
17+
user = GetUserInfoWithRelationDetail(**select_as_dict(current_user))
18+
await redis_client.setex(
19+
f'{settings.JWT_USER_REDIS_PREFIX}:{user_id}',
20+
settings.JWT_USER_REDIS_EXPIRE_SECONDS,
21+
user.model_dump_json(),
22+
)
23+
else:
24+
# TODO: 在恰当的时机，应替换为使用 model_validate_json
25+
# https://docs.pydantic.dev/latest/concepts/json/#partial-json-parsing
26+
user = GetUserInfoWithRelationDetail.model_validate(from_json(cache_user, allow_partial=True))
27+
return user

‎docs/code/launch.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "fba 调试程序",
6+
"type": "debugpy",
7+
"request": "launch",
8+
"module": "uvicorn",
9+
"console": "integratedTerminal",
10+
// 指定 python 解释器，请根据实际情况自行修改
11+
//"python": "${workspaceFolder}/.venv/bin/python", // MacOS or Linux
12+
//"python": "${workspaceFolder}/.venv/Scripts/python.exe", // Windows
13+
"env": {
14+
"PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}"
15+
},
16+
"envFile": "${workspaceFolder}/backend/.env",
17+
"args": [
18+
"backend.main:app",
19+
"--host",
20+
"0.0.0.0",
21+
"--port",
22+
"8000",
23+
"--reload"
24+
],
25+
"justMyCode": true
26+
}
27+
]
28+
}

‎docs/code/nginx.conf‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# For more information on configuration, see:
2+
# * Official English Documentation: http://nginx.org/en/docs/
3+
# * Official Russian Documentation: http://nginx.org/ru/docs/
4+
5+
worker_processes auto;
6+
error_log /var/log/nginx/error.log;
7+
pid /run/nginx.pid;
8+
9+
# Load dynamic modules. See /usr/share/doc/nginx/README.dynamic.
10+
include /usr/share/nginx/modules/*.conf;
11+
12+
events {
13+
worker_connections 1024;
14+
}
15+
16+
http {
17+
18+
include /etc/nginx/mime.types;
19+
default_type application/octet-stream;
20+
21+
sendfile on;
22+
client_max_body_size 5M;
23+
client_body_buffer_size 5M;
24+
25+
gzip on;
26+
gzip_comp_level 2;
27+
gzip_types text/plain text/css text/javascript application/javascript application/x-javascript application/xml application/x-httpd-php image/jpeg image/gif image/png;
28+
gzip_vary on;
29+
30+
keepalive_timeout 300;
31+
32+
# 添加 https conf
33+
# server {
34+
# listen 80;
35+
# listen [::]:80;
36+
# # xxx.com 应该与 .env.production 中的配置保持一致
37+
# server_name xxx.com;
38+
# rewrite ^(.*)$ https://$host$1 permanent;
39+
#}
40+
41+
server {
42+
# 删除下面两行
43+
44+
45+
46+
# 更新为与上面 server_name 相同
47+
server_name 127.0.0.1;
48+
49+
# 添加 https conf
50+
# listen 443 ssl;
51+
# ssl_certificate /etc/ssl/xxx.pem; # 证书
52+
# ssl_certificate_key /etc/ssl/xxx.key; # 密钥
53+
# ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
54+
# ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
55+
# ssl_prefer_server_ciphers on;
56+
57+
client_max_body_size 5m;
58+
59+
root /var/www/fba_ui;
60+
61+
location / {
62+
try_files $uri $uri/ /index.html;
63+
}
64+
65+
location /api/v1/ {
66+
proxy_pass http://fba_server:8001;
67+
68+
proxy_set_header Host $http_host;
69+
proxy_set_header X-Real-IP $remote_addr;
70+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
71+
proxy_set_header X-Forwarded-Proto $scheme;
72+
proxy_connect_timeout 300s;
73+
proxy_send_timeout 300s;
74+
proxy_read_timeout 300s;
75+
}
76+
77+
location /static/ {
78+
alias /var/www/fba_server/backend/static;
79+
}
80+
}
81+
}

0 commit comments

Comments
 (0)