Olares/docs/zh/developer/develop/tutorial/deploy.md

outline	description
2 3	如何使用 Studio 将单容器 Docker 应用快速部署到 Olares。

基于 Docker 镜像部署应用

本文档介绍如何使用 Studio 将单容器 Docker 应用部署到 Olares 系统。

:::info 仅限单容器应用 此方法仅适用于通过单个容器镜像运行的应用。 ::: :::tip 推荐用于测试场景 通过 Studio 部署的应用主要面向开发与测试场景。相比市场安装的正式应用，它在版本维护和数据持久化方面存在局限。如需长期稳定使用，建议先打包并上传应用，然后通过应用市场安装。 :::

前提条件

• Olares 1.12.2 及以上版本。
• 应用的容器镜像已存在，且 Olares 主机可以访问。
• 具备应用的 docker run 命令或 docker-compose.yaml 文件，用于参考端口、环境变量和挂载卷等配置信息。

创建并配置应用

本节以个人订阅和开支追踪应用 Wallos 为例，演示如何将常见的 Docker 配置（镜像、端口、环境变量、卷）映射到 Studio 中。

Docker 配置参考示例 ::: code-group

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

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 上。

配置镜像、端口和实例规格

这些字段定义了应用的核心组件。参考 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

添加环境变量

环境变量主要用于向应用传递配置信息，对应 Docker 示例中的 -e 参数或 environment 字段。

1. 向下滚动至环境变量区域，点击添加。
2. 参照下图示例，填写时区配置：
   • 键： TZ
   • 值：America/Toronto
3. 点击提交。如需添加更多变量，重复此过程。

添加存储卷

存储卷用于将 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. 点击提交。

添加完成后，可在文件管理器中确认挂载路径。

可选：配置 GPU 或数据库中间件

如果应用依赖 GPU，需要在实例规格下启用 GPU 选项并选择 GPU 厂商。

如果应用需要 Postgres 或 Redis 数据库，在实例规格下启用相应选项。

启用数据库后，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. 部署成功后，在右上角点击预览即可打开应用。

检查包文件与测试应用

通过 Studio 部署的应用标题会自动添加 -dev 后缀，以便与从应用市场安装的正式版区分。

你可以查看或编辑 OlaresManifest.yaml 等配置文件。例如，修改应用的显示名称和图标：

1. 在右上角点击 box_edit 编辑打开编辑器。

2. 点击 OlaresManifest.yaml 查看内容。

3. 修改 entrance 和 metadata 部分的 title 字段。例如，将 wallos 改为 Wallos。

4. 替换 entrance 和 metadata 部分的图标地址。

5. 在右上角点击 save 保存更改。

6. 点击应用，系统将使用更新后的配置重新安装应用。

   :::info 如果自上次部署后未检测到任何更改，点击应用将直接返回应用状态页，不会触发重装。 :::

卸载或删除应用

如果不再需要该应用，可执行以下操作：

1. 在右上角点击 more_vert。
2. 选择相应操作：
   • 卸载：仅从 Olares 系统中移除运行的实例，但在 Studio 中保留项目文件，方便继续编辑。
   • 删除：卸载应用并从 Studio 中彻底删除项目文件。此操作不可撤销。

部署故障排除

无法安装应用

如果安装失败，请查看页面底部的错误提示。点击查看可打开详细日志。

运行时遇到问题

应用启动后，你可以在 Studio 的部署详情页进行管理（界面类似于控制面板）。如果详情未显示，刷新页面即可。 常见操作包括：

• 点击停止按钮或重启按钮后重试。这通常能解决进程卡死等临时性故障。
• 查看事件或日志以排查错误。具体方法请参考导出问题容器日志。