Skip to content

Commit ac49bd9

Browse files
wu-clanwu-clan
committed
update docs
1 parent bde7c13 commit ac49bd9

File tree

6 files changed

+65
-56
lines changed

6 files changed

+65
-56
lines changed

‎docs/.vuepress/config.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ export default defineUserConfig({
7474
},
7575
watermark: true,
7676
markdownPower: {
77+
abbr: true,
78+
annotation: true,
7779
icons: true,
7880
},
7981
markdownEnhance: {

‎docs/changelog.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,7 @@ title: 更新日志
55
::: info 版本号
66
历经漫长的打磨与优化，fba 正式迎来了首个里程碑版本 [v1.0.0](#v100---2025-02-24)。选择以 1.0.0 作为起点，不仅象征着
77
fba [核心架构](./guide/summary/intro.md#伪三层架构)
8-
的成熟与稳定，更意味着它已完全通过验证，可以安心投入生产环境使用。在未来的版本迭代中，我们将严格遵循 [语义化版本规范](https://semver.org/lang/zh-CN/)
9-
，持续为开发者带来更优质的产品体验。敬请期待！🤗
8+
的成熟与稳定，更意味着它已完全通过验证，可以安心投入生产环境使用。在未来的版本迭代中，我们将持续为开发者带来更优质的产品体验。敬请期待！🤗
109
:::
1110

1211
<a id="v1.0.0"></a>

‎docs/guide/deploy/Docker.md

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -61,16 +61,10 @@ title: Docker 部署
6161

6262
2. env
6363

64-
进入 `deploy/backend/docker-compose` 目录，创建环境变量文件 `.env`
65-
66-
```shell
67-
touch .env.server ../../../backend/.env
68-
```
69-
70-
将初始化环境变量配置拷贝到环境变量文件中
64+
进入 `deploy/backend/docker-compose` 目录，拷贝环境变量文件 `.env.server`
7165

7266
::: warning
73-
如果你需要使用 PostgreSQL 数据库，需修改 `.env.server` 部分配置如下：
67+
如果你需要使用 PostgreSQL 数据库，执行命令前，需修改 `.env.server` 部分配置如下：
7468
```env
7569
DATABASE_TYPE='postgresql'
7670
DATABASE_HOST='fba_postgres'
@@ -84,9 +78,7 @@ title: Docker 部署
8478
cp .env.server ../../../backend/.env
8579
```
8680

87-
3. 按需修改配置文件 `backend/core/conf.py` 和 `.env`
88-
89-
建议修改 `.env` 中的 `ENVIRONMENT` 为 `pro`
81+
3. 按需修改配置文件 `backend/core/conf.py` 和 `backend/.env`
9082

9183
4. 更新脚本文件
9284

@@ -316,7 +308,7 @@ title: Docker 部署
316308

317309
进入 deploy 目录，修改 `nginx.conf` 文件
318310

319-
```nginx
311+
```nginx :collapsed-lines
320312
# For more information on configuration, see:
321313
# * Official English Documentation: http://nginx.org/en/docs/
322314
# * Official Russian Documentation: http://nginx.org/ru/docs/
@@ -347,6 +339,8 @@ title: Docker 部署
347339
gzip_vary on;
348340
349341
keepalive_timeout 300;
342+
343+
# 添加 https conf
350344
# [!code ++:7]
351345
# server {
352346
# listen 80;
@@ -357,12 +351,15 @@ title: Docker 部署
357351
#}
358352
359353
server {
360-
# 删除这两行 [!code --:2]
354+
# 删除下面两行
355+
# [!code --:2]
361356
listen 80 default_server;
362357
listen [::]:80 default_server;
363358
364359
# 更新为与上面 server_name 相同 [!code warning]
365360
server_name 127.0.0.1;
361+
362+
# 添加 https conf
366363
# [!code ++:6]
367364
# listen 443 ssl;
368365
# ssl_certificate /etc/ssl/xxx.pem; # 证书
@@ -380,7 +377,6 @@ title: Docker 部署
380377
}
381378
382379
location /api/v1/ {
383-
# 更新 fba_server 为 0.0.0.0 [!code warning]
384380
proxy_pass http://fba_server:8001;
385381
386382
proxy_set_header Host $http_host;

‎docs/guide/summary/intro.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,8 @@ mvc 架构作为常规设计模式，在 python web 中很常见，但是三层
6363

6464
- backend 后端
6565
- alembic/ 数据库迁移
66-
- app/ 应用
67-
- admin 系统后台
66+
- app 应用
67+
- admin/ 系统后台
6868
- api/ 接口
6969
- crud/ CRUD
7070
- model 模型

‎docs/guide/summary/quick-start.md

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -52,11 +52,17 @@ title: 快速开始
5252

5353
3. 安装依赖包
5454

55-
拉取项目到本地后，进入项目 `backend` 目录，执行以下命令
55+
- 架构依赖
5656

57-
```shell
58-
pip install -r requirements.txt
59-
```
57+
拉取项目到本地后，进入项目 `backend` 目录，执行以下命令安装架构依赖
58+
59+
```shell
60+
pip install -r requirements.txt
61+
```
62+
63+
- 插件依赖
64+
65+
执行 `backend/scripts/init_plugin.py` 文件安装插件依赖
6066

6167
4. 创建数据库：`fba`，选择 utf8mb4 编码，postgres 用户可忽略编码
6268
5. 启动 Redis
@@ -120,11 +126,15 @@ title: 快速开始
120126

121127
11. 启动 fastapi 服务
122128

123-
::: warning
129+
::: info
124130
此项目默认使用 CLI 启动服务，为了方便本地调试，你仍然可以选择在 IDE 中右键运行 `run.py` 文件
131+
:::
132+
133+
::: warning
134+
如果你在项目中安装了 [应用级插件](../../plugin/dev.md#插件分类)，请务必使用 `run.py`
135+
文件启动项目，否则，您将收到启动错误
125136

126-
如果你在项目中安装了 [独立 app 插件](../../plugin/market.md)，请务必使用 `run.py`
127-
启动项目，否则，您将收到启动错误，详情：[fastapi/fastapi#13372 (comment)](https://github.com/fastapi/fastapi/discussions/13372#discussioncomment-12211232)
137+
详情：[fastapi/fastapi#13372 (comment)](https://github.com/fastapi/fastapi/discussions/13372#discussioncomment-12211232)
128138
:::
129139

130140
帮助

‎docs/plugin/dev.md

Lines changed: 33 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -26,72 +26,74 @@ title: 插件开发
2626

2727
::::
2828

29-
### APP 说明
29+
### 插件分类
3030

31-
- 独立 app
31+
与插件相关的部分文档中，可能高频次出现以下两个词
3232

33-
在 `backend/app` 目录下的应用（admin、task...），视为独立 app
33+
- ==应用级插件=={.note}
3434

35-
- 非独立 app
35+
在 [项目结构](../guide/summary/intro.md#项目结构) 中，app
36+
目录下的一级文件夹被视为应用，此原理同样应用于插件系统。也就是说，如果插件被开发为应用，那么它们将会像应用一样被注入到系统中，我们称这类插件为【应用级插件】
3637

37-
现有 app 的扩展功能
38+
- ==扩展级插件=={.note}
39+
40+
与【应用级插件】相反，如果插件不被开发为应用，那么它们将被开发为 app 目录下已存在应用的扩展功能，并做为扩展 API
41+
被注入应用中，我们称这类插件为【扩展级插件】
3842

3943
### 插件目录结构
4044

4145
::: file-tree
4246

43-
- backend fba 目录
44-
- plugin fba 目录
47+
- backend 固定目录
48+
- plugin 固定目录
4549
- xxx 插件名
46-
- api/ 接口，务必查看下方【插件接口】
47-
- crud/ CRUD
48-
- model 模型
50+
- api/ 接口，务必查看下方 [接口路由](#插件路由)
51+
- crud/ CRUD（非必须项）
52+
- model 模型（非必须项）
4953
- \_\_init__.py 必须在此文件内导入所有模型类
5054
- …
51-
- schema/ 数据传输
52-
- service/ 服务
53-
- utils/ 工具包，如果插件无需独立工具，则无需此目录
55+
- schema/ 数据传输（非必须项）
56+
- service/ 服务（非必须项）
57+
- utils/ 工具包（非必须项）
5458
- \_\_init__.py 作为 python 包保留（必须项）
55-
- conf.py 常量配置，如果插件不需要独立常量配置，则无需此文件
56-
- plugin.toml 插件配置文件（必填项）
57-
- README.md 插件使用说明
58-
- requirements.txt 依赖包文件（非必须项）如果插件不需要安装额外依赖，则无需此文件
59+
- conf.py 常量配置（非必须项）
60+
- plugin.toml 插件配置文件（必须项）
61+
- README.md 插件使用说明（必须项）
62+
- requirements.txt 依赖包文件（非必须项）如果插件需要安装依赖，则必须
5963

6064
:::
6165

62-
### 插件接口
66+
### 插件路由
67+
68+
如果插件符合插件开发的要求，则插件中的所有路由都将自动注入到 FastAPI 应用中，无需任何其他操作，但值得注意的是，启动时间可能会随着插件数量的递增而增加，因为
69+
fba 会在启动前对所有插件进行解析
6370

64-
- 独立 app
71+
- 应用级插件
6572

6673
插件路由应完全遵循 [路由结构](../guide/reference/router.md#路由结构) 进行定义
6774

68-
- 非独立 app
75+
- 扩展级插件
6976

70-
插件路由必须根据现有 app 中的目录结构进行 1:1 复制，可参考 fba
77+
插件路由必须根据现有应用中的目录结构进行 1:1 复制，可参考 fba
7178
中的内置插件 [notice](https://github.com/fastapi-practices/fastapi_best_architecture/tree/master/backend/plugin/notice/api)
7279

73-
### 插件路由
74-
75-
如果插件符合插件开发的要求，则插件中的所有路由都将自动注入到 FastAPI 应用中，无需任何其他操作，但值得注意的是，启动时间可能会随着插件数量的递增而增加，因为
76-
fba 会在启动前对所有插件进行解析
77-
7880
### 插件配置
7981

8082
`plugin.toml` 是插件的配置文件，它必须存在，此配置文件需根据插件的属性进行定义
8183

82-
- 独立 app
84+
- 应用级插件
8385

8486
```toml
85-
# app 配置
87+
# 应用配置
8688
[app]
87-
# 插件路由器版本，默认为 v1（可参考源码 `backend/app/admin/api/router.py`）
89+
# 插件路由器版本，默认为 v1，可参考源码：backend/app/admin/api/router.py
8890
router = ['v1']
8991
```
9092

91-
- 非独立 app
93+
- 扩展级插件
9294

9395
```toml
94-
# app 配置
96+
# 应用配置
9597
[app]
9698
# 此插件属于哪个 app
9799
include = ''

0 commit comments

Comments
 (0)