ZimaOS Docker应用适配手册

如何将应用发布到ZimaOS

Docker应用发布与适配教程
PC应用编译与上线教程
云应用迁移教程

ZimaOS Docker应用清单与推荐配置

模块化里程碑：优先进行应用升级而不需要重启

应用倾向性判断

初步预测应用适配工作量，是否可以直接适配，是否需要自行构建镜像等。

一般来说，应用的官方网站可以大致分为以下三种倾向性：

Docker自部署

难度：🌟
特点：官方网站或GitHub优先提供自部署选项。
例如：LocalAI, OpenWebUI 和 Nextcloud 等。
这意味着该应用的开发者可能在自部署环境中开发和测试过。这也意味着应用本身具有自部署经验，且开发者及社区通常也有相应经验，适配起来相对容易。
很有可能会提供一个最小配置的AIO镜像，然后我们可以直接进行配置。

PC自部署

难度：🌟🌟🌟
特点：官方网站或GitHub优先提供Win/Mac/Linux的下载，但主要通过WebUI提供主界面。
例如：AUTOMATIC1111/stable-diffusion-webui
代表了该应用的安装过程，这通常由开发者和社区验证过。但可能没有现成的Docker镜像，因为这不是该项目启动时的重点。
如果没有现成的docker镜像，可以相对容易地将其打包成Docker镜像，因为安装过程中几乎不需要担心错误。只需要配置所需环境并预先安装依赖项。

云服务

难度：🌟🌟🌟🌟🌟
特点：官方网站或GitHub建议使用他们提供的云服务，并同时提供自部署方式。通常应用也被描述为一个可以解决多种需求的全方位平台。
例如：Dify, TaskingAI 等。
该应用的开发者通常优先考虑云集群的部署环境，并且很可能基于K8s等容器编排环境进行开发。提供的自部署选项通常是通过docker compose或k8s构建的。启动一个完整的应用涉及多个容器服务和多个镜像，同时需要大量的环境变量甚至外部文件，以使应用能够正常启动。
这类应用需要花费大量精力学习启动过程中需要的各种服务关系，以及大量环境变量的含义和设置方法。同时，如果超出了ZimaOS的应用能力，自己构建镜像将相对困难，因为需要了解该程序所用技术栈的具体配置方法。

了解应用组件

分析应用依赖了哪些重复服务，不同配置的影响，用户需要关注哪些内容。

分析服务需求

通常，每个应用都有自己的独立前端和后端，可能依赖一些共同服务，如：

各种数据库：mysql, redis, pg等。
各种共享API：
- LLMs：Ollama, LocalAI, LM Studio
- ……

由于当前阶段不支持共享服务和预装/推荐依赖，
对于应用开发者/适配者：
可以在适配时优先考虑使用开箱即用的AIO镜像，或者考虑将所需服务打包在镜像或compose中。
对于ZimaOS开发者：
考虑支持预装和推荐的依赖。

分析数据存储需求

在清楚了解后，根据ZimaOS定义的数据目录结构进行相应的初始化映射，并通过适当的提示告知用户他们需要关注的目录。

分析端口需求

WebUI服务的端口，HTTP/HTTPS
- 通常系统可以自由分配，修改不会影响正常使用
- 有些应用可能对这些端口有特定要求，需要明确
API端口
- 许多暴露API的应用端口是常规端口，需先使用原始端口，然后考虑自动分配
- 必要时需要通过提示告知用户
- 例如，Ollama的113114端口
特殊目的的端口，必须存在，如DNS端口
- 一些端口有特定的目的，必须分配，否则核心功能无法正常使用
- 例如，adguard使用的DNS端口等
应用特有的辅助功能端口
- 一些端口应有自己特殊的用途，如用于内网发现等
- 这些端口必须使用原端口，否则辅助功能将失效

由于当前阶段ZimaOS不支持灵活的端口分配，
对于应用开发者/适配者：
可以在适配过程中根据应用特点配置端口并提供提示。
对于ZimaOS开发者：
可以考虑支持定义的端口分配机制。

分析设备需求

GPU需求
CPU需求
USB设备需求
…

在适配时考虑设置所需的设备，并考虑在GPU不可用时是否回退到CPU。

由于当前阶段ZimaOS不支持灵活的设备分配，
对于应用开发者/适配者：
可以在适配过程中根据应用特点配置设备并提供提示。
对于ZimaOS开发者：
可以考虑支持定义的设备分配机制，以及设备需求的检测和反馈机制。

分析运行时需求

nvidia
…

这种需求较少，但推荐在适配时了解相关的运行时需求，进行配置并适当写入提示信息。

阅读官方自部署方案

在适配时优先学习官方最佳实践

官方的自部署方案和文档通常包含一些优秀的实际案例和部署技巧，提前阅读可以加速适配。

适配到ZimaOS Docker应用

现在可以将之前学到的信息整合，适配到ZimaOS应用中。

在开始编写时，可以参考之前应用的文件进行编写：
https://github.com/IceWhaleTech/CasaOS-AppStore/tree/main/Apps

编写docker-compose.yaml
根据定义，在x-casaos字段中添加应用元数据
- 多语言字段至少包含en_us，因为这是回退字段。
准备图标和截图，并在x-casaos字段中填入对应的链接。
测试安装
提交到GitHub

x-casaos字段定义

x-casaos:
    architectures:                  # 支持的架构列表
        - amd64
        - arm
        - arm64
    main: syncthing                 # `services`下主服务的名称
    author: CasaOS团队
    category: 备份
    description:                    # 支持多语言
        en_us: Syncthing是一个持续文件同步程序。它实时同步两个或更多计算机之间的文件，安全地保护您的数据免受窥探。您的数据仅属于您，您有权选择存储位置、是否与第三方共享以及如何通过互联网传输。
    developer: Syncthing
    icon: https://cdn.jsdelivr.net/gh/IceWhaleTech/CasaOS-AppStore@main/Apps/Syncthing/icon.png
    tagline:                        # 支持多语言
        en_us: 免费、安全且分布式的文件同步工具。
    thumbnail: https://cdn.jsdelivr.net/gh/IceWhaleTech/CasaOS-AppStore@main/Apps/Jellyfin/thumbnail.jpg
    title:                          # 支持多语言
        en_us: Syncthing
    tips:
        before_install:
            en_us: |
                (用户需要在安装前阅读的一些注意事项，如默认`用户名`和`密码`——支持markdown格式！)
    index: /                        # Web界面的索引页，例如index.html
    port_map: "8384"                # Web界面的端口

字段描述

Descriptions

详细描述

Tagline

尽量用一句话表达精髓。

图标和截图要求

图标

优先使用官方Logo的SVG图像
- 通常在官方网站的头部
次要使用PNG图像
如果没有图标，找设计师绘制一个

截图

优先使用官方提供的截图
次要使用运行时截图

设计干预

设计师决定是否干预修改

其他提示

容器需要访问其他主机端口

如果主机上运行其他服务（例如Chroma, LocalAi或LMStudio），需要使用http://host.docker.internal:xxxx从Docker容器访问主机服务，因为localhost:xxxx

Zima-Docs

构建应用