mirror of
https://github.com/Websoft9/websoft9.git
synced 2025-01-23 09:12:59 +08:00
docs
This commit is contained in:
qiaofeng1227
parent
2d099d4e56
commit
d4400edb82
@ -1,22 +1,22 @@
|
||||
# API设计文档
|
||||
# API 设计文档
|
||||
|
||||
## API结构
|
||||
## API 结构
|
||||
|
||||
### 请求
|
||||
|
||||
#### 请求方式
|
||||
|
||||
支持如下两种调用方式：
|
||||
支持如下两种调用方式：
|
||||
|
||||
* get
|
||||
* post
|
||||
- get
|
||||
- post
|
||||
|
||||
#### 请求头（公共参数）
|
||||
|
||||
| 参数名称 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| Version | 接口版本 | string |可选 |
|
||||
| Language | 接口显示语言 | string |可选 |
|
||||
| 参数名称 | 用途 | 类型 | 必要性 |
|
||||
| -------- | ------------ | ------ | ------ |
|
||||
| Version | 接口版本 | string | 可选 |
|
||||
| Language | 接口显示语言 | string | 可选 |
|
||||
|
||||
#### 安全验证
|
||||
|
||||
@ -26,21 +26,20 @@
|
||||
|
||||
[业务接口详情](#业务接口详情)
|
||||
|
||||
|
||||
### 响应结果
|
||||
|
||||
#### 响应头（公共参数）
|
||||
|
||||
|返回参数 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| HTTP状态码 | 判断接口调用是否成功（200或404） | Integer |必须 |
|
||||
| 返回参数 | 用途 | 类型 | 必要性 |
|
||||
| ----------- | ---------------------------------- | ------- | ------ |
|
||||
| HTTP 状态码 | 判断接口调用是否成功（200 或 404） | Integer | 必须 |
|
||||
|
||||
#### 响应主体
|
||||
|
||||
|返回参数 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| ResponseData | 各个接口的业务数据 | object(依据接口而异) |必须 |
|
||||
| Error | 错误code和错误信息 | ErrorInfo | 非必须 ,无错误时不返回 |
|
||||
| 返回参数 | 用途 | 类型 | 必要性 |
|
||||
| ------------ | -------------------- | -------------------- | ---------------------- |
|
||||
| ResponseData | 各个接口的业务数据 | object(依据接口而异) | 必须 |
|
||||
| Error | 错误 code 和错误信息 | ErrorInfo | 非必须 ,无错误时不返回 |
|
||||
|
||||
```
|
||||
{
|
||||
@ -51,7 +50,7 @@
|
||||
Message: "Insufficient system resources (cpu, memory, disk space).",
|
||||
Detail: "Error detail information"
|
||||
}
|
||||
},
|
||||
},
|
||||
"Error": {
|
||||
Code: "Requirement.NotEnough",
|
||||
Message: "Insufficient system resources (cpu, memory, disk space).",
|
||||
@ -62,29 +61,28 @@
|
||||
|
||||
#### 错误代码设计
|
||||
|
||||
错误代码参考 [AWS API](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/errors-overview.html) 的分类方式：
|
||||
错误代码参考 [AWS API](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/errors-overview.html) 的分类方式：
|
||||
|
||||
* Client errors: These errors are usually caused by something the client did, such as specifying an incorrect or invalid parameter in the request, or using an action or resource on behalf of a user that doesn't have permission to use the action or resource. These errors are accompanied by a 400-series HTTP response code.
|
||||
- Client errors: These errors are usually caused by something the client did, such as specifying an incorrect or invalid parameter in the request, or using an action or resource on behalf of a user that doesn't have permission to use the action or resource. These errors are accompanied by a 400-series HTTP response code.
|
||||
|
||||
* Server errors: These errors are usually caused by an AWS server-side issue. These errors are accompanied by a 500-series HTTP response code.
|
||||
- Server errors: These errors are usually caused by an AWS server-side issue. These errors are accompanied by a 500-series HTTP response code.
|
||||
|
||||
##### Client errors
|
||||
##### Client errors
|
||||
|
||||
| code |message | detail |
|
||||
| --------------------------------------------- | ------ | ------ |
|
||||
| Client.Parameter.Blank.Error | p 必填参数为空 |null |
|
||||
| Client.Parameter.Format.Error | p 参数语法不符 |null |
|
||||
| Client.Parameter.Value.NotExist.Error | p 参数值错误 |null |
|
||||
| Client.Parameter.Value.Repeat.Error | p 参数值重复 |null |
|
||||
| code | message | detail |
|
||||
| ------------------------------------- | -------------- | ------ |
|
||||
| Client.Parameter.Blank.Error | p 必填参数为空 | null |
|
||||
| Client.Parameter.Format.Error | p 参数语法不符 | null |
|
||||
| Client.Parameter.Value.NotExist.Error | p 参数值错误 | null |
|
||||
| Client.Parameter.Value.Repeat.Error | p 参数值重复 | null |
|
||||
|
||||
##### Server errors
|
||||
|
||||
| code |message | detail |
|
||||
| --------------------------------------------- | ------ | ------ |
|
||||
| Server.Container.Error | Docker 返回原始错误 |错误详细信息 |
|
||||
| Server.SystemError | 系统原始错误 | 错误详细信息 |
|
||||
| Server.*** | 其他可以友好提示的错误 | 错误详细信息 |
|
||||
##### Server errors
|
||||
|
||||
| code | message | detail |
|
||||
| ---------------------- | ---------------------- | ------------ |
|
||||
| Server.Container.Error | Docker 返回原始错误 | 错误详细信息 |
|
||||
| Server.SystemError | 系统原始错误 | 错误详细信息 |
|
||||
| Server.\*\*\* | 其他可以友好提示的错误 | 错误详细信息 |
|
||||
|
||||
## 业务接口详情
|
||||
|
||||
@ -98,19 +96,18 @@ AppInstall
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名称 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| app_name | 应用名称 | string |必须 |
|
||||
| customer_app_name | 用户自定义应用名称 | string |必须 |
|
||||
| app_version | 应用版本 | string |必须 |
|
||||
| 参数名称 | 用途 | 类型 | 必要性 |
|
||||
| ----------------- | ------------------ | ------ | ------ |
|
||||
| app_name | 应用名称 | string | 必须 |
|
||||
| customer_app_name | 用户自定义应用名称 | string | 必须 |
|
||||
| app_version | 应用版本 | string | 必须 |
|
||||
|
||||
#### 返回结果
|
||||
|
||||
| 返回值 |类型 |必要性 |
|
||||
| ------ | ------ |------ |
|
||||
| ResponseData | String(AppID) |必须 |
|
||||
| Error | ErrorInfo |非必须 |
|
||||
|
||||
| 返回值 | 类型 | 必要性 |
|
||||
| ------------ | ------------- | ------ |
|
||||
| ResponseData | String(AppID) | 必须 |
|
||||
| Error | ErrorInfo | 非必须 |
|
||||
|
||||
### App 卸载
|
||||
|
||||
@ -120,17 +117,16 @@ AppUninstall
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名称 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| app_id | 卸载该app | string |必须 |
|
||||
| 参数名称 | 用途 | 类型 | 必要性 |
|
||||
| -------- | ---------- | ------ | ------ |
|
||||
| app_id | 卸载该 app | string | 必须 |
|
||||
|
||||
#### 返回结果
|
||||
|
||||
| 返回值 |类型 |必要性 |
|
||||
| ------ | ------ |------ |
|
||||
| ResponseData | String(AppID) |必须 |
|
||||
| error | ErrorInfo |非必须 |
|
||||
|
||||
| 返回值 | 类型 | 必要性 |
|
||||
| ------------ | ------------- | ------ |
|
||||
| ResponseData | String(AppID) | 必须 |
|
||||
| error | ErrorInfo | 非必须 |
|
||||
|
||||
### App 重启
|
||||
|
||||
@ -140,17 +136,16 @@ AppRestart
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名称 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| app_id | 重启该app | string |必须 |
|
||||
| 参数名称 | 用途 | 类型 | 必要性 |
|
||||
| -------- | ---------- | ------ | ------ |
|
||||
| app_id | 重启该 app | string | 必须 |
|
||||
|
||||
#### 返回结果
|
||||
|
||||
| 返回值 |类型 |必要性 |
|
||||
| ------ | ------ |------ |
|
||||
| ResponseData | String(AppID) |必须 |
|
||||
| error | ErrorInfo |非必须 |
|
||||
|
||||
| 返回值 | 类型 | 必要性 |
|
||||
| ------------ | ------------- | ------ |
|
||||
| ResponseData | String(AppID) | 必须 |
|
||||
| error | ErrorInfo | 非必须 |
|
||||
|
||||
### App 启动
|
||||
|
||||
@ -160,16 +155,16 @@ AppStart
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名称 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| app_id | 启动该app | string |必须 |
|
||||
| 参数名称 | 用途 | 类型 | 必要性 |
|
||||
| -------- | ---------- | ------ | ------ |
|
||||
| app_id | 启动该 app | string | 必须 |
|
||||
|
||||
#### 返回结果
|
||||
|
||||
| 返回值 |类型 |必要性 |
|
||||
| ------ | ------ |------ |
|
||||
| ResponseData | String(AppID) |必须 |
|
||||
| error | ErrorInfo |非必须 |
|
||||
| 返回值 | 类型 | 必要性 |
|
||||
| ------------ | ------------- | ------ |
|
||||
| ResponseData | String(AppID) | 必须 |
|
||||
| error | ErrorInfo | 非必须 |
|
||||
|
||||
### App 停止
|
||||
|
||||
@ -179,16 +174,16 @@ AppStop
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名称 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| app_id | 停止该app | string |必须 |
|
||||
| 参数名称 | 用途 | 类型 | 必要性 |
|
||||
| -------- | ---------- | ------ | ------ |
|
||||
| app_id | 停止该 app | string | 必须 |
|
||||
|
||||
#### 返回结果
|
||||
|
||||
| 返回值 |类型 |必要性 |
|
||||
| ------ | ------ |------ |
|
||||
| ResponseData | String(AppID) |必须 |
|
||||
| error | ErrorInfo |非必须 |
|
||||
| 返回值 | 类型 | 必要性 |
|
||||
| ------------ | ------------- | ------ |
|
||||
| ResponseData | String(AppID) | 必须 |
|
||||
| error | ErrorInfo | 非必须 |
|
||||
|
||||
### App 状态查询
|
||||
|
||||
@ -198,25 +193,26 @@ AppStatus
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名称 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| app_id | 查询该app的信息 | string |必须 |
|
||||
| 参数名称 | 用途 | 类型 | 必要性 |
|
||||
| -------- | ----------------- | ------ | ------ |
|
||||
| app_id | 查询该 app 的信息 | string | 必须 |
|
||||
|
||||
#### 返回结果
|
||||
|
||||
| 返回值 |类型 |必要性 |
|
||||
| ------ | ------ |------ |
|
||||
| ResponseData | AppStatusInfo |必须 |
|
||||
| error | ErrorInfo |非必须 |
|
||||
| 返回值 | 类型 | 必要性 |
|
||||
| ------------ | ------------- | ------ |
|
||||
| ResponseData | AppStatusInfo | 必须 |
|
||||
| error | ErrorInfo | 非必须 |
|
||||
|
||||
AppStatusInfo 说明:
|
||||
|
||||
```
|
||||
{
|
||||
|
||||
app_id：应用ID,
|
||||
|
||||
status：应用运行状态,[installing(创建中)，running(运行中)，exited(停止)，restarting(反复重启)，failed(失败)]
|
||||
|
||||
|
||||
status_reason：{ // 只有failed时才有内容
|
||||
Code：错误代码
|
||||
Message：错误提示信息
|
||||
@ -234,18 +230,19 @@ AppList
|
||||
|
||||
#### 请求参数
|
||||
|
||||
| 参数名称 | 用途 |类型 |必要性 |
|
||||
| ------ | --------------------------------------------- | ------ |------ |
|
||||
| app_id | 查询指定的 app | string | 非必须 |
|
||||
| 参数名称 | 用途 | 类型 | 必要性 |
|
||||
| -------- | -------------- | ------ | ------ |
|
||||
| app_id | 查询指定的 app | string | 非必须 |
|
||||
|
||||
#### 返回结果
|
||||
|
||||
| 返回值 |类型 |必要性 |
|
||||
| ------ | ------ |------ |
|
||||
| ResponseData | Array of AppDetailInfo |必须 |
|
||||
| error | ErrorInfo |非必须 |
|
||||
| 返回值 | 类型 | 必要性 |
|
||||
| ------------ | ---------------------- | ------ |
|
||||
| ResponseData | Array of AppDetailInfo | 必须 |
|
||||
| error | ErrorInfo | 非必须 |
|
||||
|
||||
AppDetailInfo 说明:
|
||||
|
||||
```
|
||||
{
|
||||
|
||||
@ -258,33 +255,33 @@ AppDetailInfo 说明:
|
||||
trade_mark：应用商标,
|
||||
|
||||
status：应用运行状态,[installing(创建中)，running(运行中)，exited(停止)，restarting(反复重启)，failed(失败)]
|
||||
|
||||
|
||||
status_reason：{ // 只有failed时才有内容
|
||||
Code：错误代码
|
||||
Message：错误提示信息
|
||||
Detail：错误真实信息
|
||||
},
|
||||
|
||||
|
||||
official_app：是否为官方应用,
|
||||
|
||||
|
||||
image_url：图片路径,
|
||||
|
||||
|
||||
running_info: { // 只有status=running才有值，其他时候为空
|
||||
|
||||
|
||||
port：应用端口,
|
||||
|
||||
compose_file：docker compose文件路径,
|
||||
|
||||
url：应用网址,
|
||||
|
||||
|
||||
admin_url：管理员网址,
|
||||
|
||||
user_name：用户名,
|
||||
|
||||
password：密码,
|
||||
|
||||
|
||||
default_domain: 默认域名,
|
||||
|
||||
|
||||
set_domain: 用户自定义域名,
|
||||
}
|
||||
|
||||
|
||||
@ -22,6 +22,11 @@ StackHub 的 release 的版本号由项目主版本号和各微服务和插件
|
||||
2. CHANGELOG 文件，来记录每次变更的具体内容
|
||||
Release 目前手动进行，将合并 appmanage 和 cockpit 插件的 CHANGELOG
|
||||
|
||||
## 日志
|
||||
|
||||
Appmanage 日志采用 logging 生成，按自然日分割日志文件。日志路径：/var/lib/docker/volumes/w9appmanage_logs/\_data
|
||||
其他微服务采用 Dockhub 公开镜像，用 docker 容器的日志访问命令即可查看。
|
||||
|
||||
## 更新与升级
|
||||
|
||||
执行升级脚本(/install/update.sh)来实现自动升级。
|
||||
|
||||
@ -1 +1,76 @@
|
||||
# Developer Guide
|
||||
|
||||
## Appmanage
|
||||
|
||||
### 开发环境以及组件
|
||||
|
||||
Python3.10, FastAPI, RQ, logging
|
||||
|
||||
### 关键技术实现
|
||||
|
||||
#### 日志分割
|
||||
|
||||
```
|
||||
logPath = 'logs/'
|
||||
if not os.path.exists(logPath):
|
||||
os.makedirs(logPath)
|
||||
logName = 'app_manage.log'
|
||||
logFile = logPath + logName
|
||||
formatter = logging.Formatter('%(asctime)s %(levelname)s: %(message)s')
|
||||
# handler
|
||||
time_rotating_file_handler = handlers.TimedRotatingFileHandler(filename=logFile, when="MIDNIGHT", interval=1, encoding='utf-8')
|
||||
time_rotating_file_handler.setLevel(logging.DEBUG)
|
||||
time_rotating_file_handler.setFormatter(formatter)
|
||||
```
|
||||
|
||||
#### RQ
|
||||
|
||||
任务管理器启动：
|
||||
|
||||
```
|
||||
rq worker --url redis://websoft9-redis:6379/0
|
||||
```
|
||||
|
||||
RQ 队列创建：
|
||||
|
||||
```
|
||||
# 指定 Redis 容器的主机名和端口
|
||||
redis_conn = Redis(host='websoft9-redis', port=6379)
|
||||
|
||||
# 使用指定的 Redis 连接创建 RQ 队列
|
||||
q = Queue(connection=redis_conn,default_timeout=3600)
|
||||
```
|
||||
|
||||
RQ 队列新增排队任务：
|
||||
|
||||
```
|
||||
q.enqueue(install_app_delay, app_name, customer_name, app_version, job_id=app_id)
|
||||
```
|
||||
|
||||
获取队列中任务的信息：
|
||||
|
||||
```
|
||||
# 获取 StartedJobRegistry 实例
|
||||
started = StartedJobRegistry(queue=q)
|
||||
finish = FinishedJobRegistry(queue=q)
|
||||
deferred = DeferredJobRegistry(queue=q)
|
||||
failed = FailedJobRegistry(queue=q)
|
||||
scheduled = ScheduledJobRegistry(queue=q)
|
||||
cancel = CanceledJobRegistry(queue=q)
|
||||
|
||||
# 获取正在执行的作业 ID 列表
|
||||
run_job_ids = started.get_job_ids()
|
||||
finish_job_ids = finish.get_job_ids()
|
||||
wait_job_ids = deferred.get_job_ids()
|
||||
failed_jobs = failed.get_job_ids()
|
||||
scheduled_jobs = scheduled.get_job_ids()
|
||||
cancel_jobs = cancel.get_job_ids()
|
||||
```
|
||||
|
||||
### API 文档
|
||||
|
||||
[FastAPI 文档](https://github.com/Websoft9/StackHub/blob/main/appmanage/docs/developer.md) 使用 swagger 自动生成，访问地址：http://IP:PORT/docs。
|
||||
|
||||
### Cockpit 插件
|
||||
|
||||
待补充。。。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user