前言
本文作为一篇对于 1Panel 应用商店应用的详细开发文档，修复了官方文档久久不更新的BUG，同时可以将本文内容喂给 AI 以获得较为完美的 AI 协作。
准备工作
- 确保您的应用程序符合 1Panel 应用商店的上架要求，具体要求请参考 应用上架前提。
- 准备好应用的相关信息，包括名称、描述、图标等。
- 确保您的应用可以在 1Panel 环境中正常运行。
文件夹格式
├── halo // 应用根目录 ├── logo.png // 应用 logo , 最好是 180 * 180 px,不要超过 10 KB ├── data.yml // 应用声明文件 ├── README.md // 应用的 README ├── 2.2.0 // 应用版本，注意不要以 v 开头 │ ├── data.yml // 应用的参数配置，下面有详细介绍 │ ├── data // 挂载出来的目录（非必须） │ ├── scripts // 脚本目录 存放 init.sh、upgrade.sh、uninstall.sh（非必须） │ └── docker-compose.yml // docker-compose 文件 └── 2.3.2 ├── data.yml ├── data └── docker-compose.yml应用声明文件 data.yml 说明
# === 官方应用商店兼容字段（上架官方商店必填，其余情况选填） ===# https://apps.fit2cloud.com/1panel# 显示名称name: Halo# 分类标签tags: 建站# 副标题title: 强大易用的开源建站工具# 应用描述description: 强大易用的开源建站工具# === 以下为 1Panel 应用商店解析的数据结构，必须保留此结构 ===additionalProperties: # === 必填字段 === # 应用程序唯一标识符，用于系统内部识别及创建文件夹，仅限英文（必填） key: halo # 应用程序显示名称（必填） name: Halo # 应用程序类型（必填） # 可选值: website: 网站应用，支持在1Panel中一键部署，如 Wordpress、Halo等 # runtime: 运行时环境，如 MySQL、Redis、OpenResty 等 # tool: 工具类应用，大部分应用不属于上述两类的，可归为工具类，如 FileBrowser、phpMyAdmin 等 type: website # 分类标签数组，用于应用商店分类显示（必填），可选值可见：https://github.com/1Panel-dev/appstore/blob/dev/data.yaml tags: - Website # === 描述信息字段（选填，建议填写）=== # 中英文描述，建议20-30个字符，v1 版本格式 shortDescZh: 强大易用的开源建站工具 shortDescEn: Powerful and easy-to-use open source website builder # 多语言描述，建议20-30个字符，v2 版本格式 description: # 简体中文 zh: 强大易用的开源建站工具 # 繁体中文 zh-hant: 強大易用的開源建站工具 # 英文 en: A powerful and easy-to-use open source website building tool # 日语 ja: 強力で使いやすいオープンソースのウェブサイト構築ツール # 马来语 ms: Alat pembinaan laman web sumber terbuka yang kuat dan mudah digunakan # 巴西葡萄牙语 pt-br: Uma ferramenta de construção de sites de código aberto poderosa e fácil de usar # 俄语 ru: Мощный и удобный инструмент с открытым исходным кодом для создания веб-сайтов # 韩语 ko: 강력하고 사용하기 쉬운 오픈소스 웹사이트 구축 도구 # 土耳其语 tr: Güçlü ve kullanımı kolay açık kaynaklı web sitesi oluşturma aracı # === 功能配置字段（选填）=== # 是否支持跨版本更新，默认false crossVersionUpdate: true # 安装数量限制，0表示无限制，默认0 limit: 0 # 推荐级别，数值越小越推荐，用于应用商店排序，默认9999 recommend: 5 # === 链接信息字段（选填）=== # 官方网站链接，必须是有效的 HTTP/HTTPS URL website: https://halo.run/ # GitHub 仓库链接，必须是有效的HTTP/HTTPS URL github: https://github.com/halo-dev/halo # 文档链接，必须是有效的HTTP/HTTPS URL document: https://docs.halo.run/ # === 系统要求字段（选填）=== # 内存要求（MB），用于系统资源检查和用户提示 # 常见值：512, 1024, 2048, 4096 memoryRequired: 1024 # 支持的 CPU 架构数组 # 可选值：amd64, arm64, armv7, ppc64le, s390x, riscv64 architectures: - amd64 - arm64 - ppc64le - s390x # 是否需要GPU支持，默认false gpuSupport: false # === 版本兼容性字段（选填）=== # 最低面板版本要求，0表示无要求，默认0 # 示例：1.0, 1.5, 2.0 version: 0 # 废弃版本标记，0表示未废弃，默认0，若不为 0，则与当前系统版本号对比，若大于等于该版本号，则不出现在应用商店中 deprecated: 0README.md 编写要求
## 基本结构规范## 产品介绍用一句或一段话简要介绍应用的主要功能和用途。## 默认账户信息如果应用有默认登录凭据，应在文件开头明确标注。## 主要功能使用 "## 主要功能" 或 "## 关键特性" 作为二级标题，然后用项目符号列表详细描述各项功能。### 分类组织对于复杂功能，使用三级标题进行分类组织，每个分类下用项目符号详细说明。## 配置和使用说明### 注意事项重要的使用注意事项应放在显眼位置，使用 "## 注意事项" 标题。### 配置步骤详细的配置说明应使用清晰的步骤格式，包含具体的命令和路径。代码示例应使用适当的语法高亮。项目应提供中英文两个版本的 README 文件，分别命名为 README.md（中文）和 README_en.md（英文）。
命令和配置示例应使用适当的代码块格式，并标注语言类型以获得正确的语法高亮。
应用的参数配置 data.yml 说明
版本目录下的 data.yml 文件用于定义应用程序特定版本的安装参数和表单字段配置。
基本结构如下：
# === 配置文件说明 ===# 路径：应用程序版本目录下（如 1.0.0/data.yml）# 用途：定义对应版本应用的安装参数及表单字段配置，支撑 1Panel 平台安装流程的参数解析与用户交互# === 核心数据结构（必须保留）===additionalProperties: # 用户安装应用时需填写的配置参数列表 formFields: # ------------------------------ # 基础演示字段（通用文本输入示例） # ------------------------------ - type: "text" # 字段类型：text(通用文本) / password(敏感密码) / select(下拉选择) / service(服务选择) / number(数字输入) labelZh: "演示标签" # 中文显示标签（必填） labelEn: "Demo Label" # 英文显示标签（必填） # 多语言标签配置（可选，建议补充以支持多语言环境） label: zh: "演示标签" zh-hant: "示範標籤" en: "Demo Label" ja: "デモラベル" ms: "Label Demo" pt-br: "Rótulo de Demonstração" ru: "Демо Метка" ko: "데모 라벨" tr: "Demo Etiketi" # 多语言描述说明（可选，用于解释字段用途） description: zh: "这是一个演示标签，用于展示通用文本字段的配置格式" zh-hant: "這是一個示範標籤，用於展示通用文字欄位的設定格式" en: "This is a demo label to show the configuration format of general text fields" ja: "これは汎用テキストフィールドの設定形式を示すデモラベルです" ms: "Ini adalah label demo untuk menunjukkan format konfigurasi medan teks umum" pt-br: "Este é um rótulo de demonstração para mostrar o formato de configuração de campos de texto geral" ru: "Это демонстрационная метка для отображения формата конфигурации общих текстовых полей" ko: "일반 텍스트 필드의 구성 형식을 보여주기 위한 데모 라벨입니다" tr: "Genel metin alanlarının yapılandırma formatını göstermek için bir demo etiketidir" required: true # 是否为必填项（必填） envKey: "APP_NAME" # 环境变量键名（必填，不可包含空格，用于关联 Docker Compose 配置） default: "demo" # 默认值（可选） edit: false # 是否允许用户修改该字段 random: false # 是否在默认值后追加随机字符串 rule: "paramCommon" # 输入验证规则（可选）：paramPort(端口1-65535) / paramExtUrl(URL格式) / paramCommon(英文/数字/.-_，2-30位) / paramComplexity(含特殊字符，6-30位，首尾非特殊字符) # ------------------------------ # 常用功能字段配置示例 # ------------------------------ # 1. 应用 HTTP 端口配置（数字输入类型） # 有 web 访问端口的优先使用此 envKey： PANEL_APP_PORT_HTTP # envKey 中包含 PANEL_APP_PORT 前缀会被认定为端口类型，并且用于安装前的端口占用校验。 - type: "number" labelZh: "HTTP 端口" labelEn: "HTTP Port" label: zh: "HTTP 端口" zh-hant: "HTTP 埠" en: "HTTP Port" ja: "HTTPポート" ms: "Port HTTP" pt-br: "Porta HTTP" ru: "Порт HTTP" ko: "HTTP 포트" tr: "HTTP bağlantı noktası" description: zh: "设置应用的 HTTP 访问端口，有效范围：1-65535" zh-hant: "設定應用程式的 HTTP 存取埠，有效範圍：1-65535" en: "Set the HTTP access port for the application, valid range: 1-65535" ja: "アプリケーションのHTTPアクセスポートを設定します。有効範囲：1-65535" ms: "Tetapkan port akses HTTP untuk aplikasi, julat sah: 1-65535" pt-br: "Defina a porta de acesso HTTP para o aplicativo, intervalo válido: 1-65535" ru: "Установите порт HTTP-доступа для приложения, допустимый диапазон: 1-65535" ko: "애플리케이션의 HTTP 접근 포트를 설정합니다. 유효 범위: 1-65535" tr: "Uygulama için HTTP erişim bağlantı noktasını ayarlayın, geçerli aralık: 1-65535" required: true envKey: "PANEL_APP_PORT_HTTP" # 关联 Docker Compose 的 HTTP 端口配置键名 default: 8080 # 默认端口（常用Web应用端口） edit: true # 允许用户根据服务器端口占用情况修改 rule: "paramPort" # 强制端口格式验证 # 2. 数据库服务配置（支持多类型数据库选择） - type: "apps" # 服务类型：仅用于数据库选择（主选类型+子选实例） labelZh: "数据库服务" labelEn: "Database Service" label: zh: "数据库服务" zh-hant: "資料庫服務" en: "Database Service" ja: "データベースサービス" ms: "Perkhidmatan Pangkalan Data" pt-br: "Serviço de Banco de Dados" ru: "Сервис баз данных" ko: "데이터베이스 서비스" tr: "Veritabanı Hizmetleri" description: zh: "选择应用依赖的数据库类型及对应服务实例（需提前在 1Panel 中部署数据库服务）" zh-hant: "選擇應用程式依賴的資料庫類型及對應服務實例（需提前在 1Panel 中部署資料庫服務）" en: "Select the database type and corresponding service instance that the application depends on (deploy the database service in 1Panel in advance)" ja: "アプリケーションが依存するデータベースの種類と対応するサービスインスタンスを選択します（事前に1Panelでデータベースサービスをデプロイする必要があります）" ms: "Pilih jenis pangkalan data dan contoh perkhidmatan yang bergantung kepada aplikasi (perlu menyebarkan perkhidmatan pangkalan data dalam 1Panel terlebih dahulu)" pt-br: "Selecione o tipo de banco de dados e a instância de serviço correspondente da qual o aplicativo depende (implante o serviço de banco de dados no 1Panel com antecedência)" ru: "Выберите тип базы данных и соответствующий экземпляр службы, от которых зависит приложение (расположите службу базы данных в 1Panel заранее)" ko: "애플리케이션이 의존하는 데이터베이스 유형 및 해당 서비스 인스턴스를 선택합니다 (1Panel에서 미리 데이터베이스 서비스를 배포해야 함)" tr: "Uygulamanın bağımlı olduğu veritabanı türünü ve ilgili hizmet örneğini seçin (önceden 1Panel'de veritabanı hizmetini dağıtmanız gerekiyor)" required: true envKey: "PANEL_DB_TYPE" # 数据库类型环境变量键名（如 postgresql/mysql/mariadb） default: "postgresql" # 默认数据库类型（PostgreSQL 兼容性更优） edit: false # 固定数据库类型，不允许用户修改 # 可选数据库类型列表 values: - label: "PostgreSQL" value: "postgresql" - label: "MySQL" value: "mysql" - label: "MariaDB" value: "mariadb" # 数据库实例选择子配置 child: type: "service" # 子字段类型：服务实例选择 envKey: "PANEL_DB_HOST" # 数据库主机地址环境变量键名 required: true # 必须选择具体实例 default: "" # 无默认值，强制用户选择 # 3. 数据库名称配置 - type: "text" labelZh: "数据库名称" labelEn: "Database Name" label: zh: "数据库名称" zh-hant: "資料庫名稱" en: "Database Name" ja: "データベース名" ms: "Nama Pangkalan Data" pt-br: "Nome do Banco de Dados" ru: "Имя базы данных" ko: "데이터베이스 이름" tr: "Veritabanı Adı" description: zh: "应用所需的数据库名称，将自动创建（遵循英文/数字/.-_ 命名规则）" zh-hant: "應用程式所需的資料庫名稱，將自動建立（遵循英文/數字/.-_ 命名規則）" en: "The database name required by the application, which will be created automatically (follow the naming rule: English/numbers/.-_)" ja: "アプリケーションに必要なデータベース名で、自動的に作成されます（命名規則：英語/数字/.-_ に準拠）" ms: "Nama pangkalan data yang diperlukan oleh aplikasi, akan dibuat secara automatik (ikut peraturan penamaan: Bahasa Inggeris/nombor/.-_)" pt-br: "O nome do banco de dados necessário para o aplicativo, que será criado automaticamente (siga a regra de nomenclatura: Inglês/números/.-_)" ru: "Имя базы данных, необходимое для приложения, будет создано автоматически (соблюдайте правило именования: английский/цифры/.-_)" ko: "애플리케이션에 필요한 데이터베이스 이름으로, 자동으로 생성됩니다 (영문/숫자/.-_ 명명 규칙 준수)" tr: "Uygulama için gerekli veritabanı adı, otomatik olarak oluşturulur (İngilizce/sayılar/.-_ adlandırma kuralını izleyin)" required: true envKey: "PANEL_DB_NAME" default: "" edit: false # 自动生成，不允许用户修改 random: true # 在默认值后追加随机字符串，避免重复 rule: "paramCommon" # 强制通用命名规则验证 # 4. 数据库用户配置 - type: "text" labelZh: "数据库用户" labelEn: "Database User" label: zh: "数据库用户" zh-hant: "資料庫用戶" en: "Database User" ja: "データベースユーザー" ms: "Pengguna Pangkalan Data" pt-br: "Usuário do Banco de Dados" ru: "Пользователь базы данных" ko: "데이터베이스 사용자" tr: "Veritabanı Kullanıcısı" description: zh: "应用访问数据库的专用用户，将自动创建（权限绑定对应数据库）" zh-hant: "應用程式存取資料庫的專用使用者，將自動建立（權限繫結對應資料庫）" en: "Dedicated user for the application to access the database, which will be created automatically (permissions bound to the corresponding database)" ja: "アプリケーションがデータベースにアクセスするための専用ユーザーで、自動的に作成されます（対応するデータベースにアクセス権が設定されます）" ms: "Pengguna khusus untuk aplikasi mengakses pangkalan data, akan dibuat secara automatik (izin terikat pada pangkalan data yang sepadan)" pt-br: "Usuário dedicado para o aplicativo acessar o banco de dados, que será criado automaticamente (permissões vinculadas ao banco de dados correspondente)" ru: "Выделенный пользователь для доступа приложения к базе данных, будет создан автоматически (права привязаны к соответствующей базе данных)" ko: "애플리케이션이 데이터베이스에 접근하기 위한 전용 사용자로, 자동으로 생성됩니다 (해당 데이터베이스에 권한 바인딩)" tr: "Uygulamanın veritabanına erişmesi için özel kullanıcı, otomatik olarak oluşturulur (ilgili veritabanına izin bağlama)" required: true envKey: "PANEL_DB_USER" default: "" edit: false random: true rule: "paramCommon" # 5. 数据库密码配置（敏感信息） - type: "password" # 密码类型：输入内容隐藏显示 labelZh: "数据库密码" labelEn: "Database Password" label: zh: "数据库密码" zh-hant: "資料庫密碼" en: "Database Password" ja: "データベースパスワード" ms: "Kata Laluan Pangkalan Data" pt-br: "Senha do Banco de Dados" ru: "Пароль базы данных" ko: "데이터베이스 비밀번호" tr: "Veritabanı Parolası" description: zh: "数据库用户的访问密码，自动生成高强度随机密码（无需手动输入）" zh-hant: "資料庫使用者的存取密碼，自動生成高強度隨機密碼（無需手動輸入）" en: "Access password for the database user, automatically generate a high-strength random password (no manual input required)" ja: "データベースユーザーのアクセスパスワードで、高強度のランダムパスワードが自動生成されます（手動入力不要）" ms: "Kata laluan akses untuk pengguna pangkalan data, automatik menjana kata laluan rawak berketahanan tinggi (tidak perlu memasukkan secara manual)" pt-br: "Senha de acesso para o usuário do banco de dados, gera automaticamente uma senha aleatória de alta segurança (não é necessário digitar manualmente)" ru: "Пароль доступа для пользователя базы данных, автоматически генерируется сложный случайный пароль (ручной ввод не требуется)" ko: "데이터베이스 사용자의 접근 비밀번호로, 고강도 랜덤 비밀번호가 자동 생성됩니다（수동 입력 불필요）" tr: "Veritabanı kullanıcısı için erişim parolası, yüksek güvenlikli rastgele parola otomatik olarak oluşturulur (elle giriş gerekmez)" required: true envKey: "PANEL_DB_USER_PASSWORD" default: "" edit: false random: true # 强制生成随机密码，提升安全性 # 6. Redis 缓存服务配置（单一服务选择） - type: "service" # 服务类型：用于缓存服务（Redis/Memcached等）选择 key: "redis" # 依赖服务标识：创建应用前需先部署 Redis 服务 labelZh: "Redis 缓存服务" labelEn: "Redis Cache Service" label: zh: "Redis 服务" zh-hant: "Redis 服務" en: "Redis Service" ja: "Redis サービス" ms: "Perkhidmatan Redis" pt-br: "Serviço Redis" ru: "Сервис Redis" ko: "Redis 서비스" tr: "Redis Hizmeti" description: zh: "选择应用依赖的 Redis 服务实例（需提前在 1Panel 中部署 Redis）" zh-hant: "選擇應用程式依賴的 Redis 服務實例（需提前在 1Panel 中部署 Redis）" en: "Select the Redis service instance that the application depends on (deploy Redis in 1Panel in advance)" ja: "アプリケーションが依存するRedisサービスインスタンスを選択します（事前に1PanelでRedisをデプロイする必要があります）" ms: "Pilih contoh perkhidmatan Redis yang bergantung kepada aplikasi (perlu menyebarkan Redis dalam 1Panel terlebih dahulu)" pt-br: "Selecione a instância do serviço Redis da qual o aplicativo depende (implante o Redis no 1Panel com antecedência)" ru: "Выберите экземпляр службы Redis, от которого зависит приложение (расположите Redis в 1Panel заранее)" ko: "애플리케이션이 의존하는 Redis 서비스 인스턴스를 선택합니다 (1Panel에서 미리 Redis를 배포해야 함)" tr: "Uygulamanın bağımlı olduğu Redis hizmet örneğini seçin (önceden 1Panel'de Redis'i dağıtmanız gerekiyor)" required: true envKey: "REDIS_HOST" # Redis 主机地址环境变量键名 default: "" edit: false # 仅允许选择已部署实例，不允许手动输入docker-compose.yml 说明
版本目录下的 docker-compose.yml 文件用于定义应用程序的容器化部署配置。 一般来说，对于大多数应用，可以参考以下示例进行编写：
# 网络配置：复用 1Panel 平台统一网络，实现容器间互联互通networks: 1panel-network: external: true # 声明使用已存在的外部网络（由 1Panel 自动创建）services: # Halo 主服务配置（服务名可根据实际需求自定义） halo: container_name: ${CONTAINER_NAME} # 容器名称，固定写法，多容器时可加后缀区分，如 ${CONTAINER_NAME}-db image: halohub/halo-pro:2.21.8 # 容器镜像 restart: always # 重启策略 networks: - 1panel-network # 加入 1Panel 统一网络，支持与数据库、缓存等服务通信 volumes: # 数据卷挂载：将容器数据目录映射到宿主机，实现数据持久化 - ./data:/root/.halo2 ports: # 端口映射：将宿主机端口（由 1Panel 配置的 HTTP 端口）映射到容器内默认端口 8090 - ${PANEL_APP_PORT_HTTP}:8090 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"] interval: 30s timeout: 5s retries: 5 start_period: 30s command: # 数据库连接配置（通过环境变量注入，与 1Panel 安装表单参数关联） - --spring.r2dbc.url=r2dbc:pool:${PANEL_DB_TYPE}://${PANEL_DB_HOST}:${PANEL_DB_PORT}/${PANEL_DB_NAME} - --spring.r2dbc.username=${PANEL_DB_USER} # 数据库用户名 - --spring.r2dbc.password=${PANEL_DB_USER_PASSWORD} # 数据库密码 - --spring.sql.init.platform=${PANEL_DB_TYPE} # 数据库平台类型（适配 MySQL/PostgreSQL 等） # Halo 核心配置 - --halo.external-url=${HALO_EXTERNAL_URL} # Halo 外部访问地址（用于生成链接、回调等） environment: - JVM_OPTS= labels: createdBy: "Apps" # 1Panel 应用市场识别标签（固定写法，不可修改，用于平台管理）对于现有的 docker-compose.yml 文件，为确保其能在 1Panel 平台正常运行，可根据以下要点进行检查和调整：
网络配置：确保包含
networks部分，并正确引用1panel-network外部网络。1Panel 平台所有应用默认部署在该统一网络下，若缺失此配置，应用将无法与数据库、Redis 等依赖服务（同样部署在该网络）进行内部通信，可能导致连接失败。容器名称与环境变量：
- 容器名称需使用
${CONTAINER_NAME}变量（固定写法），该值由 1Panel 自动生成并注入，确保多应用部署时容器名称不冲突；若为多容器应用（如应用+数据库），可在变量后加后缀（如${CONTAINER_NAME}-db）区分。 - 与 1Panel 安装表单关联的参数（如端口、数据库信息、访问地址等），需使用对应环境变量（如
${PANEL_APP_PORT_HTTP}${PANEL_DB_HOST}），变量名需与data.yml中formFields的envKey完全一致，否则参数无法正常传递。
- 容器名称需使用
数据持久化配置：核心数据目录需通过
volumes挂载到宿主机（如示例中./data:/root/.halo2）。1Panel 平台会将./data映射到宿主机的应用专属数据目录（由平台统一管理），若缺失此配置，容器删除或重建时，应用数据（如配置、内容、日志等）将全部丢失。标签配置：必须保留
labels: createdBy: "Apps"配置（固定写法，不可修改）。该标签是 1Panel 识别应用为“应用市场应用”的核心标识，缺失后平台将无法对应用进行统一管理。
脚本文件说明
1Panel 支持三种标准的应用程序生命周期脚本：
init.sh: 应用程序初始化脚本，在应用程序首次安装时执行upgrade.sh: 应用程序升级脚本，在应用程序版本升级过程中执行，具体在升级任务的执行阶段uninstall.sh: 应用程序卸载脚本，在应用程序被删除时执行
data 目录说明
有些应用在挂载数据卷时，可能需要预置一些初始数据文件（如配置文件、模板文件等）。在这种情况下，可以将这些预置数据文件放在版本目录下的 data 目录中，同时在 docker-compose.yml 中将 data 目录挂载到容器的相应路径。当然，如果你想要提交到 git 仓库，对于空文件夹，可以在 data 目录下放置一个 .gitkeep 文件，以确保该目录被版本控制系统跟踪。
本地测试
将应用目录上传到安装有 1Panel 服务器的的 /opt/1panel/resource/apps/local 文件夹下，然后在 1Panel 应用商店中点击 同步本地应用，选择“本地应用”分类，即可看到该应用，点击安装即可进行测试。
最后
提交一个 Pr，完事
评论 (0)