---
title: 为1Panel添加自己想要的应用
categories:
  - 技术
tags:
  - 1panel
cover: https://pic.biss.click/image/fa0178dd-b1f6-48eb-8690-42faf26c9f52.webp
abbrlink: bb18d851
summary: >-
  这篇文章详细介绍了如何为1Panel添加自定义应用的过程，包括预准备工作、创建文件和配置应用声明文件等步骤。首先，作者强调了Fork仓库和创建新分支的重要性。接着，文章逐步讲解了如何在应用目录下创建所需的文件和子目录，如halo、logo.png、data.yml、README.md等。特别详细地说明了应用声明文件data.yml的构成，包括基本信息、应用标签、类型等关键配置。此外，还解释了关于端口字段和type字段的具体使用方法，提供了实际安装时填写form表单的示例。整个过程不仅清晰易懂，而且为开发者提供了一套完整的操作指南，有助于他们更好地理解和实施应用添加到1Panel的过程。
date: 2025-08-19 10:43:16
---

记录一下自己为1Panel贡献自己应用的经历

# 预准备
1. Fork仓库
    {% link 1Panel appstore 仓库,1panel appstore,https://github.com/1Panel-dev/appstore %}
    把仓库fork到自己的仓库
2. pull
    ```bash
    git clone -b dev https://<your-github-username>/appstore
    ```
    创建新分支
    ```bash
    cd appstore
    git checkout -b app/<app-name>
    ```
# 创建文件

## 文件目录
```
├──halo // 以 halo 的 key 命名 ，下面解释什么是 key 
	├── 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`

本文件主要用于声明应用的一些信息
```yml
additionalProperties:  #固定参数
    key: halo   #应用的 key ，仅限英文，用于在 Linux 创建文件夹
    name: Halo  #应用名称
    tags:  
        - WebSite #应用标签，可以有多个，请参照下方的标签列表 
	description:  
	  en: Powerful and easy-to-use open source website builder
	  zh: 强大易用的开源建站工具 #应用中文描述，不要超过30个字
	  zh-Hant:
	  ja:   
	  ms: 
	  pt-br: 
	  ru:  
	  ko: 
    type: website  #应用类型，区别于应用分类，只能有一个，请参照下方的类型列表
    crossVersionUpdate: true  #是否可以跨大版本升级
    limit: 0  #应用安装数量限制，0 代表无限制
    website: https://halo.run/  #官网地址
    github: https://github.com/halo-dev/halo #github 地址 
    document: https://docs.halo.run/ #文档地址
```
## 应用标签 - tags 字段
| key      | name     |
|----------|----------|
| WebSite  | 建站       |
| Server   | Web 服务器  |
| Runtime  | 运行环境     |
| Database | 数据库      |
| Tool     | 工具       |
| CI/CD    | CI/CD    |
| Local    | 本地       |

# 应用类型 - type 字段

| type    | 说明                                                      |
|---------|---------------------------------------------------------|
| website | website 类型在 1Panel 中支持在网站中一键部署,wordpress halo 都是此 type  |
| runtime | mysql openresty redis 等类型的应用                            |
| tool    | phpMyAdmin redis-commander jenkins 等类型的应用               |

# 应用参数配置文件 data.yml 
（注意区分于应用主目录下面的 `data.yaml`）

本文件主要用于生成安装时要填写的 form 表单，在应用版本文件夹下面 可以无表单，但是需要有这个 data.yml文件，并且包含 formFields 字段

以安装 halo 时的 form 表单 为例

如果要生成上面的表单，需要这么填写 `data.yml`
```yml
	additionalProperties:  #固定参数
	    formFields:  
	        - default: ""  
	          envKey: PANEL_DB_HOST  #docker-compose 文件中的参数
	          key: mysql  #依赖应用的 key , 例如 mysql
		  label:  
		   en: Database Service  
	           ja: データベースサービス  
		   ms: Perkhidmatan Pangkalan Data  
		   pt-br: Serviço de Banco de Dados  
		   ru: Сервис базы данных  
		   ko: 데이터베이스 서비스  
		   zh: 数据库服务  
		   zh-Hant: 數據庫 服務
		  required: true  #是否必填
	          type: service  #如果需要依赖其他应用，例如数据库，使用此 type 
	        - default: halo  
	          envKey: PANEL_DB_NAME  
	          label:  
	            en: Database  
		    ja: データベース  
		    ms: Pangkalan Data  
		    pt-br: Banco de Dados  
		    ru: База данных  
		    ko: 데이터베이스  
		    zh: 数据库名  
		    zh-Hant: 資料庫名稱
	          random: true  #是否在 default 文字后面，增加随机字符串
	          required: true  
	          rule: paramCommon  #校验规则
	          type: text  #需要手动填写的，使用此 type
	        - default: halo  
	          envKey: PANEL_DB_USER  
		  label:  
		    en: User  
		    ja: ユーザー  
		    ms: Pengguna  
		    pt-br: Usuário  
		    ru: Пользователь  
		    ko: 사용자  
		    zh: 数据库用户  
		    zh-Hant: 資料庫使用者
	          random: true  
	          required: true  
	          rule: paramCommon  
	          type: text  
	        - default: halo  
	          envKey: PANEL_DB_USER_PASSWORD  
		  label:  
		    en: Password  
		    ja: パスワード  
		    ms: Kata laluan  
		    pt-br: Senha  
		    ru: Пароль  
		    ko: 비밀번호  
		    zh: 数据库用户密码  
		    zh-Hant: 資料庫使用者密碼 
	          random: true  
	          required: true  
	          rule: paramComplexity  
	          type: password  #密码字段使用此 type
	        - default: admin  
	          envKey: HALO_ADMIN  
	          labelEn: Admin Username  
	          labelZh: 超级管理员用户名  
	          required: true  
	          rule: paramCommon  
	          type: text 
	        - default: http://localhost:8080  
	          edit: true  
	          envKey: HALO_EXTERNAL_URL  
		  label:  
		    en: External URL  
		    ja: 外部URL  
		    ms: URL Luaran  
		    pt-br: URL Externa  
		    ru: Внешний URL  
		    ko: 외부 URL  
		    zh: 外部访问地址  
		    zh-Hant: 外部訪問地址 
	          required: true  
	          rule: paramExtUrl  
	          type: text  
	        - default: 8080  
	          edit: true  
	          envKey: PANEL_APP_PORT_HTTP  
		  label:  
		    en: Port  
		    ja: ポート  
		    ms: Port  
		    pt-br: Porta  
		    ru: Порт  
		    ko: 포트  
		    zh: 端口  
		    zh-Hant: 埠
	          required: true  
	          rule: paramPort  
	          type: number #端口使用此 type 
```
## 关于端口字段：
`PANEL_APP_PORT_HTTP` 有 `web` 访问端口的优先使用此 `envKey`
`envKey` 中包含 `PANEL_APP_PORT` 前缀会被认定为端口类型，并且用于安装前的端口占用校验。注意：端口需要是外部端口
## 关于 type 字段：
| type     | 说明                                                                                      |
|----------|-----------------------------------------------------------------------------------------|
| service  | type: service 如果该应用需要依赖其他组件，如 mysql redis 等，可以通过 key: mysql 定义依赖的名称，在创建应用时会要求先创建依赖的应用。  |
| password | type: password 敏感信息，如密码相关的字段会默认不显示明文。                                                   |
| text     | type: text 一般内容，比如数据库名称，默认明文显示。                                                         |
| number   | type: number 一般用在端口相关的配置上，只允许输入数字。                                                      |

简单的例子
```yml
# type: service，定义一个 mysql 的 service 依赖。
- child:  
    default: ""  
    envKey: PANEL_DB_HOST  
    required: true  
    type: service  
  default: mysql  
  envKey: PANEL_DB_TYPE  
  label:  
    en: Database Service  
    ja: データベースサービス  
    ms: Perkhidmatan Pangkalan Data  
    pt-br: Serviço de Banco de Dados  
    ru: Сервис баз данных  
    ko: 데이터베이스 서비스  
    zh-hant: 資料庫服務  
    zh: 数据库服务  
  required: true  
  type: apps  
  values:  
    - label: MySQL  
      value: mysql  
    - label: MariaDB  
      value: mariadb

# type: password
- default: word  
  envKey: PANEL_DB_USER_PASSWORD  
  labelEn: Database Password  
  labelZh: 数据库密码  
  label:  
    en: Database Password  
    ja: データベースのパスワード  
    ms: Kata Laluan Pangkalan Data  
    pt-br: Senha do Banco de Dados  
    ru: Пароль базы данных  
    ko: 데이터베이스 비밀번호  
    zh-hant: 資料庫密碼  
    zh: 数据库密码  
  random: true  
  required: true  
  type: password

# type: text
- default: ""  
  edit: true  
  envKey: REDIS_HOST  
  key: redis  
  required: true  
  type: service  
  label:  
    en: Redis Service  
    ja: Redis サービス  
    ms: Perkhidmatan Redis  
    pt-br: Serviço Redis  
    ru: Сервис Redis  
    ko: Redis 서비스  
    zh-Hant: Redis 服務  
    zh: Redis 服务
    
# type: number
- default: ""  
  edit: true  
  envKey: DBHUB_DB_PORT  
  required: true  
  type: text  
  label:  
    en: Database Port  
    ja: データベースのポート  
    ms: Pangkalan Data Port  
    pt-br: Porta do Banco de Dados  
    ru: Порт базы данных  
    ko: 데이터베이스 포트  
    zh-hant: 資料庫端口  
    zh: 数据库端口

# type: select
- default: "ERROR"  
  envKey: LOG_LEVEL  
  required: true  
  type: select  
  values:  
    - label: DEBUG  
      value: "DEBUG"  
    - label: INFO  
      value: "INFO"  
    - label: WARNING  
      value: "WARNING"  
    - label: ERROR  
      value: "ERROR"  
    - label: CRITICAL  
      value: "CRITICAL"
```
rule 字段目前支持的几种校验
| rule            | 规则                                 |
|-----------------|------------------------------------|
| paramPort       | 用于限制端口范围为 1-65535                  |
| paramExtUrl     | 格式为 http(s)://(域名/ip):(端口)         |
| paramCommon     | 英文、数字、.-和_,长度2-30                  |
| paramComplexity | 支持英文、数字、.%@$!&~_-,长度6-30，特殊字符不能在首尾 |

应用 `docker-compose.yml` 文件

`${PANEL_APP_PORT_HTTP} `类型的参数，都在 `data.yml` 中有声明

```yml
version: "3"  
services:  
  halo:  
    image: halohub/halo:2.2.0  
    container_name: ${CONTAINER_NAME}  // 固定写法，勿改
    restart: always  
    networks:  
      - 1panel-network  // 1Panel 创建的应用都在此网络下
    volumes:  
      - ./data:/root/.halo2  
    ports:  
      - ${PANEL_APP_PORT_HTTP}:8090  
    command:  
      - --spring.r2dbc.url=r2dbc:pool:${HALO_PLATFORM}://${PANEL_DB_HOST}:${HALO_DB_PORT}/${PANEL_DB_NAME}  
      - --spring.r2dbc.username=${PANEL_DB_USER}  
      - --spring.r2dbc.password=${PANEL_DB_USER_PASSWORD}  
      - --spring.sql.init.platform=${HALO_PLATFORM}  
      - --halo.external-url=${HALO_EXTERNAL_URL}  
      - --halo.security.initializer.superadminusername=${HALO_ADMIN}  
      - --halo.security.initializer.superadminpassword=${HALO_ADMIN_PASSWORD}  
    labels:  
      createdBy: "Apps"  
  
networks:  
  1panel-network:  
    external: true
```
## 脚本
1Panel 在 安装之前、升级之前、卸载之后支持执行 .sh 脚本
分别对应 init.sh upgrade.sh uninstall.sh
存放目录(以halo为例) : halo/2.2.0/scripts

# 本地测试
将应用目录上传到 1Panel 的 /opt/1panel/resource/apps/local 文件夹下
注意：/opt 为 1Panel 默认安装目录，请根据自己的实际情况修改
上传完成后，目录结构如下
```
├──halo 
	├── logo.png 
	├── data.yml
	├── README.md 
	├── 2.2.0 
	    ├── data.yml 
	    ├── data  
	    └── docker-compose.yml
```
在 1Panel 应用商店中，点击更新应用列表按钮同步本地应用

v1.2 版本及之前版本的本地应用，请参考这个文档修改

# 提交文件
```bash
git add .
git commit -m "Add my-app"
git push origin dev
```
# 提交 Pull Request
在你的仓库点击 Pull requests 菜单
点击 New pull request ，填写标题和描述
选择由你的分支提交到 1Panel-dev/appstore