feat: add docs to main (#1559)

2025-07-17 11:58:59 +08:00
parent e00018de59
commit af8e3b172c
1037 changed files with 40779 additions and 2 deletions
--- a/docs/zh/developer/develop/tutorial/index.md
+++ b/docs/zh/developer/develop/tutorial/index.md
@@ -0,0 +1,15 @@
+# 教程
+
+欢迎阅读 Olares 应用开发指南。这些详细的教程将逐步指导你从零开始构建 Olares 应用。
+
+在开始前，你可以先了解一些 Olares 的基本概念，如：
+- [Olares 的组成](../../../manual/concepts/architecture.md)
+- [Olares 应用 Chart](../../develop/package/chart.md)
+- [Olares 在 Helm 上的扩展](../package/extension.md)。
+
+这些基础知识将帮助你更有效地掌握的开发流程。
+
+你还可以先了解下 [DevBox](studio.md)，这是 Olares 为开发人员构建 Olares 应用程序提供的内置应用程序。
+
+如果你是 Olares 开发的新手，想直接开始编码，可以从[创建首个应用](./note/index.md)开始。本教程将指导你构建一个小型笔记应用程序。
+
--- a/docs/zh/developer/develop/tutorial/note/backend.md
+++ b/docs/zh/developer/develop/tutorial/note/backend.md
@@ -0,0 +1,71 @@
+# 开始后端程序开发
+
+## 克隆代码
+
+  打开后端的开发容器 IDE, 打开 Terminal，可控你的代码到 `/Code` 目录。
+
+  ```sh
+  gh auth login
+
+  cd /Code
+  git clone https://github.com/beclab/terminus-app-demo.git
+  ```
+
+  之后便可以在 IDE 中打开后端代码进行开发。
+
+  ![server IDE](/images/developer/develop/tutorial/backend/dev.jpg)
+
+## 连接数据库
+
+  在开发容器中，可以通过环境变量获取数据库信息（如果你在部署的时候以环境变量的方式将数据库参数注入容器）。
+
+  以 gorm 为例：
+  ```go
+  import (
+    "fmt"
+    "os"
+    "strconv"
+
+    "gorm.io/driver/postgres"
+    "gorm.io/gorm"
+  )
+
+
+  func init() {
+    var err error
+
+    db_host = os.Getenv("DB_HOST")
+    db_port, err = strconv.Atoi(os.Getenv("DB_PORT"))
+    if err != nil {
+        panic(err)
+    }
+    db_username = os.Getenv("DB_USER")
+    db_password = os.Getenv("DB_PWD")
+    db_name = os.Getenv("DB_NAME")
+  }
+
+
+  func main(){
+    dsn := fmt.Sprintf("host=%s user=%s password=%s dbname=%s port=%d sslmode=disable TimeZone=Asia/Shanghai",
+  	db_host, db_username, db_password, db_name, db_port)
+    db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
+    if err != nil {
+  	  panic(err)
+    }
+
+  }
+  ```
+
+## 调试
+
+  完成代码开发后，便可在 IDE 中运行调试你的代码。
+
+  ![run and debug](/images/developer/develop/tutorial/backend/debug.jpg)
+
+  也可以在 Terminal 中运行你的代码，例如：
+
+  ```sh
+  go run main.go
+  ```
+
+  这时，就可以配合前端完成接口联调。
--- a/docs/zh/developer/develop/tutorial/note/create.md
+++ b/docs/zh/developer/develop/tutorial/note/create.md
@@ -0,0 +1,190 @@
+---
+outline: [2, 3]
+---
+
+# 如何开始开发一个应用
+
+## 下载并安装 DevBox
+
+1. 从 Olares 应用市场安装 [DevBox](https://market.olares.com/app/devbox)。
+2. 在 Olares 桌面的 LaunchPad 中找到 DevBox 图标。
+3. 点击图标启动应用程序。
+
+  ![main screen](/images/developer/develop/tutorial/create/home.jpg)
+
+## 创建应用
+
+点击 **Create a new application**，从模版创建一个空白的 Olares 应用。
+- 在 **App Name** 一栏，输入你的应用名称。
+- 设置 **App type** 为 **app**。
+- 修改 APP 入口的端口。
+- **Image** 一栏填写应用将要推送的镜像仓库的镜像名称和 tag。
+
+![create app](/images/developer/develop/tutorial/create/create.jpg)
+
+## 设置应用配置
+
+创建应用程序后，你可以在 **Files** 选项卡下看到 DevBox 生成的 Olares Application Chart 文件。你可以根据需要添加、删除或重命名各种配置文件。
+
+![upload icon](/images/developer/develop/tutorial/create/add-file.jpg)
+
+### Chart.yaml
+
+`Chart.yaml `文件是 Helm Chart 规范所必须的文件之一。其中包含了应用的名称和 Chart Version，你可以[在此](https://helm.sh/docs/topics/charts/)了解更多。我们暂时先不用修改默认创建的`Chart.yaml`。
+
+### OlaresManifest.yaml
+在 `OlaresManifest.yaml` 文件中，你可以更改许多配置。例如：
+- 更改应用的标题、图标和其他详细信息
+- 添加系统中间件
+- 获取系统目录访问的权限
+- 更改应用程序的所需的资源限制
+
+#### 添加系统的[数据库集群需求](../../package/manifest.md#middleware)
+
+![config app](/images/developer/develop/tutorial/create/olares-manifest.jpg)
+
+此处我们需要申请一个 PostgreSQL 的数据库，在配置文件中添加以下内容。
+```Yaml
+middleware:
+  postgres:
+    username: postgres
+    databases:
+    - name: db
+      distributed: false
+```
+
+申请时，需要定义你的数据库访问用户名。也可以自定以密码（只需要添加一个 password 申明），也可以由系统生成随机密码。这里需要设置你的 APP 需要的 database name。另外，还可以选择申请一个分布式数据库。如果选在分布式数据库，系统会为你创建一个[citus](https://github.com/citusdata/citus)数据库
+
+完成配置后，可在你的 deployment 中引用对应的数据库配置。例如，在容器的环境变量中引用。
+```yaml
+- env:
+    - name: DB_PORT
+      value: "{{ .Values.postgres.port }}"
+    - name: DB_NAME
+      value: "{{ .Values.postgres.databases.demo }}"
+    - name: DB_USER
+      value: "{{ .Values.postgres.username }}"
+    - name: DB_HOST
+      value: "{{ .Values.postgres.host }}"
+    - name: DB_PWD
+      value: "{{ .Values.postgres.password }}"
+```
+  - `.Values.postgres.username`：对应申请 PostgreSQL 中的 username。
+  - `.Values.postgres.databases.demo`：对应申请中的 database name。
+  - `.Values.postgres.password`：对应申请中的 password
+  - `.Values.postgres.host`：系统为 APP 指定的数据库服务地址
+  - `.Values.postgres.port`：系统为 APP 指定的数据库服务的端口
+
+::: warning
+这些参数不应该被硬编码，它们必须引用系统传入的变量，并且系统会随机化配置中的数据库信息。
+:::
+
+#### 申请系统的[文件系统访问权限](../../package/manifest.md#permission)
+
+为了能在 Olares 中读取和保存文件，我们需要在 `Permissions` 一项中，配置所需的文件目录。`OlaresManifest.yaml`提供了三个位置的文件目录，分别是：
+- `appData`: 申请应用独立数据云存储空间。
+- `appCache`: 给应用申请节点本地磁盘（一般为 SSD 磁盘）数据缓存空间。
+- `userData`: 申请用户的数据目录访问权限。可列举需要访问的目录列表。
+
+完成上述配置后，就可以在你的 deployment 中引用这些配置。
+
+```yaml
+volumes:
+  - hostPath:
+      path: "{{ .Values.userspace.appCache }}/demo"
+      type: DirectoryOrCreate
+    name: appcache
+  - hostPath:
+      path: "{{ .Values.userspace.appData }}/demo"
+      type: DirectoryOrCreate
+    name: appdata
+```
+  - `.Values.userspace.appCache` 对应 appCache 目录
+  - `.Values.userspace.appData` 对应 appData 目录
+  - `.Values.userspace.userData` 对应 userData 目录
+
+### deployment.yaml
+
+`templates` 文件夹中的 `deployment.yaml` 详细描述了应用的部署配置。
+
+如果你的应用分为前后端两个不同的容器。你可以在 templates 的部署文件中，添加多个容器。DevBox 将识别这些不同的容器并将它们分别绑定到不同的开发容器。例如，
+```yaml
+containers:
+  # 前端容器
+  - env:
+      - name: PGID
+        value: "1000"
+      - name: PUID
+        value: "1000"
+      - name: TZ
+        value: Etc/UTC
+    image: bytetrade/demo-app:0.0.1
+    name: demo
+    ports:
+      - containerPort: 8080
+    resources:
+      limits:
+        cpu: "1"
+        memory: 2000Mi
+      requests:
+        cpu: 50m
+        memory: 1000Mi
+    volumeMounts:
+      - mountPath: /appcache
+        name: appcache
+
+  # Server 端容器
+  - env:
+      - name: DB_PORT
+        value: "{{ .Values.postgres.port }}"
+      - name: DB_NAME
+        value: "{{ .Values.postgres.databases.demo }}"
+      - name: DB_USER
+        value: "{{ .Values.postgres.username }}"
+      - name: DB_HOST
+        value: "{{ .Values.postgres.host }}"
+      - name: DB_PWD
+        value: "{{ .Values.postgres.password }}"
+      - name: PGID
+        value: "1000"
+      - name: PUID
+        value: "1000"
+      - name: TZ
+        value: Etc/UTC
+    image: bytetrade/demo-server:0.0.1
+    name: server
+    ports:
+      - containerPort: 9000
+    resources:
+      limits:
+        cpu: "1"
+        memory: 1000Mi
+      requests:
+        cpu: 50m
+        memory: 500Mi
+    volumeMounts:
+      - mountPath: /appcache
+        name: appcache
+      - mountPath: /appdata
+        name: appdata
+```
+
+## 绑定容器
+配置完上述信息后，你需要在 **Containers** 页面为这个开发中的应用，绑定开发容器，进行代码开发。
+
+![containers](/images/developer/develop/tutorial/create/bind.jpg)
+
+你可以为绑定的开发容器设置一个指定的开发环境，目前 DevBox 支持 NodeJS、Golang、python 三种开发容器。让我们给 demo 前端容器绑定一个 NodeJS 开发容器，给 Server 容器绑定一个 Golang 的开发容器。
+
+这里选择了创建一个新的开发容器。如果之前已经创建过未绑定的开发容器，这里也可以选择一个已有的容器进行绑定。
+
+![bind container](/images/developer/develop/tutorial/create/bind-2.jpg)
+
+## 安装应用
+完成开发容器绑定后，就可以点击右上角的安装将当前应用安装到系统中了。等待安装状态从 `Processing` 变为 `Running` 即表示应用已安装完成，可进入正式的代码开发流程。
+
+![installing](/images/developer/develop/tutorial/create/installing.jpg)
+
+此时，再次进入 Containers 页面，可以看到开发容器上的 **Open IDE** 按钮激活。点击即可进入开发环境进行代码开发。
+
+![processing](/images/developer/develop/tutorial/create/success.jpg)
--- a/docs/zh/developer/develop/tutorial/note/frontend.md
+++ b/docs/zh/developer/develop/tutorial/note/frontend.md
@@ -0,0 +1,75 @@
+# 开始前端程序开发
+
+## 预览应用
+应用安装完成后，可以通过 DevBox 的**预览**按钮，预览应用的前端效果。
+
+![preview](/images/developer/develop/tutorial/frontend/preview.jpg)
+
+## 打开 IDE
+
+打开前端的开发容器 IDE, 可以看见开发容器的预览欢迎页。之后的开发流程与[开发后端](backend.md)类似，在 Terminal 中克隆你的前端代码。
+
+::: tip
+在本教程中，因为前后端共开发容器共享了代码目录，后端 clone 代码后，前端不需要再次克隆代码。
+:::
+
+克隆完代码后，如果是 Node 项目，可能需要做配置修改。
+
+- **Vite 配置修改**
+
+  如果前端项目采用了 vite，需要增加 hmr 配置。Vite 在 dev 状态，会启动 websocket 监听服务器端发送的代码更新 reload 通知。默认 ws 端口为 server 启动的端口。而 dev app 启动了 nginx 代理，采用了标准的 443 端口。所以需要做相应修改。
+  
+  按以下方式修改 vite.config.js 文件：
+  ```js
+  export default defineConfig({
+    server: {
+      hmr: {
+        clientPort: 443,
+      },
+    },
+  });
+  ```
+- **Nginx 配置修改**
+
+  配置好项目的开发环境后，需要修改 Nginx 配置。打开 `/etc/nginx/conf.d/dev/dev.conf` 修改：
+
+  ```nginx
+  location / {
+    proxy_pass http://127.0.0.1:9000;
+    proxy_set_header            Host $http_host;
+    proxy_set_header            X-real-ip $remote_addr;
+    proxy_set_header            X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $http_connection;
+    proxy_set_header Accept-Encoding gzip;
+  }
+  ```
+
+  然后重启 Nginx：
+  ```sh
+  nginx -s reload
+  ```
+## 运行开发模式
+完成 Nginx 配置后，你就可以启动你的前端程序的开发模式，并在 Olares 中预览你的应用：
+
+```sh
+npm run dev
+```
+
+![frontend preview](/images/developer/develop/tutorial/frontend/preview2.jpg)
+
+如果你需要为前端设置后端 API 代理，可以在 Nginx 中修改代理配置
+
+  ```nginx
+  location /api/ {
+        proxy_pass http://127.0.0.1:9001;
+        proxy_set_header            Host $http_host;
+        proxy_set_header            X-real-ip $remote_addr;
+        proxy_set_header            X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $http_connection;
+        proxy_set_header Accept-Encoding gzip;
+  }
+  ```
--- a/docs/zh/developer/develop/tutorial/note/index.md
+++ b/docs/zh/developer/develop/tutorial/note/index.md
@@ -0,0 +1,16 @@
+# 创建你的首个 Olares 应用
+
+你可以通过本教程学习如何使用 DevBox 开发一个 Olares 应用。
+
+整个教程以开发一个简单的 [Note](https://github.com/beclab/terminus-app-demo) 工具为例。展示如何从创建应用开始，开发一个完整的 Olares 应用。
+
+整个教程分为以下3个部分：
+
+1. [创建应用](./create.md)<br>
+   展示如何创建一个 Olares 应用，并逐步配置这个应用的初始化开发环境。
+
+2. [开发后端](./backend.md)<br>
+   学习如何利用 DevBox 的 IDE 完成后端 Golang 程序的开发，并为前端提供 API 接口。
+
+3. [开发前端](./frontend.md)<br>
+   以 NodeJS 为例，学习如何在 DevBox 的提供的 IDE 中开始前端页面的相关开发。
--- a/docs/zh/developer/develop/tutorial/studio.md
+++ b/docs/zh/developer/develop/tutorial/studio.md
@@ -0,0 +1,13 @@
+# 了解 DevBox
+
+在 Olares 中，我们为每个开发者提供了一个为 Olares 开发应用的开发工具，这就是 DevBox。
+
+- 开发者为什么需要 DevBox 呢？
+
+  Olares 作为一个具有诸多云原生特性的系统，有大量的系统上下文环境在开发者的单机开发环境很难模拟。同时，Olares 独有的沙盒体系也需要在真实的系统环境中才能完成 End to End 的测试。所以，为了方便开发者能够最便捷的获得真实的应用仿真体验，减少开发中的系统联调尝试，我们提供 DevBox 为开发者提供自动快速构建应用沙盒的开发工具集。
+
+- DevBox 提供了哪些功能？
+
+  - 在 DevBox 中，你可以创建一个应用，生成 Olares 应用的 Chart 包。接着你可以修改这个应用 Chart 的部署脚本，移植一个现有的应用，以 Olares 的方式部署到系统中。在修改过程中，你可以尝试安装，检查错误。测试通过后，可下载对应的应用 Chart，提交给 Olares 的 [Market 仓库](https://github.com/beclab/apps)。
+
+  - 除了移植现有应用，你还可以创建一个全新的应用，在 DevBox 完成整个应用的开发到上线的工作。DevBox 中提供了在线的开发容器，开发者可以在真实的环境中完成代码开发，在程序中调用系统的其他接口或者数据库集群等等。