API Document

API.md

@@ -0,0 +1,186 @@
+# API 文档
+
+## 总体设计
+
+### 基本HTTP请求
+
+本系统后端API设计遵循RESTful规范，对于一般数据类型的增删改查使用同一URL下的POST、DELETE、PUT和GET方法进行访问。
+对于POST和PUT方法，待传输数据放在请求体中，以Json格式进行传输。DELETE和GET方法使用URL参数传递必要数据。POST为上传新数据，使用POST时数据中ID字段将被忽略。
+
+后端返回数据也全部为Json格式，使用HTTP状态码标识请求状态。当状态码为200时可以认为该请求成功达到了预期的结果。若请求失败，则状态码不为200，并且返回数据中包含`msg`
+字段对发生的错误进行了简要说明。
+
+一次失败的请求返回数据如下所示，其状态码为401（StatusUnauthorized）。
+
+```json
+{
+  "ok": false,
+  "msg": "username error"
+}
+```
+
+一般数据类型包含`ID`字段，类型为整数。DELETE方法可用此字段表示将要删除的对象。删除一个镜像的请求如下命令所示。
+
+```bash
+curl -X DELETE https://ms.educg.net/admin/image?ID=1
+```
+
+### 资源查询请求
+
+对单个资源查询的方式与删除类似，可使用该数据结构中的某些字段对数据进行查询，返回结果为Json格式。
+
+同时对该类型的多个资源进行查询时，URL一般为该资源类型的复数形式，如镜像的查询URL为`image`
+，那么同时获得多个镜像的查询的URL为`images`。特殊情况另行说明。
+对多个数据进行查询时，URL中除了必要的过滤条件外，还可包含分页参数`page`和`pageSize`，均为整数类型。返回结果中`data`
+字段为查询结果数据，`page`、`pageCount`和`pageSize`用于控制分页。
+
+```json
+{
+  "page": 1,
+  "pageCount": 100,
+  "pageSize": 2,
+  "data": [
+    {
+      "ID": 2,
+      "Other fields": "Other Values"
+    },
+    {
+      "ID": 3
+    }
+  ]
+}
+
+```
+
+### 数据结构
+数据结构使用Golang语言格式进行定义，其中`gorm.Model`为公用字段，定义如下：
+```go
+type Model struct {
+    ID        uint `gorm:"primarykey"`
+    CreatedAt time.Time
+    UpdatedAt time.Time
+    DeletedAt DeletedAt `gorm:"index"`
+}
+```
+
+数据结构中包含的Comment字段为该数据的简单描述，Doc字段为该数据的详细文档，文档应支持Markdown格式保存和渲染。
+
+## 镜像管理
+
+数据结构：
+
+```go
+type ImageModel struct {
+    gorm.Model
+    Name        string
+    Image       string
+    Comment     string
+    Command     string
+    Env         string
+    Port        string
+    UserName    string
+    IsPublished bool
+    Doc         string
+}
+```
+CURD:
++ POST：/image
++ PUT: /image
++ DELETE: /image?ID=1
++ GET /images?UserName=cg_wmj # 查询某用户的镜像
++ GET /images?IsPublish=1 # 查询所有公开镜像
+
+## 数据集管理 （尚未实现）
+
+训练数据，数据结构：
+```go
+type DataModel struct {
+    gorm.Model
+    Type        string
+    Name        string
+    Comment     string
+    Doc         string
+    UserName    string
+    Password    string
+    AccessInfo  string
+    IsPublished bool
+}
+```
+其中`Type`字段为数据集的类型，表示该数据集的访问方式，目前仅支持`Type=="dir"`访问目录格式数据，后续可能支持mysql等数据库。
+本系统中，对本地文件的访问使用Webdav协议。
+`AccessInfo`字段为该数据集的访问方式，在`Type=="dir"`时为该目录的路径。
+例如某数据集对象中，`AccessInfo=='/some/data/dir/'`，同时本系统后端地址为`https://ms.educg.net/admin/ `，那么通过WebDav协议访问`https://ms.educg.net/files/some/data/dir/ `即可访问该目录。
+
+
+CURD:
++ POST：/data
++ PUT: /data
++ DELETE: /data?ID=1
++ GET /data?UserName=cg_wmj
++ GET /data?IsPublish=1
+
+## 项目管理 （尚未实现）
+
+数据结构
+```go
+type ProjectModel struct {
+	gorm.Model
+	ProjectName string
+	UserName    string
+	GroupName   string
+	Type        string
+	Comment     string
+	Doc         string
+	IsPublic    bool
+
+	ImageID   int
+	Image     ImageModel
+	TrainData []*DataModel `gorm:"many2many:projects_data"`
+
+
+	UserPath string    // 用户目录挂载位置
+    CodePath string    // 代码目录挂载位置
+    ModelPath string   // 模型目录挂载位置
+
+	Running  bool   `gorm:"-:all"`
+}
+```
+
+其中`Type`字段为项目的类型，可选值为`jupyter`、`jupyterlab`、`jupyternotebook`、`novnc`、`vscode`、`http`。
+
+在创建或更新项目时，`TrainData`字段应该为DataModel结构的列表，其中每一个DataModel仅有`ID`即可。
+
+CURD:
++ POST：/project
++ PUT: /project
++ DELETE: /project?ID=1
++ GET /projects?UserName=cg_wmj
++ GET /projects?IsPublish=1
+
+## 运行项目 （尚未实现）
+
+数据结构
+```go
+type RunningProject struct {
+    Project   *ProjectModel
+    StartTime *time.Time
+    UserName  string
+    Nodes     int
+    Cpus      int
+    Memory    int
+    Gpus      int
+    GpuMemory int
+    URL       string
+    ControlURL string
+}
+```
+
+运行一个项目，前端发送POST请求时URL可留空，若该项目成功启动，则POST的返回内容中将包含正确的URL。
+通过此URL即可访问项目服务。ControlURL为容器服务客户端连接地址，可通过本地客户端提供更多功能。
+
+此数据结构中没有ID字段，删除时使用其对应的ProjectModel的ID。
+
+CURD:
++ POST：/running_project
++ DELETE: /running_project?ProjectID=1
++ GET /running_projects?UserName=cg_wmj

