eliott/Olares
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add zh-cn version

Browse Source
This commit is contained in:
yajing wang
2025-12-11 18:06:06 +08:00
parent 543328fa6e
commit 6ec7f214cb
13 changed files with 602 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/zh/developer/develop/tutorial/assets.md Normal file
View File

@@ -0,0 +1,26 @@
---
description: 了解如何为 Olares 应用准备和上传图标、功能图像以及宣传图。
---
# 添加图标、功能图像和宣传图
要打造视觉效果出色的应用，高质量的素材必不可少。本文档介绍应用图标、功能图像和截图的规格，以及如何将其上传至 Olares。
## 资源规格
上传前，确保图片格式正确。
| 类型 | 格式 | 文件大小上限 | 尺寸 | 描述 |
|:---------|:--------------|:--------|:---------|:-------------------------------------|
| **应用图标** | PNG，WEBP | 512 KB | 256x256 | 应用最常见的视觉符号，用于 Olares 桌面和整个系统。 |
| **功能图像** | JPEG，PNG，WEBP | 8 MB | 1440x900 | 显示在**应用市场** > **我的 Olares** 中的应用页面上。 |
| **宣传图** | JPEG，PNG，WEBP | 每张 8 MB | 1440x900 | 如果计划将应用提交至公开应用市场，必须上传至少两张。最多可上传八张。 |
## 上传并链接资源
1. 导航至 [Olares 应用市场图片托管](https://imghost.joinolares.cn/)。
2. 选择要上传的资源类型，例如应用图标。
3. 将准备好的文件拖放至上传区域，或点击选择文件。
4. 如有必要，点击图片缩略图进行简单编辑。
5. 准备就绪后，点击**上传**。
6. 上传后，该服务将提供图片的直接 URL。点击 <span class="material-symbols-outlined">content_copy</span> 将 URL 复制到剪贴板。
7. 在 **Studio** 中打开应用项目。
8. 将 URL 粘贴到 `OlaresManifest.yaml` 文件中的对应字段。

190
docs/zh/developer/develop/tutorial/deploy.md Normal file
View File

@@ -0,0 +1,190 @@
---
outline: [2, 3]
description: 如何使用 Studio 将单容器 Docker 应用快速部署到 Olares。
---
# 基于 Docker 镜像部署应用
本文档介绍如何使用 Studio 将单容器 Docker 应用部署到 Olares 系统。
:::info 仅限单容器应用
此方法仅适用于通过单个容器镜像运行的应用。
:::
:::tip 推荐用于测试场景
通过 Studio 部署的应用主要面向开发与测试场景。相比市场安装的正式应用，它在版本维护和数据持久化方面存在局限。如需长期稳定使用，建议先[打包并上传应用](package-upload.md)，然后通过应用市场安装。
:::
## 前提条件
- Olares 1.12.2 及以上版本。
- 应用的容器镜像已存在，且 Olares 主机可以访问。
- 具备应用的 `docker run` 命令或 `docker-compose.yaml` 文件，用于参考端口、环境变量和挂载卷等配置信息。
## 创建并配置应用
本节以个人订阅和开支追踪应用 [Wallos](https://hub.docker.com/r/bellamy/wallos) 为例，演示如何将常见的 Docker 配置（镜像、端口、环境变量、卷）映射到 Studio 中。
**Docker 配置参考示例**
::: code-group
```docker{3-6,8} [docker run 命令]
docker run -d \
--name wallos \
-v /path/to/config/wallos/db:/var/www/html/db \
-v /path/to/config/wallos/logos:/var/www/html/images/uploads/logos \
-e TZ=America/Toronto \
-p 8282:80 \
--restart unless-stopped \
bellamy/wallos:latest
```
```yaml{5-6,7-10,12-14} [docker compose 文件]
version: '3.0'
services:
wallos:
container_name: wallos
image: bellamy/wallos:latest
ports:
- "8282:80/tcp"
environment:
TZ: 'America/Toronto'
volumes:
- './db:/var/www/html/db'
- './logos:/var/www/html/images/uploads/logos'
restart: unless-stopped
```
:::
### 创建应用
1. 打开 Studio，选择**创建新应用**。
2. 输入**应用名称**，例如 `wallos`，然后点击**确认**。
3. 选择**将自己的容器部署到 Olares 上**。
![将自己的容器部署到 Olares 上](/images/manual/olares/studio-port-your-own-container-to-olares.png#bordered)
### 配置镜像、端口和实例规格
这些字段定义了应用的核心组件。参考 `docker run` 命令中的镜像名和 `-p` 参数，或 `docker-compose.yaml` 文件中的 `image:` 和 `ports:` 字段进行填写。
1. 在**容器镜像**字段中，粘贴镜像名称，例如 `bellamy/wallos:latest`。
2. 在**容器端口**字段中，参考 `主机端口:容器端口` 格式的映射（如 `8282:80`），填写冒号后的 `80`。
:::tip 仅需填写容器端口
端口映射的标准格式为 `主机端口:容器端口`。冒号后的是应用在内部监听的“容器端口”，冒号前的是供外部访问的“主机端口”。由于 Studio 会自动管理外部路由，你只需填写容器端口即可。
:::
3. 在**实例规格**区域，设置应用所需的最低 CPU 和内存要求。例如：
* **CPU**: 2 core
* **Memory**: 1 Gi
![部署 Wallos](/images/manual/olares/studio-deploy-wallos.png#bordered)
### 添加环境变量
环境变量主要用于向应用传递配置信息，对应 Docker 示例中的 `-e` 参数或 `environment` 字段。
1. 向下滚动至**环境变量**区域，点击**添加**。
2. 参照下图示例，填写时区配置：
- **键**： `TZ`
- **值**：`America/Toronto`
3. 点击**提交**。如需添加更多变量，重复此过程。
![添加环境变量](/images/manual/olares/studio-add-environment-variables.png#bordered)
### 添加存储卷
存储卷用于将 Olares 设备的物理存储映射到容器内部，这是确保数据持久化的关键步骤，对应 Docker 示例中的 `-v` 参数或 `volumes` 字段。
:::info 理解主机路径
主机路径是指数据在 Olares 系统中的实际存储位置，Studio 提供了三种预设的前缀路径：
- `/app/data`：应用数据目录。数据可跨节点访问，且卸载应用时**不会**删除。在文件管理器中显示为 `/Data/studio`。
- `/app/cache`：应用缓存目录。数据存在节点本地磁盘，卸载应用时会自动删除。在文件管理器中显示为 `/Cache/<device-name>/studio`。
- `/app/Home`：用户数据目录。主要用于读取外部文件，数据不会被删除。
:::
:::info 主机路径规则
- 输入的主机路径必须以 `/` 开头。
- Studio 会自动补全路径前缀。例如，应用名为 `test`，当设置主机路径为 `/app/data/folder1` 时，在文件管理器中的实际路径为 `/Data/studio/test/folder1`。
:::
本应用需要依次挂载两个存储卷：
1. 添加数据库卷。此类数据涉及高频 I/O 读写且无需永久保存。将其映射至 `/app/cache` 以便在应用卸载时自动清理。
a. 点击**存储卷**旁的**添加**。
b. **主机路径**选择 `/app/cache`，并输入 `/db`。
c. **容器路径**输入 `/var/www/html/db`。
d. 点击**提交**。
2. 添加 Logo 卷。此类数据为用户上传内容，需持久化保存，即使重装应用也不应丢失。将其映射至 `/app/data`。
a. 点击**存储卷**旁的**添加**。
b. **主机路径**选择 `/app/data`，并输入 `/logos`。
c. **容器路径**输入 `/var/www/html/images/uploads/logos`。
d. 点击**提交**。
![添加存储卷](/images/manual/olares/studio-add-storage-volumes.png#bordered)
添加完成后，可在文件管理器中确认挂载路径。
![在文件管理器中确认挂载路径](/images/manual/olares/studio-check-mounted-path-in-files.png#bordered)
### 可选：配置 GPU 或数据库中间件
如果应用依赖 GPU，需要在**实例规格**下启用 **GPU** 选项并选择 GPU 厂商。
![启用 GPU](/images/manual/olares/studio-enable-GPU.png#bordered)
如果应用需要 Postgres 或 Redis 数据库，在**实例规格**下启用相应选项。
![启用数据库](/images/manual/olares/studio-enable-databases.png#bordered)
启用数据库后，Studio 会提供一组动态变量。你必须在应用的**环境变量**中添加这些变量，应用才能连接到数据库。
- **Postgres 变量**
| 变量名 | 说明 |
|----------------|----------------|
| `$(PG_USER)` | PostgreSQL 用户名 |
| `$(PG_DBNAME)` | 数据库名称 |
| `$(PG_PASS)` | Postgres 密码 |
| `$(PG_HOST)` | Postgres 服务主机名 |
| `$(PG_PORT)` | Postgres 服务端口 |
- **Redis 变量**
| 变量名 | 说明 |
|-----------------|-------------|
| `$(REDIS_HOST)` | Redis 服务主机名 |
| `$(REDIS_PORT)` | Redis 服务端口 |
| `$(REDIS_USER)` | Redis 用户名 |
| `$(REDIS_PASS)` | Redis 密码 |
### 生成应用项目
1. 完成所有配置后点击**创建**，系统将生成应用的项目文件。
2. 创建完成后，Studio 会自动打包并部署应用。你可以在页面底部栏查看进度状态。
3. 部署成功后，在右上角点击**预览**即可打开应用。
![预览 Wallos](/images/manual/olares/studio-preview-wallos.png#bordered)
## 检查包文件与测试应用
通过 Studio 部署的应用标题会自动添加 `-dev` 后缀，以便与从应用市场安装的正式版区分。
![检查部署的应用](/images/manual/olares/studio-app-with-dev-suffix.png#bordered)
你可以查看或编辑 `OlaresManifest.yaml` 等配置文件。例如，修改应用的显示名称和图标：
1. 在右上角点击 **<span class="material-symbols-outlined">box_edit</span> 编辑**打开编辑器。
2. 点击 `OlaresManifest.yaml` 查看内容。
3. 修改 `entrance` 和 `metadata` 部分的 `title` 字段。例如，将 `wallos` 改为 `Wallos`。
4. 替换 `entrance` 和 `metadata` 部分的图标地址。
![编辑 `OlaresManifest.yaml`](/images/manual/olares/studio-edit-olaresmanifest1.png#bordered)
5. 在右上角点击 <span class="material-symbols-outlined">save</span> 保存更改。
6. 点击**应用**，系统将使用更新后的配置重新安装应用。
:::info
如果自上次部署后未检测到任何更改，点击**应用**将直接返回应用状态页，不会触发重装。
:::
![修改应用图标](/images/manual/olares/studio-change-app-icon1.png#bordered)
## 卸载或删除应用
如果不再需要该应用，可执行以下操作：
1. 在右上角点击 <span class="material-symbols-outlined">more_vert</span>。
2. 选择相应操作：
- **卸载**：仅从 Olares 系统中移除运行的实例，但在 Studio 中保留项目文件，方便继续编辑。
- **删除**：卸载应用并从 Studio 中彻底删除项目文件。此操作不可撤销。
## 部署故障排除
### 无法安装应用
如果安装失败，请查看页面底部的错误提示。点击**查看**可打开详细日志。
### 运行时遇到问题
应用启动后，你可以在 Studio 的部署详情页进行管理（界面类似于控制面板）。如果详情未显示，刷新页面即可。
常见操作包括：
- 点击**停止**按钮或**重启**按钮后重试。这通常能解决进程卡死等临时性故障。
- 查看事件或日志以排查错误。具体方法请参考[导出问题容器日志](../../../manual/olares/controlhub/manage-container.md#导出问题容器日志)。
![应用部署详情](/images/manual/olares/studio-app-deployment-details.png#bordered)

238
docs/zh/developer/develop/tutorial/develop.md Normal file
View File

@@ -0,0 +1,238 @@
---
outline: [2, 3]
description: 了解如何使用 Studio 设置开发容器，通过 VS Code 访问，并配置端口转发。
---
# 使用开发容器开发应用
Olares Studio 允许你启动预配置的开发容器来编写和调试代码（如 Node.js 脚本或 CUDA 程序），无需管理本地基础设施。这提供了与生产运行时完全隔离且一致的环境。
本文档以 Node.js 项目为例介绍设置流程。
## 前提条件
- Olares 1.12.2 及以上版本。
## 1. 初始化容器
开始编码前，需要配置容器资源并选择运行时环境。
1. 打开 Studio 并选择**创建新应用**。
2. 输入**应用名称**（例如 `My Web`），然后点击**确认**。
3. 选择**在 Olares 上写程序**作为创建方式。
![在 Olares 上写程序](/images/manual/olares/studio-coding-on-olares.png#bordered)
4. 配置**开发环境**：
a. 从下拉列表中选择 `beclab/node20-ts-dev:1.0.0`。
b. 为容器分配资源，例如：
- **CPU**：`2 core`
- **内存**：`4 Gi`
- **卷大小**：`500 Mi`
5. 在**暴露端口**字段中，输入用于调试的端口，例如 `8080`。
:::tip 暴露多个端口
端口 `80` 默认为暴露状态。如需暴露多个额外端口，请用逗号分隔。
:::
![配置开发环境](/images/manual/olares/studio-configure-dev-env.png#bordered)
6. 点击**创建**。等待左下角的状态变为`运行中`。
## 2. 访问工作区
你可以通过浏览器或本地 IDE 访问开发容器。
### 选项 A：基于浏览器的 VS Code
点击 Studio 中的**在线编辑器**，在浏览器中启动一个功能齐全的 VS Code 实例。
![在浏览器中打开 VS Code](/images/manual/olares/studio-open-vs-code-in-browser.png#bordered)
### 选项 B：本地 VS Code 远程隧道
如果更习惯使用本地设置和插件，可以通过隧道连接到容器。
1. 点击 Studio 中的**在线编辑器**以打开基于浏览器的 VS Code。
2. 点击左上角的 <span class="material-symbols-outlined">menu</span>，选择**Terminal** > **New Terminal**打开终端。
3. 安装 VS Code Tunnel CLI：
```bash
curl -SsfL https://vscode.download.prss.microsoft.com/dbazure/download/stable/17baf841131aa23349f217ca7c570c76ee87b957/vscode_cli_alpine_x64_cli.tar.gz | tar zxv -C /usr/local/bin
```
4. 创建安全隧道：
```bash
code tunnel
```
5. 按照终端提示，通过提供的 URL 使用 Microsoft 或 GitHub 帐户进行身份验证。
6. 出现提示时为隧道命，例如 `myapp-demo`。终端将输出绑定到此远程工作区的 `vscode.dev` URL。
![创建安全隧道](/images/manual/olares/studio-create-a-secure-tunnel.png#bordered)
7. 在本地机器上打开 VS Code，点击左下角的 **><** 图标，选择 **Tunnel**。
![打开远程窗口](/images/manual/olares/studio-open-remote-window.png#bordered){width=30%}
![连接远程隧道](/images/manual/olares/studio-connect-remote-tunnel.png#bordered)
8. 使用上一步中的同一帐户登录。
9. 选择刚才定义的隧道名称 `myapp-demo`。VS Code 可能需要几分钟建立连接。连接成功后，左下角的远程指示器将显示隧道名称。
![选择隧道名称](/images/manual/olares/studio-select-tunnel-name.png#bordered)
![远程隧道已连接](/images/manual/olares/studio-remote-tunnel-connected.png#bordered){width=30%}
连接成功后，你将拥有对容器文件系统和终端的完全远程访问权限，体验与本地开发一致。
## 3. 编写和运行代码
进入工作区后，无论是通过浏览器还是本地隧道，工作流与标准本地开发无异。
你可通过以下方式向工作区添加内容：
- 上传文件
- 克隆 Git 仓库
- 手动创建文件
本例演示如何手动创建一个基础网页。
1. 打开 Explorer 侧边栏并导航到 `/root/`。
:::info
Studio 将项目文件持久化在 `数据/studio/<app_name>/` 路径下。
:::
![打开根目录](/images/manual/olares/studio-open-root-directory.png#bordered)
2. 在左上角点击 <span class="material-symbols-outlined">menu</span>，选择 **Terminal** > **New Terminal** 打开终端。
3. 运行以下命令初始化项目：
```bash
npm init -y
```
4. 安装 Express 框架：
```bash
npm install express --save
```
5. 在 `/root/` 中创建文件 `index.js`，内容如下：
```js
// 确保端口与定义的一致
const express = require('express');
const app = express();
app.use(express.static('public/'));
app.listen(8080), function() {
console.log('Server is running on port 8080');
};
```
6. 在 `/root/` 中创建 `public` 目录并添加 `index.html` 文件：
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>My Web Page</title>
</head>
<body>
<h1>Hello World</h1>
<h1>Hello Olares</h1>
</body>
</html>
```
7. 启动服务器：
```bash
node index.js
```
8. 打开 VS Code 中的 **Ports** 标签页，点击转发地址查看结果。
![查看网页](/images/manual/olares/studio-view-web-page.png#bordered)
## 4. 配置端口转发
如果在创建容器后需要暴露更多端口，例如添加端口 `8081`，需要手动编辑容器配置清单。
:::tip
如果需要更改端口号，可参照相同步骤修改 `OlaresManifest.yaml` 和 `deployment.yaml` 文件。
:::
### 修改配置清单
1. 在 Studio 中，点击右上角的**<span class="material-symbols-outlined">box_edit</span>Edit**打开编辑器。
2. 编辑 `OlaresManifest.yaml`。
a. 将新端口追加到 `entrances` 列表：
```yaml
entrances:
- authLevel: private
host: myweb
icon: https://app.cdn.olares.com/appstore/default/defaulticon.webp
invisible: true
name: myweb-dev-8080
openMethod: ""
port: 8080
skip: true
title: myweb-dev-8080
# 添加以下内容
- authLevel: private
host: myweb # 必须匹配 Service metadata name
icon: https://app.cdn.olares.com/appstore/default/defaulticon.webp
invisible: true
name: myweb-dev-8081 # 唯一标识符
openMethod: ""
port: 8081 # 新端口号
skip: true
title: myweb-dev-8081
```
b. 在右上角点击 <span class="material-symbols-outlined">save</span> 保存更改。
3. 编辑 `deployment.yaml`。
a. 在 `Deployment` > `metadata` 下，将端口映射添加到 `default-thirdlevel-domains`：
```yaml
annotations:
applications.app.bytetrade.io/default-thirdlevel-domains:
'[{"appName":"myweb","entranceName":"myweb-dev-8080"},{"appName":"myweb","entranceName":"myweb-dev-8081"}]'
# # entranceName 必须匹配 OlaresManifest.yaml 中的名称
```
b. 更新 `spec` > `template` > `metadata` 下的 `studio-expose-ports` 注解：
```yaml
template:
metadata:
annotations:
applications.app.bytetrade.io/studio-expose-ports: "8080,8081"
```
c. 在 `Service` > `spec` > `ports` 下添加端口定义：
```yaml
kind: Service
spec:
ports:
- name: "80"
port: 80
targetPort: 80
- name: myweb-dev-8080
port: 8080
targetPort: 8080
# 添加以下内容
- name: myweb-dev-8081 # 必须匹配 entrance name
port: 8081
targetPort: 8081
selector:
io.kompose.service: myweb
```
d. 在右上角点击 <span class="material-symbols-outlined">save</span> 保存更改。
4. 点击**应用**重新部署容器。
部署成功后，你可以在 **服务** > **端口** 中看到列出的新端口。
![验证活动端口](/images/manual/olares/studio-verify-active-ports.png#bordered)
### 测试连接
1. 更新 `index.js` 以监听新端口：
```js
const express = require('express');
const app = express();
app.use(express.static('public/'));
app.listen(8080), function() {
console.log('Server is running on port 8080');
};
// 添加以下内容
const app_new = express();
app_new.use(express.static('new/'));
app_new.listen(8081), function() {
console.log('Server is running on port 8081');
};
```
2. 在 `/root/` 中创建 `new` 目录并添加 `index.html` 文件：
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>My Web Page</title>
</head>
<body>
<h1>This is a new page</h1>
</body>
</html>
```
3. 重启服务器：
```bash
node index.js
```
4. 检查 **Ports** 标签页确认端口 `8081` 处于活动状态且可访问。
![查看添加的端口](/images/manual/olares/studio-view-added-port.png#bordered)
5. 点击转发地址查看结果。
![查看添加的网页](/images/manual/olares/studio-verify-added-web-page.png#bordered)

29
docs/zh/developer/develop/tutorial/index.md
View File

@@ -1,15 +1,26 @@
# 教程
---
description: 学习如何使用 Studio 在 Olares 设备上部署 Docker 应用、开发新应用、进行本地打包上传以及管理应用素材。
---
# 在 Olares 上部署与开发应用
欢迎阅读 Olares 应用开发指南。这些详细的教程将逐步指导你从零开始构建 Olares 应用。
由于本地环境难以模拟云功能和沙箱系统，Studio 提供了一个真实的 Olares 环境，用于构建、移植和测试应用。通过 Studio，你可以：
- 在在线开发容器中创建全新的 Olares 应用。
- 移植现有应用，调整配置并测试安装流程。
- 待应用准备就绪后，将其打包为 Chart 并下载。
在开始前，你可以先了解一些 Olares 的基本概念，如：
- [Olares 的组成](../../concepts/architecture.md)
- [Olares 应用 Chart](../../develop/package/chart.md)
- [Olares 在 Helm 上的扩展](../package/extension.md)。
## 获取 Studio
你需要手动安装 Studio：
1. 打开**应用市场**，搜索 "Studio"。
![Studio](/images/manual/olares/studio.png#bordered)
这些基础知识将帮助你更有效地掌握的开发流程。
2. 点击**获取**，随后点击**安装**，等待安装完成。
你还可以先了解下 [DevBox](studio.md)，这是 Olares 为开发人员构建 Olares 应用程序提供的内置应用程序。
安装完成后，可从应用市场或启动台启动 Studio。
如果你是 Olares 开发的新手，想直接开始编码，可以从[创建首个应用](./note/index.md)开始。本教程将指导你构建一个小型笔记应用程序。
## 熟悉 Studio 界面
Studio 的核心功能都集中在侧边栏和**主页**：
- **主页**：欢迎页，包含常用操作入口和文档链接。
- **应用**：展示你用 Studio 创建和部署的应用列表。
- **开始**：在此开始部署或开发应用，也可上传本地 Chart 文件。
![Understand Studio user interface](/images/manual/olares/studio-ui.png#bordered)

27
docs/zh/developer/develop/tutorial/package-upload.md Normal file
View File

@@ -0,0 +1,27 @@
---
description: 从 Studio 下载应用包并在 Olares 应用市场中安装，以实现稳定且长期的使用。
---
# 打包应用并上传至应用市场
Studio 创建的应用非常适合开发和测试。如需长期稳定使用，建议通过 Olares 应用市场进行安装。
## 从 Studio 下载应用包
确认应用运行符合预期后，即可下载完整的安装包：
1. 在 **Studio** 中打开应用项目。
2. 在右上角点击 <span class="material-symbols-outlined">more_vert</span>。
3. 从下拉菜单中选择**下载**，将应用包保存至本地。
## 通过应用市场安装应用
1. 打开**应用市场**。
2. 导航至**我的 Olares**，并选择**上传自定义 Chart**。
3. 选择从 Studio 下载的 `.tgz` 应用包文件。等待上传完成。
4. 系统将弹出提示，确认应用已成功添加。点击**立即安装**。
![安装自定义 Chart](/images/manual/olares/studio-custom-install.png#bordered)
完成后，可以点击**打开**启动应用。
所有自定义安装的应用都将显示在**我的 Olares** > **Upload** 标签页下。