src/controller/image_controller.go

@@ -6,6 +6,7 @@ import (
 	"k8s-manager/src/model"
 	utils "k8s-manager/src/utils"
 	"net/http"
+	"strconv"
 )
 
 func AddImage(c *gin.Context) {
@@ -20,18 +21,23 @@ func AddImage(c *gin.Context) {
 }
 
 func DeleteImage(c *gin.Context) {
-	image := &model.ImageModel{}
-	if utils.GinErrorCheck(c, c.BindJSON(image)) {
+	id := c.Query("ID")
+	if id == "" {
+		utils.GinError(c, http.StatusBadRequest, "no id")
 		return
 	}
 	username := c.MustGet("username").(string)
-	oldImage := &model.ImageModel{Model: gorm.Model{ID: image.ID}}
+	idi, err := strconv.Atoi(id)
+	if utils.GinErrorCheck(c, err) {
+		return
+	}
+	oldImage := &model.ImageModel{Model: gorm.Model{ID: uint(idi)}}
 	oldImage.Fill()
 	if oldImage.UserName != username {
 		utils.GinError(c, http.StatusUnauthorized, "username error")
 		return
 	}
-	image.Delete()
+	oldImage.Delete()
 }
 
 func UpdateImage(c *gin.Context) {

src/model/data_model.go

@@ -10,6 +10,10 @@ type DataModel struct {
 	Type        string
 	Name        string
 	Comment     string
+	Doc         string
+	UserName    string
+	Password    string
+	IsPublished bool
 	AccessInfo  string
 }
 

src/model/project_model.go

@@ -12,10 +12,18 @@ type ProjectModel struct {
 	GroupName   string
 	Type        string
 	Comment     string
+	Doc         string
+	IsPublic    bool
 
 	ImageID   int
 	Image     ImageModel
 	TrainData []*DataModel `gorm:"many2many:projects_data"`
+
+	UserPath  string
+	CodePath  string
+	ModelPath string
+
+	Running bool `gorm:"-:all"`
 }
 
 func (*ProjectModel) TableName() string {
@@ -31,4 +39,6 @@ type RunningProject struct {
 	Memory     int
 	Gpus       int
 	GpuMemory  int
+	URL        string
+	ControlURL string
 